fullstackgtm 0.43.0 → 0.45.0

package/dist/connector.d.ts

@@ -24,6 +24,21 @@ export type ApplyPatchPlanOptions = {
      * edited mid-apply is conflicted out instead of overwritten. Default 25.
      */
     recheckEvery?: number;
+    /**
+     * Per-operation progress as the run executes (presentation only — a
+     * throwing callback never affects the run). `completed` counts every
+     * resolved operation including skips and conflicts; `total` is the plan's
+     * full operation count.
+     */
+    onOperation?: (progress: ApplyProgress) => void;
+};
+export type ApplyProgress = {
+    completed: number;
+    total: number;
+    applied: number;
+    failed: number;
+    conflicts: number;
+    skipped: number;
 };
 /**
  * Apply an approved subset of a patch plan through a connector.

package/dist/connector.js

@@ -253,7 +253,41 @@ export async function applyPatchPlan(connector, plan, options) {
                 batched.set(result.operationId, result);
         }
     }
+    // Progress ticker state: every loop iteration below pushes at most one
+    // result; `lastNotified` guards the rare early-throw path so an iteration
+    // that pushed nothing reports nothing.
+    const progressCounts = { applied: 0, failed: 0, conflicts: 0, skipped: 0 };
+    const resultsBefore = results.length;
+    let lastNotified = results.length;
+    const notifyProgress = () => {
+        if (!options.onOperation || results.length === lastNotified)
+            return;
+        lastNotified = results.length;
+        const last = results[results.length - 1];
+        if (last.status === "applied")
+            progressCounts.applied += 1;
+        else if (last.status === "failed")
+            progressCounts.failed += 1;
+        else if (last.status === "conflict")
+            progressCounts.conflicts += 1;
+        else
+            progressCounts.skipped += 1;
+        try {
+            options.onOperation({
+                completed: results.length - resultsBefore,
+                total: plan.operations.length,
+                ...progressCounts,
+            });
+        }
+        catch {
+            // progress is presentation-only
+        }
+    };
     for (const operation of plan.operations) {
+        // Report the previous iteration's result (guarded: no-op if it pushed
+        // nothing). One-iteration lag keeps this a two-line hook instead of a
+        // notify after all ten push sites; the loop-exit call below flushes the last.
+        notifyProgress();
         const batchedResult = batched.get(operation.id);
         if (batchedResult) {
             results.push(batchedResult);
@@ -342,6 +376,7 @@ export async function applyPatchPlan(connector, plan, options) {
             });
         }
     }
+    notifyProgress();
     return {
         planId: plan.id,
         provider: connector.provider,

package/dist/connectors/hubspot.d.ts

@@ -1,5 +1,5 @@
 import { type FieldMappings } from "../mappings.ts";
-import type { GtmConnector } from "../types.ts";
+import type { GtmConnector, SnapshotProgress } from "../types.ts";
 export type HubspotConnectorOptions = {
     /** Returns a HubSpot access token (private app token or OAuth access token). */
     getAccessToken: () => string | Promise<string>;
@@ -8,6 +8,8 @@ export type HubspotConnectorOptions = {
     apiBaseUrl?: string;
     /** Injectable fetch for testing. */
     fetchImpl?: typeof fetch;
+    /** Per-page snapshot-pull progress (presentation only — errors are swallowed). */
+    onProgress?: (progress: SnapshotProgress) => void;
 };
 /**
  * Reference connector for HubSpot.

package/dist/connectors/hubspot.js

@@ -89,7 +89,7 @@ export function createHubspotConnector(options) {
         }
         return map;
     }
-    async function list(path) {
+    async function list(path, onPage) {
         const results = [];
         let after;
         const seen = new Set();
@@ -104,12 +104,18 @@ export function createHubspotConnector(options) {
             const separator = path.includes("?") ? "&" : "?";
             const data = await request(`${path}${after ? `${separator}after=${encodeURIComponent(after)}` : ""}`);
             results.push(...(data.results ?? []));
+            try {
+                onPage?.(results.length);
+            }
+            catch {
+                // progress is presentation-only; never let it fail a pull
+            }
             after = data.paging?.next?.after;
         } while (after);
         return results;
     }
     async function assembleSnapshot(fetchObjects) {
-        const owners = await list("/crm/v3/owners?limit=100");
+        const owners = await list("/crm/v3/owners?limit=100", (fetched) => options.onProgress?.({ objectType: "user", fetched }));
         const users = owners
             .filter((owner) => owner.id)
             .map((owner) => ({
@@ -235,7 +241,8 @@ export function createHubspotConnector(options) {
         };
     }
     async function fetchSnapshot() {
-        return assembleSnapshot((objectType, properties, withAssociations) => list(`/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`));
+        const canonicalType = { companies: "account", contacts: "contact", deals: "deal" };
+        return assembleSnapshot((objectType, properties, withAssociations) => list(`/crm/v3/objects/${objectType}?limit=100&properties=${properties}${withAssociations ? "&associations=companies" : ""}`, (fetched) => options.onProgress?.({ objectType: canonicalType[objectType], fetched })));
     }
     const MODIFIED_DATE_PROPERTIES = {
         companies: "hs_lastmodifieddate",

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.d.ts

@@ -1,5 +1,5 @@
 import { type FieldMappings } from "../mappings.ts";
-import type { GtmConnector } from "../types.ts";
+import type { GtmConnector, SnapshotProgress } from "../types.ts";
 export type SalesforceConnection = {
     accessToken: string;
     /** e.g. https://yourorg.my.salesforce.com */
