fullstackgtm 0.11.0 → 0.12.0

package/docs/crm-health-lifecycle.md

@@ -0,0 +1,135 @@
+# The CRM-health CRUD lifecycle: no new dupes
+
+How fullstackgtm keeps a CRM healthy over time — not just episodically
+audited. Grounded in dogfooding against a real portal (an outreach sync
+tripled five open deals; our own `create:` path nearly minted a duplicate
+company) and in what the platforms actually support today (verified 2026-06).
+
+## The model: Prevent → Detect → Remediate → Verify/Attribute
+
+Every mature dedupe stack (RingLead/ZoomInfo Ops, Insycle, Openprise,
+Dedupely) converged on three layers, because each one leaks:
+
+1. **Prevent** at write time — unique keys, upserts, point-of-entry gates.
+   Leaks because: HubSpot does not dedupe companies created via API at all,
+   deals have no native dedupe on any platform, and Salesforce duplicate
+   rules skip standard lead conversion.
+2. **Detect** continuously — scheduled scans, because prevention leaked.
+3. **Remediate** via survivor-rule-driven merge — irreversible on both
+   platforms, which is why preview/dry-run is table stakes.
+
+fullstackgtm adds the layer the industry mostly lacks: **Verify/Attribute** —
+typed, approved operations with compare-and-set, readback, drift diffs, and
+record-source provenance that names *which writer* created the mess, so you
+fix the faucet instead of mopping the puddle.
+
+## C — Create: gate the faucet
+
+**Platform facts to exploit before building anything:**
+
+| | HubSpot | Salesforce |
+| --- | --- | --- |
+| Contacts | API create with existing email → **409 with existing ID** (a free find-or-create) | Duplicate Rules fire on API writes (`DUPLICATES_DETECTED`); Alert-action rules bypassable via `DuplicateRuleHeader`, Block never |
+| Companies/Accounts | **No API dedupe** (UI/import domain-dedupe does not apply to API) | Same duplicate-rule machinery |
+| Deals/Opps | **No native dedupe anywhere** | No standard duplicate rule shipped |
+| Idempotent writes | `batch/upsert` keyed on unique-value custom properties (≤10/object) | Upsert by External ID field — explicitly idempotent |
+| Leak paths | API company creates; anything without email | Standard lead conversion, Quick Create, undelete |
+
+**Our primitives and their duties:**
+- `create:<Name>` link values must be **resolve-first**: search the live CRM
+  (and the current plan run) for an existing record before creating; link to
+  a unique match, refuse on ambiguity, create only on a confirmed miss.
+  HubSpot's search API is eventually consistent (~5–10s), so same-run
+  creations are deduped in memory, not via search.
+- A standalone **`resolve` gate** (planned, 0.13): given a candidate
+  record, return existing match(es) or "safe to create" — for the CLI, the
+  library, MCP, and any external writer (sync jobs, agents, webhook
+  handlers). Identity keys are the ones the package already uses:
+  contact email, normalized account domain, and the open-deal key
+  (account + normalized name).
+- **Stamp provenance on our own creates** (HubSpot allows integrations to
+  set `hs_object_source_detail_2/3` at create time).
+- Recommend native config in `doctor`/audit: Salesforce duplicate rules
+  active? HubSpot unique-value properties defined? Prevention posture is
+  auditable configuration, not just record state.
+
+## R — Read: watch continuously, attribute the source
+
+- The regression primitive exists: `fullstackgtm diff --before a.json
+  --after b.json --fail-on-new-findings` exits 2 when a (rule, record) pair
+  fires that didn't before. "New" is a stable finding id — the hash of
+  (ruleId, objectId).
+- **The nightly watch recipe** ("CRM CI"): scheduled
+  `snapshot → audit → diff` against yesterday's snapshot, alert on exit 2.
+- **Attribution** (planned, 0.13): capture HubSpot's read-only
+  `hs_object_source`, `hs_object_source_label`, `hs_object_source_id` into
+  the canonical model so duplicate findings can say *"all five created by
+  integration X"*. The fix for recurring dupes is upstream, in the writer.
+- Incremental reads (`snapshot --since`) exist for all three connectors;
+  caveats: HubSpot deltas carry no associations and cap at 10k per object,
+  Stripe deltas catch creations only.
+
+## U — Update: governed merge
+
+**Platform facts:** HubSpot's v3 merge endpoint
+(`POST /crm/v3/objects/{type}/merge`) supports contacts, companies,
+**deals**, and tickets today (the 2019 "no deal merge API" changelog is
+obsolete). Merges are pairwise, the loser is auto-archived, primary's
+values win, **merges cannot be undone**, and a record stops merging after
+250 cumulative merges. Salesforce merge is SOAP/Apex only (no REST), only
+Lead/Contact/Account/Case, max 3 records per call.
+
+**The gap:** our three duplicate rules (`duplicate-account-domain`,
+`duplicate-contact-email`, `duplicate-open-deal`) detect groups but emit
+only merge-review *tasks* — detection without remediation.
+
+**The plan (0.12):** a `merge_records` operation type —
+`requires_human_survivor_selection` placeholder, survivor heuristics in
+`suggest` (ordered, evidence-based: most engagements → oldest → most
+complete, each with a written reason), high risk, approval required, with
+the irreversibility called out in the plan text. The dry-run plan is the
+preview every commercial tool charges for; the pre-apply snapshot is the
+loser-record archive. HubSpot first; Salesforce merge documented as
+unsupported until an Apex path justifies itself.
+
+## D — Delete/Archive: the exit ramp
+
+- `archive_record` exists in both connectors (HubSpot DELETE = archive,
+  restorable ~90 days; Salesforce DELETE = recycle bin) but no built-in
+  rule emits it. It is the endpoint for reviewed orphans; merge losers are
+  archived by the merge APIs themselves.
+- All destructive operations stay high-risk, approval-required, and behind
+  compare-and-set where the platform exposes a readable before-value.
+
+## Write-path integrity rules (our own faucet)
+
+Lessons from auditing our own apply path:
+
+1. Field writes (`set_field`/`clear_field`/`link_record`) are protected by
+   compare-and-set: the live value is read back and a drifted value returns
+   `conflict` without writing.
+2. CAS is only as good as `readField` — for HubSpot deals, `accountId` is
+   an association, not a property, and must be read via the associations
+   API or CAS silently passes on replay (fixed in 0.11.1).
+3. `create:` values are resolve-first and deduped within a plan run
+   (0.11.1); `create_task` operations carry an idempotency token in the
+   task body and pre-check for it (0.11.1, fail-open on search errors).
+4. Plan replays are blocked at the store (`--plan-id` of an applied plan
+   refuses); the `--plan <file>` path relies on CAS — prefer the store.
+
+## The operating cadence
+
+**Gate** creates (resolve-first, upserts, native rules on) →
+**Watch** nightly (snapshot, diff, exit-2 alert) →
+**Fix** governed (audit → suggest → approve → apply, incl. merge) →
+**Verify** (readback, re-audit, drift report) →
+**Attribute** (provenance names the writer; fix the faucet).
+
+## Build order
+
+| Release | Scope |
+| --- | --- |
+| 0.11.1 | Fix our own faucet: resolve-first `create:` + plan-scoped dedup, HubSpot association-aware CAS for `link_record`, domain normalization in `duplicate-account-domain`, `create_task` idempotency token |
+| 0.12 (shipped) | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions capped at low confidence; the three duplicate rules emit governed merges instead of review tasks |
+| 0.13 | `resolve` gate (CLI/lib/MCP), provenance capture + attribution in findings, prevention-posture checks |
+| docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/llms.txt

