fullstackgtm 0.47.0 → 0.48.0

package/src/index.ts

@@ -12,6 +12,27 @@ export {
 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";
+export {
+  buildLeadRoutePlan,
+  type LeadRouteCounts,
+  type LeadRouteOptions,
+  type LeadRouteResult,
+} from "./route.ts";
+export {
+  accountHierarchyToMarkdown,
+  buildAccountHierarchy,
+  type AccountHierarchyConflict,
+  type AccountHierarchyNode,
+  type AccountHierarchyReport,
+} from "./hierarchy.ts";
+export {
+  buildRelationshipMap,
+  relationshipMapToMarkdown,
+  type RelationshipMap,
+  type StakeholderNode,
+  type StakeholderRole,
+  type StakeholderSentiment,
+} from "./relationships.ts";
 export {
   CONFIG_FILE_NAME,
   loadConfig,
@@ -209,6 +230,7 @@ export {
   type AuditLogExport,
   type AuditLogVerification,
 } from "./auditLog.ts";
+export { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.ts";
 export { formatPatchPlanRun, patchPlanToMarkdown } from "./format.ts";
 export {
   computeHealth,
@@ -236,6 +258,7 @@ export {
   buildSnapshotIndex,
   builtinAuditRules,
   closingSoonInactiveRule,
+  isFindingsOnlyRule,
   duplicateAccountDomainRule,
   duplicateContactEmailRule,
   duplicateOpenDealRule,
@@ -540,6 +563,8 @@ export type {
   PatchOperationResult,
   PatchOperationType,
   PatchPlan,
+  PatchPlanAssumption,
+  PatchPlanAssumptionConfidence,
   PatchPlanRun,
   PatchPlanRunStatus,
   PatchVerification,

package/src/mcp.ts

@@ -1,3 +1,4 @@
+import type { ZodRawShape } from "zod/v4";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, resolve } from "node:path";
@@ -159,13 +160,17 @@ function packageVersion() {
   }
 }
 
+function strictSchema<T extends ZodRawShape>(shape: T) {
+  return z.object(shape).strict();
+}
+
 type ToolDefinition = {
   name: string;
   // Whether the tool can write to a CRM. Everything else reads, or writes
   // only local workspace state (market_observe appends to the local
   // observation store).
   writesCrm: boolean;
-  config: { title: string; description: string; inputSchema?: Record<string, unknown> };
+  config: { title: string; description: string; inputSchema?: unknown };
   // Args are validated by the SDK against config.inputSchema before the
   // handler runs; the loose typing here is what lets one table drive a
   // registration loop instead of per-call generics.
@@ -187,7 +192,7 @@ const toolDefinitions: ToolDefinition[] = [
         "Run a dry-run GTM hygiene audit and return a reviewable patch plan. " +
         "Sources: the realistic zero-credential demo CRM (provider: \"demo\" — richest test data), " +
         "the minimal sample dataset, a snapshot file, or a live provider.",
-      inputSchema: {
+      inputSchema: strictSchema({
         provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
         inputPath: z.string().optional(),
         configPath: z.string().optional(),
@@ -195,7 +200,7 @@ const toolDefinitions: ToolDefinition[] = [
         output: z.enum(["json", "markdown"]).optional(),
         today: z.string().optional(),
         staleDealDays: z.number().int().positive().optional(),
-      },
+      }),
     },
     handler: async ({ provider, inputPath, configPath, rules, output, today, staleDealDays }) => {
       const loaded = configPath ? loadConfig(configPath) : null;
@@ -219,11 +224,11 @@ const toolDefinitions: ToolDefinition[] = [
         "Derive values for a plan's requires_human_* placeholder operations from snapshot " +
         "evidence (account-name matching, contact associations), with confidence levels and " +
         "reasons. Read-only; feed accepted values into fullstackgtm_apply's valueOverrides.",
-      inputSchema: {
+      inputSchema: strictSchema({
         planPath: z.string(),
         provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
         inputPath: z.string().optional(),
-      },
+      }),
     },
     handler: async ({ planPath, provider, inputPath }) => {
       const plan = JSON.parse(readFileSync(resolve(process.cwd(), planPath), "utf8")) as PatchPlan;
@@ -242,14 +247,14 @@ const toolDefinitions: ToolDefinition[] = [
         "uses LLM extraction when an Anthropic/OpenAI key is configured in the server " +
         "environment or credential store, else the free deterministic keyword baseline; " +
         "'llm' and 'deterministic' force either. Read-only; every insight is provenance-marked.",
-      inputSchema: {
+      inputSchema: strictSchema({
         transcript: z.string().optional(),
         transcriptPath: z.string().optional(),
         title: z.string().optional(),
         source: z.enum(["gong", "chorus", "fathom", "manual", "csv", "unknown"]).optional(),
         extractor: z.enum(["auto", "llm", "deterministic"]).optional(),
         model: z.string().optional(),
-      },
+      }),
     },
     handler: async ({ transcript, transcriptPath, title, source, extractor, model }) => {
       const raw =
@@ -287,7 +292,7 @@ const toolDefinitions: ToolDefinition[] = [
         "(exists | ambiguous | safe_to_create) with matches and a reason, using the same " +
         "identity keys as the audit/merge engines (account domain, contact email, open-deal " +
         "key). Read-only. Never create on 'exists' or 'ambiguous'.",
-      inputSchema: {
+      inputSchema: strictSchema({
         objectType: z.enum(["account", "contact", "deal"]),
         name: z.string().optional(),
         domain: z.string().optional(),
@@ -295,7 +300,7 @@ const toolDefinitions: ToolDefinition[] = [
         accountId: z.string().optional(),
         provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
         inputPath: z.string().optional(),
-      },
+      }),
     },
     handler: async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
       const snapshot = await readSnapshot(provider, inputPath);
@@ -308,7 +313,7 @@ const toolDefinitions: ToolDefinition[] = [
     config: {
       title: "List Audit Rules",
       description: "List the built-in deterministic audit rules with ids and descriptions.",
-      inputSchema: {},
+      inputSchema: strictSchema({}),
     },
     handler: async () => {
       return content(
@@ -329,13 +334,13 @@ const toolDefinitions: ToolDefinition[] = [
         "the store's HMAC approval digests — ids not approved with `plans approve` are " +
         "refused — and the run is recorded onto the stored plan so `plans show` and " +
         "`audit-log export` include it.",
-      inputSchema: {
+      inputSchema: strictSchema({
         provider: z.enum(["hubspot", "salesforce"]),
         planPath: z.string(),
         approvedOperationIds: z.array(z.string()).min(1),
         valueOverrides: z.record(z.string(), z.string()).optional(),
         output: z.enum(["json", "markdown"]).optional(),
-      },
+      }),
     },
     handler: async ({ provider, planPath, approvedOperationIds, valueOverrides, output }) => {
       // The file may be a raw PatchPlan (audit --out) or a StoredPlan envelope
@@ -474,11 +479,11 @@ const toolDefinitions: ToolDefinition[] = [
         "and quote verbatim spans (≤300 chars) for every loud/quiet reading. Submit the full " +
         "ObservationSet via fullstackgtm_market_observe — quotes are verified character-for-" +
         "character against the captures, so never paraphrase.",
-      inputSchema: {
+      inputSchema: strictSchema({
         vendorId: z.string(),
         configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
         captureRun: z.string().optional(),
-      },
+      }),
     },
     handler: async ({ vendorId, configPath, captureRun }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
@@ -495,10 +500,10 @@ const toolDefinitions: ToolDefinition[] = [
         "Validates coverage, the verbatim-evidence rule, and mechanically verifies every quoted " +
         "span against the stored capture it cites. Returns problems if rejected; nothing is " +
         "stored unless the whole set passes. Observations are append-only — use a new runLabel.",
-      inputSchema: {
+      inputSchema: strictSchema({
         observationsPath: z.string().describe("Path to the ObservationSet JSON file"),
         configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
-      },
+      }),
     },
     handler: async ({ observationsPath, configPath }) => {
       const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
@@ -531,6 +536,7 @@ toolDefinitions.unshift({
       "Machine-readable contract for this MCP server: the tool inventory (derived from the " +
       "server's own registration table, with per-tool CRM-write flags), safety defaults, and " +
       "the CLI entrypoints for everything the tools don't cover.",
+    inputSchema: strictSchema({}),
   },
   handler: async () =>
     content({

package/src/relationships.ts

@@ -0,0 +1,115 @@
+import { normalizeDomain } from "./merge.ts";
+import type { CanonicalAccount, CanonicalContact, CanonicalGtmSnapshot } from "./types.ts";
+
+export type StakeholderRole = "economic_buyer" | "decision_maker" | "technical_buyer" | "champion" | "influencer" | "unknown";
+export type StakeholderSentiment = "positive" | "neutral" | "negative" | "unknown";
+
+export type StakeholderNode = {
+  contactId: string;
+  name: string;
+  title?: string;
+  email?: string;
+  role: StakeholderRole;
+  sentiment: StakeholderSentiment;
+  lastActivityAt?: string;
+  evidence: string[];
+};
+
+export type RelationshipMap = {
+  account: { accountId: string; name: string; domain?: string };
+  stakeholders: StakeholderNode[];
+  openDeals: Array<{ dealId: string; name: string; stage?: string; amount?: number; ownerId?: string }>;
+  gaps: string[];
+  counts: { stakeholders: number; openDeals: number; activities: number };
+};
+
+function fullName(contact: CanonicalContact): string {
+  return [contact.firstName, contact.lastName].filter(Boolean).join(" ") || contact.email || contact.id;
+}
+
+function inferRole(title: string | undefined): StakeholderRole {
+  const t = (title ?? "").toLowerCase();
+  if (/\b(cfo|ceo|coo|cro|chief|founder|owner|president)\b/.test(t)) return "economic_buyer";
+  if (/\b(vp|vice president|head of|director|gm|general manager)\b/.test(t)) return "decision_maker";
+  if (/\b(cto|cio|security|it|engineering|architect|developer|technical|data)\b/.test(t)) return "technical_buyer";
+  if (/\b(champion|revops|sales ops|revenue operations|operations)\b/.test(t)) return "champion";
+  if (t) return "influencer";
+  return "unknown";
+}
+
+function inferSentiment(text: string): StakeholderSentiment {
+  const lower = text.toLowerCase();
+  if (/\b(blocked|concern|risk|no budget|not interested|detractor|negative|unhappy)\b/.test(lower)) return "negative";
+  if (/\b(champion|excited|interested|positive|approved|referred|next step|pilot)\b/.test(lower)) return "positive";
+  return "neutral";
+}
+
+function maxSentiment(a: StakeholderSentiment, b: StakeholderSentiment): StakeholderSentiment {
+  const rank: Record<StakeholderSentiment, number> = { unknown: 0, neutral: 1, positive: 2, negative: 3 };
+  return rank[b] > rank[a] ? b : a;
+}
+
+function findAccount(snapshot: CanonicalGtmSnapshot, selector: { accountId?: string; domain?: string }): CanonicalAccount | null {
+  if (selector.accountId) return snapshot.accounts.find((account) => String(account.id) === selector.accountId) ?? null;
+  if (selector.domain) {
+    const domain = normalizeDomain(selector.domain);
+    return snapshot.accounts.find((account) => normalizeDomain(account.domain) === domain) ?? null;
+  }
+  return null;
+}
+
+export function buildRelationshipMap(snapshot: CanonicalGtmSnapshot, selector: { accountId?: string; domain?: string }): RelationshipMap {
+  const account = findAccount(snapshot, selector);
+  if (!account) throw new Error("relationships: account not found (use --account-id or --domain)");
+  const contacts = snapshot.contacts.filter((contact) => contact.accountId === account.id);
+  const contactIds = new Set(contacts.map((contact) => contact.id));
+  const activities = snapshot.activities.filter((activity) => activity.accountId === account.id || (activity.contactId ? contactIds.has(activity.contactId) : false));
+  const evidenceByContact = new Map<string, string[]>();
+  const sentimentByContact = new Map<string, StakeholderSentiment>();
+  for (const activity of activities) {
+    if (!activity.contactId || !contactIds.has(activity.contactId)) continue;
+    const text = [activity.subject, activity.type, activity.occurredAt].filter(Boolean).join(" — ");
+    evidenceByContact.set(activity.contactId, [...(evidenceByContact.get(activity.contactId) ?? []), text]);
+    sentimentByContact.set(activity.contactId, maxSentiment(sentimentByContact.get(activity.contactId) ?? "unknown", inferSentiment(text)));
+  }
+  const stakeholders = contacts.map((contact) => ({
+    contactId: String(contact.id),
+    name: fullName(contact),
+    ...(contact.title ? { title: contact.title } : {}),
+    ...(contact.email ? { email: contact.email } : {}),
+    role: inferRole(contact.title),
+    sentiment: sentimentByContact.get(contact.id) ?? "unknown",
+    ...(contact.lastActivityAt ? { lastActivityAt: contact.lastActivityAt } : {}),
+    evidence: evidenceByContact.get(contact.id) ?? [],
+  })).sort((a, b) => a.role.localeCompare(b.role) || a.name.localeCompare(b.name));
+  const openDeals = snapshot.deals.filter((deal) => deal.accountId === account.id && !deal.isClosed).map((deal) => ({
+    dealId: String(deal.id),
+    name: deal.name,
+    ...(deal.stage ? { stage: deal.stage } : {}),
+    ...(deal.amount !== undefined ? { amount: deal.amount } : {}),
+    ...(deal.ownerId ? { ownerId: deal.ownerId } : {}),
+  }));
+  const roles = new Set(stakeholders.map((s) => s.role));
+  const gaps: string[] = [];
+  if (!roles.has("economic_buyer")) gaps.push("No obvious economic buyer found from titles.");
+  if (!roles.has("decision_maker")) gaps.push("No obvious decision maker found from titles.");
+  if (stakeholders.every((s) => s.sentiment === "unknown")) gaps.push("No stakeholder activity evidence attached to this account.");
+  return { account: { accountId: String(account.id), name: account.name, ...(account.domain ? { domain: account.domain } : {}) }, stakeholders, openDeals, gaps, counts: { stakeholders: stakeholders.length, openDeals: openDeals.length, activities: activities.length } };
+}
+
+export function relationshipMapToMarkdown(map: RelationshipMap): string {
+  const lines = [`# Relationship map: ${map.account.name}`, "", `${map.counts.stakeholders} stakeholder(s), ${map.counts.openDeals} open deal(s), ${map.counts.activities} activity record(s).`, "", "## Stakeholders"];
+  for (const s of map.stakeholders) {
+    lines.push(`- ${s.name} — ${s.role}, ${s.sentiment}${s.title ? ` (${s.title})` : ""}`);
+    for (const evidence of s.evidence.slice(0, 3)) lines.push(`  - evidence: ${evidence}`);
+  }
+  if (map.openDeals.length) {
+    lines.push("", "## Open deals");
+    for (const deal of map.openDeals) lines.push(`- ${deal.name} (${deal.dealId})${deal.stage ? ` — ${deal.stage}` : ""}${deal.amount !== undefined ? ` — ${deal.amount}` : ""}`);
+  }
+  if (map.gaps.length) {
+    lines.push("", "## Gaps");
+    for (const gap of map.gaps) lines.push(`- ${gap}`);
+  }
+  return lines.join("\n");
+}

package/src/route.ts

@@ -0,0 +1,278 @@
+import { resolveAssignment, type AssignmentContext, type AssignmentPolicy } from "./assign.ts";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.ts";
+import { normalizeDomain } from "./merge.ts";
+import { stableHash } from "./rules.ts";
+import type { CanonicalAccount, CanonicalContact, CanonicalGtmSnapshot, PatchOperation, PatchPlan } from "./types.ts";
+
+/**
+ * Lead-to-account matching and routing recipes.
+ *
+ * This is the first packaged Traction-Complete-style workflow in the OSS CLI:
+ * take ownerless/unmatched leads, deterministically match them to accounts, and
+ * emit normal approval-gated patch operations. No writes happen here.
+ */
+
+export type LeadRouteOptions = {
+  /** Match contact email domains to account domains. Default true. */
+  matchByDomain?: boolean;
+  /** Also try raw company/name fields against account names when domain misses. */
+  matchByCompanyName?: boolean;
+  /** When an ownerless contact matches an owned account, set contact ownerId to the account owner. Default true. */
+  inheritAccountOwner?: boolean;
+  /** Reassign contacts that already have an owner when the matched account owner differs. Default false. */
+  reassignExistingOwner?: boolean;
+  /** Optional fallback policy for contacts that still do not have an owner. */
+  assignmentPolicy?: AssignmentPolicy;
+  /** Refuse to build larger plans unless explicitly raised. Default 500. */
+  maxOperations?: number;
+  reason?: string;
+};
+
+export type LeadRouteCounts = {
+  contactsScanned: number;
+  /** Contacts that ended with an unambiguous account context (existing link, domain match, or company-name match). */
+  matchedContacts: number;
+  matchedExistingAccount: number;
+  matchedByDomain: number;
+  matchedByCompanyName: number;
+  ambiguousAccountMatches: number;
+  skippedFreeEmail: number;
+  linkOperations: number;
+  /** Owner set_field operations proposed (account-owner inheritance + policy fallback). */
+  ownerOperations: number;
+  /** Alias for ownerOperations, named for reports that talk about owner-assigned leads. */
+  ownerAssigned: number;
+  policyAssigned: number;
+  unmatched: number;
+};
+
+export type LeadRouteResult = {
+  plan: PatchPlan;
+  counts: LeadRouteCounts;
+};
+
+function norm(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  const out = String(value).trim().toLowerCase();
+  return out || undefined;
+}
+
+function contactEmailDomain(contact: CanonicalContact): string | undefined {
+  const email = norm(contact.email);
+  if (!email || !email.includes("@")) return undefined;
+  return normalizeDomain(email.slice(email.lastIndexOf("@") + 1));
+}
+
+function rawString(record: { raw?: unknown }, keys: string[]): string | undefined {
+  if (!record.raw || typeof record.raw !== "object") return undefined;
+  const raw = record.raw as Record<string, unknown>;
+  for (const key of keys) {
+    const value = raw[key];
+    if (typeof value === "string" && value.trim()) return value.trim();
+    if (value && typeof value === "object") {
+      const nested = value as Record<string, unknown>;
+      for (const nestedKey of ["value", "name", "label"]) {
+        if (typeof nested[nestedKey] === "string" && String(nested[nestedKey]).trim()) {
+          return String(nested[nestedKey]).trim();
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+function companyNameFor(contact: CanonicalContact): string | undefined {
+  return rawString(contact, ["company", "companyName", "company_name", "account", "accountName", "account_name"]);
+}
+
+function uniqueAccount(matches: CanonicalAccount[]): CanonicalAccount | "ambiguous" | null {
+  const byId = new Map(matches.map((account) => [String(account.id), account]));
+  const unique = [...byId.values()];
+  if (unique.length === 0) return null;
+  if (unique.length > 1) return "ambiguous";
+  return unique[0];
+}
+
+function employeeBand(employeeCount: number | undefined): string | undefined {
+  if (employeeCount === undefined) return undefined;
+  if (employeeCount <= 10) return "1-10";
+  if (employeeCount <= 50) return "11-50";
+  if (employeeCount <= 200) return "51-200";
+  if (employeeCount <= 1000) return "201-1000";
+  return "1001+";
+}
+
+function routeContext(contact: CanonicalContact, account?: CanonicalAccount): AssignmentContext {
+  const geo = norm(rawString(contact, ["country", "countryCode", "country_code", "state", "region"])) ??
+    norm(rawString(account ?? { raw: undefined }, ["country", "countryCode", "country_code", "state", "region"]));
+  const department = norm(rawString(contact, ["department", "jobDepartment", "job_department"]));
+  return {
+    geo,
+    industry: norm(account?.industry),
+    employeeBand: employeeBand(account?.employeeCount),
+    department,
+    title: norm(contact.title),
+    accountOwnerId: account?.ownerId,
+  };
+}
+
+function activeOwnerIds(snapshot: CanonicalGtmSnapshot): Set<string> {
+  const ids = new Set<string>();
+  for (const user of snapshot.users) {
+    if (user.active === false) continue;
+    ids.add(String(user.id));
+    if (user.crmId) ids.add(String(user.crmId));
+  }
+  return ids;
+}
+
+export function buildLeadRoutePlan(snapshot: CanonicalGtmSnapshot, options: LeadRouteOptions = {}): LeadRouteResult {
+  const matchByDomain = options.matchByDomain ?? true;
+  const matchByCompanyName = options.matchByCompanyName ?? false;
+  const inheritAccountOwner = options.inheritAccountOwner ?? true;
+  const reassignExistingOwner = options.reassignExistingOwner ?? false;
+  const maxOperations = options.maxOperations ?? 500;
+
+  const accountsByDomain = new Map<string, CanonicalAccount[]>();
+  const accountsByName = new Map<string, CanonicalAccount[]>();
+  for (const account of snapshot.accounts) {
+    const domain = normalizeDomain(account.domain);
+    if (domain) accountsByDomain.set(domain, [...(accountsByDomain.get(domain) ?? []), account]);
+    const name = norm(account.name);
+    if (name) accountsByName.set(name, [...(accountsByName.get(name) ?? []), account]);
+  }
+
+  const operations: PatchOperation[] = [];
+  const counts: LeadRouteCounts = {
+    contactsScanned: 0,
+    matchedContacts: 0,
+    matchedExistingAccount: 0,
+    matchedByDomain: 0,
+    matchedByCompanyName: 0,
+    ambiguousAccountMatches: 0,
+    skippedFreeEmail: 0,
+    linkOperations: 0,
+    ownerOperations: 0,
+    ownerAssigned: 0,
+    policyAssigned: 0,
+    unmatched: 0,
+  };
+  const knownOwners = activeOwnerIds(snapshot);
+  let policyAssignmentIndex = 0;
+
+  for (const contact of snapshot.contacts) {
+    counts.contactsScanned += 1;
+    const currentAccount = contact.accountId ? snapshot.accounts.find((account) => account.id === contact.accountId) : undefined;
+    let matchedAccount: CanonicalAccount | undefined = currentAccount;
+    let matchRule: "existing" | "domain" | "company-name" | undefined = currentAccount ? "existing" : undefined;
+    if (currentAccount) counts.matchedExistingAccount += 1;
+
+    let skippedFreeEmail = false;
+    if (!matchedAccount && matchByDomain) {
+      const domain = contactEmailDomain(contact);
+      if (domain && FREE_EMAIL_DOMAINS.has(domain)) {
+        counts.skippedFreeEmail += 1;
+        skippedFreeEmail = true;
+      } else if (domain) {
+        const match = uniqueAccount(accountsByDomain.get(domain) ?? []);
+        if (match === "ambiguous") counts.ambiguousAccountMatches += 1;
+        else if (match) {
+          matchedAccount = match;
+          matchRule = "domain";
+          counts.matchedByDomain += 1;
+        }
+      }
+    }
+
+    if (!matchedAccount && matchByCompanyName && !skippedFreeEmail) {
+      const company = norm(companyNameFor(contact));
+      if (company && (accountsByName.get(company) ?? []).length > 0) {
+        // Name-only account matches are not safe enough to auto-link. Keep the
+        // contact unmatched and surface the skipped match as ambiguous.
+        counts.ambiguousAccountMatches += 1;
+      }
+    }
+
+    if (matchedAccount) counts.matchedContacts += 1;
+
+    const contactOps: PatchOperation[] = [];
+    if (matchedAccount && !contact.accountId) {
+      contactOps.push({
+        id: `op_${stableHash(`route:link:${contact.id}:${matchedAccount.id}`)}`,
+        objectType: "contact",
+        objectId: String(contact.id),
+        operation: "link_record",
+        field: "accountId",
+        beforeValue: contact.accountId ?? null,
+        afterValue: String(matchedAccount.id),
+        reason: options.reason ?? `Lead-to-account match by ${matchRule}: link contact to account ${matchedAccount.name} (${matchedAccount.id}).`,
+        riskLevel: "medium",
+        approvalRequired: true,
+        sourceRuleOrPolicy: "route.lead_to_account",
+      });
+      counts.linkOperations += 1;
+    }
+
+    let ownerId: string | null = null;
+    let ownerRule: string | undefined;
+    if (
+      inheritAccountOwner &&
+      matchedAccount?.ownerId &&
+      matchedAccount.ownerId !== contact.ownerId &&
+      (!contact.ownerId || reassignExistingOwner) &&
+      knownOwners.has(matchedAccount.ownerId)
+    ) {
+      ownerId = matchedAccount.ownerId;
+      ownerRule = "account-owner";
+    } else if (options.assignmentPolicy && !contact.ownerId) {
+      const assigned = resolveAssignment(options.assignmentPolicy, routeContext(contact, matchedAccount), policyAssignmentIndex, knownOwners);
+      policyAssignmentIndex += 1;
+      ownerId = assigned.ownerId;
+      ownerRule = assigned.rule;
+      if (ownerId) counts.policyAssigned += 1;
+    }
+
+    if (ownerId && ownerId !== contact.ownerId) {
+      contactOps.push({
+        id: `op_${stableHash(`route:owner:${contact.id}:${ownerId}`)}`,
+        objectType: "contact",
+        objectId: String(contact.id),
+        operation: "set_field",
+        field: "ownerId",
+        beforeValue: contact.ownerId ?? null,
+        afterValue: ownerId,
+        reason: options.reason ?? `Route contact owner by ${ownerRule ?? "policy"}${matchedAccount ? ` after matching account ${matchedAccount.name}` : ""}.`,
+        riskLevel: "medium",
+        approvalRequired: true,
+        sourceRuleOrPolicy: "route.owner_assignment",
+      });
+      counts.ownerOperations += 1;
+      counts.ownerAssigned = counts.ownerOperations;
+    }
+
+    if (contactOps.length > 1) {
+      const groupId = `grp_route_${contact.id}`;
+      for (const operation of contactOps) operation.groupId = groupId;
+    }
+    operations.push(...contactOps);
+
+    if (!matchedAccount) counts.unmatched += 1;
+  }
+
+  if (operations.length > maxOperations) {
+    throw new Error(`route would create ${operations.length} operations — above the ${maxOperations}-operation safety cap. Raise --max-operations after reviewing scope.`);
+  }
+
+  const plan: PatchPlan = {
+    id: `patch_plan_${stableHash(`route:${snapshot.provider}:${snapshot.generatedAt}:${operations.map((op) => op.id).join(",")}`)}`,
+    title: "Route leads: match contacts to accounts and owners",
+    createdAt: snapshot.generatedAt,
+    status: operations.length > 0 ? "needs_approval" : "draft",
+    dryRun: true,
+    summary: `${counts.matchedContacts} matched contact(s), ${counts.linkOperations} lead-to-account link(s), ${counts.ownerOperations} owner assignment(s), ${counts.ambiguousAccountMatches} ambiguous match(es), ${counts.unmatched} unmatched contact(s). Dry-run only; approve before apply.`,
+    findings: [],
+    operations,
+  };
+
+  return { plan, counts };
+}