@unified-product-graph/core 0.22.2 → 0.23.1

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-320 entity types across 37 domains. 1039 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+320 entity types across 37 domains. 1042 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -750,7 +750,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.",
+    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 NQL or Structured 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", "operating_lifecycle", "operating_stage"]
   }
 ];
@@ -1684,6 +1684,17 @@ var UPG_EDGE_CATALOG = {
   bug_affects_feature: { forward_verb: "affects", reverse_verb: "affected_by", classification: "cross-domain", source_type: "bug", target_type: "feature" },
   roadmap_item_references_feature: { forward_verb: "references", reverse_verb: "referenced_by", classification: "cross-domain", source_type: "roadmap_item", target_type: "feature" },
   feature_decomposes_into_task: { forward_verb: "decomposes_into", reverse_verb: "implements", classification: "hierarchy", source_type: "feature", target_type: "task" },
+  // Epic-level mirrors of the feature→task / feature→bug hierarchy (feedback
+  // df99026a). A `feature` is the flat planning root, but an `epic` is a body of
+  // work under it, and real imported ticket sets (Linear/Jira) carry bugs and
+  // pure engineering tasks that belong to ONE epic, not the feature as a whole.
+  // Without these, such tickets had to be mislabelled `user_story` (the only
+  // epic child) to keep the epic grouping. These are additive twins of the
+  // feature-level edges (same verbs/classification), so `pickCanonicalEdge` /
+  // `resolveContainmentEdge('epic', 'task'|'bug')` and the adapter import path
+  // resolve them with no further wiring.
+  epic_decomposes_into_task: { forward_verb: "decomposes_into", reverse_verb: "implements", classification: "hierarchy", source_type: "epic", target_type: "task" },
+  epic_affected_by_bug: { forward_verb: "affected_by", reverse_verb: "affects", classification: "hierarchy", source_type: "epic", target_type: "bug" },
   task_has_subtask: { forward_verb: "has_subtask", reverse_verb: "is_subtask_of", classification: "hierarchy", source_type: "task", target_type: "task" },
   // ── Planning cadence (0.20.0) ────────────────────────────────────────────────
   // The cadence axis. E1 self-nests the interval (a program-increment contains
@@ -3460,6 +3471,15 @@ var UPG_EDGE_CATALOG = {
   // by another team's graph within the portfolio (0.17.3 locked predicate).
   objective_depends_on_dependency: { forward_verb: "depends_on", reverse_verb: "dependency_of", classification: "cross-domain", source_type: "objective", target_type: "dependency", cross_product_eligible: true },
   dependency_blocks_objective: { forward_verb: "blocks", reverse_verb: "blocked_by", classification: "cross-domain", source_type: "dependency", target_type: "objective", cross_product_eligible: true },
+  // The RESOLVING side, distinct from the two blocking edges above.
+  // `dependency_blocks_objective` names an objective the dependency holds up (the
+  // waiting side); this names the objective whose completion CLEARS the
+  // dependency (the providing side). In a portfolio, a dependency in one
+  // product's graph points at the objective in another product's graph that
+  // delivers the awaited work, instead of recording it only in the free-text
+  // `resolution` property. cross_product_eligible — the resolving objective
+  // lives in another product's graph.
+  dependency_resolved_by_objective: { forward_verb: "resolved_by", reverse_verb: "resolves", classification: "cross-domain", source_type: "dependency", target_type: "objective", cross_product_eligible: true },
   // objective / initiative → strategic_question. A planning doc's "Risks & Open
   // Questions" section names unresolved coordination questions the plan is
   // exposed to (who owns a capability across teams after a reorg). The
@@ -3987,7 +4007,10 @@ var UPG_VALID_CHILDREN = {
   // task_implements_user_story edge.
   feature: ["epic", "bug", "task"],
   feature_area: ["feature", "feature_area"],
-  epic: ["user_story"],
+  // epic owns user_story (the templated promise) and, mirroring feature, may
+  // also directly contain bug/task — heterogeneous imported tickets that belong
+  // to one epic rather than the feature as a whole (feedback df99026a).
+  epic: ["user_story", "bug", "task"],
   user_story: ["acceptance_criterion"],
   task: ["task"],
   // planning_cycle (0.20.0): the cadence axis self-nests (a program-increment
@@ -10717,9 +10740,9 @@ var UPG_PROPERTY_SCHEMA = {
   // ClassificationValueProperties: ClassificationValue: a value on a classification axis.
   classification_value: {
     rationale: { type: "string", description: "Short paragraph: why this value earns its own row/column. Longer narrative belongs in `summary_md` or attached `content_piece` nodes." },
-    exemplars: { type: "string[]", description: "Free-text examples of products occupying this value. For queryable occupancy, prefer `competitor` nodes with `classified_as` edges. @example ['Sanity', 'Contentful', 'Hygraph']" },
+    exemplars: { type: "string[]", description: "Free-text examples of products occupying this value. For queryable occupancy, prefer `competitor` nodes with `classified_as` edges. @example ['Nimbus', 'Larch', 'Prism']" },
     commitments: { type: "object[]", description: "The N (typically 2\u20134) load-bearing commitments that define this category. Each commitment is a structural axis; removing it changes the category. Pairs with `capabilities`: commitments are the *load-bearing definition*; capabilities are the *surface offering*. @example [ { name: 'Typed content graph', description: 'Schemas in code; references as edges; content is structured data.' }, { name: 'Real-time backend', description: 'Live queries, CRDT collaboration, sub-second propagation.' }, { name: 'Embeddable studio', description: 'Editor is a library hosted inside the team app, not an external portal.' }, ]" },
-    capabilities: { type: "object[]", description: "Structured capability bullets across the six canonical surfaces. Each surface appears at most once per `classification_value`. Pairs with `commitments`: capabilities describe what the category *offers*; commitments describe what *defines* it. @example [ { surface: 'delivery', bullets: ['GROQ', 'GraphQL', 'REST', 'Live Content API', 'Asset CDN'] }, { surface: 'extensibility', bullets: ['Custom input components', 'Studio plugins'] }, ]" }
+    capabilities: { type: "object[]", description: "Structured capability bullets across the six canonical surfaces. Each surface appears at most once per `classification_value`. Pairs with `commitments`: capabilities describe what the category *offers*; commitments describe what *defines* it. @example [ { surface: 'delivery', bullets: ['NQL', 'GraphQL', 'REST', 'Live Sync API', 'Asset CDN'] }, { surface: 'extensibility', bullets: ['Custom input components', 'editor plugins'] }, ]" }
   },
   // CodeRepositoryProperties: Code repository.
   code_repository: {
@@ -10754,9 +10777,9 @@ var UPG_PROPERTY_SCHEMA = {
     analysis_type: { type: "string", enum: ["feature_comparison", "positioning", "swot", "pricing"], description: "Type of analysis. `feature_comparison` = side-by-side matrix. `positioning` = competitor positioning relative to each other. `swot` = strengths, weaknesses, opportunities, threats. `pricing` = pricing structure comparison." },
     analysis_date: { type: "string", description: 'ISO date conducted. Competitive intelligence decays quickly; track snapshot age. @example "2026-03-15"' },
     framework_id: { type: "string", description: 'Framework ID (references `UPGFramework.id`). @example "porter-five-forces", "swot-analysis", "competitive-matrix"' },
-    empty_cells: { type: "object[]", description: "Empty cells in a 2-axis classification matrix that earn explicit commentary. Only the strategically interesting cells. Opportunity-kind cells are the most valuable; they identify unoccupied strategic space. Each entry references two `classification_value` nodes by id (one from each `classification_axis` child of this `competitive_analysis`). `validate_graph` enforces that the refs resolve to `classification_value` nodes whose parents are distinct `classification_axis` instances. See `ClassificationValueProperties.commitments` for the inverse \"occupied cell\" structural-definition shape. @example [ { axis_a_value_ref: 'val-git-based', axis_b_value_ref: 'val-portable-text', rationale_kind: 'opportunity', rationale_md: 'No technical reason; only adoption inertia. Watching brief.' }, { axis_a_value_ref: 'val-composable', axis_b_value_ref: 'val-wysiwyg', rationale_kind: 'structural', rationale_md: 'Composable rejects HTML blobs; WYSIWYG requires them.' }, ]" },
+    empty_cells: { type: "object[]", description: "Empty cells in a 2-axis classification matrix that earn explicit commentary. Only the strategically interesting cells. Opportunity-kind cells are the most valuable; they identify unoccupied strategic space. Each entry references two `classification_value` nodes by id (one from each `classification_axis` child of this `competitive_analysis`). `validate_graph` enforces that the refs resolve to `classification_value` nodes whose parents are distinct `classification_axis` instances. See `ClassificationValueProperties.commitments` for the inverse \"occupied cell\" structural-definition shape. @example [ { axis_a_value_ref: 'val-git-based', axis_b_value_ref: 'val-structured-text', rationale_kind: 'opportunity', rationale_md: 'No technical reason; only adoption inertia. Watching brief.' }, { axis_a_value_ref: 'val-composable', axis_b_value_ref: 'val-wysiwyg', rationale_kind: 'structural', rationale_md: 'Composable rejects HTML blobs; WYSIWYG requires them.' }, ]" },
     last_updated: { type: "string", description: 'Provenance: ISO date-time this record was last observed or refreshed. Distinct from `analysis_date` (when the analysis was conducted). @example "2026-06-13"' },
-    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://www.contentful.com/changelog/"' },
+    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://docs.larch.example/changelog/"' },
     confidence: {
       type: "assessment",
       scale_id: "confidence_5",
@@ -10784,7 +10807,7 @@ var UPG_PROPERTY_SCHEMA = {
     strengths: { type: "string[]", description: "Bulleted factual strengths. Each item is a short statement, not prose. @example ['Real-time multiplayer canvas', 'Generous free tier']" },
     weaknesses: { type: "string[]", description: "Bulleted factual weaknesses: gaps, friction, or capabilities materially below market. @example ['Weak API query capabilities', 'No mobile companion']" },
     last_updated: { type: "string", description: 'Provenance: ISO date-time this record was last observed or refreshed. Lets a stale record be told apart from a fresh one. @example "2026-06-13"' },
-    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://www.contentful.com/pricing/"' },
+    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://docs.larch.example/pricing/"' },
     confidence: {
       type: "assessment",
       scale_id: "confidence_5",
@@ -10806,7 +10829,7 @@ var UPG_PROPERTY_SCHEMA = {
     quality: { type: "string", enum: ["better", "same", "worse", "missing"], description: "Quality comparison. `better` = ours is meaningfully superior. `same` = roughly equivalent. `worse` = theirs is meaningfully superior. `missing` = we have no equivalent." },
     parity_status: { type: "string", enum: ["ahead", "behind", "parity", "unique_to_us", "unique_to_them"], description: "Parity. More granular than `quality`; captures whether the gap is offensive or defensive. `ahead` = we lead. `behind` = they lead. `parity` = equivalent. `unique_to_us` / `unique_to_them` = only one side offers it." },
     last_updated: { type: "string", description: 'ISO date this assessment was last updated. Competitor feature landscapes change quickly. @example "2026-02-15"' },
-    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://www.contentful.com/changelog/"' },
+    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://docs.larch.example/changelog/"' },
     confidence: {
       type: "assessment",
       scale_id: "confidence_5",
@@ -10832,7 +10855,7 @@ var UPG_PROPERTY_SCHEMA = {
     from_value: { type: "string", description: "Reclassification only. The prior `classification_value` id the competitor was classified as before this move (the superseded cell). Absent for a first-time classification (nothing was superseded)." },
     to_value: { type: "string", description: "Reclassification only. The new `classification_value` id the competitor is classified as after this move (the cell the new classify edge points at)." },
     last_updated: { type: "string", description: 'Provenance: ISO date-time this record was last observed or refreshed. @example "2026-06-13"' },
-    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://www.contentful.com/changelog/"' },
+    source: { type: "string", description: 'Provenance: where this was observed. A changelog, pricing, or docs URL, an analyst report, or a research note. @example "https://docs.larch.example/changelog/"' },
     confidence: {
       type: "assessment",
       scale_id: "confidence_5",
@@ -10972,7 +10995,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // DashboardProperties: Dashboard entity.
   dashboard: {
-    tool: { type: "string", enum: ["looker", "amplitude", "mixpanel", "posthog", "custom"], description: "Analytics tool hosting this dashboard" },
+    tool: { type: "string", enum: ["looker", "amplitude", "mixpanel", "posthog", "omni", "custom"], description: "Analytics tool hosting this dashboard" },
     url: { type: "string", description: "URL to the live dashboard", modifier: "volatile" },
     audience: { type: "string", description: "Intended audience for this dashboard" },
     element_count: { type: "number", description: "Number of widgets or panels on the dashboard", modifier: "derived" },
@@ -12263,7 +12286,7 @@ var UPG_PROPERTY_SCHEMA = {
   // OperatingLifecycleProperties: An operating_lifecycle: a canonical, ordered (often cyclic) operating process
   operating_lifecycle: {
     cyclic: { type: "boolean", description: "True if the process loops (e.g. Analyze \u2192 Extend \u2192 Plan). The sequence is fully expressed by the stages' `stage_order`; `cyclic` adds the wrap from the last stage back to the first." },
-    source: { type: "string", description: 'Origin of the canonical model (e.g. "Sanity official content-ops lifecycle"). Optional provenance; promote to an edge if it names a real `specification`/`document`.' }
+    source: { type: "string", description: 'Origin of the canonical model (e.g. "a published content-ops lifecycle"). Optional provenance; promote to an edge if it names a real `specification`/`document`.' }
   },
   // OperatingStageProperties: An operating_stage: one ordered stage of an `operating_lifecycle`. A product's
   operating_stage: {
@@ -23131,6 +23154,12 @@ var PRODUCT_SPEC_GUIDE = {
       entity_types: ["feature_area", "feature", "epic", "user_story", "task"],
       edge_chain: ["feature_area_contains_feature", "feature_decomposed_into_epic", "epic_specified_by_user_story", "task_implements_user_story"]
     },
+    {
+      name: "Epic Work Items",
+      description: "A bug or a pure engineering/infra task that belongs to one specific epic (not the feature as a whole) attaches directly to that epic, mirroring how task and bug attach at the feature level. Use this when importing a real tracker (Linear/Jira) whose tickets are heterogeneous: keep genuine stories as user_story, but let bugs, spikes, and engineering tasks nest under their epic with their true type instead of being mislabelled to preserve the grouping.",
+      entity_types: ["epic", "task", "bug"],
+      edge_chain: ["epic_decomposes_into_task", "epic_affected_by_bug"]
+    },
     {
       name: "Planning Cadence",
       description: "The cadence axis. Create a planning_cycle (a sprint, iteration, quarter, or PI), nest finer cycles inside a coarse one, schedule the stories that flow through it, and scope the objectives the cycle serves. Scheduling and scoping are deliberate links, not containment: a story keeps its feature/epic parent.",
@@ -29947,7 +29976,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.22.2";
+var UPG_VERSION = "0.23.1";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();