fullstackgtm 0.46.0 → 0.48.0

package/src/connectors/hubspot.ts

@@ -24,6 +24,8 @@ import { SNAPSHOT_PULL_STAGES, type ProgressEmitter } from "../progress.ts";
 
 const DEFAULT_API_BASE_URL = "https://api.hubapi.com";
 
+export type HubspotWritableConnector = GtmConnector & Required<Pick<GtmConnector, "applyOperation" | "readField">>;
+
 export type HubspotConnectorOptions = {
   /** Returns a HubSpot access token (private app token or OAuth access token). */
   getAccessToken: () => string | Promise<string>;
@@ -71,7 +73,7 @@ const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHO
  * amountless deals — so audit rules can surface the gaps instead of hiding
  * them.
  */
-export function createHubspotConnector(options: HubspotConnectorOptions): Required<GtmConnector> {
+export function createHubspotConnector(options: HubspotConnectorOptions): HubspotWritableConnector {
   const baseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/$/, "");
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
@@ -1195,6 +1197,164 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
+  function fieldMapping(operation: PatchOperation): { objectPath: string; property: string } | null {
+    const objectPath = OBJECT_PATHS[operation.objectType];
+    const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+    if (!objectPath || !mappingType || !operation.field) return null;
+    const defaults = HUBSPOT_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+    return { objectPath, property: mappedField(mappings, mappingType, operation.field, defaults[operation.field] ?? operation.field) };
+  }
+
+  function normalizeHubspotReadValue(field: string | undefined, value: unknown): unknown {
+    if (field === "closeDate" && typeof value === "string") return value.split("T")[0];
+    return value ?? null;
+  }
+
+  function normalizeForComparison(value: unknown): string | null {
+    if (value === undefined || value === null || value === "") return null;
+    return String(value);
+  }
+
+  function batchErrorIds(error: any): string[] {
+    const context = error?.context ?? {};
+    const ids = context.ids ?? context.id ?? error?.id ?? error?.objectId;
+    if (Array.isArray(ids)) return ids.map(String);
+    if (ids !== undefined && ids !== null) return [String(ids)];
+    return [];
+  }
+
+  function batchErrorDetail(error: any): string {
+    const category = error?.category ? `${String(error.category)}: ` : "";
+    return `${category}${String(error?.message ?? "HubSpot batch row failed.")}`;
+  }
+
+  async function applySetFieldBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const out = new Map<string, PatchOperationResult>();
+    const mapped = operations.map((operation) => ({ operation, mapping: fieldMapping(operation) }));
+    for (const item of mapped) {
+      if (!item.mapping) {
+        out.set(item.operation.id, {
+          operationId: item.operation.id,
+          status: "skipped",
+          detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+        });
+      }
+    }
+    const clean = mapped.filter((item): item is { operation: PatchOperation; mapping: { objectPath: string; property: string } } => Boolean(item.mapping));
+    if (clean.length === 0) return operations.map((operation) => out.get(operation.id)!);
+    const objectPath = clean[0].mapping.objectPath;
+    const properties = [...new Set(clean.map((item) => item.mapping.property))];
+    const liveById = new Map<string, Record<string, unknown>>();
+    const ids = [...new Set(clean.map((item) => item.operation.objectId))];
+    for (let i = 0; i < ids.length; i += 100) {
+      const chunkIds = ids.slice(i, i + 100);
+      const data = await request(`/crm/v3/objects/${objectPath}/batch/read`, {
+        method: "POST",
+        body: JSON.stringify({ properties, inputs: chunkIds.map((id) => ({ id })) }),
+      });
+      for (const row of data?.results ?? []) {
+        if (row?.id) liveById.set(String(row.id), row.properties ?? {});
+      }
+    }
+
+    const toWrite: Array<{ operation: PatchOperation; property: string }> = [];
+    for (const { operation, mapping } of clean) {
+      const props = liveById.get(operation.objectId);
+      const current = normalizeHubspotReadValue(operation.field, props?.[mapping.property] ?? null);
+      const expected = normalizeForComparison(operation.beforeValue);
+      const found = normalizeForComparison(current);
+      if (!props || expected !== found) {
+        out.set(operation.id, {
+          operationId: operation.id,
+          status: "conflict",
+          detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+          providerData: { currentValue: current ?? null },
+        });
+        continue;
+      }
+      toWrite.push({ operation, property: mapping.property });
+    }
+
+    for (let i = 0; i < toWrite.length; i += 100) {
+      const chunk = toWrite.slice(i, i + 100);
+      let data: any;
+      try {
+        data = await request(`/crm/v3/objects/${objectPath}/batch/update`, {
+          method: "POST",
+          body: JSON.stringify({
+            inputs: chunk.map(({ operation, property }) => ({
+              id: operation.objectId,
+              properties: { [property]: operation.operation === "clear_field" ? "" : String(operation.afterValue ?? "") },
+            })),
+          }),
+        });
+      } catch (error) {
+        for (const { operation } of chunk) out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
+      const opByObjectId = new Map(chunk.map(({ operation }) => [operation.objectId, operation]));
+      for (const error of data?.errors ?? []) {
+        for (const id of batchErrorIds(error)) {
+          const operation = opByObjectId.get(id);
+          if (operation) out.set(operation.id, { operationId: operation.id, status: "failed", detail: batchErrorDetail(error) });
+        }
+      }
+      for (const result of data?.results ?? []) {
+        const operation = opByObjectId.get(String(result?.id));
+        if (operation && !out.has(operation.id)) out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Set ${chunk.find((item) => item.operation.id === operation.id)?.property ?? "field"} on ${objectPath}/${operation.objectId}.`, providerData: { id: result?.id } });
+      }
+      for (const { operation, property } of chunk) {
+        if (!out.has(operation.id)) out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Set ${property} on ${objectPath}/${operation.objectId}.` });
+      }
+    }
+    return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch update did not process this operation." });
+  }
+
+  async function applyArchiveBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const objectPath = OBJECT_PATHS[operations[0]?.objectType];
+    if (!objectPath) return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "archive_record is supported for accounts, contacts, and deals." }));
+    const out = new Map<string, PatchOperationResult>();
+    for (let i = 0; i < operations.length; i += 100) {
+      const chunk = operations.slice(i, i + 100);
+      let data: any;
+      try {
+        data = await request(`/crm/v3/objects/${objectPath}/batch/archive`, {
+          method: "POST",
+          body: JSON.stringify({ inputs: chunk.map((operation) => ({ id: operation.objectId })) }),
+        });
+      } catch (error) {
+        for (const operation of chunk) out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
+      const opByObjectId = new Map(chunk.map((operation) => [operation.objectId, operation]));
+      for (const error of data?.errors ?? []) {
+        for (const id of batchErrorIds(error)) {
+          const operation = opByObjectId.get(id);
+          if (operation) out.set(operation.id, { operationId: operation.id, status: "failed", detail: batchErrorDetail(error) });
+        }
+      }
+      for (const result of data?.results ?? []) {
+        const operation = opByObjectId.get(String(result?.id));
+        if (operation && !out.has(operation.id)) out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Archived ${objectPath}/${operation.objectId}.` });
+      }
+      for (const operation of chunk) {
+        if (!out.has(operation.id)) out.set(operation.id, { operationId: operation.id, status: "applied", detail: `Archived ${objectPath}/${operation.objectId}.` });
+      }
+    }
+    return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch archive did not process this operation." });
+  }
+
+  async function applyBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    if (operations.length === 0) return [];
+    if (operations.every((operation) => (operation.operation === "set_field" || operation.operation === "clear_field") && operation.objectType === operations[0].objectType)) {
+      return applySetFieldBatch(operations);
+    }
+    if (operations.every((operation) => operation.operation === "archive_record" && operation.objectType === operations[0].objectType)) {
+      return applyArchiveBatch(operations);
+    }
+    return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "This mixed operation batch is not supported." }));
+  }
+
   /**
    * Merge a duplicate group into the approved survivor via HubSpot's v3
    * merge API (supported for contacts, companies, deals, and tickets).
@@ -1335,10 +1495,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     // single-object read here returns HubSpot's raw "2026-03-07T00:00:00Z", which
     // made compare-and-set see a spurious drift and refuse every date-field write.
     // Mirror the snapshot's normalization so the comparison is apples-to-apples.
-    if (field === "closeDate" && typeof value === "string") {
-      return value.split("T")[0];
-    }
-    return value;
+    return normalizeHubspotReadValue(field, value);
   }
 
   return {
@@ -1347,6 +1504,8 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     fetchChanges,
     applyOperation,
     applyCreateContactsBatch,
+    applyBatch,
+    applyBatchLimit: 100,
     readField,
   };
 }

package/src/connectors/salesforce.ts

@@ -29,6 +29,8 @@ export type SalesforceConnection = {
   instanceUrl: string;
 };
 
+export type SalesforceWritableConnector = GtmConnector & Required<Pick<GtmConnector, "applyOperation" | "readField">>;
+
 export type SalesforceConnectorOptions = {
   /** Returns an access token plus the instance URL it belongs to. */
   getConnection: () => SalesforceConnection | Promise<SalesforceConnection>;
@@ -86,7 +88,7 @@ const PULL_STAGE_BY_TYPE: Record<SnapshotProgress["objectType"], (typeof SNAPSHO
  */
 export function createSalesforceConnector(
   options: SalesforceConnectorOptions,
-): Required<GtmConnector> {
+): SalesforceWritableConnector {
   const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
   const fetchImpl = options.fetchImpl ?? fetch;
   const mappings = options.fieldMappings;
@@ -489,6 +491,137 @@ export function createSalesforceConnector(
     };
   }
 
+  function normalizeSalesforceValue(value: unknown): string | null {
+    if (value === undefined || value === null || value === "") return null;
+    return String(value).split("T")[0];
+  }
+
+  function fieldMappingFor(operation: PatchOperation): { sobjectType: string; field: string } | null {
+    const sobjectType = SOBJECT_TYPES[operation.objectType];
+    const mappingType = MAPPING_OBJECT_TYPES[operation.objectType];
+    if (!sobjectType || !mappingType || !operation.field) return null;
+    const defaults = SALESFORCE_DEFAULT_FIELD_MAPPINGS[mappingType] ?? {};
+    return {
+      sobjectType,
+      field: mappedField(mappings, mappingType, operation.field, defaults[operation.field] ?? operation.field),
+    };
+  }
+
+  function compositeErrorDetail(result: any): string {
+    const errors = Array.isArray(result?.errors) ? result.errors : [];
+    const message = errors
+      .map((error: any) => [error?.statusCode, error?.message].filter(Boolean).join(": "))
+      .filter(Boolean)
+      .join("; ");
+    return message ? `Salesforce rejected this record: ${message.slice(0, 300)}.` : "Salesforce rejected this record.";
+  }
+
+  async function applySetFieldBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const out = new Map<string, PatchOperationResult>();
+    const mapped = operations.map((operation) => ({ operation, mapping: fieldMappingFor(operation) }));
+    for (const item of mapped) {
+      if (!item.mapping) {
+        out.set(item.operation.id, {
+          operationId: item.operation.id,
+          status: "skipped",
+          detail: "Field writes are only supported for accounts, contacts, and deals with an explicit field.",
+        });
+      }
+    }
+    const clean = mapped.filter((item): item is { operation: PatchOperation; mapping: { sobjectType: string; field: string } } => Boolean(item.mapping));
+    if (clean.length === 0) return operations.map((operation) => out.get(operation.id)!);
+    const sobjectType = clean[0].mapping.sobjectType;
+    const fields = [...new Set(clean.map((item) => item.mapping.field))];
+    const liveById = new Map<string, Record<string, unknown>>();
+    const ids = [...new Set(clean.map((item) => item.operation.objectId))];
+    for (let i = 0; i < ids.length; i += 200) {
+      const idList = ids.slice(i, i + 200).map((id) => `'${id.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`).join(",");
+      const rows = await query(`SELECT Id, ${fields.join(", ")} FROM ${sobjectType} WHERE Id IN (${idList})`);
+      for (const row of rows) liveById.set(String(row.Id), row);
+    }
+
+    const toWrite: Array<{ operation: PatchOperation; field: string }> = [];
+    for (const { operation, mapping } of clean) {
+      const row = liveById.get(operation.objectId);
+      const current = row?.[mapping.field] ?? null;
+      const expected = normalizeSalesforceValue(operation.beforeValue);
+      const found = normalizeSalesforceValue(current);
+      if (!row || expected !== found) {
+        out.set(operation.id, {
+          operationId: operation.id,
+          status: "conflict",
+          detail: `Value drifted since the plan was proposed: expected ${expected ?? "∅"}, found ${found ?? "∅"}. Re-run the audit.`,
+          providerData: { currentValue: current ?? null },
+        });
+        continue;
+      }
+      toWrite.push({ operation, field: mapping.field });
+    }
+
+    for (let i = 0; i < toWrite.length; i += 200) {
+      const chunk = toWrite.slice(i, i + 200);
+      const records = chunk.map(({ operation, field }) => ({
+        attributes: { type: sobjectType },
+        Id: operation.objectId,
+        [field]: operation.operation === "clear_field" ? null : String(operation.afterValue ?? ""),
+      }));
+      let response: any[];
+      try {
+        response = (await request(`/services/data/${apiVersion}/composite/sobjects`, {
+          method: "PATCH",
+          body: JSON.stringify({ allOrNone: false, records }),
+        })) as any[];
+      } catch (error) {
+        for (const { operation } of chunk) out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
+      for (let j = 0; j < chunk.length; j++) {
+        const { operation, field } = chunk[j];
+        const result = Array.isArray(response) ? response[j] : undefined;
+        out.set(operation.id, result?.success
+          ? { operationId: operation.id, status: "applied", detail: `Set ${field} on ${sobjectType}/${operation.objectId}.`, providerData: { sobjectType, field } }
+          : { operationId: operation.id, status: "failed", detail: compositeErrorDetail(result) });
+      }
+    }
+    return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch update did not process this operation." });
+  }
+
+  async function applyArchiveBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const sobjectType = SOBJECT_TYPES[operations[0]?.objectType];
+    if (!sobjectType) return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "archive_record is supported for accounts, contacts, and deals." }));
+    const out = new Map<string, PatchOperationResult>();
+    for (let i = 0; i < operations.length; i += 200) {
+      const chunk = operations.slice(i, i + 200);
+      const ids = chunk.map((operation) => encodeURIComponent(operation.objectId)).join(",");
+      let response: any[];
+      try {
+        response = (await request(`/services/data/${apiVersion}/composite/sobjects?ids=${ids}&allOrNone=false`, { method: "DELETE" })) as any[];
+      } catch (error) {
+        for (const operation of chunk) out.set(operation.id, { operationId: operation.id, status: "failed", detail: error instanceof Error ? error.message : String(error) });
+        continue;
+      }
+      for (let j = 0; j < chunk.length; j++) {
+        const operation = chunk[j];
+        const result = Array.isArray(response) ? response[j] : undefined;
+        out.set(operation.id, result?.success
+          ? { operationId: operation.id, status: "applied", detail: `Deleted ${sobjectType}/${operation.objectId}.` }
+          : { operationId: operation.id, status: "failed", detail: compositeErrorDetail(result) });
+      }
+    }
+    return operations.map((operation) => out.get(operation.id) ?? { operationId: operation.id, status: "failed", detail: "Batch delete did not process this operation." });
+  }
+
+  async function applyBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    if (operations.length === 0) return [];
+    if (operations.every((operation) => (operation.operation === "set_field" || operation.operation === "clear_field") && operation.objectType === operations[0].objectType)) {
+      return applySetFieldBatch(operations);
+    }
+    if (operations.every((operation) => operation.operation === "archive_record" && operation.objectType === operations[0].objectType)) {
+      return applyArchiveBatch(operations);
+    }
+    return operations.map((operation) => ({ operationId: operation.id, status: "skipped", detail: "This mixed operation batch is not supported." }));
+  }
+
   function escapeXml(value: string): string {
     return value
       .replace(/&/g, "&amp;")
@@ -869,6 +1002,8 @@ export function createSalesforceConnector(
     fetchChanges,
     applyOperation,
     applyCreateContactsBatch,
+    applyBatch,
+    applyBatchLimit: 200,
     readField,
   };
 }

