fullstackgtm 0.43.0 → 0.44.0

package/src/connectors/theirstack.ts

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

package/src/icp.ts

@@ -24,6 +24,10 @@ export type Icp = {
     employeeBands?: string[];
     /** ISO country codes, lowercased, e.g. ["us"] */
     geos?: string[];
+    /** technographic targeting: technology slugs the account must use, e.g.
+     *  ["salesforce","hubspot","pipedrive"] — the real CRM/MAP buying signal,
+     *  consumed by TheirStack company search. OR-matched. */
+    technologies?: string[];
   };
   persona: {
     /** seniority: "cxo","vp","director","manager","owner","senior" */
@@ -79,6 +83,81 @@ export function icpToExploriumFilters(icp: Icp): Record<string, { values?: strin
   return f;
 }
 
+/**
+ * Explorium /v1/businesses filters from the ICP — the COMPANY (account) side, for
+ * sizing the account universe (TAM). Firmographics only, no persona: the count is
+ * of matching companies. Field names differ from /v1/prospects (verified live):
+ * `country_code` (not company_country_code), `company_size` (same employee bands),
+ * `naics_category`. `/v1/businesses` total_results is a real count, capped at
+ * 60,000 (see EXPLORIUM_BUSINESS_COUNT_CAP in the connector).
+ */
+export function icpToExploriumBusinessFilters(icp: Icp): Record<string, { values?: string[] }> {
+  const f: Record<string, { values?: string[] }> = {};
+  if (icp.firmographics.geos?.length) f.country_code = { values: icp.firmographics.geos };
+  if (icp.firmographics.employeeBands?.length) f.company_size = { values: icp.firmographics.employeeBands };
+  if (icp.firmographics.naics?.length) f.naics_category = { values: icp.firmographics.naics };
+  return f;
+}
+
+/**
+ * Collapse provider-agnostic employee bands ("51-200","10001+") into a single
+ * {min,max} envelope for APIs that take integer bounds (TheirStack). An open
+ * top band ("10001+") leaves max undefined.
+ */
+export function employeeBandsToRange(bands: string[] | undefined): { min?: number; max?: number } {
+  if (!bands?.length) return {};
+  let min: number | undefined;
+  let max: number | undefined;
+  let openTop = false;
+  for (const band of bands) {
+    const plus = /^(\d+)\+$/.exec(band.trim());
+    if (plus) {
+      const lo = Number(plus[1]);
+      if (min === undefined || lo < min) min = lo;
+      openTop = true;
+      continue;
+    }
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(band.trim());
+    if (range) {
+      const lo = Number(range[1]);
+      const hi = Number(range[2]);
+      if (min === undefined || lo < min) min = lo;
+      if (max === undefined || hi > max) max = hi;
+    }
+  }
+  return { min, max: openTop ? undefined : max };
+}
+
+/**
+ * TheirStack company-search filter from the ICP: the technographic targeting that
+ * Explorium can't do. `company_technology_slug_or` is the CRM/MAP buying signal
+ * (firmographics.technologies); employee bands become min/max bounds; geos become
+ * ISO2 codes (uppercased).
+ */
+export function icpToTheirStackFilters(icp: Icp): {
+  company_technology_slug_or?: string[];
+  min_employee_count?: number;
+  max_employee_count?: number;
+  company_country_code_or?: string[];
+} {
+  const f: {
+    company_technology_slug_or?: string[];
+    min_employee_count?: number;
+    max_employee_count?: number;
+    company_country_code_or?: string[];
+  } = {};
+  if (icp.firmographics.technologies?.length) {
+    f.company_technology_slug_or = icp.firmographics.technologies.map((t) => t.trim().toLowerCase());
+  }
+  if (icp.firmographics.geos?.length) {
+    f.company_country_code_or = icp.firmographics.geos.map((g) => g.trim().toUpperCase());
+  }
+  const range = employeeBandsToRange(icp.firmographics.employeeBands);
+  if (range.min !== undefined) f.min_employee_count = range.min;
+  if (range.max !== undefined) f.max_employee_count = range.max;
+  return f;
+}
+
 /**
  * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
  * Crustdata expects these exact capitalized strings (verified: "CXO",
@@ -101,16 +180,31 @@ const CRUSTDATA_SENIORITY: Record<string, string> = {
 };
 
 /**
- * ICP industry keyword → LinkedIn industry names Crustdata filters on. Includes
- * the current LinkedIn-v2 names; for software we send the cluster (dev + IT
- * services + internet) so an OR match isn't overly narrow.
+ * ICP industry keyword → LinkedIn industry names Crustdata filters on.
+ *
+ * LinkedIn renamed its industry taxonomy (v1 → v2, ~2022), and data vendors
+ * normalize to one generation or the other. Sending ONLY the v2 names risks a
+ * zero-match when Crustdata stores v1 (and vice-versa) — observed live: a RevOps
+ * ICP whose only firmographic constraint was the v2 names returned 0 even though
+ * the title-only search returned plenty. So each cluster sends BOTH generations
+ * (OR-matched within the field): v2 ("Software Development", "IT Services and IT
+ * Consulting", "Technology, Information and Internet") AND v1 ("Computer
+ * Software", "Information Technology & Services", "Internet").
  */
 const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
-  software: ["Software Development", "Information Technology and Services", "Internet"],
-  saas: ["Software Development", "Information Technology and Services"],
-  "information technology & services": ["Information Technology and Services"],
-  "information technology and services": ["Information Technology and Services"],
-  internet: ["Internet"],
+  software: [
+    "Software Development",
+    "Computer Software",
+    "IT Services and IT Consulting",
+    "Information Technology & Services",
+    "Information Technology and Services",
+    "Technology, Information and Internet",
+    "Internet",
+  ],
+  saas: ["Software Development", "Computer Software", "IT Services and IT Consulting", "Information Technology & Services"],
+  "information technology & services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  "information technology and services": ["Information Technology & Services", "IT Services and IT Consulting"],
+  internet: ["Internet", "Technology, Information and Internet"],
   fintech: ["Financial Services"],
   "financial services": ["Financial Services"],
 };
