fullstackgtm 0.18.0 → 0.20.0

package/dist/marketOverlay.js

@@ -0,0 +1,258 @@
+import { computeFrontStates, diffFrontStates } from "./market.js";
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function termPattern(terms) {
+    const cleaned = terms.map((term) => term.trim()).filter(Boolean);
+    if (cleaned.length === 0)
+        return null;
+    const escaped = cleaned.map((term) => term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+"));
+    return new RegExp(`\\b(?:${escaped.join("|")})\\b`, "i");
+}
+/**
+ * Deterministic claim/vendor mention statistics over a call corpus.
+ * Claims match on their configured `terms` (claims without terms simply have
+ * no mention stats — the directives that need mentions will not fire for
+ * them); vendors match on name + configured `aliases`.
+ */
+export function computeOverlayStats(config, snapshot, documents) {
+    const dealById = new Map(snapshot.deals.map((deal) => [deal.id, deal]));
+    const closed = snapshot.deals.filter((deal) => deal.isClosed === true);
+    const won = closed.filter((deal) => deal.isWon === true);
+    const baselineWinRate = closed.length > 0 ? won.length / closed.length : null;
+    const dealOutcome = (dealIds) => {
+        let wonCount = 0;
+        let lostCount = 0;
+        for (const dealId of dealIds) {
+            const deal = dealById.get(dealId);
+            if (!deal || deal.isClosed !== true)
+                continue;
+            if (deal.isWon === true)
+                wonCount += 1;
+            else
+                lostCount += 1;
+        }
+        return { wonCount, lostCount };
+    };
+    const claims = config.claims.map((claim) => {
+        const pattern = termPattern(claim.terms ?? []);
+        const mentionDocs = pattern ? documents.filter((doc) => pattern.test(doc.text)) : [];
+        const mentionDealIds = [...new Set(mentionDocs.map((doc) => doc.dealId).filter((id) => !!id))];
+        const { wonCount, lostCount } = dealOutcome(mentionDealIds);
+        return {
+            claimId: claim.id,
+            mentionDocIds: mentionDocs.map((doc) => doc.id),
+            mentionDealIds,
+            wonDeals: wonCount,
+            lostDeals: lostCount,
+            winRateWhenMentioned: wonCount + lostCount > 0 ? wonCount / (wonCount + lostCount) : null,
+        };
+    });
+    const vendors = config.vendors.map((vendor) => {
+        const pattern = termPattern([vendor.name, ...(vendor.aliases ?? [])]);
+        const mentionDocs = pattern ? documents.filter((doc) => pattern.test(doc.text)) : [];
+        const mentionDealIds = [...new Set(mentionDocs.map((doc) => doc.dealId).filter((id) => !!id))];
+        const { wonCount, lostCount } = dealOutcome(mentionDealIds);
+        return {
+            vendorId: vendor.id,
+            mentionDocIds: mentionDocs.map((doc) => doc.id),
+            mentionDealIds,
+            wonWhenMentioned: wonCount,
+            lostWhenMentioned: lostCount,
+        };
+    });
+    return {
+        documents: documents.length,
+        documentsWithDeal: documents.filter((doc) => doc.dealId).length,
+        deals: { total: snapshot.deals.length, closed: closed.length, won: won.length, baselineWinRate },
+        claims,
+        vendors,
+    };
+}
+/**
+ * Directive rules v1 — deterministic over (front states × overlay stats),
+ * with explicit minimum-evidence thresholds so small samples cannot mint
+ * strategy. Requires config.anchorVendor: directives are advice to someone.
+ *
+ *   OCCUPY  — open/vacant front the anchor doesn't own loudly, and buyers
+ *             demonstrably talk about it (≥ minMentions documents).
+ *   PROMOTE — anchor is quiet on a claim whose mentioned-deal win rate beats
+ *             baseline by ≥ promoteLift (with ≥ minMentions mentioned deals).
+ *   URGENT  — a front the anchor is loud on drifted toward saturation since
+ *             the prior run (requires priorSet).
+ *   RETREAT — saturated front the anchor is loud on, with zero presence in
+ *             won-deal conversations despite a corpus that contains wins.
+ */
+export function computeDirectives(config, set, stats, options = {}) {
+    const anchor = config.anchorVendor;
+    if (!anchor)
+        throw new Error("market overlay requires anchorVendor in the config — directives are advice to someone");
+    const minMentions = options.minMentions ?? 3;
+    const promoteLift = options.promoteLift ?? 0.1;
+    const minWonDealsForRetreat = options.minWonDealsForRetreat ?? 3;
+    const fronts = computeFrontStates(config, set);
+    const frontByClaim = new Map(fronts.map((front) => [front.claimId, front]));
+    const statsByClaim = new Map(stats.claims.map((claim) => [claim.claimId, claim]));
+    const anchorIntensity = new Map();
+    const loudObservationIds = new Map();
+    for (const obs of set.observations) {
+        if (obs.vendorId === anchor)
+            anchorIntensity.set(obs.claimId, { intensity: obs.intensity, observationId: obs.id });
+        if (obs.intensity === "loud") {
+            const ids = loudObservationIds.get(obs.claimId) ?? [];
+            ids.push(obs.id);
+            loudObservationIds.set(obs.claimId, ids);
+        }
+    }
+    const directives = [];
+    const claimName = new Map(config.claims.map((claim) => [claim.id, claim.capability.split(":")[0]]));
+    const push = (type, claimId, summary, recommendation, observationIds, statsList) => {
+        directives.push({
+            id: `dir_${fnv1a(`${config.category}|${set.runLabel}|${type}|${claimId}`)}`,
+            type,
+            claimId,
+            title: `${type.toUpperCase()}: ${claimName.get(claimId) ?? claimId}`,
+            summary,
+            recommendation,
+            observationIds: [...new Set(observationIds)].filter(Boolean),
+            stats: statsList,
+        });
+    };
+    for (const claim of config.claims) {
+        const front = frontByClaim.get(claim.id);
+        const mention = statsByClaim.get(claim.id);
+        const anchorObs = anchorIntensity.get(claim.id);
+        if (!front || !anchorObs)
+            continue;
+        if ((front.state === "open" || front.state === "vacant") &&
+            (anchorObs.intensity === "absent" || anchorObs.intensity === "quiet") &&
+            mention &&
+            mention.mentionDocIds.length >= minMentions) {
+            push("occupy", claim.id, `No vendor is loud on this claim, and it came up in ${mention.mentionDocIds.length} of ${stats.documents} call documents.`, `Claim it: buyers already talk about this and nobody owns the message. Anchor is currently ${anchorObs.intensity}.`, [anchorObs.observationId], [
+                { name: "mention_documents", value: mention.mentionDocIds.length, n: stats.documents },
+                { name: "front_state", value: front.state, n: config.vendors.length },
+            ]);
+        }
+        if (anchorObs.intensity === "quiet" &&
+            mention &&
+            mention.winRateWhenMentioned !== null &&
+            stats.deals.baselineWinRate !== null &&
+            mention.wonDeals + mention.lostDeals >= minMentions &&
+            mention.winRateWhenMentioned >= stats.deals.baselineWinRate + promoteLift) {
+            push("promote", claim.id, `Anchor ships this quietly; deals where it comes up close at ${(mention.winRateWhenMentioned * 100).toFixed(0)}% vs ${(stats.deals.baselineWinRate * 100).toFixed(0)}% baseline.`, "Turn it loud: the conversion fingerprint says this claim wins deals when discussed.", [anchorObs.observationId], [
+                { name: "win_rate_when_mentioned", value: Number(mention.winRateWhenMentioned.toFixed(3)), n: mention.wonDeals + mention.lostDeals },
+                { name: "baseline_win_rate", value: Number(stats.deals.baselineWinRate.toFixed(3)), n: stats.deals.closed },
+            ]);
+        }
+        if (front.state === "saturated" &&
+            anchorObs.intensity === "loud" &&
+            mention &&
+            stats.deals.won >= minWonDealsForRetreat &&
+            stats.documentsWithDeal > 0 &&
+            mention.wonDeals === 0) {
+            push("retreat", claim.id, `${front.loudVendorIds.length} vendors shout this claim; it appears in zero of the anchor's won-deal conversations (${stats.deals.won} won deals in corpus).`, "Stop spending message budget on a saturated front that never shows up in wins.", [anchorObs.observationId, ...(loudObservationIds.get(claim.id) ?? [])], [
+                { name: "won_deals_mentioning", value: 0, n: stats.deals.won },
+                { name: "loud_vendors", value: front.loudVendorIds.length, n: config.vendors.length },
+            ]);
+        }
+    }
+    if (options.priorSet) {
+        const drift = diffFrontStates(computeFrontStates(config, options.priorSet), fronts);
+        const toward = (before, after) => {
+            const order = ["vacant", "open", "owned", "contested", "saturated"];
+            return order.indexOf(after) > order.indexOf(before);
+        };
+        for (const change of drift) {
+            const anchorObs = anchorIntensity.get(change.claimId);
+            if (!anchorObs || anchorObs.intensity !== "loud" || !toward(change.before, change.after))
+                continue;
+            const mention = statsByClaim.get(change.claimId);
+            push("urgent", change.claimId, `Front moved ${change.before} → ${change.after} since ${options.priorSet.runLabel} on a claim the anchor is loud on.`, "The window is closing: decide whether to defend (differentiate the claim) or bank the position before it saturates.", [anchorObs.observationId], [
+                { name: "front_drift", value: `${change.before}→${change.after}`, n: config.vendors.length },
+                { name: "mention_documents", value: mention?.mentionDocIds.length ?? 0, n: stats.documents },
+            ]);
+        }
+    }
+    return directives.sort((a, b) => a.type.localeCompare(b.type) || a.claimId.localeCompare(b.claimId));
+}
+/**
+ * Emit directives as a standard dry-run patch plan: one approval-gated
+ * create_task per directive against a designated CRM record (the company's
+ * own account/deal record — directives are strategy tasks, and the CRM
+ * needs somewhere to hang them). Approving and applying goes through the
+ * normal plans → approve → apply gate; nothing here writes.
+ */
+export function directivesToPlan(config, set, directives, target, now = () => new Date()) {
+    const createdAt = now().toISOString();
+    const findings = directives.map((directive) => ({
+        id: `find_${fnv1a(directive.id)}`,
+        objectType: target.objectType,
+        objectId: target.objectId,
+        ruleId: `market_directive_${directive.type}`,
+        title: directive.title,
+        severity: directive.type === "urgent" ? "critical" : "warning",
+        summary: directive.summary,
+        recommendation: directive.recommendation,
+        evidenceIds: directive.observationIds,
+    }));
+    const evidence = directives.map((directive) => ({
+        id: `ev_${fnv1a(directive.id)}`,
+        sourceSystem: "web",
+        sourceObjectType: "market_map",
+        sourceObjectId: `${config.category}/${set.runLabel}`,
+        title: directive.title,
+        text: `${directive.summary} Stats: ${directive.stats.map((stat) => `${stat.name}=${stat.value} (n=${stat.n})`).join("; ")}`,
+        observedAt: set.runAt,
+        metadata: { observationIds: directive.observationIds, stats: directive.stats },
+    }));
+    const operations = directives.map((directive) => ({
+        id: `op_${fnv1a(directive.id)}`,
+        objectType: target.objectType,
+        objectId: target.objectId,
+        operation: "create_task",
+        field: "task",
+        afterValue: `${directive.title} — ${directive.recommendation} (${directive.stats.map((stat) => `${stat.name}=${stat.value}, n=${stat.n}`).join("; ")})`,
+        reason: directive.summary,
+        riskLevel: "low",
+        approvalRequired: true,
+        sourceRuleOrPolicy: `market_directive_${directive.type}`,
+        evidenceIds: [`ev_${fnv1a(directive.id)}`],
+    }));
+    return {
+        id: `patch_plan_market_${fnv1a(`${config.category}|${set.runLabel}|${createdAt}`)}`,
+        title: `Market directives — ${config.category} (${set.runLabel})`,
+        createdAt,
+        status: "needs_approval",
+        dryRun: true,
+        summary: `${directives.length} directive(s) from the ${config.category} market map joined to CRM ground truth.`,
+        findings,
+        evidence,
+        operations,
+    };
+}
+export function overlayToMarkdown(stats, directives) {
+    const lines = [];
+    lines.push(`Corpus: ${stats.documents} documents (${stats.documentsWithDeal} deal-linked) · ` +
+        `${stats.deals.closed} closed deals, ${stats.deals.won} won` +
+        (stats.deals.baselineWinRate !== null ? ` (baseline ${(stats.deals.baselineWinRate * 100).toFixed(0)}%)` : ""));
+    lines.push("");
+    if (directives.length === 0) {
+        lines.push("No directives met the evidence thresholds. That is an answer, not a failure:");
+        lines.push("either the corpus is too thin (add calls), or the current position needs no move.");
+    }
+    for (const directive of directives) {
+        lines.push(`## ${directive.title}`);
+        lines.push(directive.summary);
+        lines.push(`→ ${directive.recommendation}`);
+        lines.push(`evidence: ${directive.observationIds.length} observation(s) · ${directive.stats
+            .map((stat) => `${stat.name}=${stat.value} (n=${stat.n})`)
+            .join(" · ")}`);
+        lines.push("");
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/marketReport.js

@@ -1,5 +1,6 @@
 import { computeFrontStates } from "./market.js";
 import { assessAxes, messageBreadth } from "./marketAxes.js";
+import { computeScaleIndex } from "./marketScale.js";
 /**
  * Render a market map as a client-ready deliverable: markdown for terminals
  * and PRs, and a self-contained printable HTML "field report" — front
@@ -98,7 +99,8 @@ function svgScatter(points, ax, ay, anchor, mini) {
     const e = escapeHtml;
     const dots = points
         .map((p) => {
-        const r = mini ? 3 + p.loud * 0.8 : 6 + p.loud * 1.6;
+        // Area-proportional: perceived bubble area tracks the size metric.
+        const r = (mini ? 4 + 14 * Math.sqrt(p.size) : 8 + 26 * Math.sqrt(p.size));
         const cls = p.vendorId === anchor ? "dot-anchor" : "dot";
         return (`<circle class="${cls}" cx="${sx(p.x).toFixed(1)}" cy="${sy(p.y).toFixed(1)}" r="${r.toFixed(1)}"/>` +
             `<text class="dot-label" style="font-size:${fsLabel}px" x="${sx(p.x).toFixed(1)}" y="${(sy(p.y) - r - 4).toFixed(1)}">${e(p.name)}</text>`);
@@ -121,7 +123,18 @@ function axisSectionsHtml(config, set) {
     const e = escapeHtml;
     const report = assessAxes(config, set);
     const vendorNames = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    // Bubble size: scale index (relative market scale from citable signals)
+    // when every placeable vendor has one; LOUD count otherwise — never mix
+    // the two semantics on one chart.
+    const scale = computeScaleIndex(config);
+    const scaleIndex = new Map(scale.vendors.map((vendor) => [vendor.vendorId, vendor.index]));
+    const useScale = report.vendors.length > 0 && report.vendors.every((vendorId) => scaleIndex.get(vendorId) !== null && scaleIndex.get(vendorId) !== undefined);
     const loudCounts = new Map(report.vendors.map((vendorId) => [vendorId, messageBreadth(vendorId, set.observations).loudCount]));
+    const maxLoud = Math.max(1, ...loudCounts.values());
+    const sizeOf = (vendorId) => useScale ? scaleIndex.get(vendorId) : (loudCounts.get(vendorId) ?? 0) / maxLoud;
+    const sizeCaption = useScale
+        ? `Dot area &#8733; relative scale index (within this vendor set, from: ${e(scale.metricsUsed.join(", "))} — citable signals, not true market share)`
+        : "Dot area &#8733; LOUD count";
     const breadthAxis = {
         id: "breadth",
         label: "Message breadth",
@@ -158,7 +171,7 @@ function axisSectionsHtml(config, set) {
             name: vendorNames.get(vendorId) ?? vendorId,
             x: xs.get(vendorId),
             y: ys.get(vendorId),
-            loud: loudCounts.get(vendorId) ?? 0,
+            size: sizeOf(vendorId),
         }));
     };
     const [px, py] = config.primaryAxes ?? [axes[0].id, axes[1]?.id ?? "breadth"];
@@ -170,7 +183,7 @@ function axisSectionsHtml(config, set) {
   <figure>${svgScatter(pointsFor(px, py), axInfo, ayInfo, config.anchorVendor, false)}
   <figcaption>Positions computed from run ${e(set.runLabel)} observations: each axis is a per-claim scoring rubric
   in the market config; a vendor sits at the intensity-weighted mean (loud=1, quiet=&#189;) of the claims it
-  voices. Dot size = LOUD count. Axis status — ${e(axInfo.label)}: ${e(statusOf(px))}; ${e(ayInfo.label)}: ${e(statusOf(py))}.</figcaption>
+  voices. ${sizeCaption}. Axis status — ${e(axInfo.label)}: ${e(statusOf(px))}; ${e(ayInfo.label)}: ${e(statusOf(py))}.</figcaption>
   </figure>
 </section>`;
     // Deliberately no axis-pairing gallery here: the report is the client-facing

package/dist/marketScale.d.ts

@@ -0,0 +1,42 @@
+import type { MarketConfig, ScaleSignal } from "./market.ts";
+/**
+ * Relative scale index over the mapped vendor set — the honest version of
+ * "bubble size = market share". True segment market share is unknowable from
+ * public data for mostly-private vendor sets, so this computes a composite
+ * index from whatever citable signals exist per vendor (review counts,
+ * headcount, disclosed revenue, self-reported customers), each of which is
+ * biased in a different direction; the composite triangulates.
+ *
+ * Method, deterministic and auditable:
+ *   1. Per metric, log10(value + 1) — these signals span orders of magnitude.
+ *   2. Normalize each metric to [0, 1] across the vendors that HAVE it
+ *      (min–max within the set; a metric only one vendor has is skipped —
+ *      it cannot rank anyone).
+ *   3. A vendor's index = arithmetic mean of its normalized metric scores
+ *      (mean-of-normalized rather than geometric-of-raw so missing signals
+ *      neither punish nor reward), reported with coverage (which metrics).
+ *
+ * Vendors with zero signals get index null — the report falls back to its
+ * LOUD-count sizing for the whole map rather than mixing semantics.
+ */
+export type VendorScale = {
+    vendorId: string;
+    /** [0, 1] within the mapped set; null when the vendor has no usable signals. */
+    index: number | null;
+    /** Metrics that contributed, with their normalized scores. */
+    coverage: Array<{
+        metric: string;
+        value: number;
+        normalized: number;
+    }>;
+    signals: ScaleSignal[];
+};
+export type ScaleReport = {
+    vendors: VendorScale[];
+    /** Metrics used (present for ≥2 vendors) and metrics skipped (singletons). */
+    metricsUsed: string[];
+    metricsSkipped: string[];
+    complete: boolean;
+};
+export declare function computeScaleIndex(config: MarketConfig): ScaleReport;
+export declare function scaleReportToText(config: MarketConfig, report: ScaleReport): string;

package/dist/marketScale.js

@@ -0,0 +1,68 @@
+export function computeScaleIndex(config) {
+    const byMetric = new Map();
+    for (const vendor of config.vendors) {
+        for (const signal of vendor.scaleSignals ?? []) {
+            if (!Number.isFinite(signal.value) || signal.value < 0)
+                continue;
+            const rows = byMetric.get(signal.metric) ?? [];
+            rows.push({ vendorId: vendor.id, value: signal.value });
+            byMetric.set(signal.metric, rows);
+        }
+    }
+    const metricsUsed = [];
+    const metricsSkipped = [];
+    const normalized = new Map();
+    for (const [metric, rows] of byMetric) {
+        // Last write wins if a vendor lists the same metric twice.
+        const perVendor = new Map(rows.map((row) => [row.vendorId, row.value]));
+        if (perVendor.size < 2) {
+            metricsSkipped.push(metric);
+            continue;
+        }
+        metricsUsed.push(metric);
+        const logs = new Map([...perVendor].map(([vendorId, value]) => [vendorId, Math.log10(value + 1)]));
+        const values = [...logs.values()];
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        const span = hi - lo || 1;
+        const scores = new Map();
+        for (const [vendorId, log] of logs) {
+            scores.set(vendorId, { value: perVendor.get(vendorId), normalized: (log - lo) / span });
+        }
+        normalized.set(metric, scores);
+    }
+    metricsUsed.sort();
+    metricsSkipped.sort();
+    const vendors = config.vendors.map((vendor) => {
+        const coverage = [];
+        for (const metric of metricsUsed) {
+            const score = normalized.get(metric)?.get(vendor.id);
+            if (score)
+                coverage.push({ metric, value: score.value, normalized: Number(score.normalized.toFixed(4)) });
+        }
+        const index = coverage.length > 0
+            ? Number((coverage.reduce((sum, entry) => sum + entry.normalized, 0) / coverage.length).toFixed(4))
+            : null;
+        return { vendorId: vendor.id, index, coverage, signals: vendor.scaleSignals ?? [] };
+    });
+    return {
+        vendors,
+        metricsUsed,
+        metricsSkipped,
+        complete: vendors.every((vendor) => vendor.index !== null),
+    };
+}
+export function scaleReportToText(config, report) {
+    const names = new Map(config.vendors.map((vendor) => [vendor.id, vendor.name]));
+    const lines = [];
+    lines.push(`Scale index (relative, within this ${config.vendors.length}-vendor set — not market share):`);
+    lines.push(`metrics used: ${report.metricsUsed.join(", ") || "none"}${report.metricsSkipped.length ? ` · skipped (single-vendor): ${report.metricsSkipped.join(", ")}` : ""}`);
+    lines.push("");
+    const ranked = [...report.vendors].sort((a, b) => (b.index ?? -1) - (a.index ?? -1));
+    for (const vendor of ranked) {
+        const idx = vendor.index === null ? "  n/a" : vendor.index.toFixed(2);
+        const cov = vendor.coverage.map((entry) => `${entry.metric}=${entry.value}`).join(", ") || "no signals";
+        lines.push(`  ${idx}  ${(names.get(vendor.vendorId) ?? vendor.vendorId).padEnd(22)} ${cov}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/mcp.js

@@ -260,7 +260,7 @@ export async function startMcpServer() {
             captureRun: z.string().optional(),
         },
     }, async ({ vendorId, configPath, captureRun }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         return content(buildWorksheet(config, vendorId, { captureRun }));
     });
     server.registerTool("fullstackgtm_market_observe", {
@@ -274,7 +274,7 @@ export async function startMcpServer() {
             configPath: z.string().optional().describe("Path to market.config.json (default ./market.config.json)"),
         },
     }, async ({ observationsPath, configPath }) => {
-        const config = loadMarketConfig(resolve(process.cwd(), configPath ?? "market.config.json"));
+        const config = loadMarketConfigOrHint(resolve(process.cwd(), configPath ?? "market.config.json"));
         const set = JSON.parse(readFileSync(resolve(process.cwd(), observationsPath), "utf8"));
         const problems = validateObservationSet(config, set);
         const failures = verifyEvidenceSpans(set.observations, loadCaptureTexts(config.category).textByHash);
@@ -292,3 +292,14 @@ export async function startMcpServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
+function loadMarketConfigOrHint(path) {
+    try {
+        return loadMarketConfig(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`No market config at ${path} — run \`fullstackgtm market init --category <name>\` in that directory first, or pass configPath.`);
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -222,6 +222,23 @@ export type PatchOperation = {
     evidenceIds?: string[];
     findingIds?: string[];
     verification?: PatchVerification;
+    /**
+     * Compare-and-set guards beyond the written field: each precondition is
+     * re-read at apply time and a mismatch turns the operation into a
+     * conflict instead of a write. Guards against a record drifting on a
+     * DIFFERENT field than the one being written (e.g. stage changed while
+     * an owner write was pending).
+     */
+    preconditions?: Array<{
+        field: string;
+        expectedValue: unknown;
+    }>;
+    /**
+     * Operations sharing a groupId are all-or-nothing at apply time: a
+     * conflict (beforeValue or precondition) on any member skips every
+     * member of the group.
+     */
+    groupId?: string;
 };
 /**
  * A patch plan is always a dry-run proposal. Applying a plan never mutates
@@ -238,6 +255,33 @@ export type PatchPlan = {
     pipelineFindings?: PipelineFinding[];
     evidence?: GtmEvidence[];
     operations: PatchOperation[];
+    /**
+     * The filter this plan's operations were selected by. Re-evaluated per
+     * record against a FRESH snapshot at apply time: any operation whose
+     * record no longer matches is reported as a conflict instead of applied.
+     * Unlike per-operation preconditions, this enforces the FULL filter —
+     * negations and relational pseudo-fields included.
+     */
+    filter?: {
+        objectType: "account" | "contact" | "deal";
+        where: string[];
+    };
+    /**
+     * Plan-level guards re-evaluated against a FRESH snapshot at apply time.
+     * If any guard fails, NO operation in the plan is applied. This is how a
+     * plan expresses cross-record eligibility ("apply only while the account
+     * still has no open deal in contractsent") that per-operation
+     * preconditions cannot reach.
+     */
+    guards?: PlanGuard[];
+};
+export type PlanGuard = {
+    objectType: "account" | "contact" | "deal";
+    /** filter expressions in bulk-update --where grammar, AND-ed */
+    where: string[];
+    /** none: guard passes when ZERO records match; some: when at least one matches */
+    expect: "none" | "some";
+    description?: string;
 };
 /** Pre-computed lookups shared by all rules so each rule stays O(n). */
 export type GtmSnapshotIndex = {

package/package.json

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