package/src/connectors/signalSources.ts

@@ -21,6 +21,7 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
+import { FREE_EMAIL_DOMAINS } from "../freeEmailDomains.ts";
 import type { SignalBucket, StagedSignalRow } from "../signals.ts";
 import { SIGNAL_BUCKETS } from "../signals.ts";
 import { parseSpoolText, spoolFilesIn } from "../spoolFiles.ts";
@@ -294,21 +295,10 @@ function fieldValue(values: Array<{ name?: string; value?: string }> | undefined
   return "";
 }
 
-const FREE_MAIL = new Set([
-  "gmail.com",
-  "yahoo.com",
-  "hotmail.com",
-  "outlook.com",
-  "icloud.com",
-  "aol.com",
-  "proton.me",
-  "protonmail.com",
-]);
-
 /** Company domain from an email, or "" for free-mail / no email. */
 function corporateDomain(email: string): string {
   if (!email.includes("@")) return "";
   const domain = email.split("@").at(-1)!.trim().toLowerCase();
-  if (!domain || FREE_MAIL.has(domain)) return "";
+  if (!domain || FREE_EMAIL_DOMAINS.has(domain)) return "";
   return domain;
 }

package/src/format.ts

@@ -1,10 +1,9 @@
 import type { PatchPlan, PatchPlanRun } from "./types.ts";
 
