@unified-product-graph/core 0.11.4 → 0.11.6

package/CHANGELOG.md

@@ -7,6 +7,15 @@ 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.

package/dist/index.cjs

@@ -706,7 +706,7 @@ var UPG_DOMAINS = [
     id: "foundations",
     label: "Foundations",
     description: "The shared specifications and foundational primitives a product organisation stewards or implements everywhere. Specifications are governed specs (query languages, protocols, data formats, encodings) like GROQ or Portable Text; primitives are the compositional units those specs define (a block, a reference, a query value). Both are registry-hostable canonicals that products implement, expose, or conform to. Distinct from a product feature: a specification has no single owner, no P&L, and no buyer; it is the rulebook many products point at.",
-    types: ["specification", "primitive"]
+    types: ["specification", "primitive", "operating_lifecycle", "operating_stage"]
   }
 ];
 var UPG_ENTITY_TO_DOMAIN = Object.freeze(
@@ -729,6 +729,8 @@ var UPG_ENTITY_META = [
   // Foundations (0.9.12): shared specifications + the primitives they define.
   { name: "specification", type_id: "ent_352", maturity: "proposed", since: "0.9.12" },
   { name: "primitive", type_id: "ent_353", maturity: "proposed", since: "0.9.12" },
+  { name: "operating_lifecycle", type_id: "ent_355", maturity: "proposed", since: "0.11.6" },
+  { name: "operating_stage", type_id: "ent_356", maturity: "proposed", since: "0.11.6" },
   // ── Strategic ──
   { name: "product", type_id: "ent_001", maturity: "stable", since: "0.1.0" },
   { name: "outcome", type_id: "ent_002", maturity: "stable", since: "0.1.0" },
@@ -1229,6 +1231,9 @@ var UPG_EDGE_CATALOG = {
   persona_pursues_job: { forward_verb: "pursues", reverse_verb: "pursued_by", classification: "semantic", source_type: "persona", target_type: "job" },
   persona_experiences_need: { forward_verb: "experiences", reverse_verb: "experienced_by", classification: "semantic", source_type: "persona", target_type: "need" },
   persona_aspires_to_desired_outcome: { forward_verb: "aspires_to", reverse_verb: "aspirational_for", classification: "hierarchy", source_type: "persona", target_type: "desired_outcome" },
+  // Delegation (0.11.6): a persona delegates work to another. The common case is human -> agent
+  // (Content Ops Lead -> Content Agent), but it also expresses human -> human (editor -> reviewer).
+  persona_delegates_to_persona: { forward_verb: "delegates_to", reverse_verb: "delegated_by", classification: "semantic", source_type: "persona", target_type: "persona" },
   persona_incurs_switching_cost: { forward_verb: "incurs", reverse_verb: "incurred_by", classification: "hierarchy", source_type: "persona", target_type: "switching_cost" },
   job_surfaces_need: { forward_verb: "surfaces", reverse_verb: "surfaces_from", classification: "causal", source_type: "job", target_type: "need" },
   job_motivates_desired_outcome: { forward_verb: "motivates", reverse_verb: "motivated_by", classification: "causal", source_type: "job", target_type: "desired_outcome" },
@@ -3210,8 +3215,13 @@ var UPG_EDGE_CATALOG = {
   specification_competes_with_specification: { forward_verb: "competes_with", reverse_verb: "competes_with", classification: "semantic", source_type: "specification", target_type: "specification" },
   primitive_defined_by_specification: { forward_verb: "defined_by", reverse_verb: "defines", classification: "semantic", source_type: "primitive", target_type: "specification" },
   primitive_composes_primitive: { forward_verb: "composes", reverse_verb: "composed_by", classification: "hierarchy", source_type: "primitive", target_type: "primitive" },
+  operating_lifecycle_contains_operating_stage: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "operating_lifecycle", target_type: "operating_stage" },
   // Stewardship: a registry specification is governed by a (registry-hostable) organization (0.9.13).
-  specification_governed_by_organization: { forward_verb: "governed_by", reverse_verb: "governs", classification: "semantic", source_type: "specification", target_type: "organization" }
+  specification_governed_by_organization: { forward_verb: "governed_by", reverse_verb: "governs", classification: "semantic", source_type: "specification", target_type: "organization" },
+  // Operating-lifecycle cross-edges (0.11.6): a product's journey phase realises a canonical
+  // operating stage (the cross-surface join key); a stage is measured by a rollup metric (loop close).
+  journey_phase_realises_operating_stage: { forward_verb: "realises", reverse_verb: "realised_by", classification: "cross-domain", source_type: "journey_phase", target_type: "operating_stage" },
+  operating_stage_measured_by_metric: { forward_verb: "measured_by", reverse_verb: "measures", classification: "cross-domain", source_type: "operating_stage", target_type: "metric" }
 };
 var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Universal semantic verbs
@@ -3367,6 +3377,9 @@ var UPG_VALID_CHILDREN = {
   //    primitive_composes_primitive catalog edges.
   specification: ["specification"],
   primitive: ["primitive"],
+  // An operating_lifecycle (e.g. the content-ops lifecycle) contains its ordered
+  // operating_stage children. Backs the operating_lifecycle_contains_operating_stage edge.
+  operating_lifecycle: ["operating_stage"],
   // ── Product (root) ─────────────────────────────────────────────────────────
   product: [
     // Strategy
@@ -6430,9 +6443,13 @@ function getLifecycleForType(entityType) {
   return UPG_LIFECYCLES.find((l) => l.entity_type === entityType);
 }
 var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
-  // ── Foundations (1 of 2): a primitive either exists or is deprecated; no
-  //    phase ladder (like metric). `specification` carries a lifecycle. ──
+  // ── Foundations (3 of 4): a primitive either exists or is deprecated; no
+  //    phase ladder (like metric). `operating_lifecycle`/`operating_stage` are
+  //    static ordered reference data (the loop is a `cyclic` flag, not a state
+  //    machine). `specification` carries a lifecycle. ──
   "primitive",
+  "operating_lifecycle",
+  "operating_stage",
   // ── User (5): personas and JTBD atoms are reference data ──────────────────
   "persona",
   "job",
@@ -9861,7 +9878,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // CodeRepositoryProperties: Code repository.
   code_repository: {
-    repo_url: { type: "string", description: "URL" },
+    repo_url: { type: "string", description: "URL", modifier: "volatile" },
     default_branch: { type: "string", description: "Default branch" },
     language: { type: "string", description: "Primary programming language" },
     ci_status: { type: "string", enum: ["passing", "failing", "unknown"], description: "Current CI status" },
@@ -10122,7 +10139,7 @@ var UPG_PROPERTY_SCHEMA = {
   data_classification: {
     level: { type: "string", enum: ["public", "internal", "confidential", "restricted"], description: "Sensitivity level" },
     handling_requirements: { type: "string", description: "Handling rules" },
-    examples: { type: "string", description: "Example data covered" },
+    examples: { type: "string[]", description: "Example data covered" },
     retention_period: { type: "string", description: "Retention period" },
     encryption_required: { type: "boolean", description: "Whether encryption is mandatory" }
   },
@@ -10616,7 +10633,7 @@ var UPG_PROPERTY_SCHEMA = {
   feature_area: {
     scope_summary: { type: "string", description: "One-line scope description. Disambiguates from sibling areas at a glance." },
     owning_team: { type: "string", description: "Team identifier or slug. Free-form display. Canonical relationship is the `team_owns_feature_area` edge." },
-    feature_count: { type: "number", description: "Approximate feature count under this area. Snapshot; `feature_area_contains_feature` edges are the source of truth." },
+    feature_count: { type: "number", description: "Approximate feature count under this area. Snapshot; `feature_area_contains_feature` edges are the source of truth.", modifier: "derived" },
     owner: { type: "string", description: "Area owner (handle or email)" },
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Importance to the product overall" },
     maturity: { type: "string", enum: ["nascent", "growing", "mature", "legacy"], description: "Maturity. `nascent` = newly-formed grouping. `mature` = established surface. `legacy` = being phased out for a successor." },
@@ -10733,7 +10750,7 @@ var UPG_PROPERTY_SCHEMA = {
   // FunnelProperties: Funnel entity.
   funnel: {
     funnel_type: { type: "string", enum: ["acquisition", "activation", "retention", "revenue", "referral", "custom"], description: "Which stage of the customer lifecycle this funnel measures" },
-    step_count: { type: "number", description: "Number of steps in the funnel" },
+    step_count: { type: "number", description: "Number of steps in the funnel", modifier: "derived" },
     overall_conversion_rate: { type: "number", description: "End-to-end conversion rate through the funnel (0-1)" }
   },
   // FunnelStepProperties: FunnelStep entity.
@@ -10886,7 +10903,7 @@ var UPG_PROPERTY_SCHEMA = {
       },
       required: ["value", "label"]
     },
-    evidence_count: { type: "number", description: "Supporting observations, quotes, or evidence items. Higher counts increase confidence." },
+    evidence_count: { type: "number", description: "Supporting observations, quotes, or evidence items. Higher counts increase confidence.", modifier: "derived" },
     novelty: { type: "string", enum: ["known", "surprising", "contradictory"], description: "Novelty against existing knowledge. `known` = confirms what we already believed. `surprising` = challenges or extends our understanding. `contradictory` = directly conflicts with a prior assumption." },
     actionability: { type: "string", enum: ["immediate", "needs_validation", "informational"], description: "Current actionability. `immediate` = clear action, no further research needed. `needs_validation` = promising but requires more evidence. `informational` = important context, no direct action." },
     source_method: { type: "string", description: 'Producing research method. @example "usability_study", "interview_series", "survey"' },
@@ -11560,7 +11577,8 @@ var UPG_PROPERTY_SCHEMA = {
     motivation: { type: "string", description: 'Primary motivation or driving need @example "Making confident, evidence-based decisions"' },
     tech_comfort: { type: "string", enum: ["low", "medium", "high", "expert", "other"], description: "Tech comfort. Closed set so personas across products compare on the same axis. Free-text colour belongs in `context` or `motivation`." },
     domain_expertise: { type: "string", description: 'Industry or domain knowledge this persona brings @example "10+ years SaaS experience", "New to healthcare IT"' },
-    audience_role: { type: "string", enum: ["buyer", "user", "champion", "influencer", "partner"], description: 'Role in the buying / adoption decision (the decision-making-unit split): who signs (buyer) vs who uses (user) vs who advocates internally (champion) vs who shapes the choice (influencer) vs who delivers / implements (partner). A portfolio must separate the economic buyer from the practitioner user; they are distinct personas with distinct jobs. Closed set so roles compare across products. @example "buyer"' }
+    audience_role: { type: "string", enum: ["buyer", "user", "champion", "influencer", "partner"], description: 'Role in the buying / adoption decision (the decision-making-unit split): who signs (buyer) vs who uses (user) vs who advocates internally (champion) vs who shapes the choice (influencer) vs who delivers / implements (partner). A portfolio must separate the economic buyer from the practitioner user; they are distinct personas with distinct jobs. Closed set so roles compare across products. @example "buyer"' },
+    actor_kind: { type: "string", enum: ["human", "agent", "system"], description: "Who performs the work: a human archetype (default; absent = human, no migration), an autonomous AI agent (e.g. Content Agent), or a non-agentic platform service. An agent persona participates in journeys via the same persona machinery and is delegated to via persona_delegates_to_persona. Human-coverage / segmentation metrics count human only; agent/system opt-in." }
   },
   // PipelineSalesProperties: Sales pipeline.
   pipeline_sales: {
@@ -11623,6 +11641,21 @@ var UPG_PROPERTY_SCHEMA = {
     defined_by: { type: "string", description: "The `specification/<slug>` this primitive comes from; nullable for spec-less internal primitives. Mirrors the `primitive_defined_by_specification` edge for quick lookup." },
     since: { type: "string", description: "Year or version the primitive was introduced." }
   },
+  // OperatingLifecycleProperties: a canonical ordered (often cyclic) operating process products' journey phases map onto.
+  operating_lifecycle: {
+    label: { type: "string", description: "Human-readable name of the operating process." },
+    cyclic: { type: "boolean", description: "True if the process loops (e.g. Analyze \u2192 Extend \u2192 Plan). Rendered linearly by stage_order with the wrap on the final stage." },
+    source: { type: "string", description: 'Origin of the canonical model (e.g. "Sanity official content-ops lifecycle").' }
+  },
+  // OperatingStageProperties: one ordered stage of an operating_lifecycle.
+  operating_stage: {
+    stage_order: { type: "number", description: "Ordered position within the lifecycle, 0-indexed." },
+    label: { type: "string", description: "Human-readable stage name." },
+    goal: { type: "string", description: "What this stage accomplishes." },
+    owner_role: { type: "string", description: "Role that owns the stage (free-text role label)." },
+    os_analogy: { type: "string", description: 'The Content-OS analogy from the source volume (e.g. "Drivers + daemons / cron").' },
+    next_stage: { type: "string", description: "Label of the next stage; on the final stage of a cyclic lifecycle this carries the wrap." }
+  },
   // PrivacyPolicyProperties: Privacy policy.
   privacy_policy: {
     version: { type: "string", description: "Version identifier of the policy" },
@@ -12023,7 +12056,7 @@ var UPG_PROPERTY_SCHEMA = {
   service_level_indicator: {
     metric_name: { type: "string", description: 'Indicator metric name. @example "Request latency p99", "Error rate", "Availability"' },
     threshold: { type: "number", description: 'Threshold that defines a "good" event. @example 200 (ms latency), 0.01 (1% error rate), 99.9 (% availability)' },
-    current_value: { type: "number", description: "Current observed value. Compared against `threshold` for SLO compliance. @example 150 (ms), 0.003 (0.3% error rate)" },
+    current_value: { type: "number", description: "Current observed value. Compared against `threshold` for SLO compliance. @example 150 (ms), 0.003 (0.3% error rate)", modifier: "snapshot" },
     unit: { type: "string", description: 'Unit of measurement. Required to interpret `threshold` and `current_value`. @example "ms", "%", "req/s", "errors/min"' },
     aggregation: { type: "string", enum: ["avg", "sum", "max", "min", "p50", "p95", "p99", "count"], description: 'Aggregation over the evaluation window. p99 and avg tell different stories. @example "p99" for tail latency, "avg" for mean throughput, "count" for total events' },
     measurement_query: { type: "string", description: "Query expression that produces `current_value`. Free-form to fit PromQL, Datadog query strings, SQL, or vendor-specific DSLs. @example 'sum(rate(http_requests_total{status=~\"5..\"}[5m])) / sum(rate(http_requests_total[5m]))'" },
@@ -12569,7 +12602,7 @@ var UPG_PROPERTY_SCHEMA = {
     completed_at: { type: "string", description: "ISO timestamp when the run completed" },
     run_status: { type: "string", enum: ["pending", "running", "completed", "failed", "canceled"], description: "Current execution status of the run" },
     triggering_event: { type: "string", description: "Event or action that triggered this run" },
-    step_count: { type: "number", description: "Number of steps executed in this run" },
+    step_count: { type: "number", description: "Number of steps executed in this run", modifier: "derived" },
     total_tokens: { type: "number", description: "Total tokens consumed across all steps" },
     total_cost: { type: "number", description: "Total monetary cost of the run" },
     error_message: { type: "string", description: "Error message if the run failed" }
@@ -12577,8 +12610,8 @@ var UPG_PROPERTY_SCHEMA = {
   // WorkflowTemplateProperties: Workflow template.
   workflow_template: {
     template_type: { type: "string", enum: ["sequential", "parallel", "conditional", "loop"], description: "Execution pattern for the workflow steps" },
-    step_count: { type: "number", description: "Number of steps in the workflow" },
-    agent_count: { type: "number", description: "Number of agents involved in the workflow" },
+    step_count: { type: "number", description: "Number of steps in the workflow", modifier: "derived" },
+    agent_count: { type: "number", description: "Number of agents involved in the workflow", modifier: "derived" },
     estimated_duration: { type: "string", description: "Estimated wall-clock duration of a full run" },
     state_schema: { type: "string", description: "Schema describing the workflow's state object" },
     checkpoint_enabled: { type: "boolean", description: "Whether the workflow supports checkpointing for recovery" },
@@ -19077,6 +19110,8 @@ var ENTITY_EMOJI = {
   pricing_strategy: "\u{1F4B1}",
   pricing_tier: "\u{1F949}",
   primitive: "\u{1F4CB}",
+  operating_lifecycle: "\u{1F504}",
+  operating_stage: "\u{1F539}",
   privacy_policy: "\u{1F6E1}\uFE0F",
   product: "\u{1F9EC}",
   product_area: "\u{1FA80}",
@@ -20367,6 +20402,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(
@@ -22852,7 +22924,7 @@ var WORKSPACE_GUIDE = {
 var FOUNDATIONS_GUIDE = {
   domain_id: "foundations",
   anchor_entity: "specification",
-  creation_sequence: ["specification", "primitive"],
+  creation_sequence: ["specification", "primitive", "operating_lifecycle", "operating_stage"],
   patterns: [
     {
       name: "Specification defines primitives",
@@ -26219,6 +26291,7 @@ var UPG_REGIONS = [
       "persona_experiences_need",
       "persona_aspires_to_desired_outcome",
       "persona_incurs_switching_cost",
+      "persona_delegates_to_persona",
       "job_surfaces_need"
     ],
     boundary_edges: [
@@ -28238,6 +28311,14 @@ var UPG_REGIONS = [
       {
         type: "primitive",
         role: "container"
+      },
+      {
+        type: "operating_lifecycle",
+        role: "container"
+      },
+      {
+        type: "operating_stage",
+        role: "leaf"
       }
     ],
     anchor: {
@@ -28250,9 +28331,21 @@ var UPG_REGIONS = [
       "specification_extends_specification",
       "specification_competes_with_specification",
       "primitive_defined_by_specification",
-      "primitive_composes_primitive"
+      "primitive_composes_primitive",
+      "operating_lifecycle_contains_operating_stage"
     ],
-    boundary_edges: []
+    boundary_edges: [
+      {
+        direction: "import",
+        edge_id: "journey_phase_realises_operating_stage",
+        crosses_into: "experience_design_brand"
+      },
+      {
+        direction: "export",
+        edge_id: "operating_stage_measured_by_metric",
+        crosses_into: "analytics_data"
+      }
+    ]
   }
 ];
 var UPG_REGION_MAP = Object.fromEntries(UPG_REGIONS.map((r) => [r.id, r]));
@@ -28778,7 +28871,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.11.4";
+var UPG_VERSION = "0.11.6";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();