fullstackgtm 0.28.3 → 0.30.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/).
 The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md).
 
+## [0.30.0] — 2026-06-17
+
+Connector fixes — the two concrete defects a real HubSpot/Salesforce shop hits.
+
+### Added
+
+- **Salesforce `dedupe`/`merge_records` now works** (Accounts and Contacts) via
+  the SOAP `merge()` call — REST has no merge resource, but the OAuth token
+  doubles as the SOAP session id, so no extra auth. Groups larger than three are
+  merged in batches (master + 2 per call); failures are reported honestly with
+  what merged before the stop. **Opportunities remain unmergeable** (Salesforce
+  exposes no opportunity merge anywhere) and are refused with that explanation.
+  Merges still flow through the approval gate and the irreversible-op drift guard
+  (the survivor/loser existence check runs before the SOAP call). Exercised by
+  unit tests; validate against a sandbox before wiring into automation.
+
+### Fixed
+
+- **HubSpot closed/won detection is now pipeline-aware.** `isClosed`/`isWon`
+  were derived by substring-matching the stage against `closedwon`/`closedlost`,
+  so custom pipelines (opaque stage ids) read every deal as open and flooded
+  stale-deal / past-close findings with false positives. The connector now reads
+  the pipeline stage metadata (`/crm/v3/pipelines/deals`: `isClosed` +
+  `probability`) once per snapshot and derives closed/won from that, falling back
+  to the substring heuristic only when the pipelines read is unavailable.
+
+## [0.29.0] — 2026-06-16
+
+### Added
+
+- **`suggestMarketConfig` and its taxonomy types (`SeedVendor`,
+  `SuggestTaxonomyOptions`, `SuggestTaxonomyResult`) are now exported from the
+  package root.** The cold-start claim-taxonomy bootstrap behind `market init
+  --auto` (shipped in 0.26.0) is now usable as a library API, not just the CLI —
+  a consumer can run it with an injected `fetchPage` (e.g. a browser-rendered
+  capture) and compose it with the already-exported `captureMarket` /
+  `classifyMarket` / `marketMapToHtml`. No behaviour change to the CLI.
+
 ## [0.28.3] — 2026-06-16
 
 Fix broken links in the published mirror. CONTRIBUTING.md and CLAUDE.md

package/README.md

@@ -281,9 +281,9 @@ Connectors differ in what the provider's API allows — stated up front so nothi
 | Field writes (`set_field`, `clear_field`, `link_record`) | ✅ | ✅ | — |
 | `create_task` | ✅ | ✅ | — |
 | `archive_record` | ✅ | ✅ | — |
-| `merge_records` (`dedupe`) | ✅ | ❌ **not supported** | — |
+| `merge_records` (`dedupe`) | ✅ | ✅ Account/Contact (SOAP); ❌ Opportunity | — |
 
