fullstackgtm 0.46.0 → 0.48.0

package/dist/route.js

@@ -0,0 +1,228 @@
+import { resolveAssignment } from "./assign.js";
+import { FREE_EMAIL_DOMAINS } from "./freeEmailDomains.js";
+import { normalizeDomain } from "./merge.js";
+import { stableHash } from "./rules.js";
+function norm(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const out = String(value).trim().toLowerCase();
+    return out || undefined;
+}
+function contactEmailDomain(contact) {
+    const email = norm(contact.email);
+    if (!email || !email.includes("@"))
+        return undefined;
+    return normalizeDomain(email.slice(email.lastIndexOf("@") + 1));
+}
+function rawString(record, keys) {
+    if (!record.raw || typeof record.raw !== "object")
+        return undefined;
+    const raw = record.raw;
+    for (const key of keys) {
+        const value = raw[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+        if (value && typeof value === "object") {
+            const nested = value;
+            for (const nestedKey of ["value", "name", "label"]) {
+                if (typeof nested[nestedKey] === "string" && String(nested[nestedKey]).trim()) {
+                    return String(nested[nestedKey]).trim();
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function companyNameFor(contact) {
+    return rawString(contact, ["company", "companyName", "company_name", "account", "accountName", "account_name"]);
+}
+function uniqueAccount(matches) {
+    const byId = new Map(matches.map((account) => [String(account.id), account]));
+    const unique = [...byId.values()];
+    if (unique.length === 0)
+        return null;
+    if (unique.length > 1)
+        return "ambiguous";
+    return unique[0];
+}
+function employeeBand(employeeCount) {
+    if (employeeCount === undefined)
+        return undefined;
+    if (employeeCount <= 10)
+        return "1-10";
+    if (employeeCount <= 50)
+        return "11-50";
+    if (employeeCount <= 200)
+        return "51-200";
+    if (employeeCount <= 1000)
+        return "201-1000";
+    return "1001+";
+}
+function routeContext(contact, account) {
+    const geo = norm(rawString(contact, ["country", "countryCode", "country_code", "state", "region"])) ??
+        norm(rawString(account ?? { raw: undefined }, ["country", "countryCode", "country_code", "state", "region"]));
+    const department = norm(rawString(contact, ["department", "jobDepartment", "job_department"]));
+    return {
+        geo,
+        industry: norm(account?.industry),
+        employeeBand: employeeBand(account?.employeeCount),
+        department,
+        title: norm(contact.title),
+        accountOwnerId: account?.ownerId,
+    };
+}
+function activeOwnerIds(snapshot) {
+    const ids = new Set();
+    for (const user of snapshot.users) {
+        if (user.active === false)
+            continue;
+        ids.add(String(user.id));
+        if (user.crmId)
+            ids.add(String(user.crmId));
+    }
+    return ids;
+}
+export function buildLeadRoutePlan(snapshot, options = {}) {
+    const matchByDomain = options.matchByDomain ?? true;
+    const matchByCompanyName = options.matchByCompanyName ?? false;
+    const inheritAccountOwner = options.inheritAccountOwner ?? true;
+    const reassignExistingOwner = options.reassignExistingOwner ?? false;
+    const maxOperations = options.maxOperations ?? 500;
+    const accountsByDomain = new Map();
+    const accountsByName = new Map();
+    for (const account of snapshot.accounts) {
+        const domain = normalizeDomain(account.domain);
+        if (domain)
+            accountsByDomain.set(domain, [...(accountsByDomain.get(domain) ?? []), account]);
+        const name = norm(account.name);
+        if (name)
+            accountsByName.set(name, [...(accountsByName.get(name) ?? []), account]);
+    }
+    const operations = [];
+    const counts = {
+        contactsScanned: 0,
+        matchedContacts: 0,
+        matchedExistingAccount: 0,
+        matchedByDomain: 0,
+        matchedByCompanyName: 0,
+        ambiguousAccountMatches: 0,
+        skippedFreeEmail: 0,
+        linkOperations: 0,
+        ownerOperations: 0,
+        ownerAssigned: 0,
+        policyAssigned: 0,
+        unmatched: 0,
+    };
+    const knownOwners = activeOwnerIds(snapshot);
+    let policyAssignmentIndex = 0;
+    for (const contact of snapshot.contacts) {
+        counts.contactsScanned += 1;
+        const currentAccount = contact.accountId ? snapshot.accounts.find((account) => account.id === contact.accountId) : undefined;
+        let matchedAccount = currentAccount;
+        let matchRule = currentAccount ? "existing" : undefined;
+        if (currentAccount)
+            counts.matchedExistingAccount += 1;
+        let skippedFreeEmail = false;
+        if (!matchedAccount && matchByDomain) {
+            const domain = contactEmailDomain(contact);
+            if (domain && FREE_EMAIL_DOMAINS.has(domain)) {
+                counts.skippedFreeEmail += 1;
+                skippedFreeEmail = true;
+            }
+            else if (domain) {
+                const match = uniqueAccount(accountsByDomain.get(domain) ?? []);
+                if (match === "ambiguous")
+                    counts.ambiguousAccountMatches += 1;
+                else if (match) {
+                    matchedAccount = match;
+                    matchRule = "domain";
+                    counts.matchedByDomain += 1;
+                }
+            }
+        }
+        if (!matchedAccount && matchByCompanyName && !skippedFreeEmail) {
+            const company = norm(companyNameFor(contact));
+            if (company && (accountsByName.get(company) ?? []).length > 0) {
+                // Name-only account matches are not safe enough to auto-link. Keep the
+                // contact unmatched and surface the skipped match as ambiguous.
+                counts.ambiguousAccountMatches += 1;
+            }
+        }
+        if (matchedAccount)
+            counts.matchedContacts += 1;
+        const contactOps = [];
+        if (matchedAccount && !contact.accountId) {
+            contactOps.push({
+                id: `op_${stableHash(`route:link:${contact.id}:${matchedAccount.id}`)}`,
+                objectType: "contact",
+                objectId: String(contact.id),
+                operation: "link_record",
+                field: "accountId",
+                beforeValue: contact.accountId ?? null,
+                afterValue: String(matchedAccount.id),
+                reason: options.reason ?? `Lead-to-account match by ${matchRule}: link contact to account ${matchedAccount.name} (${matchedAccount.id}).`,
+                riskLevel: "medium",
+                approvalRequired: true,
+                sourceRuleOrPolicy: "route.lead_to_account",
+            });
+            counts.linkOperations += 1;
+        }
+        let ownerId = null;
+        let ownerRule;
+        if (inheritAccountOwner &&
+            matchedAccount?.ownerId &&
+            matchedAccount.ownerId !== contact.ownerId &&
+            (!contact.ownerId || reassignExistingOwner) &&
+            knownOwners.has(matchedAccount.ownerId)) {
+            ownerId = matchedAccount.ownerId;
+            ownerRule = "account-owner";
+        }
+        else if (options.assignmentPolicy && !contact.ownerId) {
+            const assigned = resolveAssignment(options.assignmentPolicy, routeContext(contact, matchedAccount), policyAssignmentIndex, knownOwners);
+            policyAssignmentIndex += 1;
+            ownerId = assigned.ownerId;
+            ownerRule = assigned.rule;
+            if (ownerId)
+                counts.policyAssigned += 1;
+        }
+        if (ownerId && ownerId !== contact.ownerId) {
+            contactOps.push({
+                id: `op_${stableHash(`route:owner:${contact.id}:${ownerId}`)}`,
+                objectType: "contact",
+                objectId: String(contact.id),
+                operation: "set_field",
+                field: "ownerId",
+                beforeValue: contact.ownerId ?? null,
+                afterValue: ownerId,
+                reason: options.reason ?? `Route contact owner by ${ownerRule ?? "policy"}${matchedAccount ? ` after matching account ${matchedAccount.name}` : ""}.`,
+                riskLevel: "medium",
+                approvalRequired: true,
+                sourceRuleOrPolicy: "route.owner_assignment",
+            });
+            counts.ownerOperations += 1;
+            counts.ownerAssigned = counts.ownerOperations;
+        }
+        if (contactOps.length > 1) {
+            const groupId = `grp_route_${contact.id}`;
+            for (const operation of contactOps)
+                operation.groupId = groupId;
+        }
+        operations.push(...contactOps);
+        if (!matchedAccount)
+            counts.unmatched += 1;
+    }
+    if (operations.length > maxOperations) {
+        throw new Error(`route would create ${operations.length} operations — above the ${maxOperations}-operation safety cap. Raise --max-operations after reviewing scope.`);
+    }
+    const plan = {
+        id: `patch_plan_${stableHash(`route:${snapshot.provider}:${snapshot.generatedAt}:${operations.map((op) => op.id).join(",")}`)}`,
+        title: "Route leads: match contacts to accounts and owners",
+        createdAt: snapshot.generatedAt,
+        status: operations.length > 0 ? "needs_approval" : "draft",
+        dryRun: true,
+        summary: `${counts.matchedContacts} matched contact(s), ${counts.linkOperations} lead-to-account link(s), ${counts.ownerOperations} owner assignment(s), ${counts.ambiguousAccountMatches} ambiguous match(es), ${counts.unmatched} unmatched contact(s). Dry-run only; approve before apply.`,
+        findings: [],
+        operations,
+    };
+    return { plan, counts };
+}

package/dist/rules.d.ts

@@ -34,4 +34,5 @@ export declare const duplicateOpenDealRule: GtmAuditRule;
 export declare const activeDealAccountWithoutContactsRule: GtmAuditRule;
 export declare const closingSoonInactiveRule: GtmAuditRule;
 export declare const accountSingleSourceRule: GtmAuditRule;
+export declare function isFindingsOnlyRule(rule: GtmAuditRule): boolean;
 export declare const builtinAuditRules: GtmAuditRule[];

package/dist/rules.js

@@ -36,6 +36,91 @@ export function auditFindingId(ruleId, objectId) {
 export function patchOperationId(ruleId, objectId) {
     return `op_${stableHash(`${ruleId}:${objectId}`)}`;
 }
+const OPEN_DEAL_FLAGS_ASSUMPTION = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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) {
+    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, idleDays) {
+    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, assumptions) {
+    return findings.length > 0 ? assumptions : undefined;
+}
 export function stableHash(value) {
     let hash = 0;
     for (let index = 0; index < value.length; index += 1) {
@@ -150,7 +235,11 @@ export const orphanAccountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [ORPHAN_ACCOUNT_RELATIONSHIP_ASSUMPTION]),
+        };
     },
 };
 export const missingDealOwnerRule = {
@@ -180,7 +269,11 @@ export const missingDealOwnerRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DEAL_OWNER_POLICY_ASSUMPTION]),
+        };
     },
 };
 export const missingDealAccountRule = {
@@ -210,7 +303,11 @@ export const missingDealAccountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DEAL_ACCOUNT_POLICY_ASSUMPTION]),
+        };
     },
 };
 export const pastCloseDateRule = {
@@ -240,7 +337,14 @@ export const pastCloseDateRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+            ]),
+        };
     },
 };
 export const staleDealRule = {
@@ -280,7 +384,15 @@ export const staleDealRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                staleDealPolicyAssumption(policy.staleDealDays),
+            ]),
+        };
     },
 };
 export const missingDealAmountRule = {
@@ -312,7 +424,15 @@ export const missingDealAmountRule = {
                 approvalRequired: true,
             });
         }
