@unified-product-graph/core 0.12.7 → 0.13.0

package/dist/index.cjs

@@ -38,7 +38,10 @@ __export(index_exports, {
   MARKET_COMPETITIVE_PLAYBOOK: () => MARKET_COMPETITIVE_PLAYBOOK,
   OPERATIONS_QUALITY_PLAYBOOK: () => OPERATIONS_QUALITY_PLAYBOOK,
   PRODUCT_DELIVERY_PLAYBOOK: () => PRODUCT_DELIVERY_PLAYBOOK,
+  PROPERTY_MODIFIERS: () => PROPERTY_MODIFIERS,
+  PROPERTY_MODIFIER_SEMANTICS: () => PROPERTY_MODIFIER_SEMANTICS,
   PROPERTY_SCALE_MAP: () => PROPERTY_SCALE_MAP,
+  RECORD_ENTITY_TYPES: () => RECORD_ENTITY_TYPES,
   REFLECT_MODES: () => REFLECT_MODES,
   REGISTRY_PRODUCT_ID: () => REGISTRY_PRODUCT_ID,
   STRATEGY_OUTCOMES_PLAYBOOK: () => STRATEGY_OUTCOMES_PLAYBOOK,
@@ -140,6 +143,7 @@ __export(index_exports, {
   getDomainIdForType: () => getDomainIdForType,
   getDomainsInRing: () => getDomainsInRing,
   getEdgePropertySchema: () => getEdgePropertySchema,
+  getEntityModifierSummary: () => getEntityModifierSummary,
   getEnumScale: () => getEnumScale,
   getEnumValueMeta: () => getEnumValueMeta,
   getGuideForDomain: () => getGuideForDomain,
@@ -155,6 +159,7 @@ __export(index_exports, {
   getPropertiesForScale: () => getPropertiesForScale,
   getPropertyDefaultScale: () => getPropertyDefaultScale,
   getPropertyMigrations: () => getPropertyMigrations,
+  getPropertyModifier: () => getPropertyModifier,
   getPropertySchema: () => getPropertySchema,
   getRegion: () => getRegion,
   getRegionForEntityType: () => getRegionForEntityType,
@@ -171,6 +176,7 @@ __export(index_exports, {
   getValidChildren: () => getValidChildren,
   getVisibleTypes: () => getVisibleTypes,
   hasStatusMigration: () => hasStatusMigration,
+  isAggregateShapedProperty: () => isAggregateShapedProperty,
   isCanonical: () => isCanonical,
   isCanonicalProductStage: () => isCanonicalProductStage,
   isContainmentFreeType: () => isContainmentFreeType,
@@ -183,9 +189,12 @@ __export(index_exports, {
   isLifecyclePlannedType: () => isLifecyclePlannedType,
   isPolymorphicEdge: () => isPolymorphicEdge,
   isPortfolio: () => isPortfolio,
+  isRecordEntity: () => isRecordEntity,
   isRegisteredPolymorphicEdge: () => isRegisteredPolymorphicEdge,
+  isRuntimeStateShapedProperty: () => isRuntimeStateShapedProperty,
   isSubSequenceStep: () => isSubSequenceStep,
   isUPGDocument: () => isUPGDocument,
+  listPropertiesByModifier: () => listPropertiesByModifier,
   listStatusMigrations: () => listStatusMigrations,
   listTreePatternSummaries: () => listTreePatternSummaries,
   migrateEdge: () => migrateEdge,
@@ -2050,7 +2059,9 @@ var UPG_EDGE_CATALOG = {
   persona_belongs_to_market_segment: { forward_verb: "belongs_to", reverse_verb: "includes_persona", classification: "cross-domain", source_type: "persona", target_type: "market_segment" },
   revenue_stream_priced_by_pricing_strategy: { forward_verb: "priced_by", reverse_verb: "prices", classification: "cross-domain", source_type: "revenue_stream", target_type: "pricing_strategy" },
   revenue_stream_drives_outcome: { forward_verb: "drives", reverse_verb: "driven_by", classification: "cross-domain", source_type: "revenue_stream", target_type: "outcome" },
-  revenue_stream_measured_by_metric_cross_domain: { forward_verb: "measured_by", reverse_verb: "measures", classification: "cross-domain", source_type: "revenue_stream", target_type: "metric" },
+  // revenue_stream_measured_by_metric_cross_domain dropped in 0.13.0 Wave 1 (UPG-685 T0.1):
+  // a cross-domain-classified shadow of revenue_stream_measured_by_metric (same measured_by
+  // verbs); pickCanonicalEdge never returned it. Dual-read to the canonical in UPG_EDGE_MIGRATIONS.
   pricing_tier_targets_behavioral_segment: { forward_verb: "targets", reverse_verb: "targeted_by", classification: "cross-domain", source_type: "pricing_tier", target_type: "behavioral_segment" },
   key_resource_enables_value_proposition: { forward_verb: "enables", reverse_verb: "enabled_by", classification: "cross-domain", source_type: "key_resource", target_type: "value_proposition" },
   // 4.3 Go-To-Market Domain
@@ -3817,7 +3828,12 @@ var UPG_VALID_CHILDREN = {
   ],
   // ── Data & Analytics hierarchy ───────────────────────────────────────────────
   data_source: ["metric", "data_pipeline", "data_lineage", "event_schema"],
-  metric: ["metric", "outcome", "data_quality_rule", "metric_quality_assessment"],
+  // UPG-685 T0.4 (0.13.0 Wave 1): `outcome` removed as a metric child. It closed a
+  // containment cycle (outcome ⊃ metric ⊃ outcome) and was backed only by the CAUSAL
+  // `metric_drives_outcome` edge, not a hierarchy edge — the "metric leads to outcome"
+  // meaning lives correctly on that causal edge. The real containment (outcome ⊃ metric)
+  // is kept. Sub-metric trees (metric ⊃ metric) stay.
+  metric: ["metric", "data_quality_rule", "metric_quality_assessment"],
   data_domain: ["data_product", "data_source", "glossary_term", "data_model", "dashboard"],
   dashboard: ["report", "experiment_run"],
   // ── Content & Knowledge hierarchy ────────────────────────────────────────────
@@ -4220,43 +4236,6 @@ var SOLUTION_LIFECYCLE = {
     }
   ]
 };
-var HYPOTHESIS_LIFECYCLE = {
-  entity_type: "hypothesis",
-  initial_phase: "untested",
-  terminal_phases: ["resolved"],
-  phases: [
-    {
-      id: "untested",
-      label: "Untested",
-      description: "The belief is stated. No experiment has been designed or run.",
-      transitions_to: ["testing"]
-    },
-    {
-      id: "testing",
-      label: "Testing",
-      description: "An experiment is actively running to test this hypothesis. Evidence is being gathered.",
-      transitions_to: ["resolved"]
-    },
-    {
-      id: "resolved",
-      label: "Resolved",
-      description: "The hypothesis has been tested and a conclusion reached. The resolved phase has two states: validated (belief held) or invalidated (belief did not hold).",
-      transitions_to: [],
-      core_states: [
-        {
-          id: "validated",
-          label: "Validated",
-          description: "Evidence supports the hypothesis. The belief held. Learnings can inform solution design."
-        },
-        {
-          id: "invalidated",
-          label: "Invalidated",
-          description: "Evidence contradicts the hypothesis. The belief did not hold. Learnings prevent investment in the wrong direction."
-        }
-      ]
-    }
-  ]
-};
 var HYPOTHESIS_CLAIM_LIFECYCLE = {
   entity_type: "hypothesis",
   initial_phase: "drafted",
@@ -6409,9 +6388,7 @@ var UPG_LIFECYCLES = [
   OPPORTUNITY_LIFECYCLE,
   SOLUTION_LIFECYCLE,
   HYPOTHESIS_CLAIM_LIFECYCLE,
-  // v0.4.0 canonical (re-promoted as 'hypothesis')
-  HYPOTHESIS_LIFECYCLE,
-  // pre-v0.2.8 legacy (retained for migration compat)
+  // canonical 'hypothesis' lifecycle. The pre-v0.2.8 legacy binding (untested → testing → resolved) was removed in 0.13.0 Wave 1 (UPG-685 T0.3): it was a dead second binding for the same entity_type, always shadowed by this one, and the legacy-status remap lives in UPG_*_MIGRATIONS, not a live lifecycle.
   EXPERIMENT_LIFECYCLE,
   EXPERIMENT_PLAN_LIFECYCLE,
   EXPERIMENT_RUN_LIFECYCLE,
@@ -9019,6 +8996,7 @@ var UPG_EDGE_MIGRATIONS = {
     { kind: "rename", from: "value_proposition_targets_persona_cross_domain", to: "value_proposition_targets_persona", requires_source_type: "value_proposition", requires_target_type: "persona", reason: "Duplicate collapse (UPG-677). Byte-identical shadow of value_proposition_targets_persona; the suffixed twin never resolved." },
     { kind: "rename", from: "metric_measures_metric_cross_domain", to: "metric_measures_metric", requires_source_type: "metric", requires_target_type: "metric", reason: "Duplicate collapse (UPG-677). Byte-identical shadow of metric_measures_metric; the suffixed twin never resolved." },
     { kind: "rename", from: "insight_validates_need_cross_domain", to: "insight_validates_need", requires_source_type: "insight", requires_target_type: "need", reason: "Duplicate collapse (UPG-677). Byte-identical shadow of insight_validates_need; the suffixed twin never resolved." },
+    { kind: "rename", from: "revenue_stream_measured_by_metric_cross_domain", to: "revenue_stream_measured_by_metric", requires_source_type: "revenue_stream", requires_target_type: "metric", reason: "Duplicate collapse (UPG-685 T0.1, 0.13.0 Wave 1). Cross-domain-classified shadow of revenue_stream_measured_by_metric (same measured_by/measures verbs); pickCanonicalEdge never returned it (the semantic key wins the pair; revenue_stream_drives_metric serves the cross-domain ask). Verb-preserving collapse onto the semantic canonical." },
     // ── Tier 2: tense / suffix twins ──
     { kind: "rename", from: "metric_decomposed_into_metric", to: "metric_decomposes_into_metric", requires_source_type: "metric", requires_target_type: "metric", reason: "Duplicate collapse (UPG-677). Tense-twin of the active-voice metric_decomposes_into_metric." },
     { kind: "rename", from: "product_decided_via_decision_hierarchy", to: "product_decided_via_decision", requires_source_type: "product", requires_target_type: "decision", reason: "Duplicate collapse (UPG-677). Suffix-twin of product_decided_via_decision." },
@@ -19423,6 +19401,62 @@ function isUPGDocument(doc) {
   return validateUPGDocument(doc).valid;
 }
 
+// src/properties/property-modifiers.ts
+var PROPERTY_MODIFIERS = ["derived", "snapshot", "volatile"];
+var PROPERTY_MODIFIER_SEMANTICS = {
+  derived: "Computed from edges/children at read-time; never hand-authored. A stored value that contradicts the graph is a smell.",
+  snapshot: "A stale-stamped cache of a live reading; SHOULD pair with a `*_as_of` timestamp. Definition entities carry live state only as a snapshot.",
+  volatile: "An environment-specific pointer (URL / path / id) that may rot or be stripped on export; not portable modeling knowledge."
+};
+function listPropertiesByModifier(modifier) {
+  const out = [];
+  for (const [type, props] of Object.entries(UPG_PROPERTY_SCHEMA)) {
+    for (const [property, def] of Object.entries(props)) {
+      const m = def?.modifier;
+      if (!m) continue;
+      if (modifier && m !== modifier) continue;
+      out.push({ type, property, modifier: m });
+    }
+  }
+  return out;
+}
+function getPropertyModifier(entityType, property) {
+  return UPG_PROPERTY_SCHEMA[entityType]?.[property]?.modifier;
+}
+function getEntityModifierSummary(entityType) {
+  const props = UPG_PROPERTY_SCHEMA[entityType];
+  if (!props) return void 0;
+  const summary = { derived: [], snapshot: [], volatile: [] };
+  let any = false;
+  for (const [property, def] of Object.entries(props)) {
+    const m = def?.modifier;
+    if (!m) continue;
+    summary[m].push(property);
+    any = true;
+  }
+  return any ? summary : void 0;
+}
+var RECORD_ENTITY_TYPES = /* @__PURE__ */ new Set([
+  "ai_cost_tracker",
+  "eval_run",
+  "test_result",
+  "agent_session",
+  "cohort",
+  "ai_trace",
+  "workflow_run"
+]);
+function isRecordEntity(entityType) {
+  return RECORD_ENTITY_TYPES.has(entityType);
+}
+function isAggregateShapedProperty(name, def) {
+  if (def?.type !== "number") return false;
+  return name.endsWith("_count") || name === "headcount";
+}
+function isRuntimeStateShapedProperty(name, def) {
+  if (def?.type !== "number") return false;
+  return /_rate$/.test(name) || /_pct$/.test(name) || /^current_/.test(name) || /_remaining$/.test(name) || /_p\d+_/.test(name) || /^monthly_/.test(name) || /_per_/.test(name);
+}
+
 // src/properties/edge-property-validation.ts
 function validateEdgeProperties(edgeType, properties) {
   const schema = getEdgePropertySchema(edgeType);
@@ -21032,6 +21066,29 @@ var UPG_TREE_PATTERNS = [
     // readable money-model overview; `depth` extends into the metric -> metric
     // decomposition waterfall.
     natural_depth: 3
+  },
+  {
+    id: "north_star",
+    label: "North Star impact",
+    description: "A north-star metric, the input/sub-metrics it decomposes into, and the outcomes it drives. The metric-rooted, leading-indicator view: outcomes hang off the metric by influence (the causal `drives` edge), distinct from the OKR view where the outcome sits on top and the metric measures it.",
+    framework_id: "north-star-metric",
+    region: "strategy_outcomes",
+    gap_policy: "all-optional",
+    anchor_type: "metric",
+    // A north-star tree roots at a metric by definition; no fallback (no metric =
+    // no north-star view, honestly empty rather than rooting elsewhere).
+    fallback_anchors: [],
+    child_map: {
+      // A metric decomposes into its input/sub-metrics (the `metric_decomposes_into_metric`
+      // hierarchy) AND drives the outcomes it predicts (the causal `metric_drives_outcome`).
+      // The outcome is a child by INFLUENCE, not containment — the leading-to-lagging chain.
+      // Following the causal edge by type-adjacency (cf. `strategy`'s initiative -> outcome)
+      // is how the metric-rooted view renders without re-creating the metric ⊃ outcome
+      // containment cycle removed in UPG-685 T0.4. The assembler's `seen` set terminates the
+      // metric -> metric recursion for free.
+      metric: [opt("metric"), opt("outcome")]
+    },
+    natural_depth: 3
   }
 ];
 var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
@@ -28440,11 +28497,6 @@ var UPG_REGIONS = [
         edge_id: "key_result_quantified_by_metric",
         crosses_into: "strategy_outcomes"
       },
-      {
-        direction: "import",
-        edge_id: "revenue_stream_measured_by_metric_cross_domain",
-        crosses_into: "business_gtm_growth"
-      },
       {
         direction: "import",
         edge_id: "service_level_objective_tracks_metric",
@@ -29465,7 +29517,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.12.7";
+var UPG_VERSION = "0.13.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -29548,7 +29600,10 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   MARKET_COMPETITIVE_PLAYBOOK,
   OPERATIONS_QUALITY_PLAYBOOK,
   PRODUCT_DELIVERY_PLAYBOOK,
+  PROPERTY_MODIFIERS,
+  PROPERTY_MODIFIER_SEMANTICS,
   PROPERTY_SCALE_MAP,
+  RECORD_ENTITY_TYPES,
   REFLECT_MODES,
   REGISTRY_PRODUCT_ID,
   STRATEGY_OUTCOMES_PLAYBOOK,
@@ -29650,6 +29705,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getDomainIdForType,
   getDomainsInRing,
   getEdgePropertySchema,
+  getEntityModifierSummary,
   getEnumScale,
   getEnumValueMeta,
   getGuideForDomain,
@@ -29665,6 +29721,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getPropertiesForScale,
   getPropertyDefaultScale,
   getPropertyMigrations,
+  getPropertyModifier,
   getPropertySchema,
   getRegion,
   getRegionForEntityType,
@@ -29681,6 +29738,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   getValidChildren,
   getVisibleTypes,
   hasStatusMigration,
+  isAggregateShapedProperty,
   isCanonical,
   isCanonicalProductStage,
   isContainmentFreeType,
@@ -29693,9 +29751,12 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   isLifecyclePlannedType,
   isPolymorphicEdge,
   isPortfolio,
+  isRecordEntity,
   isRegisteredPolymorphicEdge,
+  isRuntimeStateShapedProperty,
   isSubSequenceStep,
   isUPGDocument,
+  listPropertiesByModifier,
   listStatusMigrations,
   listTreePatternSummaries,
   migrateEdge,