fullstackgtm 0.11.0 → 0.12.0

package/src/suggest.ts

@@ -62,6 +62,11 @@ export function suggestValues(
       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,
@@ -194,6 +199,89 @@ function suggestDealAccount(
   };
 }
 
+/**
+ * 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: PatchOperation,
+  snapshot: CanonicalGtmSnapshot,
+  dealsById: Map<string, { name: string }>,
+): ValueSuggestion {
+  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 is NonNullable<typeof 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: object) {
+  return Object.values(record).filter(
+    (value) => value !== undefined && value !== null && value !== "",
+  ).length;
+}
+
+function activityMs(record: object) {
+  const value = (record as { lastActivityAt?: string }).lastActivityAt;
+  const parsed = value ? Date.parse(value) : NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
 function normalize(value: string) {
   return value
     .toLowerCase()

package/src/types.ts

@@ -41,7 +41,11 @@ export type PatchOperationType =
   | "clear_field"
   | "link_record"
   | "archive_record"
-  | "create_task";
+  | "create_task"
+  // Merge a duplicate group into a survivor. beforeValue is the group's
+  // record ids; afterValue is the survivor id (requires_human_survivor_selection
+  // until a human picks). IRREVERSIBLE on every provider that supports it.
+  | "merge_records";
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";