@unified-product-graph/core 0.11.3 → 0.11.5

package/dist/index.d.cts

@@ -18972,7 +18972,9 @@ declare const ENTITY_EMOJI: Record<string, string>;
 /**
  * UPG canonical tree patterns: the named, server-owned shapes the `get_tree`
  * tool assembles (OST, OKR, user, product, validation, strategy, feature areas,
- * delivery, architecture, journey, design system) — one per tree-shaped region.
+ * delivery, architecture, journey, design system, commercial) — one per
+ * tree-shaped region (or, for `architecture`/`commercial`, the tree-shaped
+ * containment subset of a DAG/multi-hub region).
  *
  * A tree pattern is anchor + a TYPE-DRIVEN child map, NOT a list of edge names.
  * `get_tree` roots at `anchor_type` (falling back through `fallback_anchors` when
@@ -19007,6 +19009,25 @@ interface UPGTreeChild {
      * when present and are silent when absent.
      */
     required?: boolean;
+    /**
+     * The node property `get_tree` sorts this slot's children by (ascending,
+     * nodes lacking it last). Ordering is a property of the DATA, not the viewer,
+     * so the server returns children pre-sorted rather than leaving every client
+     * to re-sort (UPG-663 sequence scalars: `phase_order`, `step_order`,
+     * `action_order`, `state_order`). Omitted -> children keep declared slot order.
+     */
+    order_by?: string;
+    /**
+     * Spine resolution for a DAG. When this slot reaches the SAME node redundantly
+     * with a path through a sibling type (e.g. `user_journey -> journey_step`
+     * directly AND `user_journey -> journey_phase -> journey_step`), name that
+     * sibling type here. A child also reachable as a grandchild through a
+     * `prefer_via`-typed child renders under that spine, NOT here -- collapsing the
+     * redundant path so the node is neither silently dropped (G5) nor
+     * double-counted (J1). A child not on the spine still renders here, so the
+     * direct path remains the fallback when the grouping layer is absent.
+     */
+    prefer_via?: string;
 }
 /** How a pattern decides what counts as a structural gap. */
 type UPGTreeGapPolicy = 'required-children-only' | 'all-optional';
@@ -19076,6 +19097,10 @@ interface UPGTreePatternEdge {
     /** The edge's classification (hierarchy, semantic, cross-domain, ...), or null. */
     kind: string | null;
     required: boolean;
+    /** Node scalar this slot's children are sorted by, when declared (J2). */
+    order_by?: string;
+    /** Sibling type whose path is the canonical spine for this child (J1), when declared. */
+    prefer_via?: string;
 }
 /** A pattern with its child map resolved to concrete edges (for introspection). */
 interface UPGTreePatternDetail extends UPGTreePattern {
@@ -21560,7 +21585,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.11.3";
+declare const UPG_VERSION: "0.11.5";
 /**
  * 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

@@ -18972,7 +18972,9 @@ declare const ENTITY_EMOJI: Record<string, string>;
 /**
  * UPG canonical tree patterns: the named, server-owned shapes the `get_tree`
  * tool assembles (OST, OKR, user, product, validation, strategy, feature areas,
- * delivery, architecture, journey, design system) — one per tree-shaped region.
+ * delivery, architecture, journey, design system, commercial) — one per
+ * tree-shaped region (or, for `architecture`/`commercial`, the tree-shaped
+ * containment subset of a DAG/multi-hub region).
  *
  * A tree pattern is anchor + a TYPE-DRIVEN child map, NOT a list of edge names.
  * `get_tree` roots at `anchor_type` (falling back through `fallback_anchors` when
@@ -19007,6 +19009,25 @@ interface UPGTreeChild {
      * when present and are silent when absent.
      */
     required?: boolean;
+    /**
+     * The node property `get_tree` sorts this slot's children by (ascending,
+     * nodes lacking it last). Ordering is a property of the DATA, not the viewer,
+     * so the server returns children pre-sorted rather than leaving every client
+     * to re-sort (UPG-663 sequence scalars: `phase_order`, `step_order`,
+     * `action_order`, `state_order`). Omitted -> children keep declared slot order.
+     */
+    order_by?: string;
+    /**
+     * Spine resolution for a DAG. When this slot reaches the SAME node redundantly
+     * with a path through a sibling type (e.g. `user_journey -> journey_step`
+     * directly AND `user_journey -> journey_phase -> journey_step`), name that
+     * sibling type here. A child also reachable as a grandchild through a
+     * `prefer_via`-typed child renders under that spine, NOT here -- collapsing the
+     * redundant path so the node is neither silently dropped (G5) nor
+     * double-counted (J1). A child not on the spine still renders here, so the
+     * direct path remains the fallback when the grouping layer is absent.
+     */
+    prefer_via?: string;
 }
 /** How a pattern decides what counts as a structural gap. */
 type UPGTreeGapPolicy = 'required-children-only' | 'all-optional';
