@unified-product-graph/core 0.9.4 → 0.9.6

package/CHANGELOG.md

@@ -7,7 +7,34 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
-## [0.9.4] - 2026-06-09
+## [0.9.6] - 2026-06-10
+
+**Canonical shared-entity registry + drift detection (canonical-registry initiative, Phases 2–3).** The core of the registry: a portfolio can now define a shared entity ONCE and have every product's local copy link to it as a canonical instance, with drift surfaced automatically. Decision: `2026-06-10-canonical-shared-entity-registry.md`.
+
+### Added
+- **`instance_of` cross-edge** (9th member of `UPG_CROSS_EDGE_TYPES`): a directed *product entity → canonical (registry) entity* relationship — "this product node is an instance of that shared, authoritative node." Endpoints must share a type (a `persona` instance_of a `persona`); the target is addressed as `registry/{node_id}`. Distinct from the symmetric `shares_*` peer edges and coexists with them (canonical-to-instance vs peer-equivalence; neither deprecates the other). Unlocks rollup ("every Developer instance and its per-surface jobs"), cross-instance diff, and drift detection.
+- **`registry` section on the portfolio document** (`UPGPortfolioDocument.registry`, shape `UPGRegistry`): the shared-vocabulary tier that sits above products. Canonical entities are normal `UPGBaseNode`s (no new type, no flag — canonical-ness is conferred by living in the registry). Optional and additive: portfolios without a registry stay valid and byte-identical; an empty registry is omitted on serialise. `REGISTRY_PRODUCT_ID = 'registry'` is the reserved pseudo product-id used to qualify registry references; product creation rejects it.
+- (SDK) `UPGPortfolioStore` registry accessors: `getRegistry` / `ensureRegistry` / `addRegistryNode` / `getRegistryNode` / `listRegistryNodes(type?)` / `removeRegistryNode`. The canonical serialiser round-trips the registry section (write + normalise).
+- (MCP server) three local registry tools: **`define_canonical_entity`** (create a canonical node in the registry), **`register_instance`** (create an `instance_of` edge from a product node to a canonical, enforcing the same-type constraint and the `registry/` target), and **`list_registry`** (list canonical entities, optionally with their instances). Tool surface 110 → 113. Local-only (portfolio.upg is a workspace concept; no cloud analogue).
+- (MCP server) **registry drift detection in `portfolio_validate`** (Phase 3): flags an `instance_of` edge whose target is missing from the registry, whose endpoints disagree on type, or whose instance title diverges from its canonical (off-canon rename). The payoff of the registry — a renamed-off-canon instance is now *detectable*, not silent.
+
+### Changed
+- `create_cross_product_edge` and `batch_create_cross_product_edges` reject `instance_of`, directing callers to `register_instance` (single enforcement path for the registry's same-type + `registry/` target rules). `list_cross_edge_types` now reports nine types.
+
+### Notes
+- Phase 4 (`primitive` / `standard` type for foundational shared tech) remains deferred pending a coverage pass against existing `dependency` / `capability`; it must not block the registry core. No entity / domain / edge-catalogue count change (cross-edges are a separate union from `UPG_EDGE_CATALOG`).
+
+---
+
+## [0.9.5] - 2026-06-10
+
+**Persona `audience_role` (canonical-registry initiative, Phase 1).** A small, independent property change — the first cut of the canonical shared-entity registry initiative. Decision: `2026-06-10-canonical-shared-entity-registry.md`.
+
+### Added
+- `PersonaProperties.audience_role`: optional enum `'buyer' | 'user' | 'champion' | 'influencer' | 'partner'` — the decision-making-unit (buying-committee) split. A portfolio must separate the economic **buyer** (who signs) from the practitioner **user** (who uses); they are distinct personas with distinct jobs, and flattening them loses the most important B2B distinction. Closed set so roles compare across products. Backward-compatible: optional, existing personas unaffected. No entity / edge / tool count change.
+
+### Notes
+- This unblocks the registry initiative's stopgap migration (each canonical persona gets tagged with `audience_role`). The registry core — an `instance_of` cross-edge + portfolio-tier canonical hosting + drift detection — is designed (Phases 2–4) and sequenced for later cuts.
 
 **Cross-product structure clone + pre-commit preview + target-profile coverage (batch-4, part 2).** No core spec change — one new local MCP tool plus two opt-in parameters. Decision: `2026-06-09-cross-product-structure-clone.md`.
 

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   PRODUCT_DELIVERY_PLAYBOOK: () => PRODUCT_DELIVERY_PLAYBOOK,
   PROPERTY_SCALE_MAP: () => PROPERTY_SCALE_MAP,
   REFLECT_MODES: () => REFLECT_MODES,
+  REGISTRY_PRODUCT_ID: () => REGISTRY_PRODUCT_ID,
   STRATEGY_OUTCOMES_PLAYBOOK: () => STRATEGY_OUTCOMES_PLAYBOOK,
   UPG_ACTIVE_TYPES: () => UPG_ACTIVE_TYPES,
   UPG_ANTI_PATTERNS: () => UPG_ANTI_PATTERNS,
@@ -2968,8 +2969,10 @@ var UPG_CROSS_EDGE_TYPES = [
   "cannibalises",
   "succeeds",
   "hosts",
-  "contributes_to"
+  "contributes_to",
+  "instance_of"
 ];
+var REGISTRY_PRODUCT_ID = "registry";
 
 // src/registry/entity-type-resolution.ts
 var TYPES = getTypes();
@@ -10877,7 +10880,8 @@ var UPG_PROPERTY_SCHEMA = {
     experience_level: { type: "string", enum: ["beginner", "intermediate", "advanced", "varies"], description: "How experienced this persona is in their domain" },
     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"' }
+    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"' }
   },
   // PipelineSalesProperties: Sales pipeline.
   pipeline_sales: {
@@ -26104,7 +26108,16 @@ function portfolioBody(doc) {
     product_areas: [...doc.product_areas ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((a) => orderedObject(a, ["id", "title", "description", "parent_area_id", "strategic_priority", "products"], { forceKeys: ["id", "title"] })),
     portfolios: [...doc.portfolios ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((p) => orderedObject(p, ["id", "title", "description", "parent_portfolio_id", "hierarchy_model", "products"], { forceKeys: ["id", "title"] })),
     products,
-    cross_edges: sortEdges(doc.cross_edges ?? []).map(canonicalCrossEdge)
+    cross_edges: sortEdges(doc.cross_edges ?? []).map(canonicalCrossEdge),
+    // Registry tier (shared vocabulary). Emitted only when non-empty so existing
+    // portfolio files without a registry stay byte-identical. Canonical entities
+    // are normal nodes, serialised with the same node/edge canonical rules.
+    ...doc.registry && doc.registry.nodes.length > 0 ? {
+      registry: {
+        nodes: sortNodes(doc.registry.nodes).map(canonicalNode),
+        ...doc.registry.edges && doc.registry.edges.length > 0 ? { edges: sortEdges(doc.registry.edges).map(canonicalEdge) } : {}
+      }
+    } : {}
   };
 }
 function computeBodyChecksum(doc) {
@@ -26204,6 +26217,13 @@ function normalizeDocument(obj) {
       })),
       cross_edges: raw.cross_edges ?? []
     };
+    const rawRegistry = raw.registry;
+    if (rawRegistry && Array.isArray(rawRegistry.nodes)) {
+      out2.registry = {
+        nodes: rawRegistry.nodes.map((n) => repairNodeDrift(n)),
+        ...Array.isArray(rawRegistry.edges) ? { edges: rawRegistry.edges } : {}
+      };
+    }
     return out2;
   }
   const out = {
@@ -26226,7 +26246,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.4";
+var UPG_VERSION = "0.9.6";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -26306,6 +26326,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   PRODUCT_DELIVERY_PLAYBOOK,
   PROPERTY_SCALE_MAP,
   REFLECT_MODES,
+  REGISTRY_PRODUCT_ID,
   STRATEGY_OUTCOMES_PLAYBOOK,
   UPG_ACTIVE_TYPES,
   UPG_ANTI_PATTERNS,