-**Salesforce merge** has no REST resource — it exists only in the SOAP API / Apex (Lead, Contact, Account, Case; max 3 records). This connector refuses a Salesforce `merge_records` operation honestly rather than half-merging; on Salesforce, deduplicate in the UI (or via SOAP/Apex), or use `bulk-update --archive` for the non-survivors. Native Salesforce merge is tracked future work, not a silent gap.
+**Salesforce merge** uses the SOAP `merge()` call (REST has no merge resource), so `dedupe` works on Salesforce **Accounts and Contacts** — the OAuth token doubles as the SOAP session, and groups larger than three records are merged in batches (master + 2 per call). **Opportunities cannot be merged** (Salesforce exposes no opportunity merge in the API or the UI) — for duplicate opportunities, pick a survivor and close/archive the rest. As always, merges are irreversible and go through the same approval gate + drift guard as every other write. (Validate against a sandbox first if you're wiring it into automation — the SOAP path is exercised by unit tests but a live Salesforce org is the real proof.)
 
 ### HubSpot: create a private app (~2 minutes, needs super-admin)
 

package/dist/connectors/hubspot.js

@@ -54,6 +54,37 @@ export function createHubspotConnector(options) {
         const text = await response.text();
         return text ? JSON.parse(text) : null;
     }
+    /**
+     * Map every deal stage id → its actual closed/won semantics, read from the
+     * pipeline definitions. Custom pipelines use opaque stage ids (e.g.
+     * "1234567"), so deriving closed/won by substring-matching the stage value
+     * against "closedwon"/"closedlost" mis-reads every custom-pipeline deal as
+     * open. The pipeline's own stage metadata is authoritative: `isClosed` marks
+     * a closed stage and `probability` 1.0 = won, 0.0 = lost. Best-effort — if
+     * the read is unavailable (e.g. missing scope) callers fall back to the
+     * substring heuristic so a partial-scope token still produces a snapshot.
+     */
+    async function fetchDealStageClose() {
+        const map = new Map();
+        try {
+            const data = await request("/crm/v3/pipelines/deals");
+            for (const pipeline of data?.results ?? []) {
+                for (const stage of pipeline?.stages ?? []) {
+                    if (!stage?.id)
+                        continue;
+                    const meta = stage.metadata ?? {};
+                    const isClosed = String(meta.isClosed).toLowerCase() === "true";
+                    const isWon = isClosed && Number(meta.probability) === 1;
+                    map.set(String(stage.id), { isClosed, isWon });
+                }
+            }
+        }
+        catch {
+            // Pipeline metadata unavailable — leave the map empty; the caller falls
+            // back to the substring heuristic.
+        }
+        return map;
+    }
     async function list(path) {
         const results = [];
         let after;
@@ -137,6 +168,7 @@ export function createHubspotConnector(options) {
             };
         });
         const dealProperties = `${mappedFields(mappings, "deals", HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals).join(",")},${PROVENANCE_PROPERTIES}`;
+        const stageClose = await fetchDealStageClose();
         const hubspotDeals = await fetchObjects("deals", dealProperties, true);
         const deals = hubspotDeals
             .filter((deal) => deal.id)
