fullstackgtm 0.41.0 → 0.42.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ The path to 1.0 is planned in [docs/roadmap-to-1.0.md](./docs/roadmap-to-1.0.md)
 
 ## [Unreleased]
 
+## [0.42.0] — 2026-06-25
+
+### Added
+
+- **Bulk apply for lead creation (HubSpot + Salesforce).** `applyPatchPlan` now
+  routes independent, approved `create_record` **contact** ops through a new
+  optional connector capability, `applyCreateContactsBatch`, instead of two API
+  round-trips per lead (a resolve-first search + a create). HubSpot batches the
+  resolve-first via a `search` `IN` and creates via `batch/create` (100/call);
+  Salesforce batches via a SOQL `IN` and the Composite sObject Collections API
+  (`allOrNone: false`, 200/call). A batch rejection (e.g. a duplicate that the
+  provider 4xxs the whole batch over) falls back to per-record `createRecord`, so
+  one bad row never sinks the rest and resolve-first is preserved. Turns ~2N API
+  calls into ~N/100; ops that aren't safe to batch (grouped, value-overridden,
+  company-associated, conflicted, or non-create) stay on the serial path
+  unchanged. Connectors without the capability are unaffected.
+
 ## [0.41.0] — 2026-06-23
 
 ### Added

package/dist/connector.js

@@ -227,7 +227,41 @@ export async function applyPatchPlan(connector, plan, options) {
             }
         }
     }