@@ -119,9 +213,17 @@ const CRUSTDATA_INDUSTRY: Record<string, string[]> = {
  * pipe0 Crustdata people-search config.filters from the ICP. `current_job_titles`
  * matches real LinkedIn title strings (case-sensitive), so keywords are Title
  * Cased. Seniority + industry are mapped to Crustdata's controlled vocab via the
- * tables above. NOTE: the exact pipe0→Crustdata value set could not be re-run
- * live (pipe0 credits were exhausted) — validate when credits refill; fit
- * scoring is the safety net for persona precision regardless.
+ * tables above.
+ *
+ * LIVE FINDINGS (2026-06-26): `current_job_titles` is confirmed working (a
+ * titles-only RevOps search returns results); `current_title` is rejected (422).
+ * The full ICP filter returned 0 — the prime suspect is the industry vocab
+ * (LinkedIn v1/v2 taxonomy mismatch), now hedged by sending BOTH generations in
+ * CRUSTDATA_INDUSTRY above. NOT yet re-confirmed end-to-end (pipe0 credits were
+ * exhausted mid-investigation) — re-run `enrich acquire --source pipe0` once
+ * credits refill; if it still returns 0, the next suspects are the
+ * `current_seniority_levels` shape/values and `locations`. Note fit-scoring backs
+ * up PERSONA precision but NOT industry, so the industry filter is load-bearing.
  */
 export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
   const f: Record<string, unknown> = {};

package/src/index.ts

@@ -107,6 +107,38 @@ export {
   type ScaffoldFile,
   type ScaffoldOptions,
 } from "./init.ts";
+export {
+  appendCoverage,
+  classifyAccount,
+  classifyCoverage,
+  computeCoverage,
+  coverageCountsFromSnapshot,
+  coveredAccounts,
+  coverageToText,
+  crmCheckableCriteria,
+  deriveAcvFromClosedWon,
+  deriveBuyersPerAccount,
+  estimateTam,
+  loadTamModel,
+  projectEta,
+  readCoverageTimeline,
+  saveTamModel,
+  tamDir,
+  tamReportToMarkdown,
+  type AccountTamClass,
+  type AcvBasis,
+  type DerivedAcv,
+  type DerivedBuyers,
+  type EstimateTamInput,
+  type TamClassified,
+  type TamCoverage,
+  type TamCoverageCounts,
+  type TamCrossCheck,
+  type TamEta,
+  type TamModel,
+  type TamTargeting,
+  type TamUniverse,
+} from "./tam.ts";
 export {
   apolloPullKeysForAppend,
   apolloPullKeysForRefresh,

package/src/init.ts

@@ -45,6 +45,9 @@ export function starterIcp(): Icp {
       industries: ["software", "saas"],
       employeeBands: ["51-200", "201-500", "501-1000"],
       geos: ["us"],
+      // Technographic targeting (the real RevOps signal): companies that USE a
+      // CRM/MAP. Drives `tam estimate|accounts --source theirstack`.
+      technologies: ["salesforce", "hubspot", "pipedrive"],
     },
     persona: {
       jobLevels: ["vp", "director", "manager"],

package/src/judgeEval.ts

@@ -205,7 +205,14 @@ export function defaultJudgeFn(opts: { config?: SignalsConfig; icp?: Icp; now?:
 // ---------------------------------------------------------------------------
 // The default golden set (ships inline so `icp eval --golden default` is free)
 
-const GOLD_NOW_ISO = "2026-06-23T12:00:00.000Z";
+/**
+ * The default golden set's clock. Every `firstSeen` below is relative to this
+ * instant, so grading MUST pin `now: new Date(DEFAULT_GOLDEN_NOW_ISO)` —
+ * grading against wall time lets freshness decay rot the "fresh → send" rows,
+ * and the gate starts failing on a calendar date instead of a code change.
+ */
+export const DEFAULT_GOLDEN_NOW_ISO = "2026-06-23T12:00:00.000Z";
+const GOLD_NOW_ISO = DEFAULT_GOLDEN_NOW_ISO;
 
 function goldSignal(over: {
   accountDomain: string;

package/src/runReport.ts

@@ -11,7 +11,34 @@ import { getCredential } from "./credentials.ts";
 
 type RunEvent = { ts: number; type: string; detail?: string };
 
+/**
+ * Per-row finding for the hosted run timeline. IDs + issue type ONLY — no field
+ * values ever leave the CLI, keeping the audit's row data on the operator's side
+ * while still giving the dashboard navigable, filterable detail.
+ */
+export type RunFinding = {
+  objectType: string;
+  objectId: string;
+  severity: string;
+  ruleId: string;
+  field?: string;
+  operation?: string;
+};
+
+/**
+ * Where a run's findings live in the source CRM, so the dashboard can deep-link
+ * each record. `recordUrlBase` is the provider's record URL prefix; the
+ * dashboard appends the per-object path. Just an URL prefix — no record data.
+ */
+export type RunCrm = { provider: string; recordUrlBase: string };
+
+// Bound the fire-and-forget POST: a pathological audit could surface thousands
+// of findings; cap what we ship (counts still carry the true total).
+const MAX_REPORTED_FINDINGS = 2000;
+
 let counts: Record<string, unknown> | undefined;
+let findings: RunFinding[] | undefined;
+let crm: RunCrm | undefined;
 const events: RunEvent[] = [];
 
 /** A command annotates its headline metrics (merged). */
@@ -19,6 +46,16 @@ export function reportCounts(values: Record<string, unknown>): void {
   counts = { ...(counts ?? {}), ...values };
 }
 
+/** A command reports per-row findings (IDs + issue type, no values). */
+export function reportFindings(values: RunFinding[]): void {
+  findings = values.slice(0, MAX_REPORTED_FINDINGS);
+}
+
+/** A command reports the source CRM's record-URL base for dashboard deep-links. */
+export function reportCrm(value: RunCrm): void {
+  crm = value;
+}
+
 /** A command annotates a structured event (plan saved, meter charged, …). */
 export function reportEvent(type: string, detail?: string): void {
   events.push({ ts: Date.now(), type, detail });
@@ -65,6 +102,8 @@ export async function flushRunReport(
         finishedAt,
         durationMs: finishedAt - startedAt,
         counts,
+        findings: findings?.length ? findings : undefined,
+        crm,
         events: events.length ? events : undefined,
         error,
       }),

package/src/schedule.ts

@@ -84,7 +84,13 @@ const SCHEDULABLE: Record<string, string[] | null> = {
   suggest: null,
   report: null,
   doctor: null,
-  enrich: ["append", "refresh"],
+  // `enrich append|refresh` fill blanks; `enrich acquire` creates net-new
+  // leads — but ONLY as a needs_approval `create_record` plan (`--save`,
+  // required below), never a write. This is what lets `tam populate` chip away
+  // at a TAM unattended: each firing queues a fresh lead plan, the meter is
+  // charged only at apply, and apply stays `apply --plan-id` (re-checked
+  // approved). So scheduled acquire accumulates proposals, never surprise leads.
+  enrich: ["append", "refresh", "acquire"],
   market: ["capture", "refresh"],
   // The GTM brain. `signals fetch` is read-only re: CRM (--save persists only
   // the local signal ledger). `icp judge`/`icp eval` are read-only/grade-only
@@ -98,9 +104,9 @@ const SCHEDULABLE: Record<string, string[] | null> = {
 };
 
 const ALLOWLIST_SUMMARY =
-  "audit, snapshot, enrich append|refresh, market capture|refresh, signals fetch, " +
-  "icp judge|eval, draft (stages a plan), suggest, report, doctor — " +
-  "plus apply --plan-id <id> (re-checked approved at every firing)";
+  "audit, snapshot, enrich append|refresh, enrich acquire --save (stages a lead plan), " +
+  "market capture|refresh, signals fetch, icp judge|eval, draft (stages a plan), " +
+  "suggest, report, doctor — plus apply --plan-id <id> (re-checked approved at every firing)";
 
 /**
  * Validate that an argv resolves to a schedulable fullstackgtm command.
@@ -158,6 +164,16 @@ export function validateSchedulableArgv(argv: string[]): void {
           .join(", ")}.`,
       );
     }
+    // `enrich acquire` is schedulable ONLY in its plan-producing form: without
+    // --save it's a dry-run that writes nothing AND queues nothing, so an
+    // unattended firing would silently no-op. Require --save so a scheduled
+    // acquire always leaves a needs_approval plan behind (apply stays gated).
+    if (head === "enrich" && sub === "acquire" && !argv.includes("--save")) {
+      throw new Error(
+        "Scheduled `enrich acquire` must include --save so each firing queues a needs_approval lead plan " +
+          "(without it the run produces nothing). Apply stays a separate human gate (`apply --plan-id <id>`).",
+      );
+    }
   }
 }
 

package/src/signals.ts

@@ -416,6 +416,71 @@ function withinWindow(iso: string, now: Date, windowDays: number): boolean {
   return now.getTime() - t <= windowDays * DAY_MS;
 }
 
+// ---------------------------------------------------------------------------
+// Staged rows -> signals (shared by `--from` ingest and source connectors)
+
+/**
+ * One staged signal row: the platform-agnostic intake shape every NON-job source
+ * produces (a source connector's output, or a `--from` JSON row). It carries the
+ * evidence anchor (`quote`) but none of the derived fields (`id`, `weight`,
+ * `source`) — `stagedRowToSignal` fills those so there is ONE place that gates
+ * evidence and stamps identity, whether the row came from a file or an API.
+ */
+export type StagedSignalRow = {
+  bucket: SignalBucket;
+  accountDomain: string;
+  trigger: string;
+  /** VERBATIM evidence — required, non-empty. */
+  quote: string;
+  sourceUrl?: string;
+  /** ISO 8601; defaults to run time when absent. */
+  firstSeen?: string;
+  /** Optional explicit weight; defaults to the bucket's configured weight. */
+  weight?: number;
+};
+
+/**
+ * Validate one loosely-typed staged row and turn it into a `Signal`, applying
+ * the verbatim-evidence gate (a row with no quote is rejected, never faked) and
+ * the same id/normalization logic the ATS path uses. `errorLabel` lets the
+ * caller produce a precise message ("--from f.json: row 3", "serpapi-news row 0")
+ * since both the `--from` ingest and the source-connector registry funnel here.
+ *
+ * Throws on a malformed row; returns the canonical `Signal` on success. Bucket
+ * FILTERING (skip rows outside a `--bucket` selection) stays with the caller —
+ * this function is per-row validation only.
+ */
+export function stagedRowToSignal(
+  entry: Record<string, unknown>,
+  opts: { now: Date; source: string; errorLabel: string },
+): Signal {
+  const { now, source, errorLabel } = opts;
+  const bucket = String(entry.bucket ?? "");
+  if (!SIGNAL_BUCKETS.includes(bucket as SignalBucket)) {
+    throw new Error(`${errorLabel} has unknown bucket "${bucket}" (one of ${SIGNAL_BUCKETS.join(", ")}).`);
+  }
+  const accountDomain = normalizeAccountDomain(String(entry.accountDomain ?? entry.domain ?? ""));
+  if (!accountDomain) throw new Error(`${errorLabel} is missing accountDomain.`);
+  const trigger = String(entry.trigger ?? "").trim();
+  if (!trigger) throw new Error(`${errorLabel} is missing trigger.`);
+  const quote = String(entry.quote ?? "").trim();
+  if (!quote) throw new Error(`${errorLabel} is missing the verbatim quote (the evidence anchor).`);
+  const base = { accountDomain, bucket: bucket as SignalBucket, trigger };
+  const firstSeen = typeof entry.firstSeen === "string" && entry.firstSeen ? entry.firstSeen : now.toISOString();
+  return {
+    id: signalId(base),
+    accountDomain,
+    bucket: bucket as SignalBucket,
+    trigger,
+    quote,
+    sourceUrl: String(entry.sourceUrl ?? ""),
+    firstSeen,
+    weight: typeof entry.weight === "number" ? entry.weight : DEFAULT_SIGNALS_CONFIG.buckets[bucket as SignalBucket].weight,
+    source,
+    judgedBy: null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Dedup
 
@@ -533,6 +598,31 @@ export function signalsDir(baseDir?: string): string {
   return join(baseDir ?? credentialsDir(), "signals");
 }
 
+/**
+ * Conventional webhook landing zone: `<signals>/spool`, profile-scoped. A
+ * webhook receiver (hosted, or the operator's own glue) appends one JSONL row
+ * per event to a `*.jsonl` file here; `signals fetch --connector file` reads the
+ * whole directory when given no explicit path. The CLI never writes here — the
+ * receiver does — so this is just the agreed-upon location, not a managed store.
+ * Per-source files (`rb2b.jsonl`, `hubspot.jsonl`, …) coexist. See
+ * docs/signal-spool-format.md.
+ */
+export function signalsSpoolDir(baseDir?: string): string {
+  return join(signalsDir(baseDir), "spool");
+}
+
+/**
+ * Conventional outbox: `<signals>/outbox`, profile-scoped — the SEND-side mirror
+ * of the spool. `apply --channel outbox` renders each APPROVED drafted opener to
+ * a `<channel>.jsonl` file here (one row per touch); a downstream sender (hosted,
+ * or the operator's own) drains it. The CLI WRITES governed, approved send
+ * intents here but TRANSMITS NOTHING — the "drafts everything, transmits nothing"
+ * invariant holds. See docs/outbox-format.md.
+ */
+export function signalsOutboxDir(baseDir?: string): string {
+  return join(signalsDir(baseDir), "outbox");
+}
+
 export type SignalRun = {
   id: string;
   runLabel: string;