fullstackgtm 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.12.0] — 2026-06-11
+
+Governed merges: the Remediate layer of the
+[CRM-health lifecycle](./docs/crm-health-lifecycle.md). Duplicate detection
+now ends in an approvable merge, not a chore.
+
+### Added
+
+- **`merge_records` operation type**: merges a duplicate group
+  (`beforeValue` = group ids) into an approved survivor (`afterValue`).
+  HubSpot connector implements it via the v3 merge API for companies,
+  contacts, and deals — pairwise, survivor's values win, losers archived by
+  HubSpot, **irreversible** (called out in every operation's rollback text).
+  Refuses survivors outside the group; treats 404 losers as already merged,
+  so replayed plans are safe. Salesforce skips honestly (merge is SOAP/Apex
+  only on that platform).
+- **Survivor suggestions in `suggest`**: deterministic ranking — most
+  complete record, then most recent activity — with the evidence written
+  into the reason. **Capped at low confidence by design**: an irreversible
+  merge can never clear the default bulk-approval bar; accepting one takes
+  `--min-confidence low` or an explicit `--value`.
+
+### Changed
+
+- **The three duplicate rules now emit `merge_records`** (high risk,
+  approval required, irreversibility in the rollback text) instead of
+  `create_task` review chores — detection now connects to remediation
+  inside the governed loop.
+
+## [0.11.1] — 2026-06-11
+
+Write-path integrity: fixes our own dupe faucets, found auditing the apply
+path for the new [CRM-health lifecycle](./docs/crm-health-lifecycle.md) doc.
+
+### Added
+
+- **docs/crm-health-lifecycle.md**: the full CRUD lifecycle for keeping a
+  CRM healthy — Prevent → Detect → Remediate → Verify/Attribute — grounded
+  in verified platform behavior (HubSpot/Salesforce dedupe and merge
+  support) and the build order toward governed merges and a resolve gate.
+
+### Fixed
+
+- **`create:<Name>` is now resolve-first**: it links to an unambiguous
+  existing company/account instead of creating, refuses on ambiguity, and
+  creates only on a confirmed miss — and never creates the same name twice
+  within one apply run (HubSpot search is eventually consistent, so the
+  same-run record is authoritative).
+- **HubSpot compare-and-set on `link_record` is no longer blind**:
+  `readField("deal"|"contact", id, "accountId")` reads the actual company
+  association (it is not a property), so replaying an applied link returns
+  `conflict` instead of silently re-creating companies.
+- **`create_task` is idempotent**: the operation id is stamped into the
+  task body as a token and pre-checked (fail-open), so replayed plans no
+  longer duplicate merge-review tasks on either provider.
+- **`duplicate-account-domain` normalizes domains** the same way merge
+  does — `www.acme.com`, `https://acme.com/about`, and `acme.com` now
+  group as duplicates.
+
 ## [0.11.0] — 2026-06-11
 
 Canonicalizes the paths discovered dogfooding against a real portal: the

package/README.md

@@ -59,7 +59,7 @@ fullstackgtm plans approve patch_plan_abc123 --values-from suggestions.json   #
 fullstackgtm apply --plan-id patch_plan_abc123 --provider hubspot
 ```
 
-Widen the bar deliberately: `--min-confidence low` accepts single-signal matches; `--include-creates` accepts `create:<Name>` values — approving one **creates the missing company/account record and links to it** in a single audited operation, so even record creation stays inside the typed, human-approved model. Conflicting or ambiguous evidence always yields *no* suggestion with an explanation, never a guess.
+Widen the bar deliberately: `--min-confidence low` accepts single-signal matches and **merge survivor suggestions** (irreversible merges are capped at low confidence by design, so the default bar never bulk-approves one); `--include-creates` accepts `create:<Name>` values — approving one **creates the missing company/account record and links to it** in a single audited operation, so even record creation stays inside the typed, human-approved model. Conflicting or ambiguous evidence always yields *no* suggestion with an explanation, never a guess.
 
 ```bash
 # 3. Hand the findings to whoever owns the CRM: a client-ready report

package/dist/connectors/hubspot.js

@@ -22,6 +22,10 @@ export function createHubspotConnector(options) {
     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();
     async function request(path, init = {}) {
         const token = await options.getAccessToken();
         let response;
@@ -286,21 +290,48 @@ export function createHubspotConnector(options) {
         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 = 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)}`, { method: "PUT" });
         return {
@@ -308,10 +339,24 @@ export function createHubspotConnector(options) {
             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) {
+        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 ?? []).map((row) => String(row.id));
+    }
     async function createTask(operation) {
         const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
         if (associationTypeId === undefined) {
@@ -322,7 +367,34 @@ export function createHubspotConnector(options) {
             };
         }
         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];
+            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({
@@ -368,6 +440,74 @@ export function createHubspotConnector(options) {
             detail: `Archived ${objectPath}/${operation.objectId}.`,
         };
     }
+    /**
+     * 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) {
+        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 = [];
+        const alreadyGoneIds = [];
+        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) {
         try {
             switch (operation.operation) {
@@ -378,6 +518,8 @@ export function createHubspotConnector(options) {
                     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:
@@ -405,6 +547,13 @@ export function createHubspotConnector(options) {
         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];
+            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(`/crm/v3/objects/${objectPath}/${encodeURIComponent(objectId)}?properties=${encodeURIComponent(property)}`);

package/dist/connectors/salesforce.js

@@ -23,6 +23,8 @@ export function createSalesforceConnector(options) {
     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();
     async function request(path, init = {}) {
         const connection = await options.getConnection();
         const url = path.startsWith("http")
@@ -228,11 +230,28 @@ export function createSalesforceConnector(options) {
                 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,
@@ -269,27 +288,65 @@ export function createSalesforceConnector(options) {
                     // 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/dist/merge.d.ts

@@ -42,6 +42,7 @@ export type MergeReport = {
     conflicts: MergeConflict[];
     suggestions: MergeSuggestion[];
 };
+export declare function normalizeDomain(domain?: string): string | undefined;
 export declare function mergeSnapshots(snapshots: CanonicalGtmSnapshot[]): {
     snapshot: CanonicalGtmSnapshot;
     report: MergeReport;

package/dist/merge.js

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

package/dist/rules.js

@@ -1,3 +1,4 @@
+import { normalizeDomain } from "./merge.js";
 /**
  * Placeholder used as `afterValue` when the right value is a human decision
  * (e.g. which owner to assign). Apply orchestration refuses to write these
@@ -316,7 +317,7 @@ export const duplicateAccountDomainRule = {
     evaluate: ({ snapshot }) => {
         const findings = [];
         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),
@@ -332,13 +333,14 @@ export const duplicateAccountDomainRule = {
                 id: patchOperationId("duplicate-account-domain", anchor.id),
                 objectType: "account",
                 objectId: anchor.id,
-                operation: "create_task",
-                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",
+                operation: "merge_records",
+                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",
                 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 };
@@ -368,13 +370,14 @@ export const duplicateContactEmailRule = {
                 id: patchOperationId("duplicate-contact-email", anchor.id),
                 objectType: "contact",
                 objectId: anchor.id,
-                operation: "create_task",
-                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",
+                operation: "merge_records",
+                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",
                 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 };
@@ -414,13 +417,14 @@ export const duplicateOpenDealRule = {
                 id: patchOperationId("duplicate-open-deal", anchor.id),
                 objectType: "deal",
                 objectId: anchor.id,
-                operation: "create_task",
-                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",
+                operation: "merge_records",
+                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",
                 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 };

package/dist/suggest.js

@@ -22,6 +22,10 @@ export function suggestValues(plan, snapshot) {
             suggestions.push(suggestDealAccount(operation, dealsById, accountsByNorm, accountsById, contactsByName));
             continue;
         }
+        if (placeholder === "requires_human_survivor_selection") {
+            suggestions.push(suggestSurvivor(operation, snapshot, dealsById));
+            continue;
+        }
         if (placeholder === "requires_human_owner_selection" && activeUsers.length === 1) {
             suggestions.push({
                 operationId: operation.id,
@@ -140,6 +144,79 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
     };
 }
+/**
+ * Survivor selection for merge_records. Ranking is deterministic and
+ * evidence-based: most complete record first (count of populated canonical
+ * fields), most recent activity as the tiebreaker, group order last.
+ * Confidence is capped at "low" by design: merges are irreversible, so a
+ * survivor suggestion must never clear the default bulk-approval bar —
+ * accepting one requires --min-confidence low or an explicit --value.
+ */
+function suggestSurvivor(operation, snapshot, dealsById) {
+    const base = {
+        operationId: operation.id,
+        objectType: operation.objectType,
+        objectId: operation.objectId,
+        objectName: dealsById.get(operation.objectId)?.name,
+        placeholder: "requires_human_survivor_selection",
+    };
+    const groupIds = Array.isArray(operation.beforeValue)
+        ? operation.beforeValue.map((id) => String(id))
+        : [];
+    if (groupIds.length < 2) {
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: "Operation does not carry a duplicate group (expected ids in beforeValue).",
+        };
+    }
+    const collection = operation.objectType === "account"
+        ? snapshot.accounts
+        : operation.objectType === "contact"
+            ? snapshot.contacts
+            : operation.objectType === "deal"
+                ? snapshot.deals
+                : [];
+    const records = groupIds
+        .map((id) => collection.find((row) => row.id === id))
+        .filter((row) => row !== undefined);
+    if (records.length !== groupIds.length) {
+        return {
+            ...base,
+            suggestedValue: null,
+            confidence: "none",
+            reason: "Not every group member is present in the snapshot; re-run the audit before merging.",
+        };
+    }
+    const ranked = [...records].sort((a, b) => {
+        const completeness = populatedFields(b) - populatedFields(a);
+        if (completeness !== 0)
+            return completeness;
+        return activityMs(b) - activityMs(a);
+    });
+    const winner = ranked[0];
+    const runnerUp = ranked[1];
+    const name = "name" in winner && typeof winner.name === "string" ? winner.name : winner.id;
+    return {
+        ...base,
+        suggestedValue: winner.id,
+        confidence: "low",
+        reason: `"${name}" (${winner.id}) is the most complete record in the group ` +
+            `(${populatedFields(winner)} populated fields vs ${populatedFields(runnerUp)}` +
+            `${activityMs(winner) > activityMs(runnerUp) ? ", and more recent activity" : ""}). ` +
+            `Merging is IRREVERSIBLE — survivor suggestions never exceed low confidence; ` +
+            `approve with --min-confidence low or an explicit --value after review.`,
+    };
+}
+function populatedFields(record) {
+    return Object.values(record).filter((value) => value !== undefined && value !== null && value !== "").length;
+}
+function activityMs(record) {
+    const value = record.lastActivityAt;
+    const parsed = value ? Date.parse(value) : NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
 function normalize(value) {
     return value
         .toLowerCase()

package/dist/types.d.ts

@@ -10,7 +10,7 @@ export type RiskLevel = "low" | "medium" | "high";
 export type ApprovalStatus = "draft" | "needs_approval" | "approved" | "rejected" | "applied";
 export type GtmObjectType = "account" | "contact" | "deal" | "user" | "activity";
 export type GtmEvidenceSourceSystem = "salesforce" | "hubspot" | "gong" | "chorus" | "fathom" | "manual" | "csv" | "mock" | "unknown";
-export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task";
+export type PatchOperationType = "set_field" | "clear_field" | "link_record" | "archive_record" | "create_task" | "merge_records";
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 /**
  * One claim that a canonical record exists in an external system. A record

package/docs/api.md

@@ -40,7 +40,7 @@ release.
 - `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
-- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`.
+- `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). The Salesforce connector skips `merge_records` honestly (SOAP/Apex-only on that platform).
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1; `applyOperation` implements every operation type.
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).