@unified-product-graph/core 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -7,6 +7,15 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.8.4] - 2026-06-02
+
+Framework exercises. `UPG_VERSION` is now `0.8.4` (catalogue change). Folds the 0.8.3 patch train (CLI/MCP wiring fixes; no catalogue change).
+
+### Added
+- `framework_exercise` entity type (Workspace domain): one run of a framework over a set of entities. Containment-free, with a draft/active/archived lifecycle and `framework_id` + `inputs_snapshot` properties.
+- `framework_exercise_includes_node` edge (`includes` / `included_in`, polymorphic target): links an exercise to each entity it scores and carries the framework's per-entity result (a MoSCoW bucket, a RICE score, a canvas slot, a funnel stage) as edge properties.
+- Gated edge properties: `UPGEdge.properties` plus a `carries_properties` capability flag on edge definitions. Only edges that opt in may carry a payload; the canonical serializer round-trips it byte-stably. New `edgeCarriesProperties(type)` helper.
+
 ## [0.8.2] - 2026-06-02
 
 Co-version with the @unified-product-graph/* 0.8.2 release train.

package/dist/index.cjs

@@ -104,6 +104,7 @@ __export(index_exports, {
   collectSlugsForType: () => collectSlugsForType,
   compareVersions: () => compareVersions,
   computeBodyChecksum: () => computeBodyChecksum,
+  edgeCarriesProperties: () => edgeCarriesProperties,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
   formatUpgText: () => formatUpgText,
@@ -676,8 +677,8 @@ var UPG_DOMAINS = [
   {
     id: "workspace",
     label: "Workspace",
-    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure.",
-    types: ["workspace"]
+    description: "Spatial thinking spaces for arranging entities, debating decisions, and committing to the graph. Workspaces are transient canvases that sit alongside all other domains, letting you compose and explore relationships before they become permanent graph structure. A framework exercise is a structured workspace: one run of a framework (MoSCoW, RICE, Kano, \u2026) applied to a chosen set of entities, with each entity's result recorded on the exercise-to-entity edge rather than the entity itself.",
+    types: ["workspace", "framework_exercise"]
   }
 ];
 var UPG_ENTITY_TO_DOMAIN = Object.freeze(
@@ -1103,7 +1104,8 @@ var UPG_ENTITY_META = [
   { name: "integration_partner", type_id: "ent_311", maturity: "stable", since: "0.1.0" },
   { name: "partner_revenue_share", type_id: "ent_312", maturity: "stable", since: "0.1.0" },
   // ── Workspace ──
-  { name: "workspace", type_id: "ent_328", maturity: "proposed", since: "0.2.0" }
+  { name: "workspace", type_id: "ent_328", maturity: "proposed", since: "0.2.0" },
+  { name: "framework_exercise", type_id: "ent_350", maturity: "proposed", since: "0.8.4" }
 ];
 var UPG_ENTITY_META_BY_NAME = new Map(
   UPG_ENTITY_META.map((m) => [m.name, m])
@@ -2256,6 +2258,18 @@ var UPG_EDGE_CATALOG = {
   // universal across the DDD type family. Verbs follow DDD literature:
   // aggregate belongs_to context, context contains aggregates.
   node_belongs_to_bounded_context: { forward_verb: "belongs_to", reverse_verb: "contains", classification: "cross-domain", source_type: "node", target_type: "bounded_context" },
+  // ── Cross-domain: Framework exercises ────────────────────────────────────────
+  // A framework_exercise is one run of a framework (MoSCoW, RICE, Kano, …) over a
+  // set of entities. It `includes` each entity it touches; the framework's
+  // per-entity result — a MoSCoW bucket, a RICE score, a canvas slot, a funnel
+  // stage — rides on this edge's `properties`, NOT on the entity node. A value
+  // that exists only within a specific exercise is a fact about the relationship,
+  // not the entity, so it lives on the edge (same principle as owner-as-edge).
+  // Polymorphic (`target_type: 'node'`): an exercise can include any entity type,
+  // which closes the feature-only limitation structurally. `carries_properties`
+  // opts this edge into the gated edge-property model. See ADR
+  // 2026-06-02-framework-exercises.
+  framework_exercise_includes_node: { forward_verb: "includes", reverse_verb: "included_in", classification: "cross-domain", source_type: "framework_exercise", target_type: "node", carries_properties: true },
   // ── New edges replacing deleted string properties ────────────────────
   // Marketing
   marketing_strategy_pursues_outcome: { forward_verb: "pursues", reverse_verb: "pursued_by", classification: "cross-domain", source_type: "marketing_strategy", target_type: "outcome" },
@@ -2885,7 +2899,9 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   "node_owned_by_department",
   "node_owned_by_person",
   // Universal architecture references
-  "node_belongs_to_bounded_context"
+  "node_belongs_to_bounded_context",
+  // Framework exercises (an exercise can include any entity type)
+  "framework_exercise_includes_node"
 ];
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 function isPolymorphicEdge(key) {
@@ -2895,6 +2911,10 @@ function isPolymorphicEdge(key) {
 function isRegisteredPolymorphicEdge(key) {
   return _POLY_KEY_SET.has(key);
 }
+function edgeCarriesProperties(type) {
+  const def = UPG_EDGE_CATALOG[type];
+  return def?.carries_properties === true;
+}
 
 // src/catalog/legacy-product-stages.ts
 var LEGACY_PRODUCT_STAGES = Object.freeze({
@@ -3546,7 +3566,13 @@ function canBeChildOf(childType, parentType) {
   return getValidChildren(parentType).includes(childType);
 }
 var UPG_CONTAINMENT_FREE_TYPES = /* @__PURE__ */ new Set([
-  "person"
+  "person",
+  // A framework_exercise has no structural parent: it anchors to the entities
+  // it scores via the `framework_exercise_includes_node` edge, not by
+  // containment. Modelling it as a product child would force a containment edge
+  // and read against the whole point of the exercise model (relational, not
+  // hierarchical). Same posture as `person`. See ADR 2026-06-02-framework-exercises.
+  "framework_exercise"
 ]);
 function isContainmentFreeType(entityType) {
   return UPG_CONTAINMENT_FREE_TYPES.has(entityType);
@@ -5848,6 +5874,31 @@ var TEMPLATE_LIFECYCLES = [
   // ── Phase B: SALES_DEAL (qualified → proposal → negotiation → won/lost) ─────
   fromTemplate("deal", SALES_DEAL_TEMPLATE)
 ];
+var FRAMEWORK_EXERCISE_LIFECYCLE = {
+  entity_type: "framework_exercise",
+  initial_phase: "draft",
+  terminal_phases: ["archived"],
+  phases: [
+    {
+      id: "draft",
+      label: "Draft",
+      description: "The exercise has been created and entities pulled into scope, but the framework's inputs have not all been filled in yet.",
+      transitions_to: ["active", "archived"]
+    },
+    {
+      id: "active",
+      label: "Active",
+      description: "The current, authoritative run of its framework. Its include edges carry the live results consumers read, rank, and render by.",
+      transitions_to: ["archived"]
+    },
+    {
+      id: "archived",
+      label: "Archived",
+      description: "A past run, retained for provenance. Still queryable but superseded by a newer exercise and hidden from default views. Can be revived to active.",
+      transitions_to: ["active"]
+    }
+  ]
+};
 var UPG_LIFECYCLES = [
   // Product (root)
   PRODUCT_LIFECYCLE,
@@ -5949,6 +6000,8 @@ var UPG_LIFECYCLES = [
   // Product & Growth
   VARIANT_LIFECYCLE,
   GROWTH_CAMPAIGN_LIFECYCLE,
+  // Workspace
+  FRAMEWORK_EXERCISE_LIFECYCLE,
   // ── Template-generated lifecycles ─────────────────────────────────
   ...TEMPLATE_LIFECYCLES
 ];
@@ -10138,6 +10191,11 @@ var UPG_PROPERTY_SCHEMA = {
     },
     methodology: { type: "string", description: "Forecasting methodology used" }
   },
+  // FrameworkExerciseProperties: Framework exercise: one run of a framework over a set of entities.
+  framework_exercise: {
+    framework_id: { type: "string", description: "Which framework this exercise runs: a framework id (e.g. 'moscow', 'rice-scoring', 'kano-model'). Resolves against the framework catalog." },
+    inputs_snapshot: { type: "object", description: "Optional frozen copy of the framework's input spec at apply time, so a historical exercise still renders correctly if the framework definition later evolves (inputs added, removed, or rescaled)." }
+  },
   // 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" },
@@ -19756,7 +19814,7 @@ var PORTFOLIO_GUIDE = {
 var WORKSPACE_GUIDE = {
   domain_id: "workspace",
   anchor_entity: "workspace",
-  creation_sequence: ["workspace"],
+  creation_sequence: ["workspace", "framework_exercise"],
   patterns: [],
   required_bridges: [],
   anti_patterns: [
@@ -24764,7 +24822,7 @@ var NODE_KEY_ORDER = [
   "sort_order",
   "properties"
 ];
-var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence"];
+var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence", "properties"];
 var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence"];
 var PRODUCT_KEY_ORDER = ["id", "title", "description", "stage", "properties"];
 function canonicalNode(node) {
@@ -24776,7 +24834,8 @@ function canonicalNode(node) {
 }
 function canonicalEdge(edge) {
   return orderedObject(edge, EDGE_KEY_ORDER, {
-    forceKeys: ["id", "source", "target", "type"]
+    forceKeys: ["id", "source", "target", "type"],
+    openKeys: ["properties"]
   });
 }
 function canonicalCrossEdge(edge) {
@@ -24930,7 +24989,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.8.2";
+var UPG_VERSION = "0.8.4";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -25079,6 +25138,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   collectSlugsForType,
   compareVersions,
   computeBodyChecksum,
+  edgeCarriesProperties,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,