@@ -145,13 +177,15 @@ export function createHubspotConnector(options) {
             const companyId = deal.associations?.companies?.results?.[0]?.id;
             const stage = stringOrUndefined(readMapped(props, "deals", "stage", "dealstage"));
             const normalizedStage = (stage ?? "").toLowerCase();
-            const isWon = normalizedStage.includes("closedwon");
-            const isClosed = isWon || normalizedStage.includes("closedlost");
-            const forecastCategory = isWon
-                ? "closed_won"
-                : normalizedStage.includes("closedlost")
-                    ? "closed_lost"
-                    : "pipeline";
+            // Prefer the pipeline stage's actual closed/won metadata; fall back to
+            // the substring heuristic only when the stage isn't in the pipeline map
+            // (pipelines unreadable, or a deal on a deleted stage).
+            const stageMeta = stage ? stageClose.get(stage) : undefined;
+            const isWon = stageMeta ? stageMeta.isWon : normalizedStage.includes("closedwon");
+            const isClosed = stageMeta
+                ? stageMeta.isClosed
+                : isWon || normalizedStage.includes("closedlost");
+            const forecastCategory = isWon ? "closed_won" : isClosed ? "closed_lost" : "pipeline";
             const lastActivityAt = stringOrUndefined(readMapped(props, "deals", "lastActivityAt", "hs_last_sales_activity_timestamp"));
             return {
                 id: String(deal.id),

package/dist/connectors/salesforce.js

@@ -5,6 +5,12 @@ const SOBJECT_TYPES = {
     contact: "Contact",
     deal: "Opportunity",
 };
+// SObjects the SOAP merge() call supports. Opportunity is deliberately absent —
+// Salesforce has no opportunity merge at all (API or UI).
+const SOAP_MERGEABLE = {
+    account: "Account",
+    contact: "Contact",
+};
 const MAPPING_OBJECT_TYPES = {
     account: "accounts",
     contact: "contacts",
@@ -282,6 +288,97 @@ export function createSalesforceConnector(options) {
             detail: `Deleted ${sobjectType}/${operation.objectId}.`,
         };
     }
+    function escapeXml(value) {
+        return value
+            .replace(/&/g, "&")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&apos;");
+    }
+    /**
+     * One SOAP merge() call: master + up to 2 records to merge. Salesforce has no
+     * REST merge resource, but the Partner SOAP API's merge() works for Account,
+     * Contact, Lead, and Case, and accepts the OAuth access token as the SOAP
+     * session id. Returns ok/detail (the SOAP fault/error message is operational
+     * — MALFORMED_ID, entity-locked — not a data echo, so it's surfaced, capped).
+     */
+    async function soapMerge(sobjectType, masterId, loserIds) {
+        const connection = await options.getConnection();
+        const version = apiVersion.replace(/^v/, ""); // SOAP path uses "59.0", not "v59.0"
+        const url = `${connection.instanceUrl.replace(/\/$/, "")}/services/Soap/u/${version}`;
+        const toMerge = loserIds.map((id) => `<urn:recordToMergeIds>${escapeXml(id)}</urn:recordToMergeIds>`).join("");
+        const envelope = `<?xml version="1.0" encoding="UTF-8"?>` +
+            `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com" xmlns:urn1="urn:sobject.partner.soap.sforce.com">` +
+            `<soapenv:Header><urn:SessionHeader><urn:sessionId>${escapeXml(connection.accessToken)}</urn:sessionId></urn:SessionHeader></soapenv:Header>` +
+            `<soapenv:Body><urn:merge><urn:request>` +
+            `<urn:masterRecord><urn1:type>${sobjectType}</urn1:type><urn1:Id>${escapeXml(masterId)}</urn1:Id></urn:masterRecord>` +
+            toMerge +
+            `</urn:request></urn:merge></soapenv:Body></soapenv:Envelope>`;
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: "POST",
+                headers: { "Content-Type": "text/xml; charset=UTF-8", SOAPAction: '""' },
+                body: envelope,
+            });
+        }
+        catch (error) {
+            const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+            return { ok: false, detail: `Cannot reach the Salesforce SOAP endpoint${cause}.` };
+        }
+        const text = await response.text().catch(() => "");
+        if (!response.ok) {
+            const fault = /<faultstring>([\s\S]*?)<\/faultstring>/.exec(text)?.[1]?.trim();
+            return { ok: false, detail: `Salesforce SOAP merge failed (HTTP ${response.status})${fault ? `: ${fault.slice(0, 200)}` : ""}.` };
+        }
+        if (!/<success>\s*true\s*<\/success>/i.test(text)) {
+            const message = /<message>([\s\S]*?)<\/message>/.exec(text)?.[1]?.trim();
+            return { ok: false, detail: `Salesforce rejected the merge${message ? `: ${message.slice(0, 200)}` : ""}.` };
+        }
+        return { ok: true };
+    }
+    async function mergeRecords(operation) {
+        const sobjectType = SOAP_MERGEABLE[operation.objectType];
+        if (!sobjectType) {
+            return {
+                operationId: operation.id,
+                status: "skipped",
+                detail: operation.objectType === "deal"
+                    ? "Salesforce opportunities cannot be merged (no merge exists in the API or the UI). Pick a survivor and close/archive the duplicate opportunities instead."
+                    : `Salesforce merge supports Account and Contact only (not ${operation.objectType}).`,
+            };
+        }
+        const master = operation.objectId;
+        const group = Array.isArray(operation.beforeValue) ? operation.beforeValue.map(String) : [];
+        const losers = group.filter((id) => id !== master);
+        if (losers.length === 0) {
+            return { operationId: operation.id, status: "skipped", detail: "Nothing to merge — no records besides the survivor." };
+        }
+        // SOAP merge() takes the master + at most 2 records per call; batch larger
+        // duplicate groups. A mid-batch failure is reported with what was merged so
+        // far (merges are irreversible).
+        const merged = [];
+        for (let i = 0; i < losers.length; i += 2) {
+            const batch = losers.slice(i, i + 2);
+            const result = await soapMerge(sobjectType, master, batch);
+            if (!result.ok) {
+                return {
+                    operationId: operation.id,
+                    status: "failed",
+                    detail: `${result.detail} Merged ${merged.length} of ${losers.length} into ${master} before failing — IRREVERSIBLE; the remaining duplicates were not merged.`,
+                    providerData: { survivorId: master, mergedRecordIds: merged },
+                };
+            }
+            merged.push(...batch);
+        }
+        return {
+            operationId: operation.id,
+            status: "applied",
+            detail: `Merged ${merged.length} ${sobjectType} record(s) into ${master} (irreversible).`,
+            providerData: { survivorId: master, mergedRecordIds: merged },
+        };
+    }
     async function applyOperation(operation) {
         try {
             switch (operation.operation) {
@@ -341,14 +438,7 @@ export function createSalesforceConnector(options) {
                 case "create_task":
                     return await createTask(operation);
                 case "merge_records":
-                    // Salesforce merge exists only in the SOAP API and Apex (Lead,
-                    // Contact, Account, Case; max 3 records) — there is no REST merge
-                    // resource. Surface that honestly instead of half-merging.
-                    return {
-                        operationId: operation.id,
-                        status: "skipped",
-                        detail: "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
-                    };
+                    return await mergeRecords(operation);
                 case "archive_record":
                     return await archiveRecord(operation);
                 default:

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export { sampleSnapshot } from "./sampleData.ts";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, type CallScorecard, type LlmCredential, type LlmExtractedInsight, type LlmProvider, type Rubric, type ScoredDimension, } from "./llm.ts";
 export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
 export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, type CaptureEntry, type CaptureOptions, type ClaimFront, type ClaimIntensity, type FrontDrift, type FrontState, type MarketAxis, type MarketClaim, type MarketConfig, type MarketObservation, type MarketVendor, type ObservationConfidence, type ObservationSet, type ObservationStore, type ScaleSignal, type SpanVerificationFailure, } from "./market.ts";
+export { suggestMarketConfig, type SeedVendor, type SuggestTaxonomyOptions, type SuggestTaxonomyResult, } from "./marketTaxonomy.ts";
 export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, type AxesReport, type AxisAssessment, type AxisPairing, type PrincipalComponent, } from "./marketAxes.ts";
 export { buildWorksheet, classifyMarket, type ClassifyMarketOptions, type ClassifyMarketResult, type MarketWorksheet, } from "./marketClassify.ts";
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, type CallDocument, type ClaimMentionStats, type DirectiveStat, type DirectiveType, type MarketDirective, type OverlayOptions, type OverlayStats, type VendorMentionStats, } from "./marketOverlay.ts";