-        return { findings, operations };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                DEAL_AMOUNT_POLICY_ASSUMPTION,
+            ]),
+        };
     },
 };
 function duplicateGroups(items, keyOf) {
@@ -365,7 +485,11 @@ export const duplicateAccountDomainRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DUPLICATE_ACCOUNT_DOMAIN_ASSUMPTION]),
+        };
     },
 };
 export const duplicateContactEmailRule = {
@@ -402,7 +526,11 @@ export const duplicateContactEmailRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [DUPLICATE_CONTACT_EMAIL_ASSUMPTION]),
+        };
     },
 };
 export const duplicateOpenDealRule = {
@@ -449,7 +577,15 @@ export const duplicateOpenDealRule = {
                 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 };
+        return {
+            findings,
+            operations,
+            assumptions: assumptionsIfFindings(findings, [
+                OPEN_DEAL_FLAGS_ASSUMPTION,
+                MISSING_CLOSED_WON_FLAGS_ASSUMPTION,
+                DUPLICATE_OPEN_DEAL_ASSUMPTION,
+            ]),
+        };
     },
 };
 export const activeDealAccountWithoutContactsRule = {
@@ -491,7 +627,15 @@ export const activeDealAccountWithoutContactsRule = {
                 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,
+            ]),
+        };
     },
 };
 export const closingSoonInactiveRule = {
@@ -536,12 +680,21 @@ export const closingSoonInactiveRule = {
                 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 = {
     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",
     evaluate: ({ snapshot }) => {
@@ -566,9 +719,16 @@ export const accountSingleSourceRule = {
                 recommendation: "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) {
+    return rule.emitsOperations === false;
+}
 export const builtinAuditRules = [
     orphanAccountRule,
     missingDealOwnerRule,

package/dist/types.d.ts

@@ -58,6 +58,13 @@ export type CreateRecordPayload = {
     dealPipeline?: string;
 };
 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.
@@ -323,6 +330,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
@@ -374,6 +385,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[];
 };
 /**
  * A deterministic audit rule. Rules read the snapshot through the context and
@@ -385,6 +398,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;
 };
 export type PatchOperationResult = {
@@ -435,6 +450,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

package/docs/api.md

@@ -37,9 +37,10 @@ release.
 
 ## Connectors
 
-- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, readField?, fetchChanges? }`.
+- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, applyBatch?, applyBatchLimit?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
+  - `applyBatch?(operations)` — optional bulk apply path for consecutive homogeneous `set_field`, `clear_field`, or `archive_record` runs selected by `applyPatchPlan`. It must return one result per input operation; field-write implementations preserve CAS by batch-reading live target values first and writing only clean records. Connectors without it stay on the sequential `applyOperation` path. `applyBatchLimit?` declares max operations per `applyBatch` call (default 200; Salesforce 200, HubSpot 100). Salesforce uses SOQL `IN` CAS reads plus Composite sObject Collections update/delete (`allOrNone:false`); HubSpot uses batch/read + batch/update/archive.
   - `applyCreateContactsBatch?(operations)` — optional bulk fast-path for
     independent `create_record` contact ops. `applyPatchPlan` routes safe-to-batch
     creates here (batched resolve-first + batched create — ~N/100 calls instead of
@@ -68,7 +69,8 @@ release.
 Commands: `init`, `login` / `logout`, `snapshot`, `audit`, `report`, `diff`, `merge`, `plans`,
 `apply`, `suggest`, `audit-log` (`export` / `verify`),
 `call` (`parse` / `classify` / `score` / `link` / `plan`), `resolve`,
-`bulk-update`, `dedupe`, `reassign`, `fix`, `health`,
+`hierarchy` (`report`), `relationships` (`account`),
+`route` (`leads`), `bulk-update`, `dedupe`, `reassign`, `fix`, `health`,
 `market` (`init` / `capture` / `classify` / `worksheet` / `observe` / `fronts` /
 `axes` / `overlay` / `scale` / `report` / `refresh`),
 `tam` (`estimate` / `accounts` / `status` / `report` / `populate`),
@@ -159,8 +161,8 @@ per-rule detail with capped examples, and next steps. `auditReportToMarkdown` /
 
 ## Governed write verbs
 
-Plan builders behind `bulk-update`, `dedupe`, and `reassign` — every one
-emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
+Plan builders behind `route`, `bulk-update`, `dedupe`, and `reassign` — every
+one emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
 
 - `buildBulkUpdatePlan(snapshot, options: BulkUpdateOptions)` with
   `parseWhere` (filter expressions: `=`, `!=`, `~`, `!~`, `:empty`,
@@ -178,6 +180,22 @@ emits a standard dry-run `PatchPlan` for the normal approve → apply chain:
   `assignUnowned` (CLI `--assign-unowned`) it targets ownerless records
   (`ownerId:empty`) and claims them for `--to` — the backfill twin of
   `enrich acquire`'s create-time assignment, for clearing existing ownerless debt.
+- `buildLeadRoutePlan(snapshot, options: LeadRouteOptions)` — matches contacts
+  to accounts by email domain and optional company-name fallback, skips free
+  email domains and ambiguous matches, then emits approval-gated account-link
+  and owner-assignment operations. Owner routing can inherit active account
+  owners for ownerless contacts or use the shared deterministic
+  `AssignmentPolicy`; existing owners are preserved unless
+  `reassignExistingOwner` (CLI `--reassign-owned`) is set.
+
+Read-only prevention reports:
+
+- `buildAccountHierarchy(snapshot)` / `accountHierarchyToMarkdown(report)` —
+  provider parent hints plus subdomain inference, with duplicate-domain,
+  ambiguous-parent, and parent-cycle conflicts surfaced rather than written.
+- `buildRelationshipMap(snapshot, { accountId | domain })` /
+  `relationshipMapToMarkdown(map)` — account stakeholders, inferred roles,
+  activity sentiment evidence, open deals, and missing-role gaps.
 
 `fix` is CLI-only composition of existing surfaces (audit → suggest →
 approve → apply for one rule).

package/docs/architecture.md

@@ -57,9 +57,12 @@ provider  ──fetchSnapshot()──►  CanonicalGtmSnapshot
 - `auditLog.ts` — hash-chained, signed export of every apply run.
 
 **Governed write verbs (each builds a plan; never writes directly)**
-- `bulkUpdate.ts`, `dedupe.ts`, `reassign.ts` — filtered/duplicate/ownership
-  plan builders. `merge.ts` — snapshot diff/merge + entity resolution.
+- `bulkUpdate.ts`, `dedupe.ts`, `reassign.ts`, `route.ts` — filtered,
+  duplicate, ownership handoff, and lead-to-account/owner routing plan builders.
+  `merge.ts` — snapshot diff/merge + entity resolution.
 - `resolve.ts` — the create-gate (exists / ambiguous / safe_to_create).
+- `hierarchy.ts`, `relationships.ts` — read-only account hierarchy and
+  stakeholder relationship-map reports for planning/prevention workflows.
 
 **Connectors** (`connectors/`)
 - `hubspot.ts`, `salesforce.ts`, `stripe.ts` + their `*Auth.ts` OAuth/device

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.46.0",
+  "version": "0.48.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/skills/fullstackgtm/SKILL.md

@@ -94,7 +94,7 @@ Tools over stdio: `fullstackgtm_audit` (read-only), `fullstackgtm_rules`,
 This CLI ships governed **primitives** — there is no `outbound` mega-command.
 **You (the agent) are the orchestrator:** chain these verbs into the play the
 operator wants, surface the one approve gate, and bridge the last mile to the
-sender (**the package never sends**). [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md)
+sender (**the package never sends**). [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md)
 has five worked plays — cold-start lead-fill, the trigger→judge→draft outbound
 loop, scheduled-continuous, ABM-from-companies, and hygiene-gated outbound.
 `fullstackgtm init` scaffolds a workspace (icp.json + enrich config + a PLAYBOOK
@@ -102,7 +102,7 @@ pointing at those recipes) to start from.
 
 ## Going deeper
 
-- [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/packages/fullstackgtm/docs/recipes.md) — five composable GTM plays over the primitives (cold-start, outbound loop, scheduled, ABM, hygiene-gated)
+- [docs/recipes.md](https://github.com/fullstackgtm/core/blob/main/docs/recipes.md) — five composable GTM plays over the primitives (cold-start, outbound loop, scheduled, ABM, hygiene-gated)
 - [llms.txt](https://github.com/fullstackgtm/core/blob/main/llms.txt) — the full invariant map per layer (calls, market, write verbs, enrich, schedule, engagement/health)
 - [INSTALL_FOR_AGENTS.md](https://github.com/fullstackgtm/core/blob/main/INSTALL_FOR_AGENTS.md) — deterministic install-and-verify with expected outputs
 - [docs/api.md](https://github.com/fullstackgtm/core/blob/main/docs/api.md) — semver-covered surfaces: canonical model, rule interface, plan/apply contract, connectors, config, CLI, MCP