@unified-product-graph/core 0.23.2 → 0.25.0

package/CHANGELOG.md

@@ -214,7 +214,7 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [0.14.1] - 2026-06-17
 
-**Release rider: a browser-safe `crypto` import in the canonical serialiser (unblocks Sanity Studio).** The canonical serialiser imported `crypto` in a form that broke browser bundlers; it is namespaced to `node:crypto`. Fix only.
+**Release rider: a browser-safe `crypto` import in the canonical serialiser (unblocks browser bundlers).** The canonical serialiser imported `crypto` in a form that broke browser bundlers; it is namespaced to `node:crypto`. Fix only.
 
 ### Fixed
 - Browser-safe `crypto` import in `format/canonical.ts`.

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-320 entity types across 37 domains. 1042 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+320 entity types across 37 domains. 1058 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -3508,7 +3508,105 @@ var UPG_EDGE_CATALOG = {
   // product's feature or capability, authored in a different graph within the
   // portfolio, fits the 0.17.3 locked predicate.
   objective_defers_feature: { forward_verb: "defers", reverse_verb: "deferred_by", classification: "cross-domain", source_type: "objective", target_type: "feature", carries_properties: true, property_schema: DEFER_EDGE_PROPERTY_SCHEMA, cross_product_eligible: true, deliberate_only: true },
-  objective_defers_capability: { forward_verb: "defers", reverse_verb: "deferred_by", classification: "semantic", source_type: "objective", target_type: "capability", carries_properties: true, property_schema: DEFER_EDGE_PROPERTY_SCHEMA, cross_product_eligible: true, deliberate_only: true }
+  objective_defers_capability: { forward_verb: "defers", reverse_verb: "deferred_by", classification: "semantic", source_type: "objective", target_type: "capability", carries_properties: true, property_schema: DEFER_EDGE_PROPERTY_SCHEMA, cross_product_eligible: true, deliberate_only: true },
+  // ── Enterprise GTM coordination batch (0.24.0, Track 1 Wave A) ───────────────
+  // The catalog modelled each go-to-market department's nouns but almost none of
+  // the handoffs between them, and the enterprise motion IS the handoffs (audit
+  // `2026-07-16-enterprise-gtm-coverage-audit.md`, §3). Sixteen additive edges
+  // wire the buying committee onto the deal, give the enablement lattice a demand
+  // side, close the pre-sale win/loss LEARN loop, make post-sale account-scoped,
+  // and complete the audience-projection lattice. None are hierarchy — every one
+  // is a lateral coordination link — so UPG_VALID_CHILDREN is untouched. Verbs
+  // are precedent-matched (cited per row); classification per the standard
+  // taxonomy. Two edges are portfolio-crossing by construction (a deal in a
+  // field-ops graph blocked by a feature in a product graph; a win/loss study in
+  // a research graph analysing a deal in another) → cross_product_eligible at
+  // mint, one line rather than a later migration (audit §7-addendum decision 6).
+  // Buying committee (F2). A contact was reachable only via account_contains_contact;
+  // it could not attach to the deal it influences. This is the substrate of every
+  // qualification framework (MEDDICC/SPICED) and of multi-threading. Semantic, not
+  // hierarchy: the contact is parented under its account (account_contains_contact),
+  // so a deal references it laterally, not by containment; and semantic, not
+  // cross-domain, because deal and contact are both in the sales domain (T1.7
+  // guardrail: a within-domain edge is not cross-domain). @example deal "Northwind
+  // platform expansion" involves contact "VP Engineering" (buying_role: 'economic_buyer').
+  deal_involves_contact: { forward_verb: "involves", reverse_verb: "involved_in", classification: "semantic", source_type: "deal", target_type: "contact" },
+  // Enablement demand side (F3). GTM's objection→rebuttal→proof_point chain had
+  // supply but nothing consuming it in a deal context. Mirrors the positioning
+  // precedent (positioning_challenged_by_objection). @example deal "Northwind
+  // platform expansion" challenged_by objection "no SOC 2 report yet".
+  deal_challenged_by_objection: { forward_verb: "challenged_by", reverse_verb: "challenges", classification: "cross-domain", source_type: "deal", target_type: "objection" },
+  // Enablement deployed in context (F3). Which battlecard was armed on which deal.
+  // Mirrors gtm_strategy_arms_with_competitive_battle_card. @example deal armed_with
+  // competitive_battle_card "vs. Meridian Cloud".
+  deal_armed_with_competitive_battle_card: { forward_verb: "armed_with", reverse_verb: "arms", classification: "cross-domain", source_type: "deal", target_type: "competitive_battle_card" },
+  // Loss cause (F3). Gives competitive_battle_card.win_rate its derivation path —
+  // nothing in the graph could previously compute it. Causal (a directional
+  // outcome), mirroring lead_becomes_account. @example deal "Sterling Data Systems
+  // renewal" lost_to competitor "Meridian Cloud".
+  deal_lost_to_competitor: { forward_verb: "lost_to", reverse_verb: "won", classification: "causal", source_type: "deal", target_type: "competitor" },
+  // Close mechanism (F4). MSA/SOW/order form reachable from the deal; contract
+  // previously bound only legal_entity and partnership. Mirrors
+  // deal_quoted_via_quote_document. @example deal closed_via contract "Northwind MSA".
+  deal_closed_via_contract: { forward_verb: "closed_via", reverse_verb: "closes", classification: "cross-domain", source_type: "deal", target_type: "contract" },
+  // Pipeline blocker (F5). "Which roadmap items unblock how much pipeline"; plugs
+  // into change_blast_radius. Mirrors epic_affected_by_bug. cross_product_eligible:
+  // the deal lives in the field-ops graph, the blocking feature in the product
+  // graph. @example deal blocked_by feature "SAML SSO".
+  deal_blocked_by_feature: { forward_verb: "blocked_by", reverse_verb: "blocks", classification: "cross-domain", source_type: "deal", target_type: "feature", cross_product_eligible: true },
+  // Win/loss LEARN loop (F3). Win/loss analysis is a research genre, not a new
+  // type — a research_study analyses the deal. Closes the pre-sale learning loop
+  // (the post-sale one already existed via support_ticket_reveals_need). Mirrors
+  // proof_point_derived_from_insight's provenance shape. cross_product_eligible:
+  // the study may live in a research graph distinct from the deal's field-ops
+  // graph. @example research_study "Q3 competitive win/loss" analyzes deal
+  // "Sterling Data Systems renewal".
+  research_study_analyzes_deal: { forward_verb: "analyzes", reverse_verb: "analyzed_by", classification: "cross-domain", source_type: "research_study", target_type: "deal", cross_product_eligible: true },
+  // Account-scoped sensing (F5). Nearly every CS edge hung off product; only one
+  // scoped anything to an account. Mirrors product_supports_via_support_ticket.
+  // @example account "Northwind Logistics" raises support_ticket "onboarding SSO
+  // blocker".
+  account_raises_support_ticket: { forward_verb: "raises", reverse_verb: "raised_by", classification: "cross-domain", source_type: "account", target_type: "support_ticket" },
+  // Account health (F5). Mirrors product_health_scored_via_customer_health_score.
+  // @example account health_scored_via customer_health_score "Northwind Q3 health".
+  account_health_scored_via_customer_health_score: { forward_verb: "health_scored_via", reverse_verb: "scores", classification: "cross-domain", source_type: "account", target_type: "customer_health_score" },
+  // Account churn (F5). Churn lands on the account, not just the product. Mirrors
+  // product_loses_because_churn_reason. @example account lost_because churn_reason
+  // "switched to incumbent suite".
+  account_lost_because_churn_reason: { forward_verb: "lost_because", reverse_verb: "causes_churn_for", classification: "cross-domain", source_type: "account", target_type: "churn_reason" },
+  // Onboarding / implementation (F5). Reuses the Program Management machinery
+  // (project/milestone/deliverable/status_report) for enterprise onboarding.
+  // Mirrors the operate-a-thing-via-a-plan shape of product_operated_via_playbook.
+  // @example account implements_via project "Northwind rollout".
+  account_implements_via_project: { forward_verb: "implements_via", reverse_verb: "implements", classification: "cross-domain", source_type: "account", target_type: "project" },
+  // Renewal object-path (F5). A renewal is a deal of deal_type 'renewal'; this
+  // completes the lead→account→deal→subscription→deal cycle. Causal (a directional
+  // renewal event), mirroring quote_document_advances_deal. @example subscription
+  // "Northwind annual" renews_via deal "Northwind FY27 renewal".
+  subscription_renews_via_deal: { forward_verb: "renews_via", reverse_verb: "renews", classification: "causal", source_type: "subscription", target_type: "deal" },
+  // Enterprise early access (F5, rider R1). An account participates in a beta
+  // program. Mirrors product_runs_beta_program's noun. @example account
+  // participates_in beta_program "SSO private beta".
+  account_participates_in_beta_program: { forward_verb: "participates_in", reverse_verb: "has_participant", classification: "cross-domain", source_type: "account", target_type: "beta_program" },
+  // Security gate (F4, rider R2). The security questionnaire/review as a deal gate,
+  // reusing the Security noun rather than minting security_questionnaire. Mirrors
+  // service_level_agreement_covers_account's account↔security cross-domain shape.
+  // @example deal gated_by security_review "Northwind vendor security assessment".
+  deal_gated_by_security_review: { forward_verb: "gated_by", reverse_verb: "gates", classification: "cross-domain", source_type: "deal", target_type: "security_review" },
+  // Audience-projection subject axis (Ruling 4, A15). messaging's only subject edge
+  // was positioning_communicated_via_messaging — messaging could not be ABOUT a
+  // feature, so audience-scoped feature projections were unexpressable at the root.
+  // Mirrors the positioning precedent. The rendered projection is NOT stored (views
+  // philosophy); this edge stores the atom the lens queries. @example feature "SAML
+  // SSO" communicated_via messaging "SSO beta enablement one-pager".
+  feature_communicated_via_messaging: { forward_verb: "communicated_via", reverse_verb: "communicates", classification: "cross-domain", source_type: "feature", target_type: "messaging" },
+  // Launch coordination seam (Ruling 4, A16). launch had edges to
+  // release/feature/channel/campaign/metric/messaging but none to Program
+  // Management — the GTM readiness checklist (who builds the demo env, trains the
+  // SEs, by when) had no home. Reuses project/milestone/deliverable, the same move
+  // as account_implements_via_project. @example launch "SSO GA" coordinated_via
+  // project "SSO launch readiness".
+  launch_coordinated_via_project: { forward_verb: "coordinated_via", reverse_verb: "coordinates", classification: "cross-domain", source_type: "launch", target_type: "project" }
 };
 var UPG_CROSS_ELIGIBLE_CATALOG_EDGE_TYPES = Object.keys(UPG_EDGE_CATALOG).filter(
   (k) => UPG_EDGE_CATALOG[k].cross_product_eligible === true
@@ -6816,6 +6914,8 @@ var PROPERTY_SCALE_MAP = {
   // market/risk (UPG-579 Option B)
   probability: "confidence_5",
   // sales/forecast (UPG-579 Option B)
+  qualification_score: "confidence_5",
+  // sales/deal — how confident the qualification is (0.24.0)
   // ── Effort ───────────────────────────────────────────────────────────────
   effort: "effort_5",
   // discovery
@@ -10310,7 +10410,10 @@ var UPG_PROPERTY_SCHEMA = {
   account: {
     account_type: { type: "string", enum: ["prospect", "customer", "partner", "churned"], description: "Relationship status of this account" },
     industry: { type: "string", description: "Industry vertical the account operates in" },
-    employee_count: { type: "number", description: "Number of employees at the account", modifier: "snapshot" }
+    employee_count: { type: "number", description: "Number of employees at the account", modifier: "snapshot" },
+    segment: { type: "string", enum: ["smb", "mid_market", "enterprise", "strategic"], description: "Go-to-market tier this account is served at. A segmentation *decision* (how the field org treats the account), distinct from `employee_count` (a raw fact) and aligned with but not identical to the ideal customer profile's `company_size` buckets. `strategic` is the tier that escalates to a dedicated account-plan graph (Tier 3 client model)." },
+    annual_contract_value: { type: "number", description: "Annual contract value in the account's billing currency. The single most common enterprise account-tiering input; a snapshot that changes on expansion or renewal.", modifier: "snapshot" },
+    region: { type: "string", description: 'Geographic region the account is managed in (e.g. "EMEA", "NA-West"). Free-form: territory taxonomies vary by org and are modelled structurally via the `territory` entity when they need to be queryable.' }
   },
   // AcquisitionChannelProperties: AcquisitionChannel entity.
   acquisition_channel: {
@@ -10899,7 +11002,8 @@ var UPG_PROPERTY_SCHEMA = {
   // ContactProperties: Contact.
   contact: {
     contact_role: { type: "string", description: "Job title or role within the account" },
-    is_decision_maker: { type: "boolean", description: "Whether this person has purchasing authority" }
+    is_decision_maker: { type: "boolean", description: "Whether this person has purchasing authority" },
+    buying_role: { type: "string", enum: ["champion", "economic_buyer", "technical_evaluator", "end_user", "detractor", "influencer", "procurement", "legal", "security"], description: "Role this contact plays in the buying committee (the decision-making unit). The substrate of enterprise multi-threading and of qualification frameworks (MEDDICC/SPICED): a deal with no `champion` and no `economic_buyer` mapped is single-threaded and at risk. `is_decision_maker` becomes largely derivable (`buying_role = economic_buyer`) but is kept for back-compat. @example 'economic_buyer'" }
   },
   // ContentCalendarProperties: Content calendar.
   content_calendar: {
@@ -11095,7 +11199,24 @@ var UPG_PROPERTY_SCHEMA = {
   deal: {
     deal_value: { type: "number", description: "Monetary value of the deal" },
     close_date: { type: "string", description: "Expected close date (ISO format)" },
-    probability: { type: "number", description: "Likelihood of closing (0-100%)" }
+    probability: { type: "number", description: "Likelihood of closing (0-100%)" },
+    deal_outcome: { type: "string", enum: ["won", "lost", "no_decision"], description: "Terminal result of the deal. An Event-axis outcome (the verdict on a one-time event), NOT a lifecycle phase, so it is `deal_outcome` and not `deal_status` per the status-convention Rule 3. Lifecycle (open/won/lost as phases) belongs on the base `status` slot; this records the win/loss verdict a closed deal carries and gives `deal_lost_to_competitor` / win-loss study derivations their anchor. @example 'won'" },
+    deal_type: { type: "string", enum: ["new_business", "expansion", "renewal"], description: "Motion this deal belongs to. Mirrors `PipelineSales.pipeline_type` at the deal grain; `renewal` is the value `subscription_renews_via_deal` points at. @example 'expansion'" },
+    next_step: { type: "string", description: "The single most-used CRM field: the next concrete action to move the deal. Free text on purpose (a coordination note, not a structured task). @example 'Send security questionnaire to procurement'" },
+    next_step_date: { type: "string", description: "When the `next_step` is due (ISO format)." },
+    qualification_framework: { type: "string", enum: ["meddicc", "bant", "spiced", "custom"], description: "Qualification framework this deal is scored against. Names the rubric so the `qualification_score` is interpretable; per-pillar booleans (MEDDICC's Metrics / Economic buyer / Decision criteria / \u2026) are deferred until `custom` recurrence proves the demand. @example 'meddicc'" },
+    qualification_score: {
+      type: "assessment",
+      scale_id: "confidence_5",
+      description: "How well-qualified the deal is, on the canonical `confidence_5` scale (UPGAssessment: numeric value plus a high/medium/low label). Coarse by design; the granular per-pillar breakdown is deferred (see `qualification_framework`).",
+      properties: {
+        value: { type: "number", description: "The numeric value, used for computation." },
+        label: { type: "string", description: "The qualitative label (what the assessor meant)." },
+        scale_id: { type: "string", description: "Which assessment scale this was rated on (optional)." },
+        normalized: { type: "number", description: "Normalized 0-1 value for cross-tool comparison (optional)." }
+      },
+      required: ["value", "label"]
+    }
   },
   // DecisionProperties: Decision record. Strategic, product, engineering, or design.
   decision: {
@@ -12128,7 +12249,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // MessagingProperties: Messaging entity. Each instance is a channel/stage variant.
   messaging: {
-    channel: { type: "string", enum: ["landing_page", "email", "social", "ad", "pitch", "press", "in_product", "other"], description: "Channel this messaging variant is crafted for" },
+    channel: { type: "string", enum: ["landing_page", "email", "social", "ad", "pitch", "press", "in_product", "enablement", "other"], description: "Channel this messaging variant is crafted for. `enablement` is the internal field-ops channel (SE/PMM/SA enablement one-pagers, battlecards' narrative), distinct from `pitch` (external, customer-facing)." },
     funnel_stage: { type: "string", enum: ["awareness", "consideration", "conversion", "retention"], description: "Marketing funnel stage this variant targets" },
     headline: { type: "string", description: "Primary headline or hook" },
     body: { type: "string", description: "Full message body copy" },
@@ -23538,6 +23659,12 @@ var GTM_GUIDE = {
       description: "Strategy defines positioning, positioning spawns messaging variants, messaging addresses objections with rebuttals backed by proof points",
       entity_types: ["positioning", "messaging", "objection", "rebuttal", "proof_point"],
       edge_chain: ["gtm_strategy_positions_via_positioning", "positioning_communicated_via_messaging", "positioning_challenged_by_objection", "objection_countered_by_rebuttal", "rebuttal_evidenced_by_proof_point"]
+    },
+    {
+      name: "Audience Projection Lattice",
+      description: "One feature approaching launch needs many faces: what the internal field org (SE/PMM/SA) needs to know differs from what an enterprise champion needs at beta versus GA. Model the atoms, not the rendered pages. A feature is communicated_via messaging variants; each variant targets a persona (an internal field-ops persona or a customer persona) and is used_in a staged launch (beta, then GA); the launch is coordinated_via a project (the readiness checklist: demo env, SE training, by when). The projection itself is a query over these atoms, rendered by the product, never a stored copy that drifts.",
+      entity_types: ["feature", "messaging", "persona", "launch", "project"],
+      edge_chain: ["feature_communicated_via_messaging", "messaging_targets_persona", "launch_ships_feature", "launch_coordinated_via_project"]
     }
   ],
   required_bridges: [
@@ -23583,17 +23710,33 @@ var SALES_GUIDE = {
       description: "Pipelines qualify leads, leads become accounts, accounts negotiate deals that progress through pipeline stages and convert to subscriptions",
       entity_types: ["pipeline_sales", "lead", "account", "deal", "pipeline_stage", "subscription"],
       edge_chain: ["pipeline_sales_qualifies_lead", "lead_becomes_account", "account_negotiates_deal", "deal_at_pipeline_stage", "pipeline_sales_converts_to_subscription"]
+    },
+    {
+      name: "Enterprise Buying Committee",
+      description: "An enterprise deal is a months-long coordination effort, not a forecast row. Attach the decision-making unit directly to the deal (each contact carries a buying_role: champion, economic buyer, technical evaluator, procurement, detractor), then wire the gauntlet the deal must clear: objections it faces, the security review that gates it, and the contract it closes via. A deal with no champion and no economic buyer mapped is single-threaded and at risk.",
+      entity_types: ["deal", "contact", "objection", "security_review", "contract"],
+      edge_chain: ["account_negotiates_deal", "deal_involves_contact", "deal_challenged_by_objection", "deal_gated_by_security_review", "deal_closed_via_contract"]
+    },
+    {
+      name: "Win/Loss Learning Loop",
+      description: "Close the pre-sale learning loop the way the post-sale one already closes (support_ticket reveals need). A deal is armed with a competitive battlecard; when it is lost to a competitor, a win/loss research_study analyses it. This gives competitive_battle_card.win_rate a derivation path (nothing could compute it before) and turns lost deals into structured competitive intelligence rather than a note in a closed record.",
+      entity_types: ["deal", "competitive_battle_card", "competitor", "research_study"],
+      edge_chain: ["deal_armed_with_competitive_battle_card", "deal_lost_to_competitor", "research_study_analyzes_deal"]
     }
   ],
   required_bridges: [
     { edge_type: "lead_sourced_from_acquisition_channel", target_domain: "growth", when: "Track where leads come from for attribution" },
     { edge_type: "subscription_subscribes_to_pricing_tier", target_domain: "pricing", when: "Subscriptions should link to the tier purchased" },
-    { edge_type: "account_partners_via_partnership", target_domain: "business_model", when: "Partner accounts should link to the partnership entity" }
+    { edge_type: "account_partners_via_partnership", target_domain: "business_model", when: "Partner accounts should link to the partnership entity" },
+    { edge_type: "deal_blocked_by_feature", target_domain: "product_spec", when: 'When a roadmap gap holds up pipeline, link the deal to the blocking feature so "which features unblock how much revenue" is queryable' },
+    { edge_type: "account_implements_via_project", target_domain: "program_mgmt", when: "Post-sale onboarding/implementation reuses the program-management machinery (project/milestone/deliverable), scoped to the account" }
   ],
   anti_patterns: [
     { description: "Deals without pipeline stages: every deal needs a current position in the pipeline" },
     { description: "Leads without source attribution. Attribution drives channel optimisation." },
-    { description: "Forecasts without probability: weight deals by likelihood to close" }
+    { description: "Forecasts without probability: weight deals by likelihood to close" },
+    { name: "Single-threaded enterprise deal", description: "An enterprise deal with no contacts attached (deal_involves_contact) or no champion/economic_buyer among their buying_role values is single-threaded: the whole relationship rests on one unmapped person. Attach the buying committee and map at least the champion and economic buyer.", affected_entity: "deal", remediation: "Create deal_involves_contact edges to the committee and set each contact's buying_role." },
+    { name: "Won/lost recorded only as a phase", description: "The deal outcome (won/lost/no_decision) is an Event-axis fact and belongs on deal_outcome, not conflated with the lifecycle status. A lost deal with no deal_lost_to_competitor edge also strands the competitive signal that competitive_battle_card.win_rate depends on.", affected_entity: "deal", remediation: "Set deal_outcome, and on a loss create deal_lost_to_competitor plus a win/loss research_study via research_study_analyzes_deal." }
   ]
 };
 var MARKETING_GUIDE = {
@@ -29982,7 +30125,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.23.2";
+var UPG_VERSION = "0.25.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();