+    // Bulk fast-path: route independent, approved create_record CONTACT ops
+    // through the connector's batch API (batched resolve-first read + batched
+    // writes) instead of one round-trip per record. Only ops that are safe to
+    // batch are eligible — every other op (grouped, needs an override, carries a
+    // company association, conflicted, or any non-create op) stays on the serial
+    // path below, so the safety contract is unchanged. Results are merged in by
+    // id; the serial loop short-circuits anything already resolved here.
+    const batched = new Map();
+    if (connector.applyCreateContactsBatch && !guardFailure) {
+        const eligible = plan.operations.filter((operation) => approved.has(operation.id) &&
+            operation.operation === "create_record" &&
+            operation.objectType === "contact" &&
+            options.valueOverrides?.[operation.id] === undefined &&
+            !requiresHumanInput(operation.afterValue) &&
+            !operation.groupId &&
+            !operation.afterValue?.associateCompanyName &&
+            !conflicts.has(operation.id) &&
+            !irreversibleStale.has(operation.id) &&
+            !(staleByFilter && staleByFilter.has(operation.objectId)));
+        // Only worth the batch machinery for more than a couple of creates.
+        if (eligible.length > 2) {
+            const batchResults = await connector.applyCreateContactsBatch(eligible);
+            for (const result of batchResults)
+                batched.set(result.operationId, result);
+        }
+    }
     for (const operation of plan.operations) {
+        const batchedResult = batched.get(operation.id);
+        if (batchedResult) {
+            results.push(batchedResult);
+            attempted += 1;
+            if (batchedResult.status === "applied")
+                applied += 1;
+            continue;
+        }
         if (!approved.has(operation.id)) {
             results.push({
                 operationId: operation.id,

package/dist/connectors/hubspot.js

@@ -555,6 +555,129 @@ export function createHubspotConnector(options) {
             providerData: { id: contactId, created: true },
         };
     }
+    /** Bulk resolve-first lookup: which match values already exist (value→id). */
+    async function searchContactsByValues(property, values) {
+        const found = new Map();
+        for (let i = 0; i < values.length; i += 100) {
+            const chunk = values.slice(i, i + 100);
+            const data = await request(`/crm/v3/objects/contacts/search`, {
+                method: "POST",
+                body: JSON.stringify({
+                    filterGroups: [{ filters: [{ propertyName: property, operator: "IN", values: chunk }] }],
+                    properties: [property],
+                    limit: 100,
+                }),
+            });
+            for (const rec of (data?.results ?? [])) {
+                const v = rec?.properties?.[property];
+                if (typeof v === "string" && rec.id)
+                    found.set(v.toLowerCase(), String(rec.id));
+            }
+        }
+        return found;
+    }
+    /**
+     * Batch create_record for contacts: bulk resolve-first (search IN), then
+     * bulk-create the genuine misses (batch/create, 100/call) — two API calls per
+     * ~100 leads instead of two per lead. On a batch-create rejection (e.g. an
+     * email collision HubSpot 409s the whole batch over), it falls back to
+     * per-record createRecord for that chunk, so one bad row never sinks the rest
+     * and resolve-first is preserved. Returns one result per input op.
+     */
+    async function applyCreateContactsBatch(operations) {
+        const byId = new Map();
+        // Group by the HubSpot search property (matchKey is usually uniform across a
+        // plan, but a mixed plan stays correct this way).
+        const groups = new Map();
+        for (const op of operations) {
+            const matchKey = op.afterValue?.matchKey || "email";
+            const searchProperty = HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey;
+            let arr = groups.get(searchProperty);
+            if (!arr)
+                groups.set(searchProperty, (arr = []));
+            arr.push(op);
+        }
+        for (const [searchProperty, ops] of groups) {
+            const wanted = ops
+                .map((op) => String(op.afterValue.matchValue ?? "").trim())
+                .filter(Boolean);
+            const existing = await searchContactsByValues(searchProperty, [...new Set(wanted.map((v) => v.toLowerCase()))]);
+            const toCreate = [];
+            const seenInBatch = new Set();
+            for (const op of ops) {
+                const payload = op.afterValue;
+                const matchKey = payload.matchKey || "email";
+                const matchValue = String(payload.matchValue ?? "").trim();
+                if (!matchValue) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+                    continue;
+                }
+                const lower = matchValue.toLowerCase();
+                const dedupeKey = `${matchKey}:${lower}`;
+                const already = createdContactsByMatch.get(dedupeKey);
+                if (already) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+                    continue;
+                }
+                const existingId = existing.get(lower);
+                if (existingId) {
+                    createdContactsByMatch.set(dedupeKey, existingId);
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+                    continue;
+                }
+                if (seenInBatch.has(lower)) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+                    continue;
+                }
+                seenInBatch.add(lower);
+                toCreate.push(op);
+            }
+            for (let i = 0; i < toCreate.length; i += 100) {
+                const chunk = toCreate.slice(i, i + 100);
+                const inputs = chunk.map((op) => {
+                    const payload = op.afterValue;
+                    const properties = { ...payload.properties };
+                    if (payload.ownerId && !properties.hubspot_owner_id)
+                        properties.hubspot_owner_id = String(payload.ownerId);
+                    properties.hs_object_source_detail_2 = `fullstackgtm acquire (${op.id})`;
+                    return { properties };
+                });
+                try {
+                    const data = await request(`/crm/v3/objects/contacts/batch/create`, {
+                        method: "POST",
+                        body: JSON.stringify({ inputs }),
+                    });
+                    const created = (data?.results ?? []);
+                    const idByValue = new Map();
+                    for (const rec of created) {
+                        const v = rec?.properties?.[searchProperty];
+                        if (typeof v === "string" && rec.id)
+                            idByValue.set(v.toLowerCase(), String(rec.id));
+                    }
+                    for (const op of chunk) {
+                        const payload = op.afterValue;
+                        const matchKey = payload.matchKey || "email";
+                        const matchValue = String(payload.matchValue).trim();
+                        const id = idByValue.get(matchValue.toLowerCase());
+                        if (id) {
+                            createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, id);
+                            byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${id}).`, providerData: { id, created: true } });
+                        }
+                        else {
+                            // Result didn't echo this value — resolve it per-record to be safe.
+                            byId.set(op.id, await createRecord(op));
+                        }
+                    }
+                }
+                catch {
+                    // Whole-chunk rejection (e.g. a collision). Isolate per record.
+                    for (const op of chunk)
+                        byId.set(op.id, await createRecord(op));
+                }
+            }
+        }
+        return operations.map((op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." });
+    }
     async function createTask(operation) {
         const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
         if (associationTypeId === undefined) {
@@ -801,6 +924,7 @@ export function createHubspotConnector(options) {
         fetchSnapshot,
         fetchChanges,
         applyOperation,
+        applyCreateContactsBatch,
         readField,
     };
 }

package/dist/connectors/salesforce.js

@@ -489,6 +489,117 @@ export function createSalesforceConnector(options) {
             providerData: { id: contactId, created: true },
         };
     }
+    /**
+     * Batch create_record for contacts: bulk resolve-first (SOQL IN), then create
+     * the misses via the Composite sObject Collections API (allOrNone:false,
+     * 200/call), instead of two round-trips per lead. A record-level failure in
+     * the collection (e.g. a duplicate rule) falls back to per-record createRecord
+     * so one bad row never sinks the rest. Returns one result per input op.
+     */
+    async function applyCreateContactsBatch(operations) {
+        const byId = new Map();
+        const groups = new Map();
+        for (const op of operations) {
+            const matchKey = op.afterValue?.matchKey || "email";
+            const searchField = mappedField(mappings, "contacts", matchKey, SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey);
+            let arr = groups.get(searchField);
+            if (!arr)
+                groups.set(searchField, (arr = []));
+            arr.push(op);
+        }
+        for (const [searchField, ops] of groups) {
+            // 1. Bulk resolve-first via SOQL IN (chunked; values SOQL-escaped).
+            const existing = new Map();
+            const uniqueValues = [
+                ...new Set(ops.map((op) => String(op.afterValue.matchValue ?? "").trim()).filter(Boolean)),
+            ];
+            for (let i = 0; i < uniqueValues.length; i += 200) {
+                const inList = uniqueValues
+                    .slice(i, i + 200)
+                    .map((v) => `'${v.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`)
+                    .join(",");
+                const rows = await query(`SELECT Id, ${searchField} FROM Contact WHERE ${searchField} IN (${inList})`);
+                for (const row of rows) {
+                    const v = row?.[searchField];
+                    if (typeof v === "string" && row.Id)
+                        existing.set(v.toLowerCase(), String(row.Id));
+                }
+            }
+            // 2. Partition: existing / already-this-run / dup-in-batch / to-create.
+            const toCreate = [];
+            const seenInBatch = new Set();
+            for (const op of ops) {
+                const payload = op.afterValue;
+                const matchKey = payload.matchKey || "email";
+                const matchValue = String(payload.matchValue ?? "").trim();
+                if (!matchValue) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+                    continue;
+                }
+                const lower = matchValue.toLowerCase();
+                const dedupeKey = `${matchKey}:${lower}`;
+                const already = createdContactsByMatch.get(dedupeKey);
+                if (already) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+                    continue;
+                }
+                const existingId = existing.get(lower);
+                if (existingId) {
+                    createdContactsByMatch.set(dedupeKey, existingId);
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+                    continue;
+                }
+                if (seenInBatch.has(lower)) {
+                    byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+                    continue;
+                }
+                seenInBatch.add(lower);
+                toCreate.push(op);
+            }
+            // 3. Bulk create via Composite sObject Collections (allOrNone:false →
+            //    per-record results in request order).
+            for (let i = 0; i < toCreate.length; i += 200) {
+                const chunk = toCreate.slice(i, i + 200);
+                const records = chunk.map((op) => {
+                    const payload = op.afterValue;
+                    const fields = { ...payload.properties };
+                    if (payload.ownerId) {
+                        const ownerField = mappedField(mappings, "contacts", "ownerId", SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts.ownerId ?? "OwnerId");
+                        if (!fields[ownerField])
+                            fields[ownerField] = String(payload.ownerId);
+                    }
+                    return { attributes: { type: "Contact" }, ...fields };
+                });
+                let results;
+                try {
+                    results = (await request(`/services/data/${apiVersion}/composite/sobjects`, {
+                        method: "POST",
+                        body: JSON.stringify({ allOrNone: false, records }),
+                    }));
+                }
+                catch {
+                    for (const op of chunk)
+                        byId.set(op.id, await createRecord(op));
+                    continue;
+                }
+                for (let j = 0; j < chunk.length; j++) {
+                    const op = chunk[j];
+                    const res = Array.isArray(results) ? results[j] : undefined;
+                    const payload = op.afterValue;
+                    const matchKey = payload.matchKey || "email";
+                    const matchValue = String(payload.matchValue).trim();
+                    if (res?.success && res.id) {
+                        createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, String(res.id));
+                        byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${res.id}).`, providerData: { id: String(res.id), created: true } });
+                    }
+                    else {
+                        byId.set(op.id, await createRecord(op)); // record-level failure → isolate per record
+                    }
+                }
+            }
+        }
+        return operations.map((op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." });
+    }
     async function applyOperation(operation) {
         try {
             switch (operation.operation) {
@@ -568,6 +679,7 @@ export function createSalesforceConnector(options) {
         fetchSnapshot,
         fetchChanges,
         applyOperation,
+        applyCreateContactsBatch,
         readField,
     };
 }

package/dist/types.d.ts

@@ -384,6 +384,17 @@ export type GtmConnector = {
     provider: CrmProvider;
     fetchSnapshot: () => Promise<CanonicalGtmSnapshot>;
     applyOperation?: (operation: PatchOperation) => Promise<PatchOperationResult>;
+    /**
+     * Bulk fast-path for independent `create_record` contact ops: batch the
+     * resolve-first read and the create writes instead of one round-trip per
+     * record (orders of magnitude fewer API calls for lead acquisition). The
+     * caller (`applyPatchPlan`) only routes ops here that are safe to batch —
+     * approved, no group, no value override, no company association — and falls
+     * back to `applyOperation` for the rest. Implementations MUST preserve
+     * resolve-first (never create over an existing match) and return exactly one
+     * result per input op. Optional: connectors without it use `applyOperation`.
+     */
+    applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
     /**
      * 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,16 @@ release.
 
 ## Connectors
 
-- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, readField?, fetchChanges? }`.
+- `GtmConnector` — `{ provider, fetchSnapshot(), applyOperation?, applyCreateContactsBatch?, readField?, fetchChanges? }`.
   - Connectors never silently drop unresolvable records; audits surface them.
   - `fetchChanges(sinceIso)` returns a partial snapshot; change feeds may omit associations.
+  - `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
+    ~2N), and falls back to `applyOperation` per record on a batch rejection and
+    for any op that isn't batch-safe (grouped, value-overridden, company-
+    associated, conflicted). HubSpot: `search IN` + `batch/create`; Salesforce:
+    SOQL `IN` + Composite sObject Collections (`allOrNone:false`).
 - `createHubspotConnector(options)` — read/write/readField/fetchChanges. `applyOperation` implements every `PatchOperationType`: `set_field`, `clear_field`, `link_record`, `create_task`, `create_record` (resolve-first net-new contact/company create — re-checks the dedupe key at apply, never double-creates), `archive_record`, `merge_records` (HubSpot v3 merge — pairwise, irreversible; survivor must belong to the duplicate group). (The Salesforce connector implements the same operation set, with the platform-specific constraints noted below.)
 - `createSalesforceConnector(options)` — read/write/readField/fetchChanges; probabilities normalized to 0..1. `applyOperation` implements every operation type, with two platform constraints: `merge_records` covers **Accounts and Contacts** only (Salesforce exposes no Opportunity merge), and `create_record` resolve-first creates **contacts/accounts** (SOQL search on the match key, create only on a confirmed miss; stamps the canonical `ownerId` onto `OwnerId`).
 - `createStripeConnector(options)` — read-only billing by design (`applyOperation` returns `skipped`); email domains are the cross-system merge keys. Implements `fetchChanges` (incremental via `created[gte]`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.41.0",
+  "version": "0.42.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/src/connector.ts

@@ -2,6 +2,7 @@ import { dedupeKey } from "./dedupe.ts";
 import { requiresHumanInput } from "./rules.ts";
 import type {
   CanonicalGtmSnapshot,
+  CreateRecordPayload,
   GtmConnector,
   PatchOperation,
   PatchOperationResult,
@@ -283,7 +284,43 @@ export async function applyPatchPlan(
     }
   }
 
+  // Bulk fast-path: route independent, approved create_record CONTACT ops
+  // through the connector's batch API (batched resolve-first read + batched
+  // writes) instead of one round-trip per record. Only ops that are safe to
+  // batch are eligible — every other op (grouped, needs an override, carries a
+  // company association, conflicted, or any non-create op) stays on the serial
+  // path below, so the safety contract is unchanged. Results are merged in by
+  // id; the serial loop short-circuits anything already resolved here.
+  const batched = new Map<string, PatchOperationResult>();
+  if (connector.applyCreateContactsBatch && !guardFailure) {
+    const eligible = plan.operations.filter(
+      (operation) =>
+        approved.has(operation.id) &&
+        operation.operation === "create_record" &&
+        operation.objectType === "contact" &&
+        options.valueOverrides?.[operation.id] === undefined &&
+        !requiresHumanInput(operation.afterValue) &&
+        !operation.groupId &&
+        !(operation.afterValue as CreateRecordPayload | undefined)?.associateCompanyName &&
+        !conflicts.has(operation.id) &&
+        !irreversibleStale.has(operation.id) &&
+        !(staleByFilter && staleByFilter.has(operation.objectId)),
+    );
+    // Only worth the batch machinery for more than a couple of creates.
+    if (eligible.length > 2) {
+      const batchResults = await connector.applyCreateContactsBatch(eligible);
+      for (const result of batchResults) batched.set(result.operationId, result);
+    }
+  }
+
   for (const operation of plan.operations) {
+    const batchedResult = batched.get(operation.id);
+    if (batchedResult) {
+      results.push(batchedResult);
+      attempted += 1;
+      if (batchedResult.status === "applied") applied += 1;
+      continue;
+    }
     if (!approved.has(operation.id)) {
       results.push({
         operationId: operation.id,

package/src/connectors/hubspot.ts

@@ -660,6 +660,130 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     };
   }
 
+  /** Bulk resolve-first lookup: which match values already exist (value→id). */
+  async function searchContactsByValues(property: string, values: string[]): Promise<Map<string, string>> {
+    const found = new Map<string, string>();
+    for (let i = 0; i < values.length; i += 100) {
+      const chunk = values.slice(i, i + 100);
+      const data = await request(`/crm/v3/objects/contacts/search`, {
+        method: "POST",
+        body: JSON.stringify({
+          filterGroups: [{ filters: [{ propertyName: property, operator: "IN", values: chunk }] }],
+          properties: [property],
+          limit: 100,
+        }),
+      });
+      for (const rec of (data?.results ?? []) as Array<{ id?: string; properties?: Record<string, string> }>) {
+        const v = rec?.properties?.[property];
+        if (typeof v === "string" && rec.id) found.set(v.toLowerCase(), String(rec.id));
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Batch create_record for contacts: bulk resolve-first (search IN), then
+   * bulk-create the genuine misses (batch/create, 100/call) — two API calls per
+   * ~100 leads instead of two per lead. On a batch-create rejection (e.g. an
+   * email collision HubSpot 409s the whole batch over), it falls back to
+   * per-record createRecord for that chunk, so one bad row never sinks the rest
+   * and resolve-first is preserved. Returns one result per input op.
+   */
+  async function applyCreateContactsBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const byId = new Map<string, PatchOperationResult>();
+    // Group by the HubSpot search property (matchKey is usually uniform across a
+    // plan, but a mixed plan stays correct this way).
+    const groups = new Map<string, PatchOperation[]>();
+    for (const op of operations) {
+      const matchKey = (op.afterValue as CreateRecordPayload | undefined)?.matchKey || "email";
+      const searchProperty = HUBSPOT_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey;
+      let arr = groups.get(searchProperty);
+      if (!arr) groups.set(searchProperty, (arr = []));
+      arr.push(op);
+    }
+
+    for (const [searchProperty, ops] of groups) {
+      const wanted = ops
+        .map((op) => String((op.afterValue as CreateRecordPayload).matchValue ?? "").trim())
+        .filter(Boolean);
+      const existing = await searchContactsByValues(searchProperty, [...new Set(wanted.map((v) => v.toLowerCase()))]);
+
+      const toCreate: PatchOperation[] = [];
+      const seenInBatch = new Set<string>();
+      for (const op of ops) {
+        const payload = op.afterValue as CreateRecordPayload;
+        const matchKey = payload.matchKey || "email";
+        const matchValue = String(payload.matchValue ?? "").trim();
+        if (!matchValue) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+          continue;
+        }
+        const lower = matchValue.toLowerCase();
+        const dedupeKey = `${matchKey}:${lower}`;
+        const already = createdContactsByMatch.get(dedupeKey);
+        if (already) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+          continue;
+        }
+        const existingId = existing.get(lower);
+        if (existingId) {
+          createdContactsByMatch.set(dedupeKey, existingId);
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+          continue;
+        }
+        if (seenInBatch.has(lower)) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+          continue;
+        }
+        seenInBatch.add(lower);
+        toCreate.push(op);
+      }
+
+      for (let i = 0; i < toCreate.length; i += 100) {
+        const chunk = toCreate.slice(i, i + 100);
+        const inputs = chunk.map((op) => {
+          const payload = op.afterValue as CreateRecordPayload;
+          const properties: Record<string, string> = { ...payload.properties };
+          if (payload.ownerId && !properties.hubspot_owner_id) properties.hubspot_owner_id = String(payload.ownerId);
+          properties.hs_object_source_detail_2 = `fullstackgtm acquire (${op.id})`;
+          return { properties };
+        });
+        try {
+          const data = await request(`/crm/v3/objects/contacts/batch/create`, {
+            method: "POST",
+            body: JSON.stringify({ inputs }),
+          });
+          const created = (data?.results ?? []) as Array<{ id?: string; properties?: Record<string, string> }>;
+          const idByValue = new Map<string, string>();
+          for (const rec of created) {
+            const v = rec?.properties?.[searchProperty];
+            if (typeof v === "string" && rec.id) idByValue.set(v.toLowerCase(), String(rec.id));
+          }
+          for (const op of chunk) {
+            const payload = op.afterValue as CreateRecordPayload;
+            const matchKey = payload.matchKey || "email";
+            const matchValue = String(payload.matchValue).trim();
+            const id = idByValue.get(matchValue.toLowerCase());
+            if (id) {
+              createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, id);
+              byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${id}).`, providerData: { id, created: true } });
+            } else {
+              // Result didn't echo this value — resolve it per-record to be safe.
+              byId.set(op.id, await createRecord(op));
+            }
+          }
+        } catch {
+          // Whole-chunk rejection (e.g. a collision). Isolate per record.
+          for (const op of chunk) byId.set(op.id, await createRecord(op));
+        }
+      }
+    }
+
+    return operations.map(
+      (op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." },
+    );
+  }
+
   async function createTask(operation: PatchOperation): Promise<PatchOperationResult> {
     const associationTypeId = TASK_ASSOCIATION_TYPE_IDS[operation.objectType];
     if (associationTypeId === undefined) {
@@ -926,6 +1050,7 @@ export function createHubspotConnector(options: HubspotConnectorOptions): Requir
     fetchSnapshot,
     fetchChanges,
     applyOperation,
+    applyCreateContactsBatch,
     readField,
   };
 }

