@unified-product-graph/core 0.11.3 → 0.11.5

package/CHANGELOG.md

@@ -7,6 +7,29 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.11.5] - 2026-06-15
+
+**`get_tree` gains a `commercial` pattern: the business-model spine as a one-call tree.** The monetisation axis was the one populated, tree-shaped region with no pattern — *"show me the money model: streams, costs, tiers, and the metrics that measure them"* meant a hand-authored `query`. `commercial` roots at `business_model` and walks 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). A pricing tier reached from both its stream and its pricing strategy renders once, then as a shared reference — the same multi-parent (G5) path `delivery` relies on. It is a curated spanning tree over the containment subset of the multi-hub `business_gtm_growth` region (the GTM/value flow stays excluded — a tree would misrepresent it); company-grain financials (CAC, LTV, runway) hang off the product, not a single stream, and remain an okr/strategy concern. Declarative child-map record, no engine work, all-optional (a stream without a metric is not a structural hole). 12 patterns now; no new tools (131). A new pattern on a young tool = a patch.
+
+### Added
+- **`commercial` tree pattern** (a.k.a. business / money model). Anchor `business_model`, fallback `product`, region `business_gtm_growth`, natural depth 3, all-optional gap policy. Child map: `business_model -> {revenue_stream, cost_structure, unit_economics}`; `revenue_stream -> {pricing_tier, metric, pricing_strategy}`; `cost_structure -> {metric}`; `pricing_strategy -> {pricing_tier}`; `metric -> {metric}` (the self-nesting decomposition waterfall, cycle-terminated by the assembler's shared-reference guard). Surfaced on `list_tree_patterns` / `get_tree_pattern` introspection and the `/upg-show-tree` skill.
+
+---
+
+## [0.11.4] - 2026-06-14
+
+**`get_tree` now linearises a DAG into a tree deterministically: no double-counted node, children in canonical order.** Field-testing the `journey` pattern on a fully-wired forest surfaced two structural defects, both Tier-1 (truth, not presentation — two competent agents must get the identical tree). A step reachable both directly (`user_journey -> journey_step`) and through its phase (`-> journey_phase -> journey_step`) rendered twice: once in full, once as a hollow `shared` reference — the exact mirror of the 0.9.17 silent-drop fix (G5), now silent *duplication* (J1). And children came back in storage order, ignoring the `*_order` scalars they carry, so every client had to re-sort (J2). Both are fixed by two declarative slot fields on the pattern child-map; the assembler does the linearisation once, server-side. No new tools (131); a behaviour fix on a young tool = a patch.
+
+### Added
+- **`order_by` on a tree pattern child slot.** Names the node scalar `get_tree` sorts the slot's children by (ascending, nodes lacking it last). Wired on the `journey` pattern: `journey_phase -> phase_order`, `journey_step -> step_order`, `journey_action -> action_order`, `screen_state -> state_order` (the UPG-663 sequence convention). Surfaced on `get_tree_pattern` introspection rows. 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 (J2).
+- **`prefer_via` on a tree pattern child slot.** Names the sibling type whose path is the canonical spine when a slot reaches the same node redundantly by two declared paths. The `journey` pattern's direct `user_journey -> journey_step` slot declares `prefer_via: journey_phase`: a step also reachable through a phase renders under the phase only. A step in no phase still renders directly (the direct path is the fallback, never a silent drop). Surfaced on `get_tree_pattern` rows (J1).
+
+### Changed
+- **`get_tree` returns children in canonical order across every pattern.** Children are grouped by their declared slot position, then sorted by the slot's `order_by` scalar (stable within ties). Previously edge/storage order. A pattern with no `order_by` slots is unaffected beyond the now-deterministic slot grouping.
+- **`get_tree` collapses a redundant DAG path instead of double-counting it.** A node reachable from one parent by two declared paths renders once, under the `prefer_via` spine. Genuine multi-parent sharing (a node under two *different* parents) is unchanged — it still renders once in full and as a `shared` reference elsewhere (the 0.9.17 G5 behaviour). Verified on the saturated journey forest: every redundant direct-plus-phase step now renders once; legitimate cross-parent shares preserved.
+
+---
+
 ## [0.11.3] - 2026-06-14
 
 **A reclassification now supersedes the prior value instead of leaving a stale edge.** 0.11.0 recorded a competitor's move in the reclassification history but kept the old same-axis classify edge, so after a move the competitor was classified as BOTH the old and the new value — `get_portfolio_tree` double-counted it (Data's brief, confirmed live on 0.11.1). This release retires the prior edge as part of the move, keyed off a new axis cardinality field so a genuinely multi-select axis is never collapsed. Property add + behaviour fix = a patch.

package/dist/index.cjs

@@ -20152,8 +20152,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",
@@ -20339,11 +20339,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
   },
@@ -20360,6 +20367,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(
@@ -20381,7 +20425,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;
@@ -28768,7 +28815,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();