@@ -13,6 +13,8 @@ export type SalesforceConnectorOptions = {
     apiVersion?: string;
     /** Injectable fetch for testing. */
     fetchImpl?: typeof fetch;
+    /** Per-page snapshot-pull progress (presentation only — errors are swallowed). */
+    onProgress?: (progress: SnapshotProgress) => void;
 };
 /**
  * Reference connector for Salesforce.

package/dist/connectors/salesforce.js

@@ -116,7 +116,7 @@ export function createSalesforceConnector(options) {
         const text = await response.text();
         return text ? JSON.parse(text) : null;
     }
-    async function query(soql) {
+    async function query(soql, onPage) {
         const records = [];
         let next = `/services/data/${apiVersion}/query?q=${encodeURIComponent(soql)}`;
         const seen = new Set();
@@ -127,6 +127,12 @@ export function createSalesforceConnector(options) {
             seen.add(next);
             const data = await request(next);
             records.push(...(data?.records ?? []));
+            try {
+                onPage?.(records.length);
+            }
+            catch {
+                // progress is presentation-only; never let it fail a pull
+            }
             next = data?.nextRecordsUrl ?? undefined;
         }
         return records;
@@ -138,7 +144,8 @@ export function createSalesforceConnector(options) {
         return mappedFields(mappings, objectType, SALESFORCE_DEFAULT_FIELD_MAPPINGS[objectType]).join(", ");
     }
     async function assembleSnapshot(whereClause) {
-        const sfUsers = await query(`SELECT ${selectFields("owners")} FROM User${whereClause}`);
+        const progressFor = (objectType) => (fetched) => options.onProgress?.({ objectType, fetched });
+        const sfUsers = await query(`SELECT ${selectFields("owners")} FROM User${whereClause}`, progressFor("user"));
         const users = sfUsers.map((user) => {
             const id = String(readMapped(user, "owners", "id", "Id"));
             const email = stringOrUndefined(readMapped(user, "owners", "email", "Email"));
@@ -153,7 +160,7 @@ export function createSalesforceConnector(options) {
                 active: Boolean(readMapped(user, "owners", "isActive", "IsActive")),
             };
         });
-        const sfAccounts = await query(`SELECT ${selectFields("accounts")} FROM Account${whereClause}`);
+        const sfAccounts = await query(`SELECT ${selectFields("accounts")} FROM Account${whereClause}`, progressFor("account"));
         const accounts = sfAccounts.map((account) => {
             const id = String(readMapped(account, "accounts", "id", "Id"));
             return {
@@ -170,7 +177,7 @@ export function createSalesforceConnector(options) {
                 raw: account,
             };
         });
-        const sfContacts = await query(`SELECT ${selectFields("contacts")} FROM Contact${whereClause}`);
+        const sfContacts = await query(`SELECT ${selectFields("contacts")} FROM Contact${whereClause}`, progressFor("contact"));
         const contacts = sfContacts.map((contact) => {
             const id = String(readMapped(contact, "contacts", "id", "Id"));
             return {
@@ -188,7 +195,7 @@ export function createSalesforceConnector(options) {
                 raw: contact,
             };
         });
-        const sfOpportunities = await query(`SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`);
+        const sfOpportunities = await query(`SELECT ${selectFields("deals")} FROM Opportunity${whereClause}`, progressFor("deal"));
         const deals = sfOpportunities.map((opportunity) => {
             const id = String(readMapped(opportunity, "deals", "id", "Id"));
             const probability = numberOrUndefined(readMapped(opportunity, "deals", "probability", "Probability"));

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;