@unified-product-graph/core 0.17.4 → 0.17.6

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.
 
-319 entity types across 37 domains. 1024 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+319 entity types across 37 domains. 1026 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -1386,7 +1386,13 @@ var UPG_EDGE_CATALOG = {
   research_study_collects_survey_response: { forward_verb: "collects", reverse_verb: "collected_in", classification: "hierarchy", source_type: "research_study", target_type: "survey_response" },
   observation_evidenced_by_quote: { forward_verb: "evidenced_by", reverse_verb: "evidences", classification: "hierarchy", source_type: "observation", target_type: "quote" },
   affinity_cluster_synthesises_insight: { forward_verb: "synthesises", reverse_verb: "synthesised_from", classification: "hierarchy", source_type: "affinity_cluster", target_type: "insight" },
-  insight_informs_opportunity: { forward_verb: "informs", reverse_verb: "informed_by", classification: "cross-domain", source_type: "insight", target_type: "opportunity" },
+  // deliberate_only (0.17.6): "this insight informs that opportunity" is a
+  // PM-judgment link — which of many opportunities a finding actually feeds is
+  // authored, never inferred from a source's hierarchy. Auto-nest / adapter
+  // parentage resolvers decline to materialise it (fall through to a
+  // node_informs_node link or a decline+warn); explicit create_edge /
+  // resolve_edge_for_pair still return it. Fixes the latent auto-emission.
+  insight_informs_opportunity: { forward_verb: "informs", reverse_verb: "informed_by", classification: "cross-domain", source_type: "insight", target_type: "opportunity", deliberate_only: true },
   // 1.5 Market Intelligence Domain
   // product → competitive_analysis closes the parallel gap to
   // product → persona. competitive_analysis is the anchor of the
@@ -2304,6 +2310,11 @@ var UPG_EDGE_CATALOG = {
   document_describes_positioning: { forward_verb: "describes", reverse_verb: "described_by", classification: "semantic", source_type: "document", target_type: "positioning" },
   document_describes_decision: { forward_verb: "describes", reverse_verb: "described_by", classification: "semantic", source_type: "document", target_type: "decision" },
   document_contains_insight: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "insight" },
+  // Research-provenance containment (0.17.5): a synthesis document is walkable
+  // to the evidence it sourced. Within-graph containment (the document and the
+  // evidence co-reside), so NOT cross_product_eligible.
+  document_contains_quote: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "quote" },
+  document_contains_observation: { forward_verb: "contains", reverse_verb: "contained_in", classification: "semantic", source_type: "document", target_type: "observation" },
   // 5.3 Customer Education & Training Domain
   product_educates_via_education_program: { forward_verb: "educates_via", reverse_verb: "educates", classification: "hierarchy", source_type: "product", target_type: "education_program" },
   education_program_teaches_via_tutorial: { forward_verb: "teaches_via", reverse_verb: "teaches", classification: "hierarchy", source_type: "education_program", target_type: "tutorial" },
@@ -12350,7 +12361,8 @@ var UPG_PROPERTY_SCHEMA = {
     session_ref: { type: "string", description: "Capturing session reference. Convenience field; the canonical relationship to study/session is an edge per P14. Retained as a lightweight context anchor for AI inference." },
     is_highlighted: { type: "boolean", description: "Flagged as a highlight. Absorbed from the deprecated Highlight entity." },
     highlight_tag: { type: "string", description: 'Free-form highlight type tag. @example "pain", "delight", "behaviour", "moment of clarity"' },
-    sentiment: { type: "string", enum: ["positive", "neutral", "negative", "mixed"], description: "Structured sentiment. Tools like Dovetail and EnjoyHQ converge on these four values. More precise than `highlight_tag` for aggregation." }
+    sentiment: { type: "string", enum: ["positive", "neutral", "negative", "mixed"], description: "Structured sentiment. Tools like Dovetail and EnjoyHQ converge on these four values. More precise than `highlight_tag` for aggregation." },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this observation was captured in the originating recording or transcript. A per-moment locator, not a study-level link. Distinct from `session_ref`, which holds an opaque session ID.", modifier: "volatile" }
   },
   // OnCallRotationProperties: On-call rotation.
   on_call_rotation: {
@@ -12394,7 +12406,8 @@ var UPG_PROPERTY_SCHEMA = {
   participant: {
     alias: { type: "string", description: 'Anonymous alias for privacy (e.g. "P01")' },
     recruit_source: { type: "string", description: "How the participant was recruited" },
-    consent_status: { type: "string", enum: ["pending", "given", "withdrawn"], description: "Current consent status for data usage" }
+    consent_status: { type: "string", enum: ["pending", "given", "withdrawn"], description: "Current consent status for data usage" },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this participant appears in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
   },
   // PartnerProgramProperties: Partner program.
   partner_program: {
@@ -12617,7 +12630,8 @@ var UPG_PROPERTY_SCHEMA = {
   // QuoteProperties: Verbatim quote from a participant.
   quote: {
     text: { type: "string", description: "Quoted text" },
-    timestamp: { type: "string", description: "When said (ISO timestamp or session offset)" }
+    timestamp: { type: "string", description: "When said (ISO timestamp or session offset)" },
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this quote was spoken in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
   },
   // QuoteDocumentProperties: Quote document.
   quote_document: {
@@ -23057,7 +23071,13 @@ var USER_RESEARCH_GUIDE = {
   anti_patterns: [
     { description: "Insights without evidence: every insight must trace back to observations and quotes" },
     { description: "Orphan quotes: quotes should belong to observations, not float independently" },
-    { description: "Research studies without questions: always define what you want to learn before starting" }
+    { description: "Research studies without questions: always define what you want to learn before starting" },
+    {
+      name: "Study conflation",
+      affected_entity: "research_study",
+      description: "Do not merge multiple research rounds with different stated goals into one `research_study` (or one participant pool) just because they were synthesized into the same downstream document. If two rounds have different research questions, they are different `research_study` nodes, even if an analyst wrote them up together.",
+      remediation: "Verify against the *original* recording or session metadata, not the synthesis doc's grouping."
+    }
   ]
 };
 var MARKET_INTELLIGENCE_GUIDE = {
@@ -29967,7 +29987,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.17.4";
+var UPG_VERSION = "0.17.6";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();