fullstackgtm 0.42.0 → 0.44.0

package/dist/connectors/hubspot.js

@@ -406,18 +406,35 @@ export function createHubspotConnector(options) {
             providerData: { companyId, ...(createdCompanyName ? { createdCompany: true } : {}) },
         };
     }
-    /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
-    async function searchCompaniesByName(name) {
+    /** Exact-value company lookup (by `name` or `domain`) for resolve-first creates. */
+    async function searchCompaniesBy(property, value) {
         const data = await request(`/crm/v3/objects/companies/search`, {
             method: "POST",
             body: JSON.stringify({
-                filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
-                properties: ["name"],
+                filterGroups: [{ filters: [{ propertyName: property, operator: "EQ", value }] }],
+                properties: [property],
                 limit: 3,
             }),
         });
         return (data?.results ?? []).map((row) => String(row.id));
     }
+    const searchCompaniesByName = (name) => searchCompaniesBy("name", name);
+    /** Stamp `domain` on a company only when it has none (fill-blank, never clobber). */
+    async function fillCompanyDomainIfEmpty(companyId, domain) {
+        try {
+            const data = await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}?properties=domain`);
+            const current = data?.properties?.domain;
+            if (typeof current === "string" && current.trim())
+                return; // already has one — leave it
+            await request(`/crm/v3/objects/companies/${encodeURIComponent(companyId)}`, {
+                method: "PATCH",
+                body: JSON.stringify({ properties: { domain } }),
+            });
+        }
+        catch {
+            // Best-effort: a failed domain fill must not sink the contact create.
+        }
+    }
     /** Exact-value contact lookup (by any searchable property) for resolve-first creates. */
     async function searchContactsBy(property, value) {
         const data = await request(`/crm/v3/objects/contacts/search`, {
@@ -431,39 +448,55 @@ export function createHubspotConnector(options) {
         return (data?.results ?? []).map((row) => String(row.id));
     }
     /**
-     * Resolve a company by exact name, creating it on a confirmed miss. Returns
-     * the company id, or null on ambiguity (≥2 existing) so the caller skips the
-     * association rather than guessing. Same-run safe via createdCompaniesByName.
+     * Resolve a company to a real account record, creating it on a confirmed miss.
+     * Matches by DOMAIN first (the accurate key) and falls back to exact name;
+     * creates with the domain stamped, and fills the domain on a name-matched
+     * account that lacks one — so the account is signal-watchable. Returns null on
+     * ambiguity (≥2 matches) so the caller skips the association rather than
+     * guessing. Same-run safe via createdCompaniesByName.
      */
-    async function resolveOrCreateCompanyByName(name, opId) {
-        const nameKey = name.toLowerCase();
-        const already = createdCompaniesByName.get(nameKey);
+    async function resolveOrCreateCompany(name, domain, opId) {
+        const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+        const already = createdCompaniesByName.get(cacheKey);
         if (already)
             return already;
-        const matches = await searchCompaniesByName(name);
-        if (matches.length > 1)
-            return null;
-        if (matches.length === 1) {
-            createdCompaniesByName.set(nameKey, matches[0]);
-            return matches[0];
+        // 1. Domain-first match (accurate; an account matched here already has it).
+        if (domain) {
+            const byDomain = await searchCompaniesBy("domain", domain);
+            if (byDomain.length > 1)
+                return null;
+            if (byDomain.length === 1) {
+                createdCompaniesByName.set(cacheKey, byDomain[0]);
+                return byDomain[0];
+            }
         }
+        // 2. Exact-name match; stamp the domain if the account has none.
+        const byName = await searchCompaniesByName(name);
+        if (byName.length > 1)
+            return null;
+        if (byName.length === 1) {
+            if (domain)
+                await fillCompanyDomainIfEmpty(byName[0], domain);
+            createdCompaniesByName.set(cacheKey, byName[0]);
+            return byName[0];
+        }
+        // 3. Create with name + domain (provenance is best-effort).
+        const props = { name, ...(domain ? { domain } : {}) };
         let created;
         try {
             created = await request(`/crm/v3/objects/companies`, {
                 method: "POST",
-                body: JSON.stringify({
-                    properties: { name, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` },
-                }),
+                body: JSON.stringify({ properties: { ...props, hs_object_source_detail_2: `fullstackgtm acquire (${opId})` } }),
             });
         }
         catch {
             created = await request(`/crm/v3/objects/companies`, {
                 method: "POST",
-                body: JSON.stringify({ properties: { name } }),
+                body: JSON.stringify({ properties: props }),
             });
         }
         const id = String(created.id);
