@unified-product-graph/core 0.9.1 → 0.9.2

package/dist/index.d.cts

@@ -1442,10 +1442,10 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
-    journey_phase_has_step: {
+    journey_phase_spans_journey_step: {
         forward_verb: string;
         reverse_verb: string;
-        classification: "hierarchy";
+        classification: "cross-domain";
         source_type: string;
         target_type: string;
     };
@@ -1456,6 +1456,20 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    journey_action_surfaces_need: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
+    journey_action_realised_by_feature: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
     product_systematised_in_design_system: {
         forward_verb: string;
         reverse_verb: string;
@@ -10694,14 +10708,19 @@ interface UserJourneyProperties {
     /** Scenario context */
     scenario?: string;
 }
-/** Phase within a user journey. Groups journey steps into stages.
+/** Phase within a user journey. A temporal BAND over the journey's step
+ * timeline, not a container that owns steps (UPG-663). A journey map renders
+ * phases as a horizontal band above one timeline; a phase spans a range of
+ * that timeline. Steps belong to the journey, not the phase.
  *
  * Per UPG principle P14, structural relationships are edges:
- *   parent journey: `user_journey_contains_journey_phase`
- *   contained steps: `journey_phase_contains_journey_step`
- *   sequenced phase: ordering via `phase_order` here; the
- *     `journey_phase_precedes_journey_phase` edge captures the explicit
- *     phase-to-phase chain when it matters for branching journeys.
+ *   parent journey: `user_journey_passes_through_journey_phase`
+ *     (the journey carries the phase as a non-owning band overlay)
+ *   spanned steps: `journey_phase_spans_journey_step` (non-owning; the steps
+ *     are owned by `user_journey_contains_journey_step`, mirroring the
+ *     marketing precedent `customer_journey_stage_spans_journey_step`)
+ *   phase ordering: the `phase_order` scalar below (the convention shared
+ *     with `journey_step.step_order` and `journey_action.action_order`)
  *
  * @example
  * const properties: JourneyPhaseProperties = {
@@ -10739,16 +10758,27 @@ interface JourneyPhaseProperties {
      */
     timeframe?: string;
 }
-/** Single step within a user journey.
+/** Single step within a user journey. A user-moment on the journey's single
+ * step timeline. Steps belong to the journey via
+ * `user_journey_contains_journey_step` (the stable 0.1.0 spine); a
+ * `journey_phase` spans a range of them but does not own them (UPG-663).
  *
  * @example
  * const properties: JourneyStepProperties = {
+ *   step_order: 1,
  *   touchpoint: 'in-product',
  *   channel: 'in-product',
  *   emotion_score: 4,
  * }
  */
 interface JourneyStepProperties {
+    /**
+     * Display order within the journey's step timeline (0-indexed). The scalar
+     * ordering convention shared with `journey_phase.phase_order` and
+     * `journey_action.action_order` (UPG-663). For branching journeys, the
+     * explicit `journey_step_precedes_journey_step` edge captures the chain.
+     */
+    step_order?: number;
     /** Interaction touchpoint */
     touchpoint?: string;
     /** Channel (e.g. "web", "email", "in-store") */
@@ -10763,16 +10793,24 @@ interface JourneyStepProperties {
     owner?: string;
 }
 /** Discrete action at a journey step, classified by service layer.
+ * The finest blueprint layer (a service-blueprint row within a moment).
  * Enables service blueprint rendering and cross-domain linking.
  *
  * Per UPG principle P14, structural relationships are edges:
- *   parent step: `journey_step_contains_journey_action`
- *   performing system: `service_performs_journey_action` (the `system` property
- *     is a display label; the canonical link is the edge when a `service` entity exists)
- *   downstream pain: `journey_action_surfaces_need`
+ *   parent step: `journey_step_has_action` (the step owns its actions)
+ *   downstream need: `journey_action_surfaces_need`. Opportunity discovery
+ *     routes through `need`, which reaches `opportunity` via
+ *     `opportunity_addresses_need`; the `pain_score` / `opportunity_score`
+ *     scalars below are blueprint-cell diagnostics that fuel that discovery.
+ *   realising feature: `journey_action_realised_by_feature`
+ *
+ * The `system` property is a display label naming the performing system; when
+ * a `service` entity exists, model the relationship structurally rather than
+ * relying on the label.
  *
  * @example
  * const properties: JourneyActionProperties = {
+ *   action_order: 0,
  *   layer: 'user',
  *   action_description: 'User pastes a meeting transcript into the empty canvas',
  *   channel: 'in-app',
@@ -10784,6 +10822,13 @@ interface JourneyStepProperties {
  * }
  */
 interface JourneyActionProperties {
+    /**
+     * Display order of this action within its step (0-indexed). The scalar
+     * ordering convention shared with `journey_phase.phase_order` and
+     * `journey_step.step_order` (UPG-663). Orders the service-blueprint rows
+     * within a single moment.
+     */
+    action_order?: number;
     /** Service layer */
     layer: 'user' | 'frontstage' | 'backstage' | 'support';
     /** Plain-language description. Primary content of the action. */
@@ -18005,7 +18050,7 @@ type UPGNode<T extends keyof UPGPropertyMap = keyof UPGPropertyMap> = UPGBaseNod
  * AUTO-GENERATED by scripts/generate-property-registry.ts
  * Do not edit manually. Run: npx tsx scripts/generate-property-registry.ts
  *
- * Generated: 2026-06-09T14:25:02.253Z
+ * Generated: 2026-06-09T16:53:52.006Z
  * Entity types with properties: 316
  */
 interface PropertyDefinition {
@@ -20446,7 +20491,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.9.1";
+declare const UPG_VERSION: "0.9.2";
 /**
  * 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

@@ -1442,10 +1442,10 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
-    journey_phase_has_step: {
+    journey_phase_spans_journey_step: {
         forward_verb: string;
         reverse_verb: string;
-        classification: "hierarchy";
+        classification: "cross-domain";
         source_type: string;
         target_type: string;
     };
@@ -1456,6 +1456,20 @@ declare const UPG_EDGE_CATALOG: {
         source_type: string;
         target_type: string;
     };
+    journey_action_surfaces_need: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
+    journey_action_realised_by_feature: {
+        forward_verb: string;
+        reverse_verb: string;
+        classification: "cross-domain";
+        source_type: string;
+        target_type: string;
+    };
     product_systematised_in_design_system: {
         forward_verb: string;
         reverse_verb: string;
@@ -10694,14 +10708,19 @@ interface UserJourneyProperties {
     /** Scenario context */
     scenario?: string;
 }
-/** Phase within a user journey. Groups journey steps into stages.
+/** Phase within a user journey. A temporal BAND over the journey's step
+ * timeline, not a container that owns steps (UPG-663). A journey map renders
+ * phases as a horizontal band above one timeline; a phase spans a range of
+ * that timeline. Steps belong to the journey, not the phase.
  *
  * Per UPG principle P14, structural relationships are edges:
- *   parent journey: `user_journey_contains_journey_phase`
- *   contained steps: `journey_phase_contains_journey_step`
- *   sequenced phase: ordering via `phase_order` here; the
- *     `journey_phase_precedes_journey_phase` edge captures the explicit
- *     phase-to-phase chain when it matters for branching journeys.
+ *   parent journey: `user_journey_passes_through_journey_phase`
+ *     (the journey carries the phase as a non-owning band overlay)
+ *   spanned steps: `journey_phase_spans_journey_step` (non-owning; the steps
+ *     are owned by `user_journey_contains_journey_step`, mirroring the
+ *     marketing precedent `customer_journey_stage_spans_journey_step`)
+ *   phase ordering: the `phase_order` scalar below (the convention shared
+ *     with `journey_step.step_order` and `journey_action.action_order`)
  *
  * @example
  * const properties: JourneyPhaseProperties = {
@@ -10739,16 +10758,27 @@ interface JourneyPhaseProperties {
      */
     timeframe?: string;
 }
-/** Single step within a user journey.
+/** Single step within a user journey. A user-moment on the journey's single
+ * step timeline. Steps belong to the journey via
+ * `user_journey_contains_journey_step` (the stable 0.1.0 spine); a
+ * `journey_phase` spans a range of them but does not own them (UPG-663).
  *
  * @example
  * const properties: JourneyStepProperties = {
+ *   step_order: 1,
  *   touchpoint: 'in-product',
  *   channel: 'in-product',
  *   emotion_score: 4,
  * }
  */
 interface JourneyStepProperties {
+    /**
+     * Display order within the journey's step timeline (0-indexed). The scalar
+     * ordering convention shared with `journey_phase.phase_order` and
+     * `journey_action.action_order` (UPG-663). For branching journeys, the
+     * explicit `journey_step_precedes_journey_step` edge captures the chain.
+     */
+    step_order?: number;
     /** Interaction touchpoint */
     touchpoint?: string;
     /** Channel (e.g. "web", "email", "in-store") */
@@ -10763,16 +10793,24 @@ interface JourneyStepProperties {
     owner?: string;
 }
 /** Discrete action at a journey step, classified by service layer.
+ * The finest blueprint layer (a service-blueprint row within a moment).
  * Enables service blueprint rendering and cross-domain linking.
  *
  * Per UPG principle P14, structural relationships are edges:
- *   parent step: `journey_step_contains_journey_action`
- *   performing system: `service_performs_journey_action` (the `system` property
- *     is a display label; the canonical link is the edge when a `service` entity exists)
- *   downstream pain: `journey_action_surfaces_need`
+ *   parent step: `journey_step_has_action` (the step owns its actions)
+ *   downstream need: `journey_action_surfaces_need`. Opportunity discovery
+ *     routes through `need`, which reaches `opportunity` via
+ *     `opportunity_addresses_need`; the `pain_score` / `opportunity_score`
+ *     scalars below are blueprint-cell diagnostics that fuel that discovery.
+ *   realising feature: `journey_action_realised_by_feature`
+ *
+ * The `system` property is a display label naming the performing system; when
+ * a `service` entity exists, model the relationship structurally rather than
+ * relying on the label.
  *
  * @example
  * const properties: JourneyActionProperties = {
+ *   action_order: 0,
  *   layer: 'user',
  *   action_description: 'User pastes a meeting transcript into the empty canvas',
  *   channel: 'in-app',
@@ -10784,6 +10822,13 @@ interface JourneyStepProperties {
  * }
  */
 interface JourneyActionProperties {
+    /**
+     * Display order of this action within its step (0-indexed). The scalar
+     * ordering convention shared with `journey_phase.phase_order` and
+     * `journey_step.step_order` (UPG-663). Orders the service-blueprint rows
+     * within a single moment.
+     */
+    action_order?: number;
     /** Service layer */
     layer: 'user' | 'frontstage' | 'backstage' | 'support';
     /** Plain-language description. Primary content of the action. */
@@ -18005,7 +18050,7 @@ type UPGNode<T extends keyof UPGPropertyMap = keyof UPGPropertyMap> = UPGBaseNod
  * AUTO-GENERATED by scripts/generate-property-registry.ts
  * Do not edit manually. Run: npx tsx scripts/generate-property-registry.ts
  *
- * Generated: 2026-06-09T14:25:02.253Z
+ * Generated: 2026-06-09T16:53:52.006Z
  * Entity types with properties: 316
  */
 interface PropertyDefinition {
@@ -20446,7 +20491,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.9.1";
+declare const UPG_VERSION: "0.9.2";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.js

@@ -1292,8 +1292,24 @@ var UPG_EDGE_CATALOG = {
   journey_step_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_step", target_type: "feature" },
   opportunity_improves_user_journey: { forward_verb: "improves", reverse_verb: "improved_by", classification: "cross-domain", source_type: "opportunity", target_type: "user_journey" },
   user_journey_passes_through_journey_phase: { forward_verb: "passes_through", reverse_verb: "is_phase_of", classification: "hierarchy", source_type: "user_journey", target_type: "journey_phase" },
-  journey_phase_has_step: { forward_verb: "has_step", reverse_verb: "is_step_in", classification: "hierarchy", source_type: "journey_phase", target_type: "journey_step" },
+  // (since v0.9.2, UPG-663) A journey_phase is a temporal BAND over the
+  // journey's single step timeline, not a container that owns steps. Steps
+  // belong to the journey via `user_journey_contains_journey_step` (the stable
+  // 0.1.0 spine); a phase merely SPANS a range of them. Mirrors the marketing
+  // precedent `customer_journey_stage_spans_journey_step`. Renamed from the
+  // owning `journey_phase_has_step` (hierarchy) so a step has exactly one
+  // containment parent. See UPG_EDGE_MIGRATIONS['0.9.2'].
+  journey_phase_spans_journey_step: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "cross-domain", source_type: "journey_phase", target_type: "journey_step" },
   journey_step_has_action: { forward_verb: "has_action", reverse_verb: "is_action_in", classification: "hierarchy", source_type: "journey_step", target_type: "journey_action" },
+  // (since v0.9.2, UPG-663) journey_action outbound edges. Fixes the
+  // discovery dead-end (D2). The finest blueprint layer carries pain_score /
+  // opportunity_score "to drive opportunity discovery" but previously had zero
+  // outbound edges. Opportunity discovery routes through `need` (mirroring
+  // `journey_step_reveals_need`), which already reaches `opportunity` via the
+  // user chain; the action does not link an opportunity directly. The feature
+  // edge mirrors `journey_step_realised_by_feature` one level deeper.
+  journey_action_surfaces_need: { forward_verb: "surfaces", reverse_verb: "surfaced_in", classification: "cross-domain", source_type: "journey_action", target_type: "need" },
+  journey_action_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_action", target_type: "feature" },
   // 2.5 UI System Domain
   product_systematised_in_design_system: { forward_verb: "systematised_in", reverse_verb: "systematises", classification: "hierarchy", source_type: "product", target_type: "design_system" },
   product_built_with_design_component: { forward_verb: "built_with", reverse_verb: "built_for", classification: "hierarchy", source_type: "product", target_type: "design_component" },
@@ -3051,8 +3067,13 @@ var UPG_VALID_CHILDREN = {
   // parallel to `observation: ['quote']`. Research-synthesis canon.
   // Pairs with `insight_evidenced_by_quote` in the edge catalog.
   // ── Design hierarchy ────────────────────────────────────────────────────────
+  // (UPG-663, v0.9.2) A user_journey owns its steps (the stable 0.1.0 spine)
+  // and carries phases as a non-owning band overlay. A journey_phase is NO
+  // LONGER a containment parent of journey_step: it SPANS steps via the
+  // `journey_phase_spans_journey_step` edge (mirroring the marketing
+  // `customer_journey_stage_spans_journey_step` precedent), so each step has
+  // exactly one containment parent and the journey has one canonical step list.
   user_journey: ["journey_step", "journey_phase"],
-  journey_phase: ["journey_step"],
   journey_step: ["journey_action"],
   // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
   // parallel to `observation: ['quote']`. Research-synthesis canon
@@ -7605,6 +7626,20 @@ function getSplitMigrations(fromVersion, toVersion) {
   return result;
 }
 var UPG_EDGE_MIGRATIONS = {
+  "0.9.2": [
+    // (since v0.9.2, UPG-663) Journey-model disambiguation. A journey_phase
+    // is a temporal BAND over the journey's single step timeline, not a
+    // container that owns steps. The owning hierarchy edge
+    // `journey_phase_has_step` is renamed to the non-owning
+    // `journey_phase_spans_journey_step` (mirroring the marketing precedent
+    // `customer_journey_stage_spans_journey_step`). Steps stay owned by the
+    // journey via `user_journey_contains_journey_step` (the stable 0.1.0
+    // spine), so each step keeps a single containment parent and the journey
+    // renders one canonical step list. Endpoints are unchanged
+    // (journey_phase → journey_step); only the edge key and its grammar
+    // (verb has_step → spans, classification hierarchy → cross-domain) change.
+    { kind: "rename", from: "journey_phase_has_step", to: "journey_phase_spans_journey_step", requires_source_type: "journey_phase", requires_target_type: "journey_step", reason: "Journey-model disambiguation (UPG-663): a phase spans steps, it does not own them. The phase to step edge becomes non-owning (verb has_step to spans), so the step keeps a single containment parent (the journey) and the journey has one canonical step list." }
+  ],
   "0.9.0": [
     // (since v0.9.0, UPG-660) theme → roadmap_theme. The four canonical edges that
     // touch the roadmap theme are renamed to the roadmap_theme form. Endpoint guards
@@ -10103,6 +10138,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // JourneyActionProperties: Discrete action at a journey step, classified by service layer.
   journey_action: {
+    action_order: { type: "number", description: "Display order of this action within its step (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_step.step_order` (UPG-663). Orders the service-blueprint rows within a single moment." },
     layer: { type: "string", enum: ["user", "frontstage", "backstage", "support"], description: "Service layer" },
     action_description: { type: "string", description: "Plain-language description. Primary content of the action." },
     channel: { type: "string", enum: ["in-app", "email", "web", "mobile", "phone", "in-person", "sms", "social", "other"], description: "Channel or surface. Keeps service-blueprint columns consistent across the journey." },
@@ -10134,7 +10170,7 @@ var UPG_PROPERTY_SCHEMA = {
     system: { type: "string", description: "Performing system or service" },
     notes: { type: "string", description: "Free-text notes, observations, or follow-up questions" }
   },
-  // JourneyPhaseProperties: Phase within a user journey. Groups journey steps into stages.
+  // JourneyPhaseProperties: Phase within a user journey. A temporal BAND over the journey's step
   journey_phase: {
     phase_order: { type: "number", description: "Display order within the journey (0-indexed)" },
     label: { type: "string", description: 'Short human-readable name. @example "Discovery", "Onboarding", "Activation"' },
@@ -10145,8 +10181,9 @@ var UPG_PROPERTY_SCHEMA = {
     key_questions: { type: "string[]", description: "Open questions the user asks themselves. Fuel for design and content priorities." },
     timeframe: { type: "string", description: 'Typical time window. @example "first 30 seconds", "days 1\u20137", "onboarding week"' }
   },
-  // JourneyStepProperties: Single step within a user journey.
+  // JourneyStepProperties: Single step within a user journey. A user-moment on the journey's single
   journey_step: {
+    step_order: { type: "number", description: "Display order within the journey's step timeline (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_action.action_order` (UPG-663). For branching journeys, the explicit `journey_step_precedes_journey_step` edge captures the chain." },
     touchpoint: { type: "string", description: "Interaction touchpoint" },
     channel: { type: "string", description: 'Channel (e.g. "web", "email", "in-store")' },
     emotion_score: {
@@ -18069,8 +18106,13 @@ var STANDARD_LABELS = {
   interview_guide: { alt_labels: ["discussion guide", "interview script", "moderator guide"] },
   survey_response: { alt_labels: ["survey answer", "questionnaire response"] },
   // Design layer
-  user_journey: { alt_labels: ["journey map", "customer journey", "experience map", "journey"] },
-  journey_step: { alt_labels: ["touchpoint", "journey stage", "journey phase"] },
+  // (UPG-663) alt_labels must not collide with other entity types' canonical
+  // names or alt_labels, or the string->type resolver is ambiguous.
+  // Dropped 'customer journey' (collides with customer_journey_stage),
+  // 'touchpoint' and 'journey phase' (both distinct entity surfaces: a
+  // touchpoint is the journey_step.touchpoint property, a phase is journey_phase).
+  user_journey: { alt_labels: ["journey map", "experience map", "journey"] },
+  journey_step: { alt_labels: ["journey moment", "journey stage"] },
   design_component: { alt_labels: ["component", "ui component", "design element"] },
   design_token: { alt_labels: ["token", "style token", "css variable"] },
   wireframe: { alt_labels: ["wireflow", "lo-fi mockup", "skeleton"] },
@@ -20135,7 +20177,11 @@ var PRODUCT_SPEC_GUIDE = {
 var UX_DESIGN_GUIDE = {
   domain_id: "ux_design",
   anchor_entity: "user_journey",
-  creation_sequence: ["user_journey", "journey_phase", "journey_action", "journey_step", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
+  // (UPG-663) creation order follows containment: a journey_action is a child
+  // of a journey_step, so the step must precede the action. The journey is the
+  // anchor; phases are the band overlay; steps are the timeline; actions
+  // decompose a step into service-blueprint rows.
+  creation_sequence: ["user_journey", "journey_phase", "journey_step", "journey_action", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
   patterns: [
     {
       name: "Journey to Screen Flow",
@@ -23432,6 +23478,40 @@ var UPG_ANTI_PATTERNS = [
     stages: ["concept", "validation", "build", "beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "fundamental" }
+  },
+  // ── Experience-design layer ─────────────────────────────────────────────
+  {
+    id: "journey-phases-without-canonical-steps",
+    name: "Journey phases without a step spine",
+    description: 'The graph has journey phases spanning steps (`journey_phase_spans_journey_step`), but no journey owns its steps via `user_journey_contains_journey_step`. A phase is a band over a step timeline, not a container. When the timeline itself is missing there is no canonical answer to "what are the steps of this journey?". The phase overlay points at steps the journey does not own.',
+    structured_condition: {
+      operator: "and",
+      checks: [
+        {
+          check: {
+            type: "relationship",
+            source_type: "journey_phase",
+            edge_type: "journey_phase_spans_journey_step",
+            target_type: "journey_step",
+            comparison: "exists"
+          }
+        },
+        {
+          check: {
+            type: "relationship",
+            source_type: "user_journey",
+            edge_type: "user_journey_contains_journey_step",
+            target_type: "journey_step",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "Steps owned by no journey render a different step list per consumer: the phase overlay sees them, a journey-direct walk does not. The journey has no deterministic step spine to traverse, score, or map to screens.",
+    remediation: "Own every step under its journey with `user_journey_contains_journey_step`, then let phases span ranges of that single timeline via `journey_phase_spans_journey_step`. The phase is a non-owning band overlay, not the step container.",
+    stages: ["concept", "validation", "build", "beta", "launch", "growth"],
+    severity: "high",
+    source: { kind: "fundamental" }
   }
 ];
 function getAntiPatternById(id) {
@@ -25954,7 +26034,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.1";
+var UPG_VERSION = "0.9.2";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();