@@ -15,6 +15,7 @@ at/above `--fail-on`.
 - [README](https://github.com/fullstackgtm/core/blob/main/README.md): install, five-minute loop, auth ladder, MCP setup, programmatic use
 - [INSTALL_FOR_AGENTS](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md): deterministic install-and-verify steps with expected outputs
 - [API reference](https://github.com/fullstackgtm/core/blob/main/docs/api.md): semver-covered surfaces — canonical model, rule interface, plan/apply contract, connector contract, config, CLI, MCP tools
+- [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
 ## Key invariants

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.11.0",
+  "version": "0.12.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",

package/src/connectors/hubspot.ts

@@ -54,6 +54,10 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
+  // create:<Name> dedup within one connector lifetime (one apply run): the
+  // search API is eventually consistent, so a just-created company is
+  // invisible to search — this map is the authoritative same-run record.
+  const createdCompaniesByName = new Map<string, string>();
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const token = await options.getAccessToken();
@@ -384,21 +388,46 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     if (!companyId) {
       return { operationId: operation.id, status: "skipped", detail: "link_record needs a target company id." };
     }
-    // `create:<Name>` creates the company first, then links — the approved
-    // value spells out exactly what will happen, so creation stays inside
-    // the typed, human-approved operation model.
+    // `create:<Name>` is resolve-first: link to an existing company when one
+    // unambiguously matches, refuse on ambiguity, create only on a confirmed
+    // miss — and never create the same name twice within one apply run
+    // (HubSpot's search API is eventually consistent, so a just-created
+    // record is invisible to search for several seconds).
     let createdCompanyName: string | null = null;
+    let resolvedExisting = false;
     if (companyId.startsWith("create:")) {
       const name = companyId.slice("create:".length).trim();
       if (!name) {
         return { operationId: operation.id, status: "skipped", detail: "create: needs a company name (create:<Name>)." };
       }
-      const created = await request(`/crm/v3/objects/companies`, {
-        method: "POST",
-        body: JSON.stringify({ properties: { name } }),
-      });
-      companyId = String(created.id);
-      createdCompanyName = name;
+      const nameKey = name.toLowerCase();
+      const alreadyCreated = createdCompaniesByName.get(nameKey);
+      if (alreadyCreated) {
+        companyId = alreadyCreated;
+        resolvedExisting = true;
+      } else {
+        const matches = await searchCompaniesByName(name);
+        if (matches.length > 1) {
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail: `create:${name} is ambiguous — ${matches.length} companies already named "${name}" (ids ${matches.join(", ")}). Link an explicit company id instead.`,
+          };
+        }
+        if (matches.length === 1) {
+          companyId = matches[0];
+          resolvedExisting = true;
+          createdCompaniesByName.set(nameKey, companyId);
+        } else {
+          const created = await request(`/crm/v3/objects/companies`, {
+            method: "POST",
+            body: JSON.stringify({ properties: { name } }),
+          });
+          companyId = String(created.id);
+          createdCompanyName = name;
+          createdCompaniesByName.set(nameKey, companyId);
+        }
+      }
     }
     await request(
       `/crm/v4/objects/${fromPath}/${encodeURIComponent(operation.objectId)}/associations/default/companies/${encodeURIComponent(companyId)}`,
@@ -409,11 +438,26 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       status: "applied",
       detail: createdCompanyName
         ? `Created company "${createdCompanyName}" (${companyId}) and linked ${fromPath}/${operation.objectId} to it.`
-        : `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
+        : resolvedExisting
+          ? `Linked ${fromPath}/${operation.objectId} to existing company ${companyId} (resolved by name, nothing created).`
+          : `Linked ${fromPath}/${operation.objectId} to company ${companyId}.`,
       providerData: { companyId, ...(createdCompanyName ? { createdCompany: true } : {}) },
     };
   }
 
+  /** Exact-name company lookup for resolve-first creates. Returns matching ids (max 3 fetched). */
+  async function searchCompaniesByName(name: string): Promise<string[]> {
+    const data = await request(`/crm/v3/objects/companies/search`, {
+      method: "POST",
+      body: JSON.stringify({
+        filterGroups: [{ filters: [{ propertyName: "name", operator: "EQ", value: name }] }],
+        properties: ["name"],
+        limit: 3,
+      }),
+    });
+    return ((data?.results ?? []) as Array<{ id: string }>).map((row) => String(row.id));
+  }
+
   async function createTask(operation: PatchOperation): Promise<PatchOperationResult> {
     const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
     if (associationTypeId === undefined) {
@@ -424,7 +468,33 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
       };
     }
     const subject = operation.field ? humanizeField(operation.field) : "Follow up";
-    const body = String(operation.afterValue ?? operation.reason ?? "");
+    // The operation id doubles as an idempotency token: it is stamped into
+    // the task body and pre-checked so a replayed plan does not create the
+    // same task twice. Fail-open — a search hiccup must not block the apply.
+    const token = `fsgtm ${operation.id.replace(/^op_/, "")}`;
+    try {
+      const existing = await request(`/crm/v3/objects/tasks/search`, {
+        method: "POST",
+        body: JSON.stringify({
+          filterGroups: [
+            { filters: [{ propertyName: "hs_task_body", operator: "CONTAINS_TOKEN", value: token.split(" ")[1] }] },
+          ],
+          limit: 1,
+        }),
+      });
+      const hit = (existing?.results ?? [])[0] as { id?: string } | undefined;
+      if (hit?.id) {
+        return {
+          operationId: operation.id,
+          status: "skipped",
+          detail: `Task for this operation already exists (task ${hit.id}); not creating a duplicate.`,
+          providerData: { id: hit.id, existing: true },
+        };
+      }
+    } catch {
+      // fall through to create
+    }
+    const body = `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`;
     const response = await request(`/crm/v3/objects/tasks`, {
       method: "POST",
       body: JSON.stringify({
@@ -472,6 +542,75 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
+  /**
+   * Merge a duplicate group into the approved survivor via HubSpot's v3
+   * merge API (supported for contacts, companies, deals, and tickets).
+   * Merges are pairwise and IRREVERSIBLE; the survivor's values win on
+   * conflict and each loser is archived by HubSpot. A loser that is already
+   * gone (404 — e.g. a replayed plan) is treated as already merged.
+   */
+  async function mergeRecords(operation: PatchOperation): Promise<PatchOperationResult> {
+    const objectPath = OBJECT_PATHS[operation.objectType];
+    if (!objectPath || operation.objectType === "user" || operation.objectType === "activity") {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "merge_records is supported for accounts, contacts, and deals.",
+      };
+    }
+    const survivorId = String(operation.afterValue ?? "");
+    const groupIds = Array.isArray(operation.beforeValue)
+      ? operation.beforeValue.map((id) => String(id))
+      : [];
+    if (!survivorId || groupIds.length < 2) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: "merge_records needs a survivor id (afterValue) and the duplicate group ids (beforeValue).",
+      };
+    }
+    if (!groupIds.includes(survivorId)) {
+      return {
+        operationId: operation.id,
+        status: "skipped",
+        detail: `Survivor ${survivorId} is not in the duplicate group (${groupIds.join(", ")}); refusing to merge into an unrelated record.`,
+      };
+    }
+    const losers = groupIds.filter((id) => id !== survivorId);
+    const mergedIds: string[] = [];
+    const alreadyGoneIds: string[] = [];
+    for (const loser of losers) {
+      try {
+        await request(`/crm/v3/objects/${objectPath}/merge`, {
+          method: "POST",
+          body: JSON.stringify({ primaryObjectId: survivorId, objectIdToMerge: loser }),
+        });
+        mergedIds.push(loser);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes(" 404")) {
+          alreadyGoneIds.push(loser); // replayed plan: loser already merged/archived
+          continue;
+        }
+        return {
+          operationId: operation.id,
+          status: "failed",
+          detail: `Merged ${mergedIds.length} of ${losers.length} into ${survivorId}, then failed on ${loser}: ${message}`,
+          providerData: { survivorId, mergedIds, alreadyGoneIds },
+        };
+      }
+    }
+    return {
+      operationId: operation.id,
+      status: mergedIds.length === 0 && alreadyGoneIds.length === losers.length ? "skipped" : "applied",
+      detail:
+        mergedIds.length === 0 && alreadyGoneIds.length === losers.length
+          ? `All ${losers.length} duplicates were already merged into ${survivorId}; nothing to do.`
+          : `Merged ${mergedIds.length} duplicate ${objectPath} into ${survivorId}${alreadyGoneIds.length ? ` (${alreadyGoneIds.length} already gone)` : ""}. Irreversible.`,
+      providerData: { survivorId, mergedIds, alreadyGoneIds },
+    };
+  }
+
   async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
     try {
       switch (operation.operation) {
@@ -482,6 +621,8 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           return await linkRecord(operation);
         case "create_task":
           return await createTask(operation);
+        case "merge_records":
+          return await mergeRecords(operation);
         case "archive_record":
           return await archiveRecord(operation);
         default:
@@ -519,6 +660,15 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     if (!objectPath || !mappingType) {
       throw new Error(`Field reads are only supported for accounts, contacts, and deals.`);
     }
+    // accountId is an association in HubSpot, not a property — without this
+    // branch the compare-and-set on link_record reads null and passes blind.
+    if (field === "accountId" && (objectType === "deal" || objectType === "contact")) {
+      const data = await request(
+        `/crm/v4/objects/${objectPath}/${encodeURIComponent(objectId)}/associations/companies?limit=1`,
+      );
+      const first = (data?.results ?? [])[0] as { toObjectId?: number | string } | undefined;
+      return first?.toObjectId !== undefined ? String(first.toObjectId) : null;
+    }
     const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
     const property = mappedField(mappings, mappingType, field, defaults[field] ?? field);
     const data = await request(

package/src/connectors/salesforce.ts

@@ -63,6 +63,8 @@ export function createSalesforceConnector(
   const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
+  // create:<Name> dedup within one connector lifetime (one apply run).
+  const createdAccountsByName = new Map<string, string>();
 
   async function request(path: string, init: RequestInit = {}): Promise<any> {
     const connection = await options.getConnection();
@@ -318,11 +320,29 @@ export function createSalesforceConnector(
         detail: "Tasks can be attached to accounts, contacts, and deals.",
       };
     }
+    // Idempotency: the operation id is stamped into the Description and
+    // pre-checked, so replaying a plan does not duplicate tasks. Fail-open.
+    const token = `fsgtm:${operation.id}`;
+    try {
+      const existing = await query(
+        `SELECT Id FROM Task WHERE Description LIKE '%${token.replace(/'/g, "\\'")}%' LIMIT 1`,
+      );
+      if (existing.length > 0) {
+        return {
+          operationId: operation.id,
+          status: "skipped",
+          detail: `Task for this operation already exists (task ${existing[0].Id}); not creating a duplicate.`,
+          providerData: { id: String(existing[0].Id), existing: true },
+        };
+      }
+    } catch {
+      // fall through to create
+    }
     const response = await request(`/services/data/${apiVersion}/sobjects/Task`, {
       method: "POST",
       body: JSON.stringify({
         Subject: operation.field ? humanizeField(operation.field) : "Follow up",
-        Description: String(operation.afterValue ?? operation.reason ?? ""),
+        Description: `${String(operation.afterValue ?? operation.reason ?? "")}\n\n[${token}]`,
         Status: "Not Started",
         Priority: "Normal",
         ...reference,
@@ -364,27 +384,67 @@ export function createSalesforceConnector(
           // link_record on a deal is just setting AccountId in Salesforce.
           return await setField(operation);
         case "link_record": {
-          // `create:<Name>` creates the Account first, then links — creation
-          // stays inside the typed, human-approved operation model.
+          // `create:<Name>` is resolve-first: link to an unambiguous existing
+          // Account, refuse on ambiguity, create only on a confirmed miss —
+          // and never create the same name twice within one apply run.
           const value = String(operation.afterValue ?? "");
           if (value.startsWith("create:")) {
             const name = value.slice("create:".length).trim();
             if (!name) {
               return { operationId: operation.id, status: "skipped", detail: "create: needs an account name (create:<Name>)." };
             }
-            const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
-              method: "POST",
-              body: JSON.stringify({ Name: name }),
-            });
-            const result = await setField({ ...operation, operation: "set_field", afterValue: String(created.id) });
+            const nameKey = name.toLowerCase();
+            let accountId = createdAccountsByName.get(nameKey);
+            let createdNew = false;
+            if (!accountId) {
+              const soqlName = name.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+              const matches = await query(
+                `SELECT Id FROM Account WHERE Name = '${soqlName}' LIMIT 3`,
+              );
+              if (matches.length > 1) {
+                return {
+                  operationId: operation.id,
+                  status: "skipped",
+                  detail: `create:${name} is ambiguous — ${matches.length} accounts already named "${name}". Link an explicit account id instead.`,
+                };
+              }
+              if (matches.length === 1) {
+                accountId = String(matches[0].Id);
+              } else {
+                const created = await request(`/services/data/${apiVersion}/sobjects/Account`, {
+                  method: "POST",
+                  body: JSON.stringify({ Name: name }),
+                });
+                accountId = String(created.id);
+                createdNew = true;
+              }
+              createdAccountsByName.set(nameKey, accountId);
+            }
+            const result = await setField({ ...operation, operation: "set_field", afterValue: accountId });
             return result.status === "applied"
-              ? { ...result, detail: `Created account "${name}" (${created.id}) and linked ${operation.objectType}/${operation.objectId} to it.`, providerData: { accountId: String(created.id), createdAccount: true } }
+              ? {
+                  ...result,
+                  detail: createdNew
+                    ? `Created account "${name}" (${accountId}) and linked ${operation.objectType}/${operation.objectId} to it.`
+                    : `Linked ${operation.objectType}/${operation.objectId} to existing account ${accountId} (resolved by name, nothing created).`,
+                  providerData: { accountId, ...(createdNew ? { createdAccount: true } : {}) },
+                }
               : result;
           }
           return await setField({ ...operation, operation: "set_field" });
         }
         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.",
+          };
         case "archive_record":
           return await archiveRecord(operation);
         default:

package/src/merge.ts

@@ -55,7 +55,7 @@ const CONFLICT_IGNORED_FIELDS = new Set([
   "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
 ]);
 
-function normalizeDomain(domain?: string): string | undefined {
+export function normalizeDomain(domain?: string): string | undefined {
   if (!domain) return undefined;
   return domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").replace(/\/.*$/, "") || undefined;
 }

package/src/rules.ts

@@ -1,3 +1,4 @@
+import { normalizeDomain } from "./merge.ts";
 import type {
   AuditFinding,
   CanonicalActivity,
@@ -333,7 +334,7 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
   evaluate: ({ snapshot }) => {
     const findings: AuditFinding[] = [];
     const operations = [];
-    for (const [domain, accounts] of duplicateGroups(snapshot.accounts, (account) => account.domain)) {
+    for (const [domain, accounts] of duplicateGroups(snapshot.accounts, (account) => normalizeDomain(account.domain))) {
       const anchor = accounts[0];
       findings.push({
         id: auditFindingId("duplicate-account-domain", anchor.id),
@@ -349,13 +350,15 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
         id: patchOperationId("duplicate-account-domain", anchor.id),
         objectType: "account" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${accounts.length} accounts sharing ${domain} and merge duplicates`,
-        reason: "Duplicate accounts split pipeline, attribution, and ownership.",
-        riskLevel: "medium" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: accounts.map((account) => account.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate accounts split pipeline, attribution, and ownership. Merge the ${accounts.length} accounts sharing ${domain} into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };
@@ -387,13 +390,15 @@ export const duplicateContactEmailRule: GtmAuditRule = {
         id: patchOperationId("duplicate-contact-email", anchor.id),
         objectType: "contact" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${contacts.length} contacts sharing ${email} and merge duplicates`,
-        reason: "Duplicate contacts fragment engagement history and double-route outreach.",
-        riskLevel: "low" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: contacts.map((contact) => contact.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate contacts fragment engagement history and double-route outreach. Merge the ${contacts.length} contacts sharing ${email} into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };
@@ -436,13 +441,15 @@ export const duplicateOpenDealRule: GtmAuditRule = {
         id: patchOperationId("duplicate-open-deal", anchor.id),
         objectType: "deal" as const,
         objectId: anchor.id,
-        operation: "create_task" as const,
-        field: "merge_review_task",
-        beforeValue: null,
-        afterValue: `Review ${deals.length} duplicate open deals named "${anchor.name}" — keep one, archive ${deals.length - 1}`,
-        reason: "Duplicate open deals inflate pipeline and forecast the same revenue more than once.",
-        riskLevel: "medium" as const,
+        operation: "merge_records" as const,
+        field: "merge",
+        beforeValue: deals.map((deal) => deal.id),
+        afterValue: "requires_human_survivor_selection",
+        reason: `Duplicate open deals inflate pipeline and forecast the same revenue more than once. Merge the ${deals.length} deals named "${anchor.name}" into one survivor.`,
+        riskLevel: "high" as const,
         approvalRequired: true,
+        rollback:
+          "IRREVERSIBLE: provider merges cannot be unmerged. The pre-apply snapshot retains every record's field values; recreate a record manually from it if a merge was wrong.",
       });
     }
     return { findings, operations };