-        createdCompaniesByName.set(nameKey, id);
+        createdCompaniesByName.set(cacheKey, id);
         return id;
     }
     /**
@@ -487,7 +520,7 @@ export function createHubspotConnector(options) {
             return { operationId: operation.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." };
         }
         if (operation.objectType === "account") {
-            const id = await resolveOrCreateCompanyByName(matchValue, operation.id);
+            const id = await resolveOrCreateCompany(matchValue, stringOrUndefined(payload.properties?.domain), operation.id);
             if (id === null) {
                 return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — multiple companies named "${matchValue}". Not creating.` };
             }
@@ -534,10 +567,11 @@ export function createHubspotConnector(options) {
         let companyNote = "";
         if (payload.associateCompanyName) {
             try {
-                const companyId = await resolveOrCreateCompanyByName(payload.associateCompanyName, operation.id);
+                const companyId = await resolveOrCreateCompany(payload.associateCompanyName, payload.associateCompanyDomain, operation.id);
                 if (companyId) {
                     await request(`/crm/v4/objects/contacts/${encodeURIComponent(contactId)}/associations/default/companies/${encodeURIComponent(companyId)}`, { method: "PUT" });
-                    companyNote = ` Linked to company "${payload.associateCompanyName}" (${companyId}).`;
+                    const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+                    companyNote = ` Linked to company "${payload.associateCompanyName}"${domainNote} (${companyId}).`;
                 }
                 else {
                     companyNote = ` Company "${payload.associateCompanyName}" was ambiguous; left unlinked.`;

package/dist/connectors/outboxChannel.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Outbox channel connector — the governed SEND-side terminus of the outbound
+ * loop (signal → judge → draft → approve → apply → outbox), and the mirror image
+ * of the webhook spool. It is a `GtmConnector` whose `applyOperation` RENDERS an
+ * approved drafted opener to a local outbox artifact instead of writing a CRM —
+ * so it reuses the entire governed apply machinery (approval set, integrity/HMAC
+ * verification, idempotency, run recording) with no change to the apply engine.
+ *
+ * THE INVARIANT IT KEEPS: the CLI **transmits nothing**. Rendering an approved
+ * opener to `<home>/signals/outbox/<channel>.jsonl` is a local file write, never
+ * an SMTP/API connection. A downstream sender (the hosted product, or the
+ * operator's own MTA) drains the outbox and does the actual transmission. This
+ * is the send-side half of the open-core boundary: the governed artifact + its
+ * format are open; always-on transmission infrastructure is hosted/opt-in.
+ *
+ * Governance: it only renders ops that came from `draft` (a `create_task` op
+ * whose policy is `draft:<channel>`); any other op is `skipped` (it is not a
+ * general CRM writer). Idempotent on the operation id — re-applying an approved
+ * plan never duplicates an outbox row. Read paths (`fetchSnapshot`) intentionally
+ * throw: a channel has no snapshot, and `applyPatchPlan` never calls it for a
+ * draft plan (no guards/filter/irreversible ops → no snapshot needed).
+ */
+import type { GtmConnector } from "../types.ts";
+/** One approved, ready-to-send touch — a governed send INTENT, not a sent message. */
+export type OutboxEntry = {
+    /** Idempotency key = the source operation id (stable per draft op). */
+    id: string;
+    /** email | linkedin | task — from the draft op's `draft:<channel>` policy. */
+    channel: string;
+    /** The CRM target the opener is addressed to (a sender resolves id → address). */
+    objectType: string;
+    objectId: string;
+    /** The APPROVED opener, verbatim as it was signed in the plan op. */
+    body: string;
+    /** The draft op's human-readable reason (carries the account + trigger). */
+    reason?: string;
+    /** Evidence ids the opener was grounded in (the verbatim signal quote). */
+    evidenceIds: string[];
+    /** ISO 8601 — when the CLI rendered this to the outbox (NOT a send time). */
+    renderedAt: string;
+};
+/** Channel ids this build can render to. */
+export declare const CHANNELS: readonly ["outbox"];
+export type OutboxChannelOptions = {
+    /** Outbox directory; defaults to the profile-scoped `signalsOutboxDir()`. */
+    outboxDir?: string;
+    /** Injectable clock for deterministic tests. */
+    now?: () => Date;
+};
+/**
+ * Build the outbox channel connector. With no `outboxDir`, writes to the
+ * profile-scoped conventional outbox and locks the home down (0700/0600) like
+ * the signal store; with an explicit `outboxDir` (tests), it writes there
+ * without touching the real home.
+ */
+export declare function createOutboxChannelConnector(options?: OutboxChannelOptions): GtmConnector;
+/** Resolve a channel connector by id (mirrors the source-connector registry). */
+export declare function createChannelConnector(id: string, options?: OutboxChannelOptions): GtmConnector;
+/**
+ * Read every outbox entry across all channel files in `dir` (default: the
+ * conventional outbox), newest-appended last. The reader a downstream sender (or
+ * a future `signals outbox` command) uses to drain the queue.
+ */
+export declare function listOutbox(dir?: string): OutboxEntry[];

