fullstackgtm 0.46.0 → 0.48.0

package/src/rules.ts

@@ -7,6 +7,7 @@ import type {
   CanonicalGtmSnapshot,
   GtmAuditRule,
   GtmSnapshotIndex,
+  PatchPlanAssumption,
   RiskLevel,
 } from "./types.ts";
 
@@ -50,6 +51,109 @@ export function patchOperationId(ruleId: string, objectId: string) {
   return `op_${stableHash(`${ruleId}:${objectId}`)}`;
 }
 
+
+const OPEN_DEAL_FLAGS_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-deal-derived-from-closed-won-flags",
+  text: "Derived open-deal status from canonical isClosed/isWon flags; a deal is open when neither flag is true.",
+  source: "CanonicalDeal.isClosed/isWon",
+  confidence: "derived",
+};
+
+const MISSING_CLOSED_WON_FLAGS_ASSUMPTION: PatchPlanAssumption = {
+  id: "missing-closed-won-flags-treated-open",
+  text: "Treated deals with missing isClosed/isWon flags as open so hygiene rules do not silently ignore active pipeline.",
+  source: "CanonicalDeal.isClosed/isWon",
+  confidence: "heuristic",
+};
+
+const ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION: PatchPlanAssumption = {
+  id: "account-without-contacts-or-deals-treated-orphan",
+  text: "Treated an account as orphaned when the snapshot has no contacts and no deals linked to that account.",
+  source: "snapshot account/contact/deal associations",
+  confidence: "derived",
+};
+
+const DEAL_OWNER_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "deal-owner-required-by-policy",
+  text: "Treated a missing or unknown deal owner as invalid when requireDealOwner policy is enabled.",
+  source: "GtmPolicy.requireDealOwner",
+  confidence: "heuristic",
+};
+
+const DEAL_ACCOUNT_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "deal-account-required-by-policy",
+  text: "Treated a missing or unknown deal account link as invalid when requireAccountForDeal policy is enabled.",
+  source: "GtmPolicy.requireAccountForDeal",
+  confidence: "heuristic",
+};
+
+const DEAL_AMOUNT_POLICY_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-deal-amount-required-by-policy",
+  text: "Treated open deals with missing or zero amount as forecast-risk findings unless requireDealAmount is disabled.",
+  source: "GtmPolicy.requireDealAmount",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-normalized-domain-duplicate-account",
+  text: "Treated accounts with the same normalized domain as duplicate-account candidates.",
+  source: "CanonicalAccount.domain",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_CONTACT_EMAIL_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-email-duplicate-contact",
+  text: "Treated contacts with the same lowercased email address as duplicate-contact candidates.",
+  source: "CanonicalContact.email",
+  confidence: "heuristic",
+};
+
+const DUPLICATE_OPEN_DEAL_ASSUMPTION: PatchPlanAssumption = {
+  id: "same-account-and-name-duplicate-open-deal",
+  text: "Treated open deals with the same normalized name on the same account scope as duplicate-opportunity candidates.",
+  source: "CanonicalDeal.accountId/name",
+  confidence: "heuristic",
+};
+
+const ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION: PatchPlanAssumption = {
+  id: "open-pipeline-account-needs-contact",
+  text: "Treated accounts with open pipeline but no linked contacts as coverage gaps requiring a buying-committee contact.",
+  source: "snapshot account/contact/deal associations",
+  confidence: "heuristic",
+};
+
+const SINGLE_SOURCE_ACCOUNT_ASSUMPTION: PatchPlanAssumption = {
+  id: "single-source-account-is-cross-system-gap",
+  text: "Treated an account present in only one connected system as a cross-system reconciliation gap.",
+  source: "ProviderIdentity.provider",
+  confidence: "heuristic",
+};
+
+function staleDealPolicyAssumption(days: number): PatchPlanAssumption {
+  return {
+    id: "stale-deal-days-policy",
+    text: `Treated open deals with no recorded activity for more than ${days} days as stale.`,
+    source: "GtmPolicy.staleDealDays",
+    confidence: "heuristic",
+  };
+}
+
+function closingSoonPolicyAssumption(windowDays: number, idleDays: number): PatchPlanAssumption {
+  return {
+    id: "closing-soon-idle-policy",
+    text: `Treated open deals closing within ${windowDays} days and idle for more than ${idleDays} days as silent slip risk.`,
+    source: "GtmPolicy.closingSoonDays/closingSoonIdleDays",
+    confidence: "heuristic",
+  };
+}
+
+function assumptionsIfFindings(
+  findings: AuditFinding[],
+  assumptions: PatchPlanAssumption[],
+): PatchPlanAssumption[] | undefined {
+  return findings.length > 0 ? assumptions : undefined;
+}
+
 export function stableHash(value: string) {
   let hash = 0;
   for (let index = 0; index < value.length; index += 1) {
@@ -168,7 +272,11 @@ export const orphanAccountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION]),
+    };
   },
 };
 
@@ -198,7 +306,11 @@ export const missingDealOwnerRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DEAL_OWNER_POLICY_ASSUMPTION]),
+    };
   },
 };
 
@@ -227,7 +339,11 @@ export const missingDealAccountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DEAL_ACCOUNT_POLICY_ASSUMPTION]),
+    };
   },
 };
 
