@unified-product-graph/core 0.9.19 → 0.9.20

package/CHANGELOG.md

@@ -7,6 +7,21 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.20] - 2026-06-11
+
+**The tree-pattern catalogue is now introspectable and drift-guarded.** A pattern can no longer cite an edge the grammar lacks, and clients can read the catalogue instead of reverse-engineering it.
+
+### Added
+- **Two introspection tools** (local + cloud, spec-introspection family, local 121 to 123 / cloud 95 to 97):
+  - **`list_tree_patterns`** returns every `get_tree` pattern as a summary row: id, label, the region it is the tree view of, anchor, fallback anchors, natural depth, gap policy, and slot count. Paired with `list_regions`, coverage becomes a queryable diff.
+  - **`get_tree_pattern(id)`** returns the full declarative record: region, anchor, fallbacks, gap policy, depth, and the child map resolved to concrete edges. Each parent-to-child slot carries the canonical `via` edge and its `kind`, resolved live from the edge catalogue, so a client reads the real wiring rather than reverse-engineering it from behaviour.
+- **Declarative pattern records.** `UPGTreePattern` gains `region` (ties a pattern to its region and that region's `shape`) and `gap_policy` (`required-children-only` or `all-optional`). Helpers `listTreePatternSummaries`, `describeTreePattern`, and `resolveTreePatternEdges` expose the catalogue from core.
+- **A drift-guard test.** Every pattern's every `(parent -> child)` slot must resolve to a canonical edge in the catalogue. A pattern that cites an ungrounded pair fails the build. This makes the whole class of bug structural (it already caught an `aggregate -> read_model` slot in the 0.9.19 architecture sketch that the grammar does not wire).
+
+No entity, domain, region, or edge-count change (entities 315, edges 980); local tools 121 to 123, cloud 95 to 97.
+
+---
+
 ## [0.9.19] - 2026-06-11
 
 **The tree-pattern catalogue covers every tree-shaped region, and `delivery` finally roots at the roadmap.** `get_tree` now offers 11 patterns (was 8), one per hierarchical region.

package/dist/index.cjs

@@ -113,6 +113,7 @@ __export(index_exports, {
   collectSlugsForType: () => collectSlugsForType,
   compareVersions: () => compareVersions,
   computeBodyChecksum: () => computeBodyChecksum,
+  describeTreePattern: () => describeTreePattern,
   edgeCarriesProperties: () => edgeCarriesProperties,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
@@ -180,6 +181,7 @@ __export(index_exports, {
   isSubSequenceStep: () => isSubSequenceStep,
   isUPGDocument: () => isUPGDocument,
   listStatusMigrations: () => listStatusMigrations,
+  listTreePatternSummaries: () => listTreePatternSummaries,
   migrateEdge: () => migrateEdge,
   migrateNode: () => migrateNode,
   migrateNodeProperties: () => migrateNodeProperties,
@@ -193,6 +195,7 @@ __export(index_exports, {
   resolveEntityType: () => resolveEntityType,
   resolveLabel: () => resolveLabel,
   resolveSlugCollision: () => resolveSlugCollision,
+  resolveTreePatternEdges: () => resolveTreePatternEdges,
   ringOrderedDomainIds: () => ringOrderedDomainIds,
   rotateSlug: () => rotateSlug,
   serializeCanonical: () => serializeCanonical,
@@ -19879,6 +19882,8 @@ var UPG_TREE_PATTERNS = [
     label: "Opportunity Solution Tree",
     description: "A desired outcome branching into the opportunities under it, the solutions that address them, and the hypotheses + experiment plans that validate them (Teresa Torres).",
     framework_id: "opportunity-solution-tree",
+    region: "discovery_research_validation",
+    gap_policy: "required-children-only",
     anchor_type: "outcome",
     fallback_anchors: ["desired_outcome", "opportunity"],
     child_map: {
@@ -19895,6 +19900,8 @@ var UPG_TREE_PATTERNS = [
     label: "Objectives and Key Results",
     description: "Strategic themes containing objectives, each measured by its key results and the metric that quantifies them (John Doerr).",
     framework_id: "okr-framework",
+    region: "strategy_outcomes",
+    gap_policy: "required-children-only",
     anchor_type: "strategic_theme",
     fallback_anchors: ["objective"],
     child_map: {
@@ -19908,6 +19915,8 @@ var UPG_TREE_PATTERNS = [
     id: "user",
     label: "User chain",
     description: "A persona and the jobs it pursues, branching into the needs and desired outcomes behind them.",
+    region: "users_needs",
+    gap_policy: "required-children-only",
     anchor_type: "persona",
     fallback_anchors: ["job"],
     child_map: {
@@ -19920,6 +19929,8 @@ var UPG_TREE_PATTERNS = [
     id: "product",
     label: "Product breakdown",
     description: "The product organised into feature areas, then features, and the optional epic + user story tiers beneath them.",
+    region: "product_delivery",
+    gap_policy: "required-children-only",
     anchor_type: "product",
     fallback_anchors: ["feature_area", "feature"],
     child_map: {
@@ -19935,6 +19946,8 @@ var UPG_TREE_PATTERNS = [
     label: "Validation chain",
     description: "A hypothesis through its experiment plan, the experiment (or its runs), and the learning it produced.",
     framework_id: "build-measure-learn",
+    region: "discovery_research_validation",
+    gap_policy: "required-children-only",
     anchor_type: "hypothesis",
     fallback_anchors: ["experiment_plan", "experiment"],
     child_map: {
@@ -19949,6 +19962,8 @@ var UPG_TREE_PATTERNS = [
     id: "strategy",
     label: "Strategy cascade",
     description: "Vision and mission into the strategic themes (bets), the initiatives that pursue them, and the outcomes they drive. Themes are polymorphically parented: they hang off vision, the product, or a strategic pillar, whichever the graph wired.",
+    region: "strategy_outcomes",
+    gap_policy: "required-children-only",
     anchor_type: "vision",
     fallback_anchors: ["product", "strategic_theme"],
     child_map: {
@@ -19965,6 +19980,8 @@ var UPG_TREE_PATTERNS = [
     id: "feature_areas",
     label: "Feature areas",
     description: "Feature areas and the features they contain.",
+    region: "product_delivery",
+    gap_policy: "all-optional",
     anchor_type: "feature_area",
     fallback_anchors: ["feature"],
     child_map: {
@@ -19976,6 +19993,8 @@ var UPG_TREE_PATTERNS = [
     id: "delivery",
     label: "Delivery roadmap",
     description: "How product work is scheduled and shipped: the roadmap and its themes/items, the releases they schedule, the features (and the changelog + bugs) those releases deliver, and the feature areas a theme spans. Optional epic + user story tiers appear on request.",
+    region: "product_delivery",
+    gap_policy: "all-optional",
     anchor_type: "roadmap",
     // Fallback is the product alone: a graph with no roadmap roots at the
     // product (product -> release -> feature), reported as anchor_resolved_from:
@@ -20004,6 +20023,8 @@ var UPG_TREE_PATTERNS = [
     id: "architecture",
     label: "Architecture",
     description: "The engineering platform: services and the API contracts, endpoints, schemas, queues, deployments, and dependencies they own, grouped by bounded context, with domain aggregates and their members. A DAG (a schema or queue shared by several services renders once, then as a reference).",
+    region: "engineering_platform",
+    gap_policy: "all-optional",
     anchor_type: "service",
     fallback_anchors: ["bounded_context"],
     child_map: {
@@ -20027,7 +20048,7 @@ var UPG_TREE_PATTERNS = [
         opt("library_dependency"),
         opt("feature_flag")
       ],
-      aggregate: [opt("domain_entity"), opt("value_object"), opt("command"), opt("read_model"), opt("domain_event")]
+      aggregate: [opt("domain_entity"), opt("value_object"), opt("command"), opt("domain_event")]
     },
     natural_depth: 3
   },
@@ -20035,6 +20056,8 @@ var UPG_TREE_PATTERNS = [
     id: "journey",
     label: "User journey",
     description: "A user journey over time: its phases and steps, the actions within each step, and the screens those steps surface. Falls back to a user_flow when journeys are not yet mapped.",
+    region: "experience_design_brand",
+    gap_policy: "all-optional",
     anchor_type: "user_journey",
     fallback_anchors: ["user_flow"],
     child_map: {
@@ -20050,6 +20073,8 @@ var UPG_TREE_PATTERNS = [
     id: "design_system",
     label: "Design system",
     description: "A design system broken into its components, their nested sub-components (atom to molecule to organism), and the design tokens they consume.",
+    region: "experience_design_brand",
+    gap_policy: "all-optional",
     anchor_type: "design_system",
     fallback_anchors: ["design_component"],
     child_map: {
@@ -20065,6 +20090,43 @@ var UPG_TREE_PATTERNS_BY_ID = Object.fromEntries(
 function getTreePattern(id) {
   return UPG_TREE_PATTERNS_BY_ID[id];
 }
+function resolvePatternEdge(source, target) {
+  for (const [id, def] of Object.entries(UPG_EDGE_CATALOG)) {
+    if (def.source_type === source && def.target_type === target) {
+      return { via: id, kind: def.classification };
+    }
+  }
+  return null;
+}
+function resolveTreePatternEdges(pattern) {
+  const out = [];
+  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 });
+    }
+  }
+  return out;
+}
+function describeTreePattern(id) {
+  const p = getTreePattern(id);
+  if (!p) return void 0;
+  return { ...p, fallback_anchors: [...p.fallback_anchors], edges: resolveTreePatternEdges(p) };
+}
+function listTreePatternSummaries() {
+  return UPG_TREE_PATTERNS.map((p) => ({
+    id: p.id,
+    label: p.label,
+    description: p.description,
+    framework_id: p.framework_id,
+    region: p.region,
+    anchor_type: p.anchor_type,
+    fallback_anchors: [...p.fallback_anchors],
+    natural_depth: p.natural_depth,
+    gap_policy: p.gap_policy,
+    slot_count: Object.values(p.child_map).reduce((n, cs) => n + cs.length, 0)
+  }));
+}
 
 // src/presentation/area-taxonomy.ts
 var UPG_AREA_TAXONOMY = [
@@ -28369,7 +28431,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.19";
+var UPG_VERSION = "0.9.20";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -28527,6 +28589,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   collectSlugsForType,
   compareVersions,
   computeBodyChecksum,
+  describeTreePattern,
   edgeCarriesProperties,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
@@ -28594,6 +28657,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   isSubSequenceStep,
   isUPGDocument,
   listStatusMigrations,
+  listTreePatternSummaries,
   migrateEdge,
   migrateNode,
   migrateNodeProperties,
@@ -28607,6 +28671,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   resolveEntityType,
   resolveLabel,
   resolveSlugCollision,
+  resolveTreePatternEdges,
   ringOrderedDomainIds,
   rotateSlug,
   serializeCanonical,