package/dist/connectors/outboxChannel.js

@@ -0,0 +1,170 @@
+/**
+ * Outbox channel connector — the governed SEND-side terminus of the outbound
+ * loop (signal → judge → draft → approve → apply → outbox), and the mirror image
+ * of the webhook spool. It is a `GtmConnector` whose `applyOperation` RENDERS an
+ * approved drafted opener to a local outbox artifact instead of writing a CRM —
+ * so it reuses the entire governed apply machinery (approval set, integrity/HMAC
+ * verification, idempotency, run recording) with no change to the apply engine.
+ *
+ * THE INVARIANT IT KEEPS: the CLI **transmits nothing**. Rendering an approved
+ * opener to `<home>/signals/outbox/<channel>.jsonl` is a local file write, never
+ * an SMTP/API connection. A downstream sender (the hosted product, or the
+ * operator's own MTA) drains the outbox and does the actual transmission. This
+ * is the send-side half of the open-core boundary: the governed artifact + its
+ * format are open; always-on transmission infrastructure is hosted/opt-in.
+ *
+ * Governance: it only renders ops that came from `draft` (a `create_task` op
+ * whose policy is `draft:<channel>`); any other op is `skipped` (it is not a
+ * general CRM writer). Idempotent on the operation id — re-applying an approved
+ * plan never duplicates an outbox row. Read paths (`fetchSnapshot`) intentionally
+ * throw: a channel has no snapshot, and `applyPatchPlan` never calls it for a
+ * draft plan (no guards/filter/irreversible ops → no snapshot needed).
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSecureHomeDir, writeSecureFile } from "../credentials.js";
+import { signalsOutboxDir } from "../signals.js";
+/** Channel ids this build can render to. */
+export const CHANNELS = ["outbox"];
+const DRAFT_POLICY_PREFIX = "draft:";
+/**
+ * Build the outbox channel connector. With no `outboxDir`, writes to the
+ * profile-scoped conventional outbox and locks the home down (0700/0600) like
+ * the signal store; with an explicit `outboxDir` (tests), it writes there
+ * without touching the real home.
+ */
+export function createOutboxChannelConnector(options = {}) {
+    const usingDefaultHome = options.outboxDir === undefined;
+    const dir = options.outboxDir ?? signalsOutboxDir();
+    const now = options.now ?? (() => new Date());
+    function fileFor(channel) {
+        if (!/^[\w.-]+$/.test(channel))
+            throw new Error(`Invalid outbox channel name: ${channel}`);
+        return join(dir, `${channel}.jsonl`);
+    }
+    /** Existing entry ids in a channel file (for idempotent re-apply). */
+    function existingIds(channel) {
+        const ids = new Set();
+        let raw;
+        try {
+            raw = readFileSync(fileFor(channel), "utf8");
+        }
+        catch {
+            return ids; // no file yet
+        }
+        for (const line of raw.split("\n")) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                const id = JSON.parse(t).id;
+                if (typeof id === "string")
+                    ids.add(id);
+            }
+            catch {
+                // Skip a corrupt line rather than fail the whole apply.
+            }
+        }
+        return ids;
+    }
+    function append(channel, entry) {
+        if (usingDefaultHome)
+            ensureSecureHomeDir();
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = fileFor(channel);
+        // Owner-only like the signal store: outbox carries opener text + CRM ids.
+        if (!existsSync(path))
+            writeSecureFile(path, "");
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+    }
+    async function applyOperation(operation) {
+        const policy = String(operation.sourceRuleOrPolicy ?? "");
+        if (operation.operation !== "create_task" || !policy.startsWith(DRAFT_POLICY_PREFIX)) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: "The outbox channel only renders drafted openers (create_task ops from `draft`). " +
+                    "Apply other operations through a CRM connector (--provider hubspot|salesforce).",
+            };
+        }
+        const channel = policy.slice(DRAFT_POLICY_PREFIX.length) || "task";
+        // Idempotent: a re-applied approved plan must not duplicate the row.
+        if (existingIds(channel).has(operation.id)) {
+            return {
+                operationId: operation.id,
+                status: "applied",
+                detail: `Already in outbox (${channel}.jsonl); idempotent — not duplicated. Nothing transmitted.`,
+            };
+        }
+        const entry = {
+            id: operation.id,
+            channel,
+            objectType: operation.objectType,
+            objectId: operation.objectId,
+            body: typeof operation.afterValue === "string" ? operation.afterValue : String(operation.afterValue ?? ""),
+            ...(operation.reason ? { reason: operation.reason } : {}),
+            evidenceIds: operation.evidenceIds ?? [],
+            renderedAt: now().toISOString(),
+        };
+        append(channel, entry);
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Rendered to outbox (${channel}.jsonl) for a downstream sender. Nothing was transmitted.`,
+        };
+    }
+    async function fetchSnapshot() {
+        // A channel has no readable state. apply never calls this for a draft plan
+        // (no guards/filter/irreversible ops); make the misuse explicit if it does.
+        throw new Error("The outbox channel has no snapshot to read — it is a send-side render target. " +
+            "Use it only to `apply` an approved draft plan (`apply --plan-id <id> --channel outbox`).");
+    }
+    return {
+        provider: "outbox",
+        fetchSnapshot,
+        applyOperation,
+    };
+}
+/** Resolve a channel connector by id (mirrors the source-connector registry). */
+export function createChannelConnector(id, options = {}) {
+    if (id === "outbox")
+        return createOutboxChannelConnector(options);
+    throw new Error(`Unknown channel: ${id} (one of: ${CHANNELS.join(", ")}).`);
+}
+/**
+ * Read every outbox entry across all channel files in `dir` (default: the
+ * conventional outbox), newest-appended last. The reader a downstream sender (or
+ * a future `signals outbox` command) uses to drain the queue.
+ */
+export function listOutbox(dir) {
+    const outboxDir = dir ?? signalsOutboxDir();
+    let names;
+    try {
+        names = readdirSync(outboxDir).filter((name) => name.endsWith(".jsonl")).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let raw;
+        try {
+            raw = readFileSync(join(outboxDir, name), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                out.push(JSON.parse(t));
+            }
+            catch {
+                // Skip corrupt lines.
+            }
+        }
+    }
+    return out;
+}

package/dist/connectors/prospectSources.d.ts

@@ -56,6 +56,28 @@ export declare function fetchPipe0CrustdataProspects(opts: {
     apiBaseUrl?: string;
     fetchImpl?: FetchImpl;
 }): Promise<Prospect[]>;
+export declare const EXPLORIUM_BUSINESS_COUNT_CAP = 60000;
+export type BusinessCountProbe = {
+    /** matching companies (the account universe); == cap when saturated. */
+    total: number;
+    /** true when total hit EXPLORIUM_BUSINESS_COUNT_CAP — treat total as a lower bound. */
+    capped: boolean;
+};
+/**
+ * Count the COMPANIES (accounts) matching an ICP firmographic via Explorium
+ * /v1/businesses. Returns the real total (capped at 60k — `capped` flags the
+ * ceiling) or null if the response carries no `total_results`. Use
+ * `icpToExploriumBusinessFilters` to build `filters` (firmographic field names
+ * differ from /v1/prospects).
+ */
+export declare function probeExploriumBusinessCount(opts: {
+    apiKey: string;
+    filters: Record<string, {
+        values?: string[];
+    }>;
+    apiBaseUrl?: string;
+    fetchImpl?: FetchImpl;
+}): Promise<BusinessCountProbe | null>;
 export declare function pipe0ResolveWorkEmails(opts: {
     apiKey: string;
     prospects: Prospect[];

package/dist/connectors/prospectSources.js

@@ -85,6 +85,49 @@ function strField(field) {
     const v = field?.value;
     return typeof v === "string" && v.trim() ? v : undefined;
 }
+// ---------------------------------------------------------------------------
+// TAM universe count — "how many ACCOUNTS match this ICP firmographic?"
+//
+// Verified empirically (2026-06-25) against the live providers, because the
+// obvious endpoints lie about totals:
+//   - Explorium /v1/prospects `total_results` == the PAGE size (1→1, 10→10), not
+//     the universe — useless for sizing. So is /v1/businesses for tiny pages? No:
+//   - Explorium /v1/businesses `total_results` IS a real COUNT of matching
+//     companies (US+10000-emp → 9,754; Liechtenstein+10000 → 11), capped at
+//     EXPLORIUM_BUSINESS_COUNT_CAP. At/above the cap it saturates at exactly that
+//     number, so the caller must treat a capped reading as a FLOOR, not a count.
+//   - pipe0/Crustdata people search returns only a pagination cursor, NO total —
+//     it cannot size a universe at all (callers use it for discovery, not counting).
+// So the TAM count source is Explorium /v1/businesses (a company/account count).
+export const EXPLORIUM_BUSINESS_COUNT_CAP = 60_000;
+/**
+ * Count the COMPANIES (accounts) matching an ICP firmographic via Explorium
+ * /v1/businesses. Returns the real total (capped at 60k — `capped` flags the
+ * ceiling) or null if the response carries no `total_results`. Use
+ * `icpToExploriumBusinessFilters` to build `filters` (firmographic field names
+ * differ from /v1/prospects).
+ */
+export async function probeExploriumBusinessCount(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = (opts.apiBaseUrl ?? "https://api.explorium.ai").replace(/\/$/, "");
+    const response = await fetchImpl(`${base}/v1/businesses`, {
+        method: "POST",
+        headers: { "api_key": opts.apiKey, "Content-Type": "application/json" },
+        // page_size 1: we want the envelope's total_results, not the rows. CRITICAL:
+        // do NOT send `size` — Explorium caps total_results to `size` when present
+        // (verified: size:1 → total_results:1; omitted → the real count, e.g. 19,058).
+        body: JSON.stringify({ mode: "full", page_size: 1, page: 1, filters: opts.filters }),
+    });
+    if (!response.ok) {
+        throw new Error(`Explorium /v1/businesses count failed: HTTP ${response.status} ${await safeText(response)}`);
+    }
+    const body = (await response.json());
+    const total = body.total_results;
+    if (typeof total !== "number" || !Number.isFinite(total) || total < 0)
+        return null;
+    const rounded = Math.round(total);
+    return { total: rounded, capped: rounded >= EXPLORIUM_BUSINESS_COUNT_CAP };
+}
 function normalizeLinkedin(value) {
     if (!value)
         return undefined;

package/dist/connectors/salesforce.js

@@ -37,29 +37,53 @@ export function createSalesforceConnector(options) {
     // confirmed miss is created, and an ambiguous name (>1 match) is refused.
     // Caches within the run so the same name is never created twice — shared by
     // `link_record`'s create:<Name> path and `create_record`'s company linking.
-    async function resolveOrCreateAccountByName(name) {
-        const nameKey = name.toLowerCase();
-        const cached = createdAccountsByName.get(nameKey);
+    async function resolveOrCreateAccount(name, domain) {
+        const cacheKey = domain ? `d:${domain.toLowerCase()}` : `n:${name.toLowerCase()}`;
+        const cached = createdAccountsByName.get(cacheKey);
         if (cached)
             return { id: cached, createdNew: false };
-        const soqlName = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
-        const matches = await query(`SELECT Id FROM Account WHERE Name = '${soqlName}' LIMIT 3`);
-        if (matches.length > 1)
-            return { ambiguous: matches.length };
+        const esc = (v) => v.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        // 1. Domain-first match on Website (the accurate key; Website often stores a
+        //    full URL, so match by substring).
+        if (domain) {
+            const byDomain = await query(`SELECT Id FROM Account WHERE Website LIKE '%${esc(domain)}%' LIMIT 3`);
+            if (byDomain.length > 1)
+                return { ambiguous: byDomain.length };
+            if (byDomain.length === 1) {
+                const id = String(byDomain[0].Id);
+                createdAccountsByName.set(cacheKey, id);
+                return { id, createdNew: false };
+            }
+        }
+        // 2. Exact-name match; stamp Website if the account has none (fill-blank).
+        const byName = await query(`SELECT Id, Website FROM Account WHERE Name = '${esc(name)}' LIMIT 3`);
+        if (byName.length > 1)
+            return { ambiguous: byName.length };
         let id;
         let createdNew = false;
-        if (matches.length === 1) {
-            id = String(matches[0].Id);
+        if (byName.length === 1) {
+            id = String(byName[0].Id);
+            if (domain && !stringOrUndefined(byName[0].Website)) {
+                try {
+                    await request(`/services/data/${apiVersion}/sobjects/Account/${encodeURIComponent(id)}`, {
+                        method: "PATCH",
+                        body: JSON.stringify({ Website: domain }),
+                    });
+                }
+                catch {
+                    // best-effort fill — a failed Website stamp must not sink the create.
+                }
+            }
         }
         else {
             const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
                 method: "POST",
-                body: JSON.stringify({ Name: name }),
+                body: JSON.stringify({ Name: name, ...(domain ? { Website: domain } : {}) }),
             });
             id = String(created.id);
             createdNew = true;
         }
-        createdAccountsByName.set(nameKey, id);
+        createdAccountsByName.set(cacheKey, id);
         return { id, createdNew };
     }
     async function request(path, init = {}) {
@@ -427,7 +451,7 @@ export function createSalesforceConnector(options) {
             return { operationId: operation.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." };
         }
         if (operation.objectType === "account") {
-            const resolved = await resolveOrCreateAccountByName(matchValue);
+            const resolved = await resolveOrCreateAccount(matchValue);
             if ("ambiguous" in resolved) {
                 return { operationId: operation.id, status: "skipped", detail: `create_record: ambiguous — ${resolved.ambiguous} accounts named "${matchValue}". Not creating.` };
             }
@@ -465,7 +489,7 @@ export function createSalesforceConnector(options) {
         let companyNote = "";
         if (payload.associateCompanyName) {
             try {
-                const resolved = await resolveOrCreateAccountByName(payload.associateCompanyName);
+                const resolved = await resolveOrCreateAccount(payload.associateCompanyName, payload.associateCompanyDomain);
                 if ("ambiguous" in resolved) {
                     companyNote = ` Account "${payload.associateCompanyName}" was ambiguous; left unlinked.`;
                 }
@@ -474,7 +498,8 @@ export function createSalesforceConnector(options) {
                         method: "PATCH",
                         body: JSON.stringify({ AccountId: resolved.id }),
                     });
-                    companyNote = ` Linked to account "${payload.associateCompanyName}" (${resolved.id}).`;
+                    const domainNote = payload.associateCompanyDomain ? ` (${payload.associateCompanyDomain})` : "";
+                    companyNote = ` Linked to account "${payload.associateCompanyName}"${domainNote} (${resolved.id}).`;
                 }
             }
             catch (error) {
@@ -617,7 +642,7 @@ export function createSalesforceConnector(options) {
                         if (!name) {
                             return { operationId: operation.id, status: "skipped", detail: "create: needs an account name (create:<Name>)." };
                         }
-                        const resolved = await resolveOrCreateAccountByName(name);
+                        const resolved = await resolveOrCreateAccount(name);
                         if ("ambiguous" in resolved) {
                             return {
                                 operationId: operation.id,

package/dist/connectors/signalSources.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 type { SignalBucket, StagedSignalRow } 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[]>;
+};
+/**
+ * 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 declare const fileSource: SignalSourceConnector;
+/**
+ * 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 declare const serpapiNewsSource: SignalSourceConnector;
+/**
+ * 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 declare const hubspotFormsSource: SignalSourceConnector;
+/** All registered source connectors (stable order). */
+export declare function listSignalSources(): SignalSourceConnector[];
+/** Resolve a connector by id, or null when unknown. */
+export declare function getSignalSource(id: string): SignalSourceConnector | null;