fullstackgtm 0.21.2 → 0.22.0

package/dist/index.js

@@ -1,5 +1,7 @@
 export { auditSnapshot, defaultPolicy } from "./audit.js";
-export { buildBulkUpdatePlan, parseWhere } from "./bulkUpdate.js";
+export { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.js";
+export { buildDedupePlan, dedupeKey } from "./dedupe.js";
+export { buildReassignPlans } from "./reassign.js";
 export { CONFIG_FILE_NAME, loadConfig, mergePolicy, resolveConfiguredRules, } from "./config.js";
 export { applyPatchPlan } from "./connector.js";
 export { createHubspotConnector } from "./connectors/hubspot.js";

package/dist/marketReport.js

@@ -382,8 +382,9 @@ export function marketMapToHtml(config, set) {
     const anchor = config.anchorVendor;
     const e = escapeHtml;
     const axisHtml = axisSectionsHtml(config, set);
-    const matrixRows = model.orderedClaimIds
-        .map((claimId) => {
+    const vendorNamesById = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    const frontByClaim = new Map(model.fronts.map((front) => [front.claimId, front]));
+    const matrixRow = (claimId) => {
         const claim = claimsById.get(claimId);
         if (!claim)
             return "";
@@ -398,27 +399,87 @@ export function marketMapToHtml(config, set) {
         return (`<tr class="front-${state}"><th scope="row"><span class="claim-cap">${e(claim.capability.split(":")[0])}</span>` +
             `<span class="claim-meta">${e(claim.icp)} · ${e(claim.pricingStructure)}</span></th>${cells}` +
             `<td class="front"><span class="chip chip-${state}">${state.toUpperCase()}</span></td></tr>`);
-    })
-        .join("");
-    const openList = model.orderedClaimIds
-        .filter((claimId) => {
+    };
+    // Claims grouped by front state, each group a collapsed <details> whose
+    // summary carries the stats a skimmer needs; the full matrix is one click
+    // away, not a wall the reader must climb to reach the takeaway.
+    const GROUPS = [
+        { states: ["open", "vacant"], title: "Open ground", blurb: "no vendor is loud here" },
+        { states: ["contested"], title: "Contested fronts", blurb: "2–3 vendors loud" },
+        { states: ["owned"], title: "Owned fronts", blurb: "exactly one vendor loud" },
+        { states: ["saturated"], title: "Saturated fronts", blurb: "4+ vendors loud" },
+    ];
+    const groupedMatrix = GROUPS.map((group) => {
+        const claimIds = model.orderedClaimIds.filter((claimId) => group.states.includes(stateByClaim.get(claimId) ?? "vacant"));
+        if (claimIds.length === 0)
+            return "";
+        const anchorLoud = anchor
+            ? claimIds.filter((claimId) => model.cell(anchor, claimId)?.intensity === "loud").length
+            : 0;
+        const anchorNote = anchor ? ` · ${vendorNamesById.get(anchor) ?? anchor} loud on ${anchorLoud}` : "";
+        return `<details class="claim-group"><summary><b>${e(group.title)}</b> — ${claimIds.length} claim${claimIds.length === 1 ? "" : "s"} <span class="sum-soft">(${e(group.blurb)}${anchorNote})</span></summary>
+      <table><thead><tr><th></th>${"${vendorHeads}"}<th></th></tr></thead><tbody>${claimIds.map(matrixRow).join("")}</tbody></table>
+    </details>`;
+    }).join("");
+    // The closing argument: walk from open ground to a reasoned target list.
+    const openFronts = model.orderedClaimIds.filter((claimId) => {
         const state = stateByClaim.get(claimId);
         return state === "open" || state === "vacant";
-    })
+    });
+    const targetItems = openFronts
         .map((claimId) => {
         const claim = claimsById.get(claimId);
-        return `<li><b>${e(claim?.capability.split(":")[0] ?? claimId)}</b> <span class="why">— no vendor is loud here; ${e(claim?.icp ?? "")} cell</span></li>`;
+        const front = frontByClaim.get(claimId);
+        if (!claim || !front)
+            return "";
+        const quietNames = front.quietVendorIds.map((id) => vendorNamesById.get(id) ?? id);
+        const anchorIntensity = anchor ? model.cell(anchor, claimId)?.intensity ?? "unobservable" : null;
+        const nearest = quietNames.length > 0
+            ? `Closest contenders (quiet): ${quietNames.join(", ")}.`
+            : "Nobody even ships it quietly — vacant ground.";
+        const move = anchorIntensity === "quiet"
+            ? `${e(vendorNamesById.get(anchor) ?? "The anchor")} already ships this quietly — a promote-to-loud candidate.`
+            : anchorIntensity === "absent"
+                ? "Unclaimed by the anchor: a first-mover messaging opportunity if the capability is real or buildable."
+                : "";
+        return `<li><b>${e(claim.capability.split(":")[0])}</b> <span class="sum-soft">(${e(claim.icp)} · ${e(claim.pricingStructure)})</span><br>
+        No vendor is loud on this claim. ${e(nearest)} ${move}</li>`;
     })
         .join("");
-    const appendix = model.orderedClaimIds
-        .flatMap((claimId) => config.vendors.flatMap((vendor) => {
-        const obs = model.cell(vendor.id, claimId);
-        if (!obs || obs.evidence.length === 0)
-            return [];
-        return obs.evidence.map((evidence) => `<div class="ev"><span class="ev-head">${e(vendor.name)} · ${e(claimId)} · ${obs.intensity.toUpperCase()} (${obs.confidence})</span>` +
-            `<blockquote>“${e(evidence.text)}”</blockquote>` +
-            `<span class="ev-src">${e(String(evidence.metadata?.url ?? ""))} · capture ${e(String(evidence.metadata?.captureHash ?? "").slice(0, 12))}</span></div>`);
-    }))
+    const heldFronts = anchor
+        ? model.fronts.filter((front) => front.state === "owned" && front.loudVendorIds[0] === anchor)
+        : [];
+    const heldLine = heldFronts.length > 0
+        ? `<p><b>Held ground:</b> ${e(vendorNamesById.get(anchor) ?? "the anchor")} is the sole loud vendor on ${heldFronts
+            .map((front) => `<i>${e(claimsById.get(front.claimId)?.capability.split(":")[0] ?? front.claimId)}</i>`)
+            .join(", ")} — positions to defend, not abandon.</p>`
+        : "";
+    const crowdLine = counts.saturated > 0
+        ? `<p><b>Crowded ground:</b> ${counts.saturated} claim${counts.saturated === 1 ? " is" : "s are"} saturated (4+ vendors loud) — message budget spent there buys the least differentiation.</p>`
+        : "";
+    const takeaway = `<section>
+  <h2>Where to attack</h2>
+  <p class="lede">${openFronts.length === 0 ? "No open fronts this run — every claim has at least one loud vendor. Watch the drift between runs for windows opening." : `${openFronts.length} claim${openFronts.length === 1 ? "" : "s"} in this category ${openFronts.length === 1 ? "is" : "are"} open: buyers can be reached there without out-shouting anyone.`}</p>
+  <ul class="targets">${targetItems}</ul>
+  ${heldLine}
+  ${crowdLine}
+  <p class="sum-soft">These are messaging fronts, not verdicts — join the map to CRM ground truth (\`market overlay\`) for evidence-backed OCCUPY / PROMOTE / URGENT / RETREAT directives with win-rate stats.</p>
+</section>`;
+    // Evidence grouped by vendor, collapsed: receipts on demand, not a scroll wall.
+    const appendixGroups = config.vendors
+        .map((vendor) => {
+        const items = model.orderedClaimIds.flatMap((claimId) => {
+            const obs = model.cell(vendor.id, claimId);
+            if (!obs || obs.evidence.length === 0)
+                return [];
+            return obs.evidence.map((evidence) => `<div class="ev"><span class="ev-head">${e(claimId)} · ${obs.intensity.toUpperCase()} (${obs.confidence})</span>` +
+                `<blockquote>“${e(evidence.text)}”</blockquote>` +
+                `<span class="ev-src">${e(String(evidence.metadata?.url ?? ""))} · capture ${e(String(evidence.metadata?.captureHash ?? "").slice(0, 12))}</span></div>`);
+        });
+        if (items.length === 0)
+            return "";
+        return `<details class="ev-group"><summary><b>${e(vendor.name)}</b> <span class="sum-soft">— ${items.length} quoted span${items.length === 1 ? "" : "s"}</span></summary>${items.join("")}</details>`;
+    })
         .join("");
     const vendorHeads = config.vendors
         .map((vendor) => `<th class="vh${vendor.id === anchor ? " anchor-col" : ""}"><span>${e(vendor.name)}</span></th>`)
@@ -438,14 +499,16 @@ h1 { font-size:27px; font-weight:600; line-height:1.2; }
 .meta { font-size:11px; color:var(--soft); display:flex; gap:18px; flex-wrap:wrap; margin-top:8px; }
 section { margin-top:44px; }
 h2 { font-size:17px; font-weight:600; border-bottom:1px solid var(--line); padding-bottom:7px; margin-bottom:4px; }
-.fronts { display:grid; grid-template-columns:repeat(4,1fr); gap:1px; background:var(--line); border:1px solid var(--line); margin-top:16px; }
-.fcard { background:#fff; padding:14px 16px 12px; }
-.fcard b { display:block; font-size:30px; font-weight:600; line-height:1.1; }
-.fcard span { font-size:11px; color:var(--soft); }
-.fcard.open b { color:var(--accent); }
-.openlist { margin-top:14px; font-size:14.5px; line-height:1.55; }
-.openlist li { margin:3px 0 3px 20px; }
-.openlist .why { color:var(--soft); font-size:13px; }
+details.claim-group, details.ev-group { border:1px solid var(--line); border-radius:3px; margin-top:10px; }
+details.claim-group summary, details.ev-group summary { cursor:pointer; padding:10px 14px; font-size:14px; list-style-position:inside; }
+details.claim-group summary:hover, details.ev-group summary:hover { background:var(--faint); }
+details.claim-group[open] summary, details.ev-group[open] summary { border-bottom:1px solid var(--line); }
+details.claim-group table { margin:4px 12px 12px; width:calc(100% - 24px); }
+details.ev-group .ev { margin:0 14px; }
+.sum-soft { color:var(--soft); font-size:12px; }
+.lede { font-size:16px; margin-top:12px; }
+.targets { margin-top:12px; font-size:14.5px; line-height:1.6; }
+.targets li { margin:10px 0 10px 20px; }
 .key { display:flex; gap:20px; flex-wrap:wrap; margin:14px 0 8px; font-size:10.5px; color:var(--soft); }
 .lg { display:inline-flex; align-items:center; gap:6px; }
 table { border-collapse:collapse; width:100%; margin-top:6px; }
@@ -506,34 +569,24 @@ footer { margin-top:60px; border-top:1px solid var(--ink); padding-top:12px; fon
     <span>extractor: ${e(set.extractor)}</span>
   </div>
 </header>
+${axisHtml.strategicMap}
 <section>
-  <h2>Front summary</h2>
-  <div class="fronts">
-    <div class="fcard open"><b>${counts.open + counts.vacant}</b><span>Open / vacant</span></div>
-    <div class="fcard"><b>${counts.contested}</b><span>Contested</span></div>
-    <div class="fcard"><b>${counts.owned}</b><span>Owned</span></div>
-    <div class="fcard"><b>${counts.saturated}</b><span>Saturated</span></div>
-  </div>
-  <ul class="openlist">${openList}</ul>
-</section>
-<section>
-  <h2>Claim × vendor intensity matrix</h2>
+  <h2>Claims, front by front</h2>
   <div class="key">
     <span class="lg"><i class="g g-loud"></i>LOUD — hero-level claim</span>
     <span class="lg"><i class="g g-quiet"></i>QUIET — shipped, buried</span>
     <span class="lg"><i class="g g-absent"></i>ABSENT</span>
     <span class="lg"><i class="g g-unobservable"></i>UNOBSERVABLE — capture failed</span>
   </div>
-  <table>
-    <thead><tr><th></th>${vendorHeads}<th></th></tr></thead>
-    <tbody>${matrixRows}</tbody>
-  </table>
+  ${groupedMatrix}
 </section>
-${axisHtml.strategicMap}
+${takeaway}
 <section>
   <h2>Evidence appendix</h2>
-  ${appendix}
+  <p class="sum-soft">Every loud/quiet reading is grounded in a verbatim span from a stored page capture; expand a vendor for its receipts.</p>
+  ${appendixGroups}
 </section>
+<script>window.addEventListener("beforeprint",function(){document.querySelectorAll("details").forEach(function(d){d.open=true;});});</script>
 <footer>
   <span>Generated by fullstackgtm market · deterministic render of ${e(set.runLabel)}</span>
   <span>Front rule v1: 0 loud=open · 1=owned · 2–3=contested · ≥4=saturated</span>

package/dist/reassign.d.ts

@@ -0,0 +1,19 @@
+import type { CanonicalGtmSnapshot, PatchPlan } from "./types.ts";
+export type ReassignObjectType = "account" | "contact" | "deal";
+export type ReassignOptions = {
+    /** the owner whose records are being handed off */
+    fromOwnerId: string;
+    /** the receiving owner — must be a known user in the snapshot */
+    toOwnerId: string;
+    /** which object types to compile plans for (default all three) */
+    objects?: ReassignObjectType[];
+    /** extra --where scoping, AND-ed into every plan (account fields lifted) */
+    where?: string[];
+    /** exclude records tied to an open deal in this stage (see module doc) */
+    exceptDealStage?: string;
+    /** also reassign closed deals (default false: history keeps its owner) */
+    includeClosedDeals?: boolean;
+    reason?: string;
+    maxOperations?: number;
+};
+export declare function buildReassignPlans(snapshot: CanonicalGtmSnapshot, options: ReassignOptions): PatchPlan[];

package/dist/reassign.js

@@ -0,0 +1,87 @@
+/**
+ * The ownership-handoff playbook: `reassign` compiles one bulk-update-style
+ * dry-run plan PER object type (accounts, contacts, deals by default) that
+ * moves every record owned by --from to --to. It NEVER writes — each plan
+ * flows through the same plans-approve → apply gate, and because every plan
+ * carries its full filter, eligibility (extra --where scoping AND the
+ * --except-deal-stage exclusion) is re-verified per record against a FRESH
+ * snapshot at apply time, with mid-apply rechecks. A record that drifts into
+ * the exception set mid-run surfaces as a conflict, not a bad write.
+ *
+ * --except-deal-stage <stage> excludes in-flight business end to end:
+ *   - deal plans drop deals in that stage (stage!=<stage>), and
+ *   - ALL plans drop records whose account has an OPEN deal in that stage
+ *     (accounts: openDealStages!~<stage>; deals/contacts:
+ *     account.openDealStages!~<stage>).
+ *
+ * Deal plans cover OPEN deals only unless includeClosedDeals is set: closed
+ * deals keep their historical owner in a handoff.
+ *
+ * Extra --where clauses are account-scoped where needed: a clause on a field
+ * that only exists on accounts (e.g. domain~.de) is lifted to the relational
+ * pseudo-field (account.domain~.de) for contact and deal plans, so one
+ * invocation scopes all three object types consistently.
+ */
+import { buildBulkUpdatePlan, isFilterableField, parseWhere } from "./bulkUpdate.js";
+const ALL_OBJECTS = ["account", "contact", "deal"];
+/**
+ * Scope an extra --where clause to one object type: pass through when the
+ * field is valid there, lift account-only fields to account.<field> for
+ * contacts and deals. Unknown fields fall through to buildBulkUpdatePlan's
+ * strict validation, which throws with the valid-field list.
+ */
+function scopeWhere(objectType, raw) {
+    const clause = parseWhere(raw);
+    if (isFilterableField(objectType, clause.field))
+        return raw;
+    if (objectType !== "account" && isFilterableField(objectType, `account.${clause.field}`)) {
+        return `account.${raw}`;
+    }
+    return raw;
+}
+export function buildReassignPlans(snapshot, options) {
+    if (!options.fromOwnerId || !options.toOwnerId) {
+        throw new Error("reassign requires both --from <ownerId> and --to <ownerId>.");
+    }
+    if (options.fromOwnerId === options.toOwnerId) {
+        throw new Error("reassign --from and --to are the same owner — nothing to hand off.");
+    }
+    // The receiving owner must exist: a typo'd --to would otherwise write an
+    // invalid owner onto every matched record.
+    if (!snapshot.users.some((user) => user.id === options.toOwnerId)) {
+        throw new Error(`reassign --to ${options.toOwnerId} is not a known user in the snapshot. Known users: ${snapshot.users
+            .map((user) => `${user.id} (${user.name})`)
+            .join(", ") || "none"}.`);
+    }
+    const objects = options.objects ?? ALL_OBJECTS;
+    for (const objectType of objects) {
+        if (!ALL_OBJECTS.includes(objectType)) {
+            throw new Error(`reassign --objects supports account, contact, deal — got "${objectType}".`);
+        }
+    }
+    return objects.map((objectType) => {
+        const where = [`ownerId=${options.fromOwnerId}`];
+        if (objectType === "deal" && !options.includeClosedDeals) {
+            where.push("isClosed=false"); // closed deals keep their historical owner
+        }
+        for (const extra of options.where ?? []) {
+            where.push(scopeWhere(objectType, extra));
+        }
+        if (options.exceptDealStage) {
+            const stage = options.exceptDealStage;
+            if (objectType === "deal")
+                where.push(`stage!=${stage}`);
+            where.push(objectType === "account"
+                ? `openDealStages!~${stage}`
+                : `account.openDealStages!~${stage}`);
+        }
+        return buildBulkUpdatePlan(snapshot, {
+            objectType,
+            where,
+            set: { ownerId: options.toOwnerId },
+            reason: options.reason ??
+                `reassign: hand off ${objectType}s from owner ${options.fromOwnerId} to ${options.toOwnerId}`,
+            maxOperations: options.maxOperations,
+        });
+    });
+}

package/dist/suggest.js

@@ -64,11 +64,39 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
     if (!deal) {
         return { ...base, suggestedValue: null, confidence: "none", reason: "Deal not found in the snapshot." };
     }
-    // Convention: "Contact Name - Company Name". Both signals below are
-    // independent; agreement upgrades confidence, conflict downgrades it.
-    const separatorIndex = deal.name.indexOf(" - ");
-    const left = separatorIndex >= 0 ? deal.name.slice(0, separatorIndex) : deal.name;
-    const right = separatorIndex >= 0 ? deal.name.slice(separatorIndex + 3).trim() : "";
+    // Convention 1: "Contact Name - Company Name" (hyphen, en or em dash).
+    // Both signals below are independent; agreement upgrades confidence,
+    // conflict downgrades it.
+    const separator = [" - ", " – ", " — "]
+        .map((s) => ({ s, index: deal.name.indexOf(s) }))
+        .filter(({ index }) => index >= 0)
+        .sort((a, b) => a.index - b.index)[0];
+    const left = separator ? deal.name.slice(0, separator.index).trim() : deal.name;
+    const right = separator ? deal.name.slice(separator.index + separator.s.length).trim() : "";
+    // Convention 2: "Company - Deal descriptor" (e.g. "Globex – Expansion",
+    // "Hooli – New Business"). When the right side is purely deal-descriptor
+    // words, the company is on the LEFT. Only an exact account-name match
+    // counts as high; an unknown left side proposes a create — the engine
+    // never guesses at an existing record.
+    if (left && right && isDealDescriptor(right)) {
+        const leftMatch = accountsByNorm.get(normalize(left));
+        if (leftMatch) {
+            return {
+                ...base,
+                suggestedValue: leftMatch.id,
+                confidence: "high",
+                reason: `Deal name leads with the exact account name "${leftMatch.name}" ("${right}" is a deal descriptor, not a company).`,
+            };
+        }
+        if (!contactsByName.get(normalize(left))) {
+            return {
+                ...base,
+                suggestedValue: `create:${left}`,
+                confidence: "create",
+                reason: `No account named "${left}" exists ("${right}" is a deal descriptor) — approving creates the company, then links.`,
+            };
+        }
+    }
     // Signal 1: company-name match against account names.
     let nameMatch = null;
     let nameMatchKind = "";
@@ -135,6 +163,23 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             reason: `No account named "${right}" exists and contact "${left}" has none — approving creates the company, then links.`,
         };
     }
+    // Convention 3: "<Company> <descriptor…>" without a separator (e.g.
+    // "INITECH renewal"): strip trailing descriptor words and accept only an
+    // exact account-name match on what remains.
+    if (!separator) {
+        const words = normalize(deal.name).split(" ").filter(Boolean);
+        while (words.length > 1 && DEAL_DESCRIPTOR_WORDS.has(words[words.length - 1]))
+            words.pop();
+        const strippedMatch = words.length > 0 ? accountsByNorm.get(words.join(" ")) : undefined;
+        if (strippedMatch) {
+            return {
+                ...base,
+                suggestedValue: strippedMatch.id,
+                confidence: "high",
+                reason: `Deal name leads with the exact account name "${strippedMatch.name}" (trailing words are deal descriptors).`,
+            };
+        }
+    }
     return {
         ...base,
         suggestedValue: null,
@@ -144,6 +189,23 @@ function suggestDealAccount(operation, dealsById, accountsByNorm, accountsById,
             : `Deal name "${deal.name}" has no "Contact - Company" pattern to derive a company from. Supply --value ${operation.id}=<accountId> or create:<Company Name>.`,
     };
 }
+/**
+ * Words that describe the deal rather than name a company. Used to recognize
+ * the "Company - Deal descriptor" naming convention: a segment counts as a
+ * descriptor only when EVERY word is in this list, so any real company name
+ * ("Brand New Startup") falls through to the contact/company conventions.
+ */
+const DEAL_DESCRIPTOR_WORDS = new Set([
+    "renewal", "expansion", "pilot", "annual", "monthly", "platform", "new", "business",
+    "add", "on", "addon", "upsell", "upgrade", "trial", "poc", "proof", "concept",
+    "subscription", "license", "licence", "contract", "opportunity", "deal", "engagement",
+    "implementation", "onboarding", "services", "inbound", "outbound",
+    "q1", "q2", "q3", "q4",
+]);
+function isDealDescriptor(segment) {
+    const words = normalize(segment).split(" ").filter(Boolean);
+    return words.length > 0 && words.every((word) => DEAL_DESCRIPTOR_WORDS.has(word));
+}
 /**
  * Survivor selection for merge_records. Ranking is deterministic and
  * evidence-based: most complete record first (count of populated canonical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullstackgtm",
-  "version": "0.21.2",
+  "version": "0.22.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/bulkUpdate.ts

@@ -27,6 +27,7 @@
  * `account.ownerId`, `account.contactCount`; accounts get `contactCount`
  * and `openDealCount`.
  */
+import { normalizeDomain } from "./merge.ts";
 import { stableHash } from "./rules.ts";
 import type {
   CanonicalGtmSnapshot,
@@ -40,10 +41,23 @@ export type BulkUpdateOptions = {
   objectType: "account" | "contact" | "deal";
   /** raw --where expressions, AND-ed together; at least one is required */
   where: string[];
-  /** canonical field → new value; one action only */
+  /**
+   * canonical field → new value; one action only. A value of the form
+   * `from:<sourceField>` is resolved PER RECORD from the filter view at
+   * plan time (relational pseudo-fields like account.ownerId included);
+   * records whose source value is empty are skipped, not failed, and
+   * counted in the plan summary.
+   */
   set?: Record<string, string>;
   /** propose archive_record instead of field writes */
   archive?: boolean;
+  /**
+   * bypass the archive duplicate guard: by default --archive refuses when a
+   * matched account/contact shares its identity key (normalized domain /
+   * lowercased email) with another record — those are duplicates, and
+   * archiving a duplicate discards its data where merging preserves it
+   */
+  forceArchiveDuplicates?: boolean;
   /** propose create_task on each matched record with this subject/body text */
   createTask?: string;
   /** explicit preconditions (field=value), re-verified at apply time */
@@ -131,6 +145,14 @@ const VALID_FIELDS: Record<BulkUpdateOptions["objectType"], Set<string>> = {
   deal: new Set(["id", "crmId", "accountId", "ownerId", "name", "amount", "currency", "stage", "closeDate", "dealType", "forecastCategory", "nextStep", "probability", "isClosed", "isWon", "lastActivityAt", "lastSyncAt", ...RELATIONAL_FIELDS]),
 };
 
+/** True when `field` is filterable for this object type (relational pseudo-fields included). */
+export function isFilterableField(
+  objectType: BulkUpdateOptions["objectType"],
+  field: string,
+): boolean {
+  return VALID_FIELDS[objectType].has(field);
+}
+
 function assertValidFields(objectType: BulkUpdateOptions["objectType"], clauses: WhereClause[], context: string): void {
   for (const clause of clauses) {
     if (!VALID_FIELDS[objectType].has(clause.field)) {
@@ -251,10 +273,25 @@ export function buildBulkUpdatePlan(
   const clauses = options.where.map(parseWhere);
   assertValidFields(options.objectType, clauses, "--where");
   const WRITABLE_BLOCKLIST = new Set(["id", "crmId", "contactCount", "openDealCount", "openDealStages"]);
-  for (const field of Object.keys(options.set ?? {})) {
+  // `from:<sourceField>` values resolve per record from the filter view —
+  // the source is validated with the same strictness as filters (relational
+  // pseudo-fields allowed; the WRITTEN field still must be canonical).
+  const assignments: Array<{ field: string; literal?: string; fromField?: string }> = [];
+  for (const [field, value] of Object.entries(options.set ?? {})) {
     if (!VALID_FIELDS[options.objectType].has(field) || WRITABLE_BLOCKLIST.has(field) || field.includes(".")) {
       throw new Error(`Cannot --set "${field}" on ${options.objectType}s — not a writable canonical field.`);
     }
+    if (value.startsWith("from:")) {
+      const fromField = value.slice("from:".length);
+      if (!VALID_FIELDS[options.objectType].has(fromField)) {
+        throw new Error(
+          `Cannot --set ${field}=from:${fromField} on ${options.objectType}s — unknown source field "${fromField}". Valid fields: ${[...VALID_FIELDS[options.objectType]].join(", ")}.`,
+        );
+      }
+      assignments.push({ field, fromField });
+    } else {
+      assignments.push({ field, literal: value });
+    }
   }
   const views = buildViews(snapshot, options.objectType);
   const matched = views.filter(({ view }) => clauses.every((c) => matches(view, c)));
@@ -264,6 +301,45 @@ export function buildBulkUpdatePlan(
     );
   }
 
+  // Archive duplicate guard: archiving a record that shares its identity key
+  // with another active record discards data a merge would preserve. Refuse
+  // and point at `dedupe` unless explicitly overridden. Deals are exempt —
+  // they carry no identity key.
+  if (options.archive && options.objectType !== "deal" && !options.forceArchiveDuplicates) {
+    const keyName = options.objectType === "account" ? "domain" : "email";
+    const keyOf = (record: Record<string, unknown>): string | undefined =>
+      options.objectType === "account"
+        ? normalizeDomain(record.domain as string | undefined)
+        : ((record.email as string | undefined)?.trim().toLowerCase() || undefined);
+    const allRecords = snapshot[COLLECTIONS[options.objectType]] as Array<Record<string, unknown>>;
+    const byKey = new Map<string, Array<Record<string, unknown>>>();
+    for (const record of allRecords) {
+      const key = keyOf(record);
+      if (!key) continue;
+      const existing = byKey.get(key) ?? [];
+      existing.push(record);
+      byKey.set(key, existing);
+    }
+    const collisions: string[] = [];
+    for (const { record } of matched) {
+      const key = keyOf(record);
+      if (!key) continue;
+      const others = (byKey.get(key) ?? []).filter((other) => other.id !== record.id);
+      if (others.length === 0) continue;
+      const label = (record.name as string | undefined) ?? (record.email as string | undefined) ?? "";
+      collisions.push(
+        `${options.objectType} ${record.id}${label ? ` "${label}"` : ""} shares ${keyName} "${key}" with ${others
+          .map((other) => `${other.id}${other.name ? ` "${other.name}"` : ""}`)
+          .join(", ")}`,
+      );
+    }
+    if (collisions.length > 0) {
+      throw new Error(
+        `Refusing to archive: ${collisions.length} matched record(s) look like duplicates of other records — archiving a duplicate DISCARDS its data, merging preserves it. Use \`fullstackgtm dedupe ${options.objectType} --key ${keyName}\` (merge_records) instead, or pass --force-archive-duplicates to archive anyway.\n  - ${collisions.join("\n  - ")}`,
+      );
+    }
+  }
+
   // Preconditions: explicit --require, plus every equality filter on a real
   // (re-readable, non-relational) field. The premise the plan was built on
   // is re-verified per record at apply time.
@@ -295,7 +371,9 @@ export function buildBulkUpdatePlan(
   const reason = options.reason ?? `bulk-update: ${action} where ${whereText}`;
 
   const operations: PatchOperation[] = [];
-  for (const { record } of matched) {
+  // records skipped because a from:<sourceField> value was empty, per source
+  const skippedBySource = new Map<string, number>();
+  for (const { record, view } of matched) {
     const objectId = String(record.id);
     const groupId = `grp_${options.objectType}_${objectId}`;
     const preconditions = preconditionSpecs.map((p) => ({
@@ -338,7 +416,29 @@ export function buildBulkUpdatePlan(
       });
       continue;
     }
-    for (const [field, value] of Object.entries(options.set!)) {
+    // Resolve every assignment for this record BEFORE emitting any of its
+    // operations: a record whose from:<sourceField> resolves empty is
+    // skipped whole (its operations share a groupId — half a record's
+    // updates is exactly what grouping exists to prevent).
+    const resolved: Array<{ field: string; value: string }> = [];
+    let emptySource: string | null = null;
+    for (const assignment of assignments) {
+      if (assignment.fromField !== undefined) {
+        const value = fieldValue(view, assignment.fromField);
+        if (value === "") {
+          emptySource = assignment.fromField;
+          break;
+        }
+        resolved.push({ field: assignment.field, value });
+      } else {
+        resolved.push({ field: assignment.field, value: assignment.literal! });
+      }
+    }
+    if (emptySource !== null) {
+      skippedBySource.set(emptySource, (skippedBySource.get(emptySource) ?? 0) + 1);
+      continue;
+    }
+    for (const { field, value } of resolved) {
       operations.push({
         ...shared,
         id: `op_${stableHash(`bulk-set:${options.objectType}:${objectId}:${field}:${value}`)}`,
@@ -360,13 +460,16 @@ export function buildBulkUpdatePlan(
     if (failure) throw new Error(`${failure} The guard already fails against the current snapshot — the plan would never apply.`);
   }
 
+  const skippedText = [...skippedBySource.entries()]
+    .map(([sourceField, count]) => ` ${count} skipped: empty ${sourceField}.`)
+    .join("");
   return {
-    id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${whereText}:${action}:${operations.length}`)}`,
+    id: `patch_plan_${stableHash(`bulk:${snapshot.provider}:${snapshot.generatedAt}:${options.objectType}:${whereText}:${action}:${operations.length}`)}`,
     title: `Bulk update: ${options.objectType}s where ${whereText}`,
     createdAt: snapshot.generatedAt,
     status: operations.length > 0 ? "needs_approval" : "draft",
     dryRun: true,
-    summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
+    summary: `${matched.length} ${COLLECTIONS[options.objectType]} matched (${whereText}); ${operations.length} proposed dry-run operations (${action}).${skippedText}${guards.length > 0 ? ` ${guards.length} apply-time guard(s).` : ""}`,
     findings: [],
     operations,
     filter: { objectType: options.objectType, where: options.where },