package/src/connectors/salesforce.ts

@@ -597,6 +597,118 @@ export function createSalesforceConnector(
     };
   }
 
+  /**
+   * Batch create_record for contacts: bulk resolve-first (SOQL IN), then create
+   * the misses via the Composite sObject Collections API (allOrNone:false,
+   * 200/call), instead of two round-trips per lead. A record-level failure in
+   * the collection (e.g. a duplicate rule) falls back to per-record createRecord
+   * so one bad row never sinks the rest. Returns one result per input op.
+   */
+  async function applyCreateContactsBatch(operations: PatchOperation[]): Promise<PatchOperationResult[]> {
+    const byId = new Map<string, PatchOperationResult>();
+    const groups = new Map<string, PatchOperation[]>();
+    for (const op of operations) {
+      const matchKey = (op.afterValue as CreateRecordPayload | undefined)?.matchKey || "email";
+      const searchField = mappedField(mappings, "contacts", matchKey, SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts[matchKey] ?? matchKey);
+      let arr = groups.get(searchField);
+      if (!arr) groups.set(searchField, (arr = []));
+      arr.push(op);
+    }
+
+    for (const [searchField, ops] of groups) {
+      // 1. Bulk resolve-first via SOQL IN (chunked; values SOQL-escaped).
+      const existing = new Map<string, string>();
+      const uniqueValues = [
+        ...new Set(ops.map((op) => String((op.afterValue as CreateRecordPayload).matchValue ?? "").trim()).filter(Boolean)),
+      ];
+      for (let i = 0; i < uniqueValues.length; i += 200) {
+        const inList = uniqueValues
+          .slice(i, i + 200)
+          .map((v) => `'${v.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`)
+          .join(",");
+        const rows = await query(`SELECT Id, ${searchField} FROM Contact WHERE ${searchField} IN (${inList})`);
+        for (const row of rows) {
+          const v = row?.[searchField];
+          if (typeof v === "string" && row.Id) existing.set(v.toLowerCase(), String(row.Id));
+        }
+      }
+
+      // 2. Partition: existing / already-this-run / dup-in-batch / to-create.
+      const toCreate: PatchOperation[] = [];
+      const seenInBatch = new Set<string>();
+      for (const op of ops) {
+        const payload = op.afterValue as CreateRecordPayload;
+        const matchKey = payload.matchKey || "email";
+        const matchValue = String(payload.matchValue ?? "").trim();
+        if (!matchValue) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: "create_record needs a non-empty matchValue to resolve-first." });
+          continue;
+        }
+        const lower = matchValue.toLowerCase();
+        const dedupeKey = `${matchKey}:${lower}`;
+        const already = createdContactsByMatch.get(dedupeKey);
+        if (already) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already created earlier in this run; not duplicating.`, providerData: { id: already, existing: true } });
+          continue;
+        }
+        const existingId = existing.get(lower);
+        if (existingId) {
+          createdContactsByMatch.set(dedupeKey, existingId);
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} already exists (${existingId}); resolve-first declined to create.`, providerData: { id: existingId, existing: true } });
+          continue;
+        }
+        if (seenInBatch.has(lower)) {
+          byId.set(op.id, { operationId: op.id, status: "skipped", detail: `Contact ${matchKey}=${matchValue} duplicated within this batch; not duplicating.` });
+          continue;
+        }
+        seenInBatch.add(lower);
+        toCreate.push(op);
+      }
+
+      // 3. Bulk create via Composite sObject Collections (allOrNone:false →
+      //    per-record results in request order).
+      for (let i = 0; i < toCreate.length; i += 200) {
+        const chunk = toCreate.slice(i, i + 200);
+        const records = chunk.map((op) => {
+          const payload = op.afterValue as CreateRecordPayload;
+          const fields: Record<string, string> = { ...payload.properties };
+          if (payload.ownerId) {
+            const ownerField = mappedField(mappings, "contacts", "ownerId", SALESFORCE_DEFAULT_FIELD_MAPPINGS.contacts.ownerId ?? "OwnerId");
+            if (!fields[ownerField]) fields[ownerField] = String(payload.ownerId);
+          }
+          return { attributes: { type: "Contact" }, ...fields };
+        });
+        let results: Array<{ id?: string; success?: boolean }>;
+        try {
+          results = (await request(`/services/data/${apiVersion}/composite/sobjects`, {
+            method: "POST",
+            body: JSON.stringify({ allOrNone: false, records }),
+          })) as Array<{ id?: string; success?: boolean }>;
+        } catch {
+          for (const op of chunk) byId.set(op.id, await createRecord(op));
+          continue;
+        }
+        for (let j = 0; j < chunk.length; j++) {
+          const op = chunk[j];
+          const res = Array.isArray(results) ? results[j] : undefined;
+          const payload = op.afterValue as CreateRecordPayload;
+          const matchKey = payload.matchKey || "email";
+          const matchValue = String(payload.matchValue).trim();
+          if (res?.success && res.id) {
+            createdContactsByMatch.set(`${matchKey}:${matchValue.toLowerCase()}`, String(res.id));
+            byId.set(op.id, { operationId: op.id, status: "applied", detail: `Created contact ${matchKey}=${matchValue} (${res.id}).`, providerData: { id: String(res.id), created: true } });
+          } else {
+            byId.set(op.id, await createRecord(op)); // record-level failure → isolate per record
+          }
+        }
+      }
+    }
+
+    return operations.map(
+      (op) => byId.get(op.id) ?? { operationId: op.id, status: "skipped", detail: "create_record was not processed." },
+    );
+  }
+
   async function applyOperation(operation: PatchOperation): Promise<PatchOperationResult> {
     try {
       switch (operation.operation) {
@@ -683,6 +795,7 @@ export function createSalesforceConnector(
     fetchSnapshot,
     fetchChanges,
     applyOperation,
+    applyCreateContactsBatch,
     readField,
   };
 }

package/src/types.ts

@@ -470,6 +470,17 @@ export type GtmConnector = {
   provider: CrmProvider;
   fetchSnapshot: () => Promise<CanonicalGtmSnapshot>;
   applyOperation?: (operation: PatchOperation) => Promise<PatchOperationResult>;
+  /**
+   * Bulk fast-path for independent `create_record` contact ops: batch the
+   * resolve-first read and the create writes instead of one round-trip per
+   * record (orders of magnitude fewer API calls for lead acquisition). The
+   * caller (`applyPatchPlan`) only routes ops here that are safe to batch —
+   * approved, no group, no value override, no company association — and falls
+   * back to `applyOperation` for the rest. Implementations MUST preserve
+   * resolve-first (never create over an existing match) and return exactly one
+   * result per input op. Optional: connectors without it use `applyOperation`.
+   */
+  applyCreateContactsBatch?: (operations: PatchOperation[]) => Promise<PatchOperationResult[]>;
   /**
    * Read the live value of one canonical field, used for compare-and-set:
    * apply orchestration refuses to write over values that drifted since the