fullstackgtm 0.19.0 → 0.21.0

package/src/marketOverlay.ts

@@ -0,0 +1,410 @@
+import type { AuditFinding, CanonicalGtmSnapshot, GtmEvidence, PatchOperation, PatchPlan } from "./types.ts";
+import type { ClaimFront, MarketConfig, ObservationSet } from "./market.ts";
+import { computeFrontStates, diffFrontStates } from "./market.ts";
+
+/**
+ * The directive layer: the market map joined to the company's own ground
+ * truth. The map alone says what the category looks like; the overlay says
+ * what THIS company should do about it — and two companies running the same
+ * map see different directives, because the overlay is their own conversion
+ * fingerprint.
+ *
+ * Everything here is deterministic. Inputs are the observation store (front
+ * states), a CRM snapshot (won/lost deals), and call documents (transcript
+ * text, optionally linked to deals). Claim mentions are found by exact
+ * word-boundary term matching against each claim's configured `terms` —
+ * the same posture as the rest of the map: no model in the loop, every
+ * directive carries at least one observation and at least one CRM statistic
+ * with its sample size, and small samples refuse to become claims (the
+ * minimum-evidence thresholds are explicit options, not vibes).
+ */
+
+export type CallDocument = {
+  id: string;
+  text: string;
+  /** Links the document to a deal for win/loss statistics; optional. */
+  dealId?: string;
+  occurredAt?: string;
+};
+
+export type ClaimMentionStats = {
+  claimId: string;
+  /** Documents whose text matches any of the claim's terms. */
+  mentionDocIds: string[];
+  /** Distinct deals among those documents (only docs with dealId count). */
+  mentionDealIds: string[];
+  wonDeals: number;
+  lostDeals: number;
+  /** won / (won + lost) among closed mentioned deals; null below any closure. */
+  winRateWhenMentioned: number | null;
+};
+
+export type VendorMentionStats = {
+  vendorId: string;
+  mentionDocIds: string[];
+  mentionDealIds: string[];
+  wonWhenMentioned: number;
+  lostWhenMentioned: number;
+};
+
+export type OverlayStats = {
+  documents: number;
+  documentsWithDeal: number;
+  deals: { total: number; closed: number; won: number; baselineWinRate: number | null };
+  claims: ClaimMentionStats[];
+  vendors: VendorMentionStats[];
+};
+
+export type DirectiveType = "occupy" | "promote" | "urgent" | "retreat";
+
+export type DirectiveStat = { name: string; value: number | string; n: number };
+
+export type MarketDirective = {
+  id: string;
+  type: DirectiveType;
+  claimId: string;
+  title: string;
+  summary: string;
+  recommendation: string;
+  /** ≥1 observation id and ≥1 CRM stat — the spec's evidence-chain rule. */
+  observationIds: string[];
+  stats: DirectiveStat[];
+};
+
+export type OverlayOptions = {
+  /** Minimum mention documents before OCCUPY/PROMOTE may fire (default 3). */
+  minMentions?: number;
+  /** Minimum win-rate lift over baseline for PROMOTE (default 0.10). */
+  promoteLift?: number;
+  /** Minimum won deals in the corpus before RETREAT may fire (default 3). */
+  minWonDealsForRetreat?: number;
+  /** Prior run's observations: enables URGENT (front drift) directives. */
+  priorSet?: ObservationSet;
+};
+
+function fnv1a(value: string): string {
+  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: string[]): RegExp | null {
+  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: MarketConfig,
+  snapshot: CanonicalGtmSnapshot,
+  documents: CallDocument[],
+): OverlayStats {
+  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: string[]) => {
+    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: ClaimMentionStats[] = 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 is string => !!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: VendorMentionStats[] = 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 is string => !!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: MarketConfig,
+  set: ObservationSet,
+  stats: OverlayStats,
+  options: OverlayOptions = {},
+): MarketDirective[] {
+  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<string, ClaimFront>(fronts.map((front) => [front.claimId, front]));
+  const statsByClaim = new Map(stats.claims.map((claim) => [claim.claimId, claim]));
+  const anchorIntensity = new Map<string, { intensity: string; observationId: string }>();
+  const loudObservationIds = new Map<string, string[]>();
+  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: MarketDirective[] = [];
+  const claimName = new Map(config.claims.map((claim) => [claim.id, claim.capability.split(":")[0]]));
+  const push = (
+    type: DirectiveType,
+    claimId: string,
+    summary: string,
+    recommendation: string,
+    observationIds: string[],
+    statsList: DirectiveStat[],
+  ) => {
+    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: string, after: string) => {
+      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: MarketConfig,
+  set: ObservationSet,
+  directives: MarketDirective[],
+  target: { objectType: "account" | "deal"; objectId: string },
+  now: () => Date = () => new Date(),
+): PatchPlan {
+  const createdAt = now().toISOString();
+  const findings: AuditFinding[] = 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: GtmEvidence[] = 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: PatchOperation[] = 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: OverlayStats, directives: MarketDirective[]): string {
+  const lines: string[] = [];
+  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/src/marketReport.ts

@@ -7,6 +7,7 @@ import type {
 } from "./market.ts";
 import { computeFrontStates } from "./market.ts";
 import { assessAxes, messageBreadth, type AxesReport } from "./marketAxes.ts";
+import { computeScaleIndex } from "./marketScale.ts";
 
 /**
  * Render a market map as a client-ready deliverable: markdown for terminals
@@ -105,7 +106,8 @@ export function marketMapToMarkdown(config: MarketConfig, set: ObservationSet):
   return `${lines.join("\n")}\n`;
 }
 
-type ScatterPoint = { vendorId: string; name: string; x: number; y: number; loud: number };
+/** size is normalized [0,1]; rendered area-proportionally (radius ∝ √size). */
+type ScatterPoint = { vendorId: string; name: string; x: number; y: number; size: number };
 type ScatterAxis = { label: string; negativePole: string; positivePole: string; signed: boolean };
 
 function svgScatter(
@@ -132,7 +134,8 @@ function svgScatter(
   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)}"/>` +
@@ -160,7 +163,23 @@ function axisSectionsHtml(
   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());
+  // Bubble areas stay proportional to the metric; dividing by the max just
+  // spends the full visual range without distorting any ratio.
+  const maxShare = Math.max(1e-9, ...report.vendors.map((vendorId) => scaleIndex.get(vendorId) ?? 0));
+  const sizeOf = (vendorId: string): number =>
+    useScale ? (scaleIndex.get(vendorId) as number) / maxShare : (loudCounts.get(vendorId) ?? 0) / maxLoud;
+  const sizeCaption = useScale
+    ? `Dot area &#8733; estimated revenue share of this vendor set (signals: ${e(scale.metricsUsed.join(", "))}; calibrated within-set, ACV-band stratified, citable but NOT audited — see \`market scale\` for estimates and spreads)`
+    : "Dot area &#8733; LOUD count";
 
   const breadthAxis: ScatterAxis & { id: string } = {
     id: "breadth",
@@ -202,7 +221,7 @@ function axisSectionsHtml(
         name: vendorNames.get(vendorId) ?? vendorId,
         x: xs.get(vendorId) as number,
         y: ys.get(vendorId) as number,
-        loud: loudCounts.get(vendorId) ?? 0,
+        size: sizeOf(vendorId),
       }));
   };
 
@@ -215,7 +234,7 @@ function axisSectionsHtml(
   <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>`;