fullstackgtm 0.14.0 → 0.15.0

package/dist/types.d.ts

@@ -83,11 +83,25 @@ export type CanonicalUser = {
     title?: string;
     active?: boolean;
 };
+/**
+ * Who created a record, per the provider's read-only record-source fields
+ * (HubSpot: hs_object_source / _label / _id). Populated on read; used to
+ * attribute duplicate findings to the writer that produced them.
+ */
+export type RecordProvenance = {
+    /** Provider source code, e.g. INTEGRATION, API, CRM_UI, IMPORT, FORM. */
+    source?: string;
+    /** Human label, e.g. an integration's name. */
+    sourceLabel?: string;
+    /** Provider-side id of the source (e.g. app id, import id). */
+    sourceId?: string;
+};
 export type CanonicalAccount = {
     id: string;
     provider?: CrmProvider;
     crmId?: string;
     identities?: ProviderIdentity[];
+    provenance?: RecordProvenance;
     name: string;
     domain?: string;
     industry?: string;
@@ -104,6 +118,7 @@ export type CanonicalContact = {
     provider?: CrmProvider;
     crmId?: string;
     identities?: ProviderIdentity[];
+    provenance?: RecordProvenance;
     accountId?: string;
     firstName?: string;
     lastName?: string;
@@ -121,6 +136,7 @@ export type CanonicalDeal = {
     provider?: CrmProvider;
     crmId?: string;
     identities?: ProviderIdentity[];
+    provenance?: RecordProvenance;
     accountId?: string;
     ownerId?: string;
     name: string;

package/docs/crm-health-lifecycle.md

@@ -41,12 +41,11 @@ fix the faucet instead of mopping the puddle.
   a unique match, refuse on ambiguity, create only on a confirmed miss.
   HubSpot's search API is eventually consistent (~5–10s), so same-run
   creations are deduped in memory, not via search.
-- A standalone **`resolve` gate** (planned, 0.13): given a candidate
-  record, return existing match(es) or "safe to create" — for the CLI, the
-  library, MCP, and any external writer (sync jobs, agents, webhook
-  handlers). Identity keys are the ones the package already uses:
-  contact email, normalized account domain, and the open-deal key
-  (account + normalized name).
+- The **`resolve` gate** (shipped 0.15): `fullstackgtm resolve
+  <account|contact|deal>` returns exists/ambiguous/safe_to_create with
+  matches and reasons; exit 0 = safe, exit 2 = do not create. Same identity
+  keys as the audit/merge engines. Also `resolveRecord()` and MCP
+  `fullstackgtm_resolve`.
 - **Stamp provenance on our own creates** (HubSpot allows integrations to
   set `hs_object_source_detail_2/3` at create time).
 - Recommend native config in `doctor`/audit: Salesforce duplicate rules
@@ -61,10 +60,10 @@ fix the faucet instead of mopping the puddle.
   (ruleId, objectId).
 - **The nightly watch recipe** ("CRM CI"): scheduled
   `snapshot → audit → diff` against yesterday's snapshot, alert on exit 2.
-- **Attribution** (planned, 0.13): capture HubSpot's read-only
-  `hs_object_source`, `hs_object_source_label`, `hs_object_source_id` into
-  the canonical model so duplicate findings can say *"all five created by
-  integration X"*. The fix for recurring dupes is upstream, in the writer.
+- **Attribution** (shipped 0.15): snapshots capture HubSpot's read-only
+  `hs_object_source*` into `RecordProvenance`; duplicate findings append
+  *"Created by: …"* naming the writer(s). The fix for recurring dupes is
+  upstream, in the writer.
 - Incremental reads (`snapshot --since`) exist for all three connectors;
   caveats: HubSpot deltas carry no associations and cap at 10k per object,
   Stripe deltas catch creations only.
@@ -131,5 +130,6 @@ Lessons from auditing our own apply path:
 | --- | --- |
 | 0.11.1 | Fix our own faucet: resolve-first `create:` + plan-scoped dedup, HubSpot association-aware CAS for `link_record`, domain normalization in `duplicate-account-domain`, `create_task` idempotency token |
 | 0.12 (shipped) | `merge_records` (HubSpot contacts/companies/deals) + survivor suggestions capped at low confidence; the three duplicate rules emit governed merges instead of review tasks |
-| 0.13 | `resolve` gate (CLI/lib/MCP), provenance capture + attribution in findings, prevention-posture checks |
+| 0.15 (shipped) | `resolve` gate (CLI/lib/MCP, gate exit codes), provenance capture (`hs_object_source*` → `RecordProvenance`) + attribution in duplicate findings, self-stamped creates |
+| 0.16 | prevention-posture checks (native duplicate rules active? unique-value properties defined?) · live targeted resolve lookups |
 | docs | The nightly watch recipe (existing flags, documented as CRM CI) |

package/llms.txt

@@ -18,6 +18,10 @@ at/above `--fail-on`.
 - [CRM-health lifecycle](https://github.com/fullstackgtm/core/blob/main/docs/crm-health-lifecycle.md): the Prevent → Detect → Remediate → Verify/Attribute model; no-new-dupes design
 - [CHANGELOG](https://github.com/fullstackgtm/core/blob/main/CHANGELOG.md): release history
 
+`fullstackgtm resolve <type>` is the create gate: exit 0 = safe to create,
+exit 2 = exists/ambiguous (never blind-create); duplicate findings carry
+"Created by:" writer attribution when the provider exposes record source.
+
 ## Key invariants (calls)
 
 `fullstackgtm call parse` defaults to LLM extraction (BYO Anthropic/OpenAI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.14.0",
+  "version": "0.15.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",

package/src/cli.ts

@@ -50,6 +50,7 @@ import {
   type CallScorecard,
   type LlmProvider,
 } from "./llm.ts";
+import { resolveRecord, type ResolveCandidate } from "./resolve.ts";
 import { suggestValues, type ValueSuggestion } from "./suggest.ts";
 import type { FieldMappings } from "./mappings.ts";
 import type {
@@ -90,6 +91,9 @@ Usage:
                                                ANTHROPIC_API_KEY/OPENAI_API_KEY, or \`login anthropic|openai\`);
                                                --deterministic uses the free keyword baseline. Then link the call
                                                to its deal and propose governed next-step writes.
+  fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]
+                                               the create gate: exit 0 = safe to create, exit 2 = match
+                                               found (exists/ambiguous) — call before ANY record creation
   fullstackgtm suggest --plan-id <id> | --plan <path>  [source options] [--json] [--out <path>]
                                                derive values for requires_human_* placeholders
                                                from snapshot evidence, with confidence + reasons
@@ -490,6 +494,17 @@ function parseValueOverrides(args: string[]) {
 
 async function callCommand(args: string[]) {
   const [subcommand, ...rest] = args;
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(`call parse --transcript <file> [--title t] [--source s] [--model m] [--deterministic] [--json|--ndjson] [--out <path>]
+call score --transcript <file>|--call <parsed.json> [--rubric <rubric.json>] [--model m] [--json|--out <path>]
+call link --attendees <a@x.com,...> | --domain <x.com>  [source options] [--json]
+call plan --transcript <file>|--call <parsed.json> --deal <id> [source options] [--save|--json]
+
+parse/score default to LLM extraction (Anthropic or OpenAI key via env,
+\`login anthropic|openai\`, or a one-time prompt). parse --deterministic is
+the free keyword baseline; score always needs a key (scoring is LLM work).`);
+    return;
+  }
 
   const loadParsedCall = async (): Promise<ParsedCall> => {
     const callPath = option(rest, "--call");
@@ -535,6 +550,7 @@ async function callCommand(args: string[]) {
             call_id: parsed.id,
             call_title: parsed.title ?? null,
             source_system: parsed.sourceSystem,
+            extractor: parsed.extractor,
             type: insight.type,
             title: insight.title,
             text: insight.text,
@@ -609,11 +625,20 @@ async function callCommand(args: string[]) {
   }
 
   if (subcommand === "score") {
-    const credential = await requireLlmCredential();
+    // Rubric problems surface before any credential or API work.
     const rubricPath = option(rest, "--rubric");
-    const rubric = rubricPath
-      ? parseRubric(readFileSync(resolve(process.cwd(), rubricPath), "utf8"))
-      : DEFAULT_RUBRIC;
+    let rubric = DEFAULT_RUBRIC;
+    if (rubricPath) {
+      const rubricRaw = readFileSync(resolve(process.cwd(), rubricPath), "utf8");
+      try {
+        rubric = parseRubric(rubricRaw);
+      } catch (error) {
+        throw new Error(
+          `${rubricPath} is not a valid rubric: ${error instanceof Error ? error.message : String(error)} Expected JSON like { "scale": 5, "dimensions": [{ "name": "...", "weight": 1, "rubric": "..." }] }.`,
+        );
+      }
+    }
+    const credential = await requireLlmCredential("score");
     const transcriptPath = option(rest, "--transcript");
     let transcriptText: string;
     let title = option(rest, "--title") ?? undefined;
@@ -651,12 +676,15 @@ async function callCommand(args: string[]) {
  * TTY a missing key is captured once (validated, stored 0600 like provider
  * logins). Non-interactive contexts get an actionable error instead.
  */
-async function requireLlmCredential(): Promise<{ provider: LlmProvider; apiKey: string }> {
+async function requireLlmCredential(command: "parse" | "score" = "parse"): Promise<{ provider: LlmProvider; apiKey: string }> {
   const resolved = resolveLlmCredential();
   if (resolved) return resolved;
+  // Scoring is inherently LLM work — there is no keyword fallback to suggest.
+  const fallbackHint =
+    command === "parse" ? ", or pass --deterministic for the free keyword baseline" : " (call score has no non-LLM mode)";
   if (!process.stdin.isTTY) {
     throw new Error(
-      "LLM extraction needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, run `echo \"$KEY\" | fullstackgtm login anthropic` (or `login openai`) once, or pass --deterministic for the free keyword baseline.",
+      `LLM ${command === "score" ? "scoring" : "extraction"} needs an API key. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run \`echo "$KEY" | fullstackgtm login anthropic\` (or \`login openai\`) once${fallbackHint}.`,
     );
   }
   console.error("LLM parsing needs an API key (Anthropic or OpenAI) — yours, used directly with the provider.");
@@ -773,6 +801,37 @@ function buildCallPlan(
   };
 }
 
+/**
+ * The resolve gate: exit 0 = safe to create, exit 2 = match found (exists or
+ * ambiguous — do NOT blind-create), exit 1 = error. Built for sync jobs and
+ * webhook handlers to call before any record creation.
+ */
+async function resolveCommand(args: string[]) {
+  const [objectType, ...rest] = args;
+  if (!objectType || !["account", "contact", "deal"].includes(objectType)) {
+    throw new Error("Usage: fullstackgtm resolve <account|contact|deal> [--name N] [--domain D] [--email E] [--account-id A] [source options] [--json]");
+  }
+  const candidate: ResolveCandidate = {
+    objectType: objectType as ResolveCandidate["objectType"],
+    name: option(rest, "--name") ?? undefined,
+    domain: option(rest, "--domain") ?? undefined,
+    email: option(rest, "--email") ?? undefined,
+    accountId: option(rest, "--account-id") ?? undefined,
+  };
+  const snapshot = await readSnapshot(rest);
+  const result = resolveRecord(snapshot, candidate);
+  if (rest.includes("--json")) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const marker = result.verdict === "safe_to_create" ? "✓" : result.verdict === "exists" ? "=" : "?";
+    console.log(`${marker} [${result.verdict}] ${result.reason}`);
+    for (const m of result.matches) {
+      console.log(`    ${m.id} "${m.name}" — matched by ${m.matchedBy}: ${m.detail}`);
+    }
+  }
+  if (result.verdict !== "safe_to_create") process.exitCode = 2;
+}
+
 async function suggest(args: string[]) {
   const planId = option(args, "--plan-id");
   const planPath = option(args, "--plan");
@@ -1325,6 +1384,7 @@ async function login(args: string[]) {
     return;
   }
   if (provider === "anthropic" || provider === "openai") {
+    rejectArgvSecret(args, "--token", "--key", "--api-key");
     const key = await readSecret(`${provider} API key (${provider === "anthropic" ? "sk-ant-..." : "sk-..."})`);
     if (!key) throw new Error(`No ${provider} key provided.`);
     if (!args.includes("--no-validate")) {
@@ -1601,6 +1661,10 @@ export async function runCli(argv: string[]) {
     await callCommand(args);
     return;
   }
+  if (command === "resolve") {
+    await resolveCommand(args);
+    return;
+  }
   if (command === "profiles") {
     profilesCommand(args);
     return;

package/src/connectors/hubspot.ts

@@ -10,6 +10,7 @@ import type {
   CanonicalAccount,
   CanonicalContact,
   CanonicalDeal,
+  RecordProvenance,
   CanonicalGtmSnapshot,
   CanonicalUser,
   GtmConnector,
@@ -125,11 +126,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
         active: owner.archived !== true,
       }));
 
-    const companyProperties = mappedFields(
+    // Read-only record-source fields power duplicate-finding attribution
+    // ("all five created by integration X") — see RecordProvenance.
+    const PROVENANCE_PROPERTIES = "hs_object_source,hs_object_source_label,hs_object_source_id";
+    const companyProperties = `${mappedFields(
       mappings,
       "accounts",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.accounts,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const companies = await fetchObjects("companies", companyProperties, false);
     const accounts: CanonicalAccount[] = companies
       .filter((company) => company.id)
@@ -155,16 +159,17 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           ownerId: stringOrUndefined(
             readMapped(props, "accounts", "ownerId", "hubspot_owner_id"),
           ),
+          provenance: provenanceFrom(props),
           lastSyncAt: stringOrUndefined(company.updatedAt),
           raw: company,
         };
       });
 
-    const contactProperties = mappedFields(
+    const contactProperties = `${mappedFields(
       mappings,
       "contacts",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const hubspotContacts = await fetchObjects("contacts", contactProperties, true);
     const contacts: CanonicalContact[] = hubspotContacts
       .filter((contact) => contact.id)
@@ -185,16 +190,17 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           ownerId: stringOrUndefined(
             readMapped(props, "contacts", "ownerId", "hubspot_owner_id"),
           ),
+          provenance: provenanceFrom(props),
           lastSyncAt: stringOrUndefined(contact.updatedAt),
           raw: contact,
         };
       });
 
-    const dealProperties = mappedFields(
+    const dealProperties = `${mappedFields(
       mappings,
       "deals",
       HUBSPOT_DEFAULT_FIELD_MAPPINGS.deals,
-    ).join(",");
+    ).join(",")},${PROVENANCE_PROPERTIES}`;
     const hubspotDeals = await fetchObjects("deals", dealProperties, true);
     const deals: CanonicalDeal[] = hubspotDeals
       .filter((deal) => deal.id)
@@ -220,6 +226,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           identities: [{ provider: "hubspot", externalId: String(deal.id) }],
           accountId: companyId ? String(companyId) : undefined,
           ownerId: stringOrUndefined(readMapped(props, "deals", "ownerId", "hubspot_owner_id")),
+          provenance: provenanceFrom(props),
           name: stringOrFallback(readMapped(props, "deals", "name", "dealname"), "Untitled Deal"),
           amount: numberOrUndefined(readMapped(props, "deals", "amount", "amount")),
           stage,
@@ -419,10 +426,22 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
           resolvedExisting = true;
           createdCompaniesByName.set(nameKey, companyId);
         } else {
-          const created = await request(`/crm/v3/objects/companies`, {
-            method: "POST",
-            body: JSON.stringify({ properties: { name } }),
-          });
+          let created;
+          try {
+            created = await request(`/crm/v3/objects/companies`, {
+              method: "POST",
+              body: JSON.stringify({
+                properties: { name, hs_object_source_detail_2: "fullstackgtm create: operation" },
+              }),
+            });
+          } catch {
+            // Some portals reject writes to source-detail properties — the
+            // provenance stamp is best-effort, the create is not.
+            created = await request(`/crm/v3/objects/companies`, {
+              method: "POST",
+              body: JSON.stringify({ properties: { name } }),
+            });
+          }
           companyId = String(created.id);
           createdCompanyName = name;
           createdCompaniesByName.set(nameKey, companyId);
@@ -494,6 +513,37 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     } catch {
       // fall through to create
     }
+    // A live CRM often already carries a human-created follow-up for the same
+    // record (a previous partial run, or a rep's own task). Creating another
+    // on top is duplicate noise — skip when the object already has an open
+    // task, regardless of who created it. Fail-open: a lookup hiccup must
+    // not block the apply.
+    try {
+      const objectPath = OBJECT_PATHS[operation.objectType];
+      const assoc = await request(
+        `/crm/v4/objects/${objectPath}/${encodeURIComponent(operation.objectId)}/associations/tasks?limit=20`,
+      );
+      const taskIds = ((assoc?.results ?? []) as Array<{ toObjectId?: number | string }>)
+        .map((row) => String(row.toObjectId ?? ""))
+        .filter(Boolean)
+        .slice(0, 10);
+      for (const taskId of taskIds) {
+        const existingTask = await request(
+          `/crm/v3/objects/tasks/${encodeURIComponent(taskId)}?properties=hs_task_status`,
+        );
+        const status = String(existingTask?.properties?.hs_task_status ?? "");
+        if (status !== "COMPLETED" && status !== "DELETED") {
+          return {
+            operationId: operation.id,
+            status: "skipped",
+            detail: `An open task (task ${taskId}) already exists on ${operation.objectType}/${operation.objectId}; not creating a duplicate follow-up.`,
+            providerData: { id: taskId, 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",
@@ -686,6 +736,14 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
   };
 }
 
+function provenanceFrom(props: Record<string, unknown>): RecordProvenance | undefined {
+  const source = stringOrUndefined(props.hs_object_source);
+  const sourceLabel = stringOrUndefined(props.hs_object_source_label);
+  const sourceId = stringOrUndefined(props.hs_object_source_id);
+  if (!source && !sourceLabel && !sourceId) return undefined;
+  return { source, sourceLabel, sourceId };
+}
+
 function stringOrUndefined(value: unknown): string | undefined {
   if (value === undefined || value === null || value === "") return undefined;
   return String(value);

package/src/diff.ts

@@ -7,7 +7,7 @@ import type { AuditFinding, CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
  */
 
 // Fields that change on every sync without semantic meaning.
-const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities"]);
+const IGNORED_FIELDS = new Set(["raw", "lastSyncAt", "identities", "provenance"]);
 
 export type FieldChange = { field: string; before: unknown; after: unknown };
 

package/src/index.ts

@@ -95,6 +95,7 @@ export {
   orphanAccountRule,
   pastCloseDateRule,
   patchOperationId,
+  provenanceSummary,
   requiresHumanInput,
   staleDealRule,
 } from "./rules.ts";
@@ -128,6 +129,7 @@ export {
   type Rubric,
   type ScoredDimension,
 } from "./llm.ts";
+export { resolveRecord, type ResolveCandidate, type ResolveMatch, type ResolveResult } from "./resolve.ts";
 export { suggestValues, type SuggestionConfidence, type ValueSuggestion } from "./suggest.ts";
 export type {
   ApprovalStatus,

package/src/mcp.ts

@@ -48,6 +48,7 @@ import { builtinAuditRules } from "./rules.ts";
 import { sampleSnapshot } from "./sampleData.ts";
 import { normalizeTranscript, parseCall } from "./calls.ts";
 import { extractInsightsLlm, resolveLlmCredential } from "./llm.ts";
+import { resolveRecord } from "./resolve.ts";
 import { suggestValues } from "./suggest.ts";
 import type { CanonicalGtmSnapshot, GtmConnector, PatchPlan } from "./types.ts";
 
@@ -239,6 +240,31 @@ export async function startMcpServer() {
     },
   );
 
+  server.registerTool(
+    "fullstackgtm_resolve",
+    {
+      title: "Resolve Record (create gate)",
+      description:
+        "Before creating a CRM record, check whether it already exists. Returns a verdict " +
+        "(exists | ambiguous | safe_to_create) with matches and a reason, using the same " +
+        "identity keys as the audit/merge engines (account domain, contact email, open-deal " +
+        "key). Read-only. Never create on 'exists' or 'ambiguous'.",
+      inputSchema: {
+        objectType: z.enum(["account", "contact", "deal"]),
+        name: z.string().optional(),
+        domain: z.string().optional(),
+        email: z.string().optional(),
+        accountId: z.string().optional(),
+        provider: z.enum(["sample", "demo", "hubspot", "salesforce", "stripe"]).optional(),
+        inputPath: z.string().optional(),
+      },
+    },
+    async ({ objectType, name, domain, email, accountId, provider, inputPath }) => {
+      const snapshot = await readSnapshot(provider, inputPath);
+      return content(resolveRecord(snapshot, { objectType, name, domain, email, accountId }));
+    },
+  );
+
   server.registerTool(
     "fullstackgtm_rules",
     {

package/src/merge.ts

@@ -52,7 +52,7 @@ export type MergeReport = {
 };
 
 const CONFLICT_IGNORED_FIELDS = new Set([
-  "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId",
+  "id", "provider", "crmId", "identities", "raw", "lastSyncAt", "lastActivityAt", "ownerId", "accountId", "provenance",
 ]);
 
 export function normalizeDomain(domain?: string): string | undefined {

package/src/resolve.ts

@@ -0,0 +1,157 @@
+import { normalizeDomain } from "./merge.ts";
+import type { CanonicalGtmSnapshot } from "./types.ts";
+
+/**
+ * The resolve gate — the Prevent layer of the CRM-health lifecycle.
+ *
+ * Before any writer (sync job, webhook handler, agent, this CLI's own
+ * `create:` path) creates a record, it should ask: does this record already
+ * exist? The gate answers deterministically from a snapshot using the same
+ * identity keys the audit and merge engines use:
+ *
+ *   account → normalized domain (exact), then normalized name
+ *   contact → normalized email (exact), then full name
+ *   deal    → open-deal key: (accountId | "unlinked") + normalized name
+ *
+ * Verdicts are gate-shaped: `exists` (link to it, don't create),
+ * `ambiguous` (a human must pick — do NOT blind-create), `safe_to_create`.
+ */
+
+export type ResolveCandidate = {
+  objectType: "account" | "contact" | "deal";
+  name?: string;
+  domain?: string;
+  email?: string;
+  /** For deals: scope the duplicate key to an account. */
+  accountId?: string;
+};
+
+export type ResolveMatch = {
+  id: string;
+  name: string;
+  matchedBy: "domain" | "email" | "name" | "deal_key";
+  detail: string;
+};
+
+export type ResolveResult = {
+  objectType: ResolveCandidate["objectType"];
+  verdict: "exists" | "ambiguous" | "safe_to_create";
+  matches: ResolveMatch[];
+  reason: string;
+};
+
+export function resolveRecord(
+  snapshot: CanonicalGtmSnapshot,
+  candidate: ResolveCandidate,
+): ResolveResult {
+  if (candidate.objectType === "account") return resolveAccount(snapshot, candidate);
+  if (candidate.objectType === "contact") return resolveContact(snapshot, candidate);
+  return resolveDeal(snapshot, candidate);
+}
+
+function resolveAccount(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "account" as const };
+  const domain = normalizeDomain(c.domain);
+  if (domain) {
+    const matches = snapshot.accounts
+      .filter((a) => normalizeDomain(a.domain) === domain)
+      .map((a) => match(a.id, a.name, "domain", `account domain ${a.domain} normalizes to ${domain}`));
+    if (matches.length === 1) {
+      return { ...base, verdict: "exists", matches, reason: `An account with domain ${domain} already exists: "${matches[0].name}" (${matches[0].id}). Link to it instead of creating.` };
+    }
+    if (matches.length > 1) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} accounts already share domain ${domain} — that's a duplicate group; merge it before adding more. Do not create.` };
+    }
+  }
+  if (c.name) {
+    const key = normalizeName(c.name);
+    const matches = snapshot.accounts
+      .filter((a) => normalizeName(a.name) === key)
+      .map((a) => match(a.id, a.name, "name", `account name matches "${c.name}" (domain: ${a.domain ?? "none"})`));
+    if (matches.length > 0) {
+      // Name alone is suggestive, not identity — two real companies can share
+      // a name (the merge engine treats this the same way).
+      return {
+        ...base,
+        verdict: "ambiguous",
+        matches,
+        reason: `${matches.length} account(s) named "${c.name}" exist but ${domain ? `none share domain ${domain}` : "no domain was supplied to confirm identity"}. Confirm before creating — supply a domain to disambiguate.`,
+      };
+    }
+  }
+  if (!domain && !c.name) {
+    return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --domain and/or --name to resolve an account." };
+  }
+  return { ...base, verdict: "safe_to_create", matches: [], reason: `No account matches ${domain ? `domain ${domain}` : `name "${c.name}"`}. Safe to create.` };
+}
+
+function resolveContact(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "contact" as const };
+  const email = c.email?.trim().toLowerCase();
+  if (email) {
+    const matches = snapshot.contacts
+      .filter((row) => row.email?.trim().toLowerCase() === email)
+      .map((row) => match(row.id, contactName(row), "email", `contact email matches ${email}`));
+    if (matches.length === 1) {
+      return { ...base, verdict: "exists", matches, reason: `A contact with email ${email} already exists: "${matches[0].name}" (${matches[0].id}). Update it instead of creating.` };
+    }
+    if (matches.length > 1) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} contacts already share ${email} — a duplicate group; merge before adding more. Do not create.` };
+    }
+    return { ...base, verdict: "safe_to_create", matches: [], reason: `No contact matches ${email}. Safe to create.` };
+  }
+  if (c.name) {
+    const key = normalizeName(c.name);
+    const matches = snapshot.contacts
+      .filter((row) => normalizeName(contactName(row)) === key)
+      .map((row) => match(row.id, contactName(row), "name", `contact name matches "${c.name}" (email: ${row.email ?? "none"})`));
+    if (matches.length > 0) {
+      return { ...base, verdict: "ambiguous", matches, reason: `${matches.length} contact(s) named "${c.name}" exist; names are not identity. Supply --email to resolve definitively.` };
+    }
+    return { ...base, verdict: "safe_to_create", matches: [], reason: `No contact named "${c.name}". Safe to create — but prefer resolving by email.` };
+  }
+  return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --email (preferred) or --name to resolve a contact." };
+}
+
+function resolveDeal(snapshot: CanonicalGtmSnapshot, c: ResolveCandidate): ResolveResult {
+  const base = { objectType: "deal" as const };
+  if (!c.name) {
+    return { ...base, verdict: "ambiguous", matches: [], reason: "Supply --name (and ideally --account-id) to resolve a deal." };
+  }
+  const key = `${c.accountId ?? "unlinked"}:${normalizeName(c.name)}`;
+  const open = snapshot.deals.filter((d) => d.isClosed !== true && d.isWon !== true);
+  const matches = open
+    .filter((d) => `${d.accountId ?? "unlinked"}:${normalizeName(d.name)}` === key)
+    .map((d) => match(d.id, d.name, "deal_key", `open deal with the same name on ${c.accountId ? `account ${c.accountId}` : "no account"}`));
+  if (matches.length > 0) {
+    return {
+      ...base,
+      verdict: "exists",
+      matches,
+      reason: `${matches.length} open deal(s) already match "${c.name}" on ${c.accountId ? `account ${c.accountId}` : "unlinked"} — creating another would double-count pipeline. Update the existing deal.`,
+    };
+  }
+  const closedSameName = snapshot.deals.filter(
+    (d) => (d.isClosed === true || d.isWon === true) && normalizeName(d.name) === normalizeName(c.name!),
+  );
+  return {
+    ...base,
+    verdict: "safe_to_create",
+    matches: [],
+    reason: closedSameName.length > 0
+      ? `No open deal matches; ${closedSameName.length} closed deal(s) share the name (a re-open/renewal may be intended). Safe to create.`
+      : `No open deal matches "${c.name}". Safe to create.`,
+  };
+}
+
+function contactName(row: { firstName?: string; lastName?: string }) {
+  return [row.firstName, row.lastName].filter(Boolean).join(" ") || "(unnamed)";
+}
+
+function normalizeName(value: string) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function match(id: string, name: string, matchedBy: ResolveMatch["matchedBy"], detail: string): ResolveMatch {
+  return { id, name, matchedBy, detail };
+}