package/dist/index.js

@@ -27,6 +27,7 @@ export { sampleSnapshot } from "./sampleData.js";
 export { DEFAULT_MODELS, DEFAULT_RUBRIC, detectProviderFromKey, extractInsightsLlm, forcedToolCall, parseRubric, resolveLlmCredential, scoreCallLlm, validateLlmKey, } from "./llm.js";
 export { resolveRecord } from "./resolve.js";
 export { captureMarket, computeFrontStates, createFileObservationStore, diffFrontStates, extractReadableText, loadCaptureTexts, loadMarketConfig, marketHome, normalizeForMatch, observationId, parseMarketConfig, starterMarketConfig, validateObservationSet, verifyEvidenceSpans, } from "./market.js";
+export { suggestMarketConfig, } from "./marketTaxonomy.js";
 export { assessAxes, axesReportToText, axisPosition, messageBreadth, pcaTop2, pearson, } from "./marketAxes.js";
 export { buildWorksheet, classifyMarket, } from "./marketClassify.js";
 export { computeDirectives, computeOverlayStats, directivesToPlan, overlayToMarkdown, } from "./marketOverlay.js";

package/docs/roadmap-to-1.0.md

@@ -148,11 +148,6 @@ against the 0.28 surface: still accurate, still open.
 Found by exercising the published package as a fresh RevOps user with a real
 CRM (2026-06):
 