-// `summary: true` renders only the header + the Findings-by-Rule table + an
-// operation count, for read verbs like `audit` where the full per-operation
-// dump (1,400+ lines on a real portal) buries the signal. Defaults to the full
-// view so write-preview callers (bulk-update, fix, dedupe, plans show, MCP) —
-// where you approve specific operations — keep every operation's detail.
+// `summary: true` renders the compact audit view: header, findings summary,
+// assumptions/open questions, and an operation count. Defaults to the full view
+// so write-preview callers (bulk-update, fix, dedupe, plans show, MCP) — where
+// you approve specific operations — keep every operation's detail.
 export function patchPlanToMarkdown(plan: PatchPlan, opts: { summary?: boolean } = {}) {
   const lines = [
     `# ${plan.title}`,
@@ -29,6 +28,8 @@ export function patchPlanToMarkdown(plan: PatchPlan, opts: { summary?: boolean }
     lines.push("");
   }
 
+  appendAssumptionsAndDecisionPoints(lines, plan);
+
   if (opts.summary) {
     const ops = plan.operations.length;
     lines.push(
@@ -155,6 +156,33 @@ export function formatPatchPlanRun(run: PatchPlanRun) {
   return `${lines.join("\n")}\n`;
 }
 
+
+function appendAssumptionsAndDecisionPoints(lines: string[], plan: PatchPlan) {
+  const assumptions = [...(plan.assumptions ?? [])].sort((left, right) => {
+    if (left.confidence === "guess" && right.confidence !== "guess") return -1;
+    if (left.confidence !== "guess" && right.confidence === "guess") return 1;
+    return 0;
+  });
+  const openQuestions = plan.openQuestions ?? [];
+  if (assumptions.length === 0 && openQuestions.length === 0) return;
+
+  lines.push("## Assumptions & decision points", "");
+  for (const assumption of assumptions) {
+    const warning = assumption.confidence === "guess" ? "⚠️ " : "";
+    lines.push(`- ${warning}${assumption.text}${assumption.source ? ` _(source: ${assumption.source})_` : ""}`);
+  }
+
+  if (openQuestions.length > 0) {
+    if (assumptions.length > 0) lines.push("");
+    lines.push("### Open questions", "");
+    for (const question of openQuestions) {
+      lines.push(`- ${question}`);
+    }
+  }
+
+  lines.push("");
+}
+
 function formatValue(value: unknown) {
   if (value === undefined || value === null || value === "") return "unset";
   if (typeof value === "string") return value;

package/src/freeEmailDomains.ts

@@ -0,0 +1,14 @@
+// Shared free-mail domains that should never be treated as company domains.
+export const FREE_EMAIL_DOMAINS = new Set([
+  "gmail.com",
+  "googlemail.com",
+  "yahoo.com",
+  "outlook.com",
+  "hotmail.com",
+  "live.com",
+  "icloud.com",
+  "me.com",
+  "aol.com",
+  "proton.me",
+  "protonmail.com",
+]);

package/src/hierarchy.ts

@@ -0,0 +1,185 @@
+import { normalizeDomain } from "./merge.ts";
+import type { CanonicalAccount, CanonicalGtmSnapshot } from "./types.ts";
+
+export type AccountHierarchyNode = {
+  accountId: string;
+  name: string;
+  domain?: string;
+  parentAccountId?: string;
+  parentReason?: string;
+  children: AccountHierarchyNode[];
+};
+
+export type AccountHierarchyConflict = {
+  type: "duplicate_domain" | "ambiguous_parent" | "cycle";
+  accountIds: string[];
+  key: string;
+  detail: string;
+};
+
+export type AccountHierarchyReport = {
+  generatedAt: string;
+  roots: AccountHierarchyNode[];
+  orphanAccounts: string[];
+  conflicts: AccountHierarchyConflict[];
+  counts: { accounts: number; roots: number; linkedChildren: number; conflicts: number };
+};
+
+function rawString(account: CanonicalAccount, keys: string[]): string | undefined {
+  if (!account.raw || typeof account.raw !== "object") return undefined;
+  const raw = account.raw as Record<string, unknown>;
+  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 as Record<string, unknown>;
+      for (const nestedKey of ["id", "value", "name"]) {
+        if (typeof nested[nestedKey] === "string" && String(nested[nestedKey]).trim()) return String(nested[nestedKey]).trim();
+      }
+    }
+  }
+  return undefined;
+}
+
+function parentHint(account: CanonicalAccount): string | undefined {
+  return rawString(account, ["parentAccountId", "parent_account_id", "ParentId", "parentCompanyId", "hs_parent_company_id"]);
+}
+
+function cloneNode(account: CanonicalAccount): AccountHierarchyNode {
+  return { accountId: String(account.id), name: account.name, ...(account.domain ? { domain: account.domain } : {}), children: [] };
+}
+
+function looksLikePublicSuffix(domain: string): boolean {
+  const parts = domain.split(".");
+  if (parts.length !== 2) return false;
+  const [label, tld] = parts;
+  return tld.length === 2 && ["ac", "co", "com", "edu", "gov", "net", "org"].includes(label);
+}
+
+function domainParent(childDomain: string, domains: Map<string, CanonicalAccount[]>): CanonicalAccount | "ambiguous" | null {
+  const parts = childDomain.split(".");
+  for (let i = 1; i < parts.length - 1; i++) {
+    const candidate = parts.slice(i).join(".");
+    if (candidate.split(".").length < 2 || looksLikePublicSuffix(candidate)) continue;
+    const unique = new Map((domains.get(candidate) ?? []).map((account) => [String(account.id), account]));
+    if (unique.size > 1) return "ambiguous";
+    if (unique.size === 1) return [...unique.values()][0];
+  }
+  return null;
+}
+
+function detectCycles(parentByChild: Map<string, { parentId: string; reason: string }>): { accountIds: Set<string>; cycles: string[][] } {
+  const cyclic = new Set<string>();
+  const cycles: string[][] = [];
+  const emitted = new Set<string>();
+
+  for (const start of parentByChild.keys()) {
+    const path: string[] = [];
+    const indexById = new Map<string, number>();
+    let cursor: string | undefined = start;
+    while (cursor && parentByChild.has(cursor)) {
+      const seenAt = indexById.get(cursor);
+      if (seenAt !== undefined) {
+        const cycle = path.slice(seenAt);
+        for (const id of cycle) cyclic.add(id);
+        const key = [...cycle].sort().join("|");
+        if (!emitted.has(key)) {
+          emitted.add(key);
+          cycles.push(cycle);
+        }
+        break;
+      }
+      indexById.set(cursor, path.length);
+      path.push(cursor);
+      cursor = parentByChild.get(cursor)?.parentId;
+    }
+  }
+
+  return { accountIds: cyclic, cycles };
+}
+
+export function buildAccountHierarchy(snapshot: CanonicalGtmSnapshot): AccountHierarchyReport {
+  const byId = new Map(snapshot.accounts.map((account) => [String(account.id), account]));
+  const accounts = [...byId.values()];
+  const domains = new Map<string, CanonicalAccount[]>();
+  for (const account of accounts) {
+    const domain = normalizeDomain(account.domain);
+    if (domain) domains.set(domain, [...(domains.get(domain) ?? []), account]);
+  }
+
+  const conflicts: AccountHierarchyConflict[] = [];
+  for (const [domain, accounts] of domains) {
+    const ids = [...new Set(accounts.map((account) => String(account.id)))];
+    if (ids.length > 1) conflicts.push({ type: "duplicate_domain", accountIds: ids.sort(), key: domain, detail: `${ids.length} accounts share domain ${domain}; hierarchy inference will not choose between them.` });
+  }
+
+  const nodes = new Map(accounts.map((account) => [String(account.id), cloneNode(account)]));
+  const parentByChild = new Map<string, { parentId: string; reason: string }>();
+  for (const account of accounts) {
+    const id = String(account.id);
+    const hint = parentHint(account);
+    if (hint && byId.has(hint) && hint !== id) {
+      parentByChild.set(id, { parentId: hint, reason: "provider-parent" });
+      continue;
+    }
+    const domain = normalizeDomain(account.domain);
+    if (!domain) continue;
+    const inferred = domainParent(domain, domains);
+    if (inferred === "ambiguous") conflicts.push({ type: "ambiguous_parent", accountIds: [id], key: domain, detail: `Multiple possible parent accounts found for ${domain}; leaving account as a root.` });
+    else if (inferred && String(inferred.id) !== id) parentByChild.set(id, { parentId: String(inferred.id), reason: "domain-subdomain" });
+  }
+
+  const cyclicAccounts = detectCycles(parentByChild);
+  for (const cycle of cyclicAccounts.cycles) {
+    const ordered = [...cycle].sort();
+    const key = ordered.join(" -> ");
+    conflicts.push({
+      type: "cycle",
+      accountIds: ordered,
+      key,
+      detail: `Cyclic parent hints detected among ${ordered.join(", ")}; leaving those accounts as roots instead of hiding them in a loop.`,
+    });
+  }
+  for (const accountId of cyclicAccounts.accountIds) parentByChild.delete(accountId);
+
+  const roots: AccountHierarchyNode[] = [];
+  const orphanAccounts: string[] = [];
+  const linkedChildren = new Set<string>();
+  for (const account of accounts) {
+    const id = String(account.id);
+    const node = nodes.get(id)!;
+    const parent = parentByChild.get(id);
+    if (parent && nodes.has(parent.parentId)) {
+      node.parentAccountId = parent.parentId;
+      node.parentReason = parent.reason;
+      nodes.get(parent.parentId)!.children.push(node);
+      linkedChildren.add(id);
+    } else {
+      roots.push(node);
+      if (!account.domain && !parentHint(account)) orphanAccounts.push(id);
+    }
+  }
+  const sortTree = (list: AccountHierarchyNode[]) => {
+    list.sort((a, b) => a.name.localeCompare(b.name) || a.accountId.localeCompare(b.accountId));
+    for (const node of list) sortTree(node.children);
+  };
+  sortTree(roots);
+  return { generatedAt: snapshot.generatedAt, roots, orphanAccounts: orphanAccounts.sort(), conflicts, counts: { accounts: accounts.length, roots: roots.length, linkedChildren: linkedChildren.size, conflicts: conflicts.length } };
+}
+
+export function accountHierarchyToMarkdown(report: AccountHierarchyReport): string {
+  const lines = ["# Account hierarchy", "", `${report.counts.accounts} account(s), ${report.counts.roots} root(s), ${report.counts.linkedChildren} inferred child link(s), ${report.counts.conflicts} conflict(s).`, ""];
+  const walk = (nodes: AccountHierarchyNode[], depth: number) => {
+    for (const node of nodes) {
+      const suffix = [node.domain, node.parentReason ? `via ${node.parentReason}` : undefined].filter(Boolean).join("; ");
+      lines.push(`${"  ".repeat(depth)}- ${node.name} (${node.accountId}${suffix ? ` — ${suffix}` : ""})`);
+      walk(node.children, depth + 1);
+    }
+  };
+  walk(report.roots, 0);
+  if (report.conflicts.length) {
+    lines.push("", "## Conflicts");
+    for (const conflict of report.conflicts) lines.push(`- ${conflict.type} ${conflict.key}: ${conflict.detail}`);
+  }
+  return lines.join("\n");
+}