@@ -19076,6 +19097,10 @@ interface UPGTreePatternEdge {
     /** The edge's classification (hierarchy, semantic, cross-domain, ...), or null. */
     kind: string | null;
     required: boolean;
+    /** Node scalar this slot's children are sorted by, when declared (J2). */
+    order_by?: string;
+    /** Sibling type whose path is the canonical spine for this child (J1), when declared. */
+    prefer_via?: string;
 }
 /** A pattern with its child map resolved to concrete edges (for introspection). */
 interface UPGTreePatternDetail extends UPGTreePattern {
@@ -21560,7 +21585,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.11.3";
+declare const UPG_VERSION: "0.11.5";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.js

@@ -19940,8 +19940,8 @@ function buildTypeAliases() {
 var UPG_TYPE_ALIASES = buildTypeAliases();
 
 // src/presentation/tree-patterns.ts
-var req = (type) => ({ type, required: true });
-var opt = (type) => ({ type });
+var req = (type, order_by) => order_by ? { type, required: true, order_by } : { type, required: true };
+var opt = (type, order_by) => order_by ? { type, order_by } : { type };
 var UPG_TREE_PATTERNS = [
   {
     id: "ost",
@@ -20127,11 +20127,18 @@ var UPG_TREE_PATTERNS = [
     anchor_type: "user_journey",
     fallback_anchors: ["user_flow"],
     child_map: {
-      user_journey: [opt("journey_phase"), opt("journey_step")],
-      journey_phase: [opt("journey_step")],
-      journey_step: [opt("journey_action"), opt("screen")],
+      // The phase is the grouping layer: a step reachable through a phase
+      // renders under the phase, not twice (J1). `prefer_via` collapses the
+      // redundant direct path; a step in NO phase still renders here. Children
+      // are returned in `*_order` sequence (J2), not storage order.
+      user_journey: [
+        opt("journey_phase", "phase_order"),
+        { type: "journey_step", prefer_via: "journey_phase", order_by: "step_order" }
+      ],
+      journey_phase: [opt("journey_step", "step_order")],
+      journey_step: [opt("journey_action", "action_order"), opt("screen")],
       user_flow: [opt("screen")],
-      screen: [opt("screen_state")]
+      screen: [opt("screen_state", "state_order")]
     },
     natural_depth: 3
   },
@@ -20148,6 +20155,43 @@ var UPG_TREE_PATTERNS = [
       design_component: [opt("design_component"), opt("design_token")]
     },
     natural_depth: 3
+  },
+  {
+    id: "commercial",
+    label: "Commercial / money model",
+    description: "The business-model spine: how the product captures value. The business model branches into its revenue streams, cost structure, and unit economics; a stream into its pricing tiers, the metrics that measure it, and the pricing strategy that prices it; and metrics decompose into their components (the MRR waterfall, NRR composition). A pricing tier reached from both its stream and its pricing strategy renders once, then as a shared reference.",
+    // The sustaining money-model captures value as a containment hierarchy, so it
+    // earns a tree even though business_gtm_growth is a multi-hub region: a pattern
+    // is a curated spanning tree over a SUBSET of a region (cf. `architecture` over
+    // the engineering_platform DAG). The GTM/value flow (positioning -> messaging
+    // -> funnel) is deliberately NOT here — a tree would misrepresent it; it wants
+    // sibling flow instruments. Company-grain financial metrics (CAC, LTV, runway)
+    // hang off the product, not a single stream/cost, so they live in the okr/
+    // strategy views, not this money-structure spine.
+    region: "business_gtm_growth",
+    gap_policy: "all-optional",
+    anchor_type: "business_model",
+    // Fallback is the product alone, and product is deliberately NOT a child_map
+    // parent: were business_model listed under product, the product would be a
+    // superset of the money spine and the most-nodes anchor rule would root there
+    // (the same trap delivery hit with product -> roadmap). With product childless,
+    // business_model always out-nodes it and wins; a graph with no business_model
+    // falls back to a bare product root, reported anchor_resolved_from: business_model.
+    fallback_anchors: ["product"],
+    child_map: {
+      business_model: [opt("revenue_stream"), opt("cost_structure"), opt("unit_economics")],
+      revenue_stream: [opt("pricing_tier"), opt("metric"), opt("pricing_strategy")],
+      cost_structure: [opt("metric")],
+      pricing_strategy: [opt("pricing_tier")],
+      // Self-nesting: a metric decomposes into its component metrics (Net New MRR ->
+      // New/Expansion/Contraction/Churned). The assembler's `seen` set terminates
+      // the recursion for free (a metric met again becomes a shared reference).
+      metric: [opt("metric")]
+    },
+    // Default to 3 tiers (business_model -> stream/cost -> tier/metric) for a
+    // readable money-model overview; `depth` extends into the metric -> metric
+    // decomposition waterfall.
+    natural_depth: 3
   }
 ];
 var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
@@ -20169,7 +20213,10 @@ function resolveTreePatternEdges(pattern) {
   for (const [parent, children] of Object.entries(pattern.child_map)) {
     for (const c of children) {
       const e = resolvePatternEdge(parent, c.type);
-      out.push({ parent, child: c.type, via: e?.via ?? null, kind: e?.kind ?? null, required: !!c.required });
+      const row = { parent, child: c.type, via: e?.via ?? null, kind: e?.kind ?? null, required: !!c.required };
+      if (c.order_by) row.order_by = c.order_by;
+      if (c.prefer_via) row.prefer_via = c.prefer_via;
+      out.push(row);
     }
   }
   return out;
@@ -28556,7 +28603,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.11.3";
+var UPG_VERSION = "0.11.5";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();