-- **Pipeline-aware closed-deal detection (HubSpot).** `isClosed`/`isWon` are
-  derived by substring-matching the raw `dealstage` value against
-  `closedwon`/`closedlost`. Custom pipelines use opaque stage ids, so closed
-  deals read as open and flood stale-deal/past-close findings. Fix: resolve
-  stage metadata from `/crm/v3/pipelines` once per snapshot.
 - **Rate-limit resilience.** No 429/retry/backoff handling anywhere; a
   mid-size portal snapshot is ~1,000+ sequential page requests and one
   transient failure aborts the run. Fix: honor `Retry-After`, retry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.28.3",
+  "version": "0.30.0",
   "description": "Open-source agentic GTM ops framework: canonical GTM data model, pluggable deterministic audits, reviewable dry-run patch plans, approval-gated write-back with conflict detection, and cross-system entity resolution. HubSpot, Salesforce, and Stripe connectors included.",
   "license": "Apache-2.0",
   "author": "Full Stack GTM LLC <ryan@fullstackgtm.com> (https://fullstackgtm.com)",

package/src/connectors/hubspot.ts

@@ -88,6 +88,36 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     return text ? JSON.parse(text) : null;
   }
 
+  /**
+   * Map every deal stage id → its actual closed/won semantics, read from the
+   * pipeline definitions. Custom pipelines use opaque stage ids (e.g.
+   * "1234567"), so deriving closed/won by substring-matching the stage value
+   * against "closedwon"/"closedlost" mis-reads every custom-pipeline deal as
+   * open. The pipeline's own stage metadata is authoritative: `isClosed` marks
+   * a closed stage and `probability` 1.0 = won, 0.0 = lost. Best-effort — if
+   * the read is unavailable (e.g. missing scope) callers fall back to the
+   * substring heuristic so a partial-scope token still produces a snapshot.
+   */
+  async function fetchDealStageClose(): Promise<Map<string, { isClosed: boolean; isWon: boolean }>> {
+    const map = new Map<string, { isClosed: boolean; isWon: boolean }>();
+    try {
+      const data = await request("/crm/v3/pipelines/deals");
+      for (const pipeline of data?.results ?? []) {
+        for (const stage of pipeline?.stages ?? []) {
+          if (!stage?.id) continue;
+          const meta = stage.metadata ?? {};
+          const isClosed = String(meta.isClosed).toLowerCase() === "true";
+          const isWon = isClosed && Number(meta.probability) === 1;
+          map.set(String(stage.id), { isClosed, isWon });
+        }
+      }
+    } catch {
+      // Pipeline metadata unavailable — leave the map empty; the caller falls
+      // back to the substring heuristic.
+    }
+    return map;
+  }
+
   async function list(path: string): Promise<any[]> {
     const results: any[] = [];
     let after: string | undefined;
@@ -204,6 +234,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       "deals",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals,
     ).join(",")},${PROVENANCE_PROPERTIES}`;
+    const stageClose = await fetchDealStageClose();
     const hubspotDeals = await fetchObjects("deals", dealProperties, true);
     const deals: CanonicalDeal[] = hubspotDeals
       .filter((deal) => deal.id)
@@ -212,13 +243,15 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         const companyId = deal.associations?.companies?.results?.[0]?.id;
         const stage = stringOrUndefined(readMapped(props, "deals", "stage", "dealstage"));
         const normalizedStage = (stage ?? "").toLowerCase();
-        const isWon = normalizedStage.includes("closedwon");
-        const isClosed = isWon || normalizedStage.includes("closedlost");
-        const forecastCategory = isWon
-          ? "closed_won"
-          : normalizedStage.includes("closedlost")
-            ? "closed_lost"
-            : "pipeline";
+        // Prefer the pipeline stage's actual closed/won metadata; fall back to
+        // the substring heuristic only when the stage isn't in the pipeline map
+        // (pipelines unreadable, or a deal on a deleted stage).
+        const stageMeta = stage ? stageClose.get(stage) : undefined;
+        const isWon = stageMeta ? stageMeta.isWon : normalizedStage.includes("closedwon");
+        const isClosed = stageMeta
+          ? stageMeta.isClosed
+          : isWon || normalizedStage.includes("closedlost");
+        const forecastCategory = isWon ? "closed_won" : isClosed ? "closed_lost" : "pipeline";
         const lastActivityAt = stringOrUndefined(
           readMapped(props, "deals", "lastActivityAt", "hs_last_sales_activity_timestamp"),
         );

package/src/connectors/salesforce.ts

@@ -42,6 +42,13 @@ const SOBJECT_TYPES: Partial<Record<GtmObjectType, string>> = {
   deal: "Opportunity",
 };
 
+// SObjects the SOAP merge() call supports. Opportunity is deliberately absent —
+// Salesforce has no opportunity merge at all (API or UI).
+const SOAP_MERGEABLE: Partial<Record<GtmObjectType, string>> = {
+  account: "Account",
+  contact: "Contact",
+};
+
 const MAPPING_OBJECT_TYPES: Partial<Record<GtmObjectType, Exclude<CrmObjectType, "owners">>> = {
   account: "accounts",
   contact: "contacts",
@@ -378,6 +385,105 @@ export function createSalesforceConnector(
     };
   }
 
+  function escapeXml(value: string): string {
+    return value
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&apos;");
+  }
+
+  /**
+   * One SOAP merge() call: master + up to 2 records to merge. Salesforce has no
+   * REST merge resource, but the Partner SOAP API's merge() works for Account,
+   * Contact, Lead, and Case, and accepts the OAuth access token as the SOAP
+   * session id. Returns ok/detail (the SOAP fault/error message is operational
+   * — MALFORMED_ID, entity-locked — not a data echo, so it's surfaced, capped).
+   */
+  async function soapMerge(
+    sobjectType: string,
+    masterId: string,
+    loserIds: string[],
+  ): Promise<{ ok: boolean; detail?: string }> {
+    const connection = await options.getConnection();
+    const version = apiVersion.replace(/^v/, ""); // SOAP path uses "59.0", not "v59.0"
+    const url = `${connection.instanceUrl.replace(/\/$/, "")}/services/Soap/u/${version}`;
+    const toMerge = loserIds.map((id) => `<urn:recordToMergeIds>${escapeXml(id)}</urn:recordToMergeIds>`).join("");
+    const envelope =
+      `<?xml version="1.0" encoding="UTF-8"?>` +
+      `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:partner.soap.sforce.com" xmlns:urn1="urn:sobject.partner.soap.sforce.com">` +
+      `<soapenv:Header><urn:SessionHeader><urn:sessionId>${escapeXml(connection.accessToken)}</urn:sessionId></urn:SessionHeader></soapenv:Header>` +
+      `<soapenv:Body><urn:merge><urn:request>` +
+      `<urn:masterRecord><urn1:type>${sobjectType}</urn1:type><urn1:Id>${escapeXml(masterId)}</urn1:Id></urn:masterRecord>` +
+      toMerge +
+      `</urn:request></urn:merge></soapenv:Body></soapenv:Envelope>`;
+    let response: Response;
+    try {
+      response = await fetchImpl(url, {
+        method: "POST",
+        headers: { "Content-Type": "text/xml; charset=UTF-8", SOAPAction: '""' },
+        body: envelope,
+      });
+    } catch (error) {
+      const cause = error instanceof Error && error.cause instanceof Error ? `: ${error.cause.message}` : "";
+      return { ok: false, detail: `Cannot reach the Salesforce SOAP endpoint${cause}.` };
+    }
+    const text = await response.text().catch(() => "");
+    if (!response.ok) {
+      const fault = /<faultstring>([\s\S]*?)<\/faultstring>/.exec(text)?.[1]?.trim();
+      return { ok: false, detail: `Salesforce SOAP merge failed (HTTP ${response.status})${fault ? `: ${fault.slice(0, 200)}` : ""}.` };
+    }
+    if (!/<success>\s*true\s*<\/success>/i.test(text)) {
+      const message = /<message>([\s\S]*?)<\/message>/.exec(text)?.[1]?.trim();
+      return { ok: false, detail: `Salesforce rejected the merge${message ? `: ${message.slice(0, 200)}` : ""}.` };
+    }
+    return { ok: true };
+  }
+
+  async function mergeRecords(operation: PatchOperation): Promise<PatchOperationResult> {
+    const sobjectType = SOAP_MERGEABLE[operation.objectType];
+    if (!sobjectType) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail:
+          operation.objectType === "deal"
+            ? "Salesforce opportunities cannot be merged (no merge exists in the API or the UI). Pick a survivor and close/archive the duplicate opportunities instead."
+            : `Salesforce merge supports Account and Contact only (not ${operation.objectType}).`,
+      };
+    }
+    const master = operation.objectId;
+    const group = Array.isArray(operation.beforeValue) ? (operation.beforeValue as unknown[]).map(String) : [];
+    const losers = group.filter((id) => id !== master);
+    if (losers.length === 0) {
+      return { operationId: operation.id, status: "skipped", detail: "Nothing to merge — no records besides the survivor." };
+    }
+    // SOAP merge() takes the master + at most 2 records per call; batch larger
+    // duplicate groups. A mid-batch failure is reported with what was merged so
+    // far (merges are irreversible).
+    const merged: string[] = [];
+    for (let i = 0; i < losers.length; i += 2) {
+      const batch = losers.slice(i, i + 2);
+      const result = await soapMerge(sobjectType, master, batch);
+      if (!result.ok) {
+        return {
+          operationId: operation.id,
+          status: "failed",
+          detail: `${result.detail} Merged ${merged.length} of ${losers.length} into ${master} before failing — IRREVERSIBLE; the remaining duplicates were not merged.`,
+          providerData: { survivorId: master, mergedRecordIds: merged },
+        };
+      }
+      merged.push(...batch);
+    }
+    return {
+      operationId: operation.id,
+      status: "applied",
+      detail: `Merged ${merged.length} ${sobjectType} record(s) into ${master} (irreversible).`,
+      providerData: { survivorId: master, mergedRecordIds: merged },
+    };
+  }
+
   async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
     try {
       switch (operation.operation) {
@@ -438,15 +544,7 @@ export function createSalesforceConnector(
         case "create_task":
           return await createTask(operation);
         case "merge_records":
-          // Salesforce merge exists only in the SOAP API and Apex (Lead,
-          // Contact, Account, Case; max 3 records) — there is no REST merge
-          // resource. Surface that honestly instead of half-merging.
-          return {
-            operationId: operation.id,
-            status: "skipped",
-            detail:
-              "Salesforce merge requires the SOAP API or Apex (Lead/Contact/Account/Case only) — this REST connector cannot merge. Merge in the Salesforce UI, or archive the duplicates explicitly.",
-          };
+          return await mergeRecords(operation);
         case "archive_record":
           return await archiveRecord(operation);
         default:

package/src/index.ts

@@ -226,6 +226,12 @@ export {
   type ScaleSignal,
   type SpanVerificationFailure,
 } from "./market.ts";
+export {
+  suggestMarketConfig,
+  type SeedVendor,
+  type SuggestTaxonomyOptions,
+  type SuggestTaxonomyResult,
+} from "./marketTaxonomy.ts";
 export {
   assessAxes,
   axesReportToText,