@@ -256,7 +372,14 @@ export const pastCloseDateRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -297,7 +420,15 @@ export const staleDealRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        staleDealPolicyAssumption(policy.staleDealDays),
+      ]),
+    };
   },
 };
 
@@ -327,7 +458,15 @@ export const missingDealAmountRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        DEAL_AMOUNT_POLICY_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -382,7 +521,11 @@ export const duplicateAccountDomainRule: GtmAuditRule = {
           "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 };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION]),
+    };
   },
 };
 
@@ -422,7 +565,11 @@ export const duplicateContactEmailRule: GtmAuditRule = {
           "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 };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [DUPLICATE_CONTACT_EMAIL_ASSUMPTION]),
+    };
   },
 };
 
@@ -473,7 +620,15 @@ export const duplicateOpenDealRule: GtmAuditRule = {
           "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 };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        DUPLICATE_OPEN_DEAL_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -514,7 +669,15 @@ export const activeDealAccountWithoutContactsRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        ACCOUNT_WITH_OPEN_DEAL_NEEDS_CONTACT_ASSUMPTION,
+      ]),
+    };
   },
 };
 
@@ -559,13 +722,22 @@ export const closingSoonInactiveRule: GtmAuditRule = {
         approvalRequired: true,
       });
     }
-    return { findings, operations };
+    return {
+      findings,
+      operations,
+      assumptions: assumptionsIfFindings(findings, [
+        OPEN_DEAL_FLAGS_ASSUMPTION,
+        MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+        closingSoonPolicyAssumption(windowDays, idleDays),
+      ]),
+    };
   },
 };
 
 export const accountSingleSourceRule: GtmAuditRule = {
   id: "account-single-source",
   title: "Account exists in only one connected system",
+  emitsOperations: false,
   description:
     "On merged multi-system snapshots, flags accounts known to just one source — the seams where GTM systems disagree.",
   category: "cross-system",
@@ -597,10 +769,18 @@ export const accountSingleSourceRule: GtmAuditRule = {
           "Check whether the account is missing from the other systems or matched under a different domain/name.",
       });
     }
-    return { findings, operations: [] };
+    return {
+      findings,
+      operations: [],
+      assumptions: assumptionsIfFindings(findings, [SINGLE_SOURCE_ACCOUNT_ASSUMPTION]),
+    };
   },
 };
 
+export function isFindingsOnlyRule(rule: GtmAuditRule): boolean {
+  return rule.emitsOperations === false;
+}
+
 export const builtinAuditRules: GtmAuditRule[] = [
   orphanAccountRule,
   missingDealOwnerRule,

package/src/types.ts

@@ -105,6 +105,15 @@ export type CreateRecordPayload = {
 
 export type AuditFindingSeverity = "info" | "warning" | "critical";
 
+export type PatchPlanAssumptionConfidence = "derived" | "heuristic" | "guess";
+
+export type PatchPlanAssumption = {
+  id: string;
+  text: string;
+  source?: string;
+  confidence?: PatchPlanAssumptionConfidence;
+};
+
 /**
  * One claim that a canonical record exists in an external system. A record
  * merged from several providers carries one identity per provider.
@@ -397,6 +406,10 @@ export type PatchPlan = {
    *  Account/contact hygiene findings are NOT here; read `findings` for those. */
   pipelineFindings?: PipelineFinding[];
   evidence?: GtmEvidence[];
+  /** Assumptions used to turn audit observations into findings and operations. */
+  assumptions?: PatchPlanAssumption[];
+  /** Human decisions or unresolved questions that affect how the plan should be applied. */
+  openQuestions?: string[];
   operations: PatchOperation[];
   /**
    * The filter this plan's operations were selected by. Re-evaluated per
@@ -454,6 +467,8 @@ export type GtmRuleContext = {
 export type GtmRuleResult = {
   findings: AuditFinding[];
   operations: PatchOperation[];
+  /** Rule-level assumptions that explain the policy or heuristic behind returned findings. */
+  assumptions?: PatchPlanAssumption[];
 };
 
 /**
@@ -466,6 +481,8 @@ export type GtmAuditRule = {
   description: string;
   /** Grouping for docs and discovery, e.g. "hygiene", "forecast", "coverage". */
   category?: string;
+  /** False for findings-only rules whose evaluator intentionally emits no patch operations. */
+  emitsOperations?: boolean;
   evaluate: (context: GtmRuleContext) => GtmRuleResult;
 };
 
@@ -523,6 +540,21 @@ export type GtmConnector = {
    * result per input op. Optional: connectors without it use `applyOperation`.
    */
   applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+  /**
+   * Optional bulk apply path for homogeneous operation runs selected by
+   * `applyPatchPlan` (currently consecutive `set_field` ops on one object type
+   * and consecutive `archive_record` ops on one object type). Implementations
+   * MUST return exactly one result per input operation, preserve per-operation
+   * CAS/conflict semantics for field writes, and must not write operations that
+   * would have conflicted under the serial `readField` + `applyOperation` path.
+   * Connectors without it use `applyOperation` per operation.
+   */
+  applyBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
+  /**
+   * Maximum number of operations `applyPatchPlan` should pass to one
+   * `applyBatch` call. Defaults to 200 when unspecified.
+   */
+  applyBatchLimit?: number;
   /**
    * Read the live value of one canonical field, used for compare-and-set:
    * apply orchestration refuses to write over values that drifted since the