@unified-product-graph/core 0.17.4 → 0.17.6

package/dist/index.d.cts

@@ -659,6 +659,7 @@ declare const UPG_EDGE_CATALOG: {
         classification: "cross-domain";
         source_type: string;
         target_type: string;
+        deliberate_only: true;
     };
     product_contains_competitive_analysis: {
         forward_verb: string;
@@ -4782,6 +4783,20 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    document_contains_quote: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
+    document_contains_observation: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     product_educates_via_education_program: {
         forward_verb: string;
         reverse_verb: string;
@@ -11710,6 +11725,12 @@ interface ParticipantProperties {
     recruit_source?: string;
     /** Current consent status for data usage */
     consent_status?: 'pending' | 'given' | 'withdrawn';
+    /**
+     * 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. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Discrete observation captured during research. Absorbed from the deprecated Highlight entity.
  *
@@ -11743,6 +11764,13 @@ interface ObservationProperties {
      * four values. More precise than `highlight_tag` for aggregation.
      */
     sentiment?: SignalSentiment;
+    /**
+     * 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 for AI inference. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Verbatim quote from a participant.
  * Link to the participant via an edge, not a speaker property.
@@ -11758,6 +11786,12 @@ interface QuoteProperties {
     text: string;
     /** When said (ISO timestamp or session offset) */
     timestamp?: string;
+    /**
+     * 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. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Unified insight, synthesised from evidence and observations.
  *
@@ -22204,7 +22238,7 @@ declare function isCanonical(text: string): boolean;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.17.4";
+declare const UPG_VERSION: "0.17.6";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.d.ts

@@ -659,6 +659,7 @@ declare const UPG_EDGE_CATALOG: {
         classification: "cross-domain";
         source_type: string;
         target_type: string;
+        deliberate_only: true;
     };
     product_contains_competitive_analysis: {
         forward_verb: string;
@@ -4782,6 +4783,20 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    document_contains_quote: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
+    document_contains_observation: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "semantic";
+        source_type: string;
+        target_type: string;
+    };
     product_educates_via_education_program: {
         forward_verb: string;
         reverse_verb: string;
@@ -11710,6 +11725,12 @@ interface ParticipantProperties {
     recruit_source?: string;
     /** Current consent status for data usage */
     consent_status?: 'pending' | 'given' | 'withdrawn';
+    /**
+     * 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. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Discrete observation captured during research. Absorbed from the deprecated Highlight entity.
  *
@@ -11743,6 +11764,13 @@ interface ObservationProperties {
      * four values. More precise than `highlight_tag` for aggregation.
      */
     sentiment?: SignalSentiment;
+    /**
+     * 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 for AI inference. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Verbatim quote from a participant.
  * Link to the participant via an edge, not a speaker property.
@@ -11758,6 +11786,12 @@ interface QuoteProperties {
     text: string;
     /** When said (ISO timestamp or session offset) */
     timestamp?: string;
+    /**
+     * 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. Rot-prone external pointer; treat as `volatile`.
+     */
+    source_url?: string;
 }
 /** Unified insight, synthesised from evidence and observations.
  *
@@ -22204,7 +22238,7 @@ declare function isCanonical(text: string): boolean;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.17.4";
+declare const UPG_VERSION: "0.17.6";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.js

@@ -1136,7 +1136,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
@@ -2054,6 +2060,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" },
@@ -12100,7 +12111,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: {
@@ -12144,7 +12156,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: {
@@ -12367,7 +12380,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: {
@@ -22807,7 +22821,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 = {
@@ -29717,7 +29737,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();