fullstackgtm 0.34.0 → 0.38.0

package/src/health.ts

@@ -0,0 +1,238 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { activeProfile, credentialsDir, ensureSecureHomeDir, writeSecureFile } from "./credentials.ts";
+import type { AuditFindingSeverity, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+
+/**
+ * The engagement workspace: a per-client health timeline that accrues from the
+ * verb people already run (`audit --save`). State lives in the profile dir
+ * (`$FSGTM_HOME[/profiles/<name>]`) alongside credentials and plans, so a
+ * consultant working `--profile <client>` builds a continuous record of one
+ * org's CRM health over time — not just episodic one-off audits.
+ *
+ * The score is DETERMINISTIC (no LLM): same plan + same snapshot → same score,
+ * so it is stable in CI and comparable run-over-run.
+ */
+
+// Severity weights: a critical finding costs ~3× a warning, ~10× an info.
+const SEVERITY_WEIGHT: Record<AuditFindingSeverity, number> = { info: 1, warning: 3, critical: 10 };
+
+export type HealthEntry = {
+  /** ISO timestamp of the audit that produced this entry. */
+  at: string;
+  /** The saved plan this entry summarizes (correlates to plans/ and snapshots/). */
+  planId: string;
+  /** Deterministic 0–100 hygiene score (higher is healthier). */
+  score: number;
+  /** Total finding count across all rules. */
+  findings: number;
+  /** Severity-weighted finding total (drives the score). */
+  weightedFindings: number;
+  /** Record counts at audit time — the denominator that normalizes the score. */
+  records: { accounts: number; contacts: number; deals: number; total: number };
+  /** Finding count per rule id. */
+  byRule: Record<string, number>;
+  /** Finding count per severity. */
+  severityCounts: Record<AuditFindingSeverity, number>;
+};
+
+export type HealthRuleDelta = {
+  ruleId: string;
+  current: number;
+  previous: number;
+  /** current − previous: positive = more findings (worse), negative = fewer (better). */
+  delta: number;
+};
+
+export type HealthRollup = {
+  profile: string;
+  auditCount: number;
+  first: string;
+  latest: string;
+  current: HealthEntry;
+  previous: HealthEntry | null;
+  /** current.score − previous.score: positive = improving. null on the first audit. */
+  scoreDelta: number | null;
+  ruleDeltas: HealthRuleDelta[];
+  history: Array<{ at: string; score: number; findings: number }>;
+};
+
+/**
+ * Deterministically score a saved audit. score = 100 / (1 + weighted findings
+ * per record): 0 findings → 100; one weighted finding per record → 50; the
+ * curve is bounded (0, 100], monotonic, and needs no clamping or magic
+ * constants. A messy 50-record CRM scores worse than the same finding count
+ * across 5,000 records, which is the point.
+ */
+export function computeHealth(plan: PatchPlan, snapshot: CanonicalGtmSnapshot, at: string): HealthEntry {
+  const byRule: Record<string, number> = {};
+  const severityCounts: Record<AuditFindingSeverity, number> = { info: 0, warning: 0, critical: 0 };
+  let weightedFindings = 0;
+  for (const finding of plan.findings) {
+    byRule[finding.ruleId] = (byRule[finding.ruleId] ?? 0) + 1;
+    severityCounts[finding.severity] += 1;
+    weightedFindings += SEVERITY_WEIGHT[finding.severity];
+  }
+
+  const records = {
+    accounts: snapshot.accounts.length,
+    contacts: snapshot.contacts.length,
+    deals: snapshot.deals.length,
+    total: snapshot.accounts.length + snapshot.contacts.length + snapshot.deals.length,
+  };
+
+  const penalty = weightedFindings / Math.max(records.total, 1);
+  const score = Math.round(100 / (1 + penalty));
+
+  return {
+    at,
+    planId: plan.id,
+    score,
+    findings: plan.findings.length,
+    weightedFindings,
+    records,
+    byRule,
+    severityCounts,
+  };
+}
+
+/** Roll a timeline up into the current state, the change since last time, and per-rule deltas. */
+export function summarizeHealth(entries: HealthEntry[], profile: string): HealthRollup | null {
+  if (entries.length === 0) return null;
+  // Oldest → newest, so `current` is the last entry.
+  const sorted = [...entries].sort((a, b) => a.at.localeCompare(b.at));
+  const current = sorted[sorted.length - 1];
+  const previous = sorted.length > 1 ? sorted[sorted.length - 2] : null;
+
+  const ruleIds = new Set<string>([
+    ...Object.keys(current.byRule),
+    ...(previous ? Object.keys(previous.byRule) : []),
+  ]);
+  const ruleDeltas: HealthRuleDelta[] = [...ruleIds]
+    .map((ruleId) => {
+      const cur = current.byRule[ruleId] ?? 0;
+      const prev = previous?.byRule[ruleId] ?? 0;
+      return { ruleId, current: cur, previous: prev, delta: cur - prev };
+    })
+    .sort((a, b) => b.current - a.current || a.ruleId.localeCompare(b.ruleId));
+
+  return {
+    profile,
+    auditCount: sorted.length,
+    first: sorted[0].at,
+    latest: current.at,
+    current,
+    previous,
+    scoreDelta: previous ? current.score - previous.score : null,
+    ruleDeltas,
+    history: sorted.map((entry) => ({ at: entry.at, score: entry.score, findings: entry.findings })),
+  };
+}
+
+// Sign-based and uniform: ▲ = the number went up, ▼ = down. The reader supplies
+// the meaning (score up = good; findings up = bad) — mixing arrow direction with
+// good/bad reads as contradictory ("▲ -3").
+function arrow(delta: number): string {
+  if (delta === 0) return "·";
+  return delta > 0 ? "▲" : "▼";
+}
+
+/** Human-readable rollup: headline score + trend, then per-rule change since last audit. */
+export function healthToMarkdown(rollup: HealthRollup): string {
+  const { current, scoreDelta } = rollup;
+  const lines = [`# GTM health — profile \`${rollup.profile}\``, ""];
+
+  const deltaText =
+    scoreDelta === null
+      ? "(first audit — no prior reading)"
+      : `${arrow(scoreDelta)} ${scoreDelta >= 0 ? "+" : ""}${scoreDelta} since the previous audit`;
+  lines.push(
+    `Score: **${current.score}/100** ${deltaText}`,
+    `Audits: ${rollup.auditCount} over ${shortDate(rollup.first)} → ${shortDate(rollup.latest)}`,
+    `Findings: ${current.findings} (${current.severityCounts.critical} critical, ${current.severityCounts.warning} warning, ${current.severityCounts.info} info)`,
+    `Records: ${current.records.accounts} accounts, ${current.records.contacts} contacts, ${current.records.deals} deals`,
+    "",
+  );
+
+  if (rollup.history.length > 1) {
+    lines.push("## Trend", "");
+    for (const point of rollup.history) {
+      const marker = point.at === rollup.latest ? "  ← latest" : "";
+      lines.push(`- ${shortDate(point.at)}  score ${point.score}  (${point.findings} findings)${marker}`);
+    }
+    lines.push("");
+  }
+
+  if (rollup.ruleDeltas.length > 0) {
+    lines.push("## By rule (Δ since previous audit)", "", "| Rule | Findings | Δ |", "| --- | --- | --- |");
+    for (const rule of rollup.ruleDeltas) {
+      const sign = rule.delta > 0 ? `+${rule.delta}` : `${rule.delta}`;
+      const cell = rule.delta === 0 ? "·" : `${arrow(rule.delta)} ${sign}`;
+      lines.push(`| ${rule.ruleId} | ${rule.current} | ${cell} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("> Score is deterministic: 100 / (1 + severity-weighted findings per record). Lower findings or more clean records ⇒ higher score.");
+  return `${lines.join("\n")}\n`;
+}
+
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+// ── Profile-scoped storage ──────────────────────────────────────────────────
+
+/** `$FSGTM_HOME[/profiles/<name>]/health.jsonl` — append-only, one entry per audit-save. */
+export function healthFilePath(): string {
+  return join(credentialsDir(), "health.jsonl");
+}
+
+/** `$FSGTM_HOME[/profiles/<name>]/snapshots/` — canonical snapshots correlated by plan id. */
+export function snapshotsDir(): string {
+  return join(credentialsDir(), "snapshots");
+}
+
+/** Append a health entry to the active profile's timeline (0600, owner-only). */
+export function appendHealthEntry(entry: HealthEntry): void {
+  ensureSecureHomeDir();
+  appendFileSync(healthFilePath(), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+}
+
+/** Read the active profile's health timeline; tolerant of partial/corrupt lines. */
+export function readHealthTimeline(): HealthEntry[] {
+  let raw: string;
+  try {
+    raw = readFileSync(healthFilePath(), "utf8");
+  } catch {
+    return [];
+  }
+  const entries: HealthEntry[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      entries.push(JSON.parse(trimmed) as HealthEntry);
+    } catch {
+      // Skip a torn line rather than failing the whole rollup.
+    }
+  }
+  return entries;
+}
+
+/** Persist the snapshot behind a saved audit so the timeline can diff/attribute later. */
+export function saveWorkspaceSnapshot(planId: string, snapshot: CanonicalGtmSnapshot): string {
+  if (!/^[\w.-]+$/.test(planId)) throw new Error(`Invalid plan id: ${planId}`);
+  ensureSecureHomeDir();
+  const dir = snapshotsDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = join(dir, `${planId}.json`);
+  writeSecureFile(path, `${JSON.stringify(snapshot)}\n`);
+  return path;
+}
+
+/** The active profile name, for rollup labeling. */
+export function activeWorkspaceProfile(): string {
+  return activeProfile();
+}

package/src/icp.ts

@@ -0,0 +1,313 @@
+/**
+ * ICP — the Ideal Customer Profile that makes `enrich acquire` targeted instead
+ * of random. One structured artifact drives two things:
+ *   1. discovery filters — translated per provider (Explorium, pipe0/Crustdata)
+ *      so the pull only returns ICP-shaped companies + people, and
+ *   2. fit scoring — every discovered prospect is scored against the persona so
+ *      only above-threshold leads become create_record ops.
+ *
+ * Develop one via interview: an agent (Claude Code / Codex) reads INTERVIEW_SPEC,
+ * asks the questions with its AskUserQuestion tool, and writes the answers into
+ * an Icp (CLI: `icp interview` emits the spec, `icp show` renders the result).
+ *
+ * Zero runtime deps; pure functions (translation + scoring take plain data).
+ */
+
+export type Icp = {
+  name: string;
+  firmographics: {
+    /** human industry labels, e.g. ["software","saas"] — used for keyword/industry filters */
+    industries?: string[];
+    /** Explorium naics_category codes, e.g. ["5112"] (software publishers) */
+    naics?: string[];
+    /** provider-agnostic employee bands: "1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+" */
+    employeeBands?: string[];
+    /** ISO country codes, lowercased, e.g. ["us"] */
+    geos?: string[];
+  };
+  persona: {
+    /** seniority: "cxo","vp","director","manager","owner","senior" */
+    jobLevels?: string[];
+    /** "sales","marketing","operations","finance" */
+    departments?: string[];
+    /** the title phrases that DEFINE the buyer — also the scoring signal */
+    titleKeywords?: string[];
+  };
+  signals?: { intentTopics?: string[] };
+  scoring?: {
+    /** minimum fit (0..1) for a prospect to become a create_record op. Default 0.5. */
+    threshold?: number;
+  };
+};
+
+export const DEFAULT_FIT_THRESHOLD = 0.5;
+
+const COUNTRY_NAMES: Record<string, string> = {
+  us: "United States",
+  ca: "Canada",
+  gb: "United Kingdom",
+  uk: "United Kingdom",
+};
+
+export function parseIcp(raw: string): Icp {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`icp: not valid JSON (${error instanceof Error ? error.message : String(error)})`);
+  }
+  if (!parsed || typeof parsed !== "object") throw new Error("icp: expected a JSON object");
+  const icp = parsed as Icp;
+  if (!icp.name || typeof icp.name !== "string") throw new Error('icp: missing "name"');
+  if (!icp.persona || (!icp.persona.titleKeywords?.length && !icp.persona.jobLevels?.length)) {
+    throw new Error('icp: "persona" needs at least titleKeywords or jobLevels (without them, scoring cannot rank fit)');
+  }
+  return icp;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery-filter translation
+
+/** Explorium /v1/prospects filters from the ICP. */
+export function icpToExploriumFilters(icp: Icp): Record<string, { values?: string[]; value?: boolean }> {
+  const f: Record<string, { values?: string[]; value?: boolean }> = { has_email: { value: true } };
+  if (icp.persona.jobLevels?.length) f.job_level = { values: icp.persona.jobLevels };
+  if (icp.persona.departments?.length) f.job_department = { values: icp.persona.departments };
+  if (icp.firmographics.employeeBands?.length) f.company_size = { values: icp.firmographics.employeeBands };
+  if (icp.firmographics.geos?.length) f.company_country_code = { values: icp.firmographics.geos };
+  if (icp.firmographics.naics?.length) f.naics_category = { values: icp.firmographics.naics };
+  return f;
+}
+
+/**
+ * Crustdata / LinkedIn seniority vocab. ICP job levels are normalized lowercase;
+ * Crustdata expects these exact capitalized strings (verified: "CXO",
+ * "Vice President", "Director" appear in Crustdata's docs/examples).
+ */
+const CRUSTDATA_SENIORITY: Record<string, string> = {
+  cxo: "CXO",
+  "c-suite": "CXO",
+  c_suite: "CXO",
+  founder: "Owner",
+  owner: "Owner",
+  partner: "Partner",
+  vp: "Vice President",
+  "vice president": "Vice President",
+  head: "Director",
+  director: "Director",
+  manager: "Manager",
+  senior: "Senior",
+  entry: "Entry",
+};
+
+/**
+ * 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.
+ */
+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"],
+  fintech: ["Financial Services"],
+  "financial services": ["Financial Services"],
+};
+
+/**
+ * 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.
+ */
+export function icpToCrustdataFilters(icp: Icp): Record<string, unknown> {
+  const f: Record<string, unknown> = {};
+  if (icp.persona.titleKeywords?.length) f.current_job_titles = icp.persona.titleKeywords.map(titleCase);
+  if (icp.firmographics.geos?.length) {
+    f.locations = icp.firmographics.geos.map((g) => COUNTRY_NAMES[g.toLowerCase()] ?? g);
+  }
+  if (icp.persona.jobLevels?.length) {
+    const include = [...new Set(icp.persona.jobLevels.map((l) => CRUSTDATA_SENIORITY[l.toLowerCase()]).filter(Boolean))];
+    if (include.length) f.current_seniority_levels = { include, exclude: [] };
+  }
+  if (icp.firmographics.industries?.length) {
+    const inds = [
+      ...new Set(icp.firmographics.industries.flatMap((i) => CRUSTDATA_INDUSTRY[i.toLowerCase()] ?? [titleCase(i)])),
+    ];
+    if (inds.length) f.current_employers_linkedin_industries = inds;
+  }
+  return f;
+}
+
+const ACRONYMS = new Set(["cro", "coo", "ceo", "cfo", "vp", "crm", "gtm", "saas"]);
+function titleCase(value: string): string {
+  return value
+    .split(/\s+/)
+    .map((w) => (ACRONYMS.has(w.toLowerCase()) ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(" ");
+}
+
+// ---------------------------------------------------------------------------
+// Fit scoring (persona precision; firmographics are enforced by the filter)
+
+export type IcpFit = { score: number; reasons: string[] };
+
+/**
+ * Score a prospect's PERSONA fit 0..1. Title-keyword match is the strongest
+ * signal (it's what defines the buyer); job level and department add to it.
+ * Firmographics aren't re-scored here — discovery already filtered on them.
+ */
+export function scoreProspectAgainstIcp(
+  prospect: { jobTitle?: string; jobLevel?: string; jobDepartment?: string },
+  icp: Icp,
+): IcpFit {
+  const reasons: string[] = [];
+  const title = (prospect.jobTitle ?? "").toLowerCase();
+  const keywords = (icp.persona.titleKeywords ?? []).map((k) => k.toLowerCase());
+  const levels = (icp.persona.jobLevels ?? []).map((l) => l.toLowerCase());
+  const depts = (icp.persona.departments ?? []).map((d) => d.toLowerCase());
+
+  let score = 0;
+  let weightSum = 0;
+
+  if (keywords.length) {
+    weightSum += 0.6;
+    const hit = keywords.find((k) => title.includes(k));
+    if (hit) {
+      score += 0.6;
+      reasons.push(`title matches ICP keyword "${hit}"`);
+    }
+  }
+  if (levels.length) {
+    weightSum += 0.25;
+    const level = (prospect.jobLevel ?? "").toLowerCase();
+    if (level && levels.some((l) => level.includes(l))) {
+      score += 0.25;
+      reasons.push(`seniority "${prospect.jobLevel}" in ICP levels`);
+    }
+  }
+  if (depts.length) {
+    weightSum += 0.15;
+    const dept = (prospect.jobDepartment ?? "").toLowerCase();
+    if (dept && depts.some((d) => dept.includes(d))) {
+      score += 0.15;
+      reasons.push(`department "${prospect.jobDepartment}" in ICP`);
+    }
+  }
+  const normalized = weightSum > 0 ? score / weightSum : 0;
+  if (reasons.length === 0) reasons.push("no persona signal matched the ICP");
+  return { score: Number(normalized.toFixed(3)), reasons };
+}
+
+export function fitThreshold(icp: Icp): number {
+  return icp.scoring?.threshold ?? DEFAULT_FIT_THRESHOLD;
+}
+
+// ---------------------------------------------------------------------------
+// Interview spec — an agent drives this with AskUserQuestion, then writes an Icp
+
+export type IcpInterviewQuestion = {
+  id: keyof FlatIcpAnswers;
+  header: string;
+  question: string;
+  multiSelect: boolean;
+  options: { label: string; value: string | string[]; description: string }[];
+};
+
+/** Flattened answer keys the interview collects (assembled into an Icp). */
+export type FlatIcpAnswers = {
+  industries: string[];
+  employeeBands: string[];
+  jobLevels: string[];
+  departments: string[];
+  titleKeywords: string[];
+  geos: string[];
+};
+
+export const INTERVIEW_SPEC: IcpInterviewQuestion[] = [
+  {
+    id: "industries",
+    header: "Target market",
+    question: "What company profile are you targeting? (Drives firmographic discovery filters.)",
+    multiSelect: true,
+    options: [
+      { label: "B2B SaaS / software", value: ["software", "saas"], description: "Software & internet — classic messy-CRM, RevOps-equipped buyer." },
+      { label: "Broader tech-enabled B2B", value: ["software", "information technology & services", "financial services"], description: "Any B2B running a real sales motion on a CRM." },
+      { label: "Any B2B with a CRM", value: [], description: "Vertical-agnostic — qualify on persona, not industry." },
+    ],
+  },
+  {
+    id: "employeeBands",
+    header: "Company size",
+    question: "Company size (employee bands) that fit?",
+    multiSelect: true,
+    options: [
+      { label: "Seed–Series A (1–50)", value: ["1-10", "11-50"], description: "Early; often no dedicated RevOps yet." },
+      { label: "Series B–C (51–500)", value: ["51-200", "201-500"], description: "Sweet spot: messy CRM, RevOps exists, budget exists." },
+      { label: "Growth (501–2000)", value: ["501-1000", "1001-5000"], description: "Established RevOps, many CRM writers." },
+      { label: "Enterprise (2000+)", value: ["1001-5000", "5001-10000", "10001+"], description: "Up-market; longer cycles." },
+    ],
+  },
+  {
+    id: "titleKeywords",
+    header: "Buyer persona",
+    question: "Which buyer persona(s) should discovery target and scoring reward?",
+    multiSelect: true,
+    options: [
+      { label: "RevOps leadership", value: ["revenue operations", "revops", "head of revenue operations"], description: "VP/Head/Dir Revenue Operations." },
+      { label: "Sales/Marketing Ops", value: ["sales operations", "gtm operations", "marketing operations", "revenue ops"], description: "Hands-on the CRM daily." },
+      { label: "Exec buyers", value: ["chief revenue officer", "cro", "chief operating officer", "vp of sales"], description: "Economic sign-off." },
+      { label: "CRM/SF admins", value: ["salesforce admin", "hubspot admin", "crm manager", "revops analyst"], description: "Feel the pain, champion the fix." },
+    ],
+  },
+  {
+    id: "geos",
+    header: "Geography",
+    question: "Geography?",
+    multiSelect: true,
+    options: [
+      { label: "United States", value: ["us"], description: "US-only (best data coverage)." },
+      { label: "US + Canada", value: ["us", "ca"], description: "North America." },
+      { label: "US + UK/EU", value: ["us", "gb"], description: "English-speaking + Western Europe (mind GDPR)." },
+      { label: "Global", value: [], description: "No geo filter." },
+    ],
+  },
+];
+
+/** Assemble an Icp from flattened interview answers. */
+export function icpFromAnswers(name: string, answers: FlatIcpAnswers): Icp {
+  const levelsFromTitles = inferLevels(answers.titleKeywords);
+  return {
+    name,
+    firmographics: {
+      industries: dedupe(answers.industries),
+      naics: answers.industries.some((i) => /software|saas/i.test(i)) ? ["5112"] : undefined,
+      employeeBands: dedupe(answers.employeeBands),
+      geos: dedupe(answers.geos),
+    },
+    persona: {
+      jobLevels: answers.jobLevels?.length ? dedupe(answers.jobLevels) : levelsFromTitles,
+      departments: answers.departments?.length ? dedupe(answers.departments) : ["sales", "marketing", "operations"],
+      titleKeywords: dedupe(answers.titleKeywords),
+    },
+    scoring: { threshold: DEFAULT_FIT_THRESHOLD },
+  };
+}
+
+function inferLevels(titles: string[]): string[] {
+  const levels = new Set<string>();
+  for (const t of titles.map((x) => x.toLowerCase())) {
+    if (/chief|^c[a-z]o$|cro|coo/.test(t)) levels.add("cxo");
+    if (/vp|vice president|head of/.test(t)) levels.add("vp");
+    if (/director/.test(t)) levels.add("director");
+    if (/manager|admin|analyst|operations/.test(t)) levels.add("manager");
+  }
+  return levels.size ? [...levels] : ["cxo", "vp", "director", "manager"];
+}
+
+function dedupe(values: string[] | undefined): string[] {
+  return [...new Set((values ?? []).filter(Boolean))];
+}

package/src/index.ts

@@ -1,4 +1,14 @@
 export { auditSnapshot, defaultPolicy } from "./audit.ts";
+export {
+  matchesTerritory,
+  parseAssignmentPolicy,
+  resolveAssignment,
+  type AssignmentContext,
+  type AssignmentPolicy,
+  type AssignmentResult,
+  type AssignmentStrategy,
+  type TerritoryRule,
+} from "./assign.ts";
 export { buildBulkUpdatePlan, isFilterableField, parseWhere, type BulkUpdateOptions } from "./bulkUpdate.ts";
 export { buildDedupePlan, dedupeKey, type DedupeOptions } from "./dedupe.ts";
 export { buildReassignPlans, type ReassignObjectType, type ReassignOptions } from "./reassign.ts";
@@ -131,6 +141,14 @@ export {
   type AuditLogVerification,
 } from "./auditLog.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
+export {
+  computeHealth,
+  summarizeHealth,
+  healthToMarkdown,
+  type HealthEntry,
+  type HealthRollup,
+  type HealthRuleDelta,
+} from "./health.ts";
 export { auditReportToHtml, auditReportToMarkdown, type ReportOptions } from "./report.ts";
 export {
   HUBSPOT_DEFAULT_FIELD_MAPPINGS,

package/src/mappings.ts

@@ -22,6 +22,9 @@ export const HUBSPOT_DEFAULT_FIELD_MAPPINGS: Record<
     email: "email",
     phone: "phone",
     title: "jobtitle",
+    // HubSpot-standard "LinkedIn URL"; safe to request everywhere (HubSpot
+    // ignores unknown properties rather than erroring). Powers strong dedup.
+    linkedin: "hs_linkedin_url",
     ownerId: "hubspot_owner_id",
   },
   deals: {

package/src/reassign.ts

@@ -28,10 +28,19 @@ import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
 export type ReassignObjectType = "account" | "contact" | "deal";
 
 export type ReassignOptions = {
-  /** the owner whose records are being handed off */
-  fromOwnerId: string;
+  /**
+   * the owner whose records are being handed off. Ignored (and not required)
+   * when `assignUnowned` is set — that mode targets ownerless records instead.
+   */
+  fromOwnerId?: string;
   /** the receiving owner — must be a known user in the snapshot */
   toOwnerId: string;
+  /**
+   * Backfill mode: instead of moving records from one owner to another, claim
+   * every OWNERLESS record (ownerId:empty) for `toOwnerId`. Shares the create-
+   * time assignment intent with `enrich acquire`, applied to existing debt.
+   */
+  assignUnowned?: boolean;
   /** which object types to compile plans for (default all three) */
   objects?: ReassignObjectType[];
   /** extra --where scoping, AND-ed into every plan (account fields lifted) */
@@ -65,11 +74,16 @@ export function buildReassignPlans(
   snapshot: CanonicalGtmSnapshot,
   options: ReassignOptions,
 ): PatchPlan[] {
-  if (!options.fromOwnerId || !options.toOwnerId) {
-    throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+  if (!options.toOwnerId) {
+    throw new Error("reassign requires --to <ownerId>.");
   }
-  if (options.fromOwnerId === options.toOwnerId) {
-    throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+  if (!options.assignUnowned) {
+    if (!options.fromOwnerId) {
+      throw new Error("reassign requires --from <ownerId> (or --assign-unowned to claim ownerless records).");
+    }
+    if (options.fromOwnerId === options.toOwnerId) {
+      throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+    }
   }
   // The receiving owner must exist: a typo'd --to would otherwise write an
   // invalid owner onto every matched record.
@@ -88,7 +102,7 @@ export function buildReassignPlans(
   }
 
   return objects.map((objectType) => {
-    const where = [`ownerId=${options.fromOwnerId}`];
+    const where = [options.assignUnowned ? "ownerId:empty" : `ownerId=${options.fromOwnerId}`];
     if (objectType === "deal" && !options.includeClosedDeals) {
       where.push("isClosed=false"); // closed deals keep their historical owner
     }
@@ -110,7 +124,9 @@ export function buildReassignPlans(
       set: { ownerId: options.toOwnerId },
       reason:
         options.reason ??
-        `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+        (options.assignUnowned
+          ? `reassign: claim ownerless ${objectType}s for owner ${options.toOwnerId}`
+          : `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`),
       maxOperations: options.maxOperations,
     });
   });