@unified-product-graph/core 0.9.11 → 0.9.12

package/dist/index.js

@@ -489,6 +489,12 @@ var UPG_DOMAINS = [
     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. 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"]
+  },
+  {
+    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.",
+    types: ["specification", "primitive"]
   }
 ];
 var UPG_ENTITY_TO_DOMAIN = Object.freeze(
@@ -508,6 +514,9 @@ function getDomainIdForType(entityType) {
 
 // src/registry/entity-meta.ts
 var UPG_ENTITY_META = [
+  // Foundations (0.9.12): shared specifications + the primitives they define.
+  { name: "specification", type_id: "ent_352", maturity: "proposed", since: "0.9.12" },
+  { name: "primitive", type_id: "ent_353", maturity: "proposed", since: "0.9.12" },
   // ── Strategic ──
   { name: "product", type_id: "ent_001", maturity: "stable", since: "0.1.0" },
   { name: "outcome", type_id: "ent_002", maturity: "stable", since: "0.1.0" },
@@ -2926,7 +2935,14 @@ var UPG_EDGE_CATALOG = {
   data_quality_rule_governs_data_source: { forward_verb: "governs", reverse_verb: "governed_by", classification: "semantic", source_type: "data_quality_rule", target_type: "data_source" },
   // press_release → launch (marketing → go_to_market). A press release had 0
   // outbound; it could not name the launch it announces.
-  press_release_announces_launch: { forward_verb: "announces", reverse_verb: "announced_by", classification: "cross-domain", source_type: "press_release", target_type: "launch" }
+  press_release_announces_launch: { forward_verb: "announces", reverse_verb: "announced_by", classification: "cross-domain", source_type: "press_release", target_type: "launch" },
+  // ── Foundations (0.9.12): registry-internal relationships between canonical
+  //    specifications and primitives. Product-to-foundation links (implements,
+  //    exposes, conforms_to) are portfolio cross-edges, not catalog edges.
+  specification_extends_specification: { forward_verb: "extends", reverse_verb: "extended_by", classification: "hierarchy", source_type: "specification", target_type: "specification" },
+  specification_competes_with_specification: { forward_verb: "competes_with", reverse_verb: "competes_with", classification: "semantic", source_type: "specification", target_type: "specification" },
+  primitive_defined_by_specification: { forward_verb: "defined_by", reverse_verb: "defines", classification: "semantic", source_type: "primitive", target_type: "specification" },
+  primitive_composes_primitive: { forward_verb: "composes", reverse_verb: "composed_by", classification: "hierarchy", source_type: "primitive", target_type: "primitive" }
 };
 var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Universal semantic verbs
@@ -2993,7 +3009,14 @@ var UPG_CROSS_EDGE_TYPES = [
   "instance_of",
   "area_serves_persona",
   "area_targets_market_segment",
-  "rolls_up_to"
+  "rolls_up_to",
+  "product_implements_specification",
+  "product_exposes_specification",
+  "feature_conforms_to_specification",
+  "api_contract_speaks_specification",
+  "product_exposes_primitive",
+  "feature_manipulates_primitive",
+  "primitive_stored_as_data_type"
 ];
 var REGISTRY_PRODUCT_ID = "registry";
 
@@ -3057,6 +3080,13 @@ function resolveEntityType(rawType) {
 
 // src/grammar/hierarchy.ts
 var UPG_VALID_CHILDREN = {
+  // ── Foundations (0.9.12): registry canonicals that self-nest. A
+  //    specification extends a specification (a dialect of a parent spec); a
+  //    primitive composes primitives (a block contains spans). These back the
+  //    hierarchy-classified specification_extends_specification /
+  //    primitive_composes_primitive catalog edges.
+  specification: ["specification"],
+  primitive: ["primitive"],
   // ── Product (root) ─────────────────────────────────────────────────────────
   product: [
     // Strategy
@@ -5977,9 +6007,42 @@ var FRAMEWORK_EXERCISE_LIFECYCLE = {
     }
   ]
 };
+var SPECIFICATION_LIFECYCLE = {
+  entity_type: "specification",
+  initial_phase: "draft",
+  terminal_phases: ["superseded"],
+  phases: [
+    {
+      id: "draft",
+      label: "Draft",
+      description: "Being authored. Not yet adopted as the canonical specification.",
+      transitions_to: ["active", "superseded"]
+    },
+    {
+      id: "active",
+      label: "Active",
+      description: "In force. The current authoritative version products implement and conform to.",
+      transitions_to: ["deprecated", "superseded"]
+    },
+    {
+      id: "deprecated",
+      label: "Deprecated",
+      description: "Still valid but no longer recommended; a successor exists or is imminent.",
+      transitions_to: ["superseded"]
+    },
+    {
+      id: "superseded",
+      label: "Superseded",
+      description: "Replaced by a newer specification. Retained for historical reference.",
+      transitions_to: []
+    }
+  ]
+};
 var UPG_LIFECYCLES = [
   // Product (root)
   PRODUCT_LIFECYCLE,
+  // Foundations (0.9.12)
+  SPECIFICATION_LIFECYCLE,
   // Discovery & Validation
   RESEARCH_STUDY_LIFECYCLE,
   NEED_LIFECYCLE,
@@ -6087,6 +6150,9 @@ function getLifecycleForType(entityType) {
   return UPG_LIFECYCLES.find((l) => l.entity_type === entityType);
 }
 var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
+  // ── Foundations (1 of 2): a primitive either exists or is deprecated; no
+  //    phase ladder (like metric). `specification` carries a lifecycle. ──
+  "primitive",
   // ── User (5): personas and JTBD atoms are reference data ──────────────────
   "persona",
   "job",
@@ -7158,6 +7224,50 @@ function getDeprecatedTypes() {
   return deprecated;
 }
 var UPG_PROPERTY_MIGRATIONS = {
+  // ── v0.9.12: technical-domain enum widening + data_flow orientation split ──
+  //
+  // Real authoring outgrew four engineering-domain enums. 0.9.12 widens them
+  // (see properties/domains/engineering.ts) and adds a data_flow `orientation`
+  // axis distinct from `direction` (cardinality). These rules dual-read the
+  // legacy values so graphs authored before 0.9.12 stay valid on load:
+  //   - data_flow.direction inbound/outbound/internal -> properties.orientation,
+  //     and direction resets to unidirectional (all three were one-way).
+  //   - integration_pattern.pattern_type "data sync" -> data_sync,
+  //     backend_client -> client_library.
+  //   - service.service_type backend -> api (use the new `cli` for CLI tools).
+  //   - api_contract.protocol HTTP -> REST, HTTP/SSE -> the new SSE value.
+  "0.9.12": [
+    {
+      kind: "remap_property_value",
+      type: "data_flow",
+      property: "direction",
+      value_map: { inbound: "inbound", outbound: "outbound", internal: "internal" },
+      to_property: "orientation",
+      reset_value: "unidirectional",
+      reason: "data_flow.direction conflated cardinality with orientation; the orientation values move to the new `orientation` property and direction resets to `unidirectional` (0.9.12)."
+    },
+    {
+      kind: "remap_property_value",
+      type: "integration_pattern",
+      property: "pattern_type",
+      value_map: { "data sync": "data_sync", backend_client: "client_library" },
+      reason: 'integration_pattern.pattern_type widened in 0.9.12; legacy "data sync" snake-cases to data_sync and backend_client collapses to client_library.'
+    },
+    {
+      kind: "remap_property_value",
+      type: "service",
+      property: "service_type",
+      value_map: { backend: "api" },
+      reason: "service.service_type `backend` is too generic to canonise; normalised to `api` in 0.9.12 (use `cli` for command-line tools)."
+    },
+    {
+      kind: "remap_property_value",
+      type: "api_contract",
+      property: "protocol",
+      value_map: { HTTP: "REST", "HTTP/SSE": "SSE" },
+      reason: "api_contract.protocol normalised in 0.9.12: HTTP maps to REST and HTTP/SSE maps to the new SSE value."
+    }
+  ],
   // ── v0.8.0: UPG-574 deprecated-property removal pass ───────────────────
   //
   // The seven properties tagged `@deprecated since v0.4.0` that survived the
@@ -7651,6 +7761,25 @@ function migrateNodeProperties(node, fromVersion, toVersion) {
           }
           break;
         }
+        case "remap_property_value": {
+          const props = workingNode.properties;
+          if (!props || !(m.property in props)) break;
+          const oldValue = props[m.property];
+          if (typeof oldValue !== "string" || !(oldValue in m.value_map)) break;
+          const mapped = m.value_map[oldValue];
+          const nextProps = { ...props };
+          if (m.to_property) {
+            nextProps[m.to_property] = mapped;
+            nextProps[m.property] = m.reset_value ?? mapped;
+            changes.push({ kind: "remapped_property_value", property: m.property, to_property: m.to_property, value_changed: true });
+          } else {
+            nextProps[m.property] = mapped;
+            changes.push({ kind: "remapped_property_value", property: m.property, value_changed: mapped !== oldValue });
+          }
+          workingNode.properties = nextProps;
+          mutated = true;
+          break;
+        }
       }
     }
   }
@@ -9104,7 +9233,7 @@ var UPG_PROPERTY_SCHEMA = {
   // ApiContractProperties: API contract.
   api_contract: {
     spec_url: { type: "string", description: "URL of the specification document" },
-    protocol: { type: "string", enum: ["REST", "GraphQL", "gRPC", "AsyncAPI", "SOAP", "WebSocket", "MQTT", "other"], description: "Communication protocol" },
+    protocol: { type: "string", enum: ["REST", "GraphQL", "gRPC", "AsyncAPI", "SOAP", "WebSocket", "MQTT", "SSE", "other"], description: "Communication protocol. `SSE` (server-sent events) added in 0.9.12." },
     version: { type: "string", description: "API version" },
     owner: { type: "string", description: "Maintaining person or team." }
   },
@@ -9585,7 +9714,8 @@ var UPG_PROPERTY_SCHEMA = {
   data_flow: {
     trigger: { type: "string", description: "What triggers the flow" },
     data_type: { type: "string", description: "Type of data transferred" },
-    direction: { type: "string", enum: ["unidirectional", "bidirectional"], description: "Direction" },
+    direction: { type: "string", enum: ["unidirectional", "bidirectional"], description: "Direction (cardinality of the link)." },
+    orientation: { type: "string", enum: ["inbound", "outbound", "internal"], description: "Flow orientation relative to the system or component, a separate axis from `direction` (which is cardinality). A flow can be `unidirectional` AND `inbound`. Added in 0.9.12 to split the orientation axis that authors were conflating into `direction` (inbound/outbound/internal values)." },
     protocol: { type: "string", enum: ["rest", "graphql", "grpc", "event", "webhook", "file"], description: "Communication protocol" }
   },
   // DataLineageProperties: DataLineage entity.
@@ -10341,7 +10471,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // IntegrationPatternProperties: Integration pattern between systems.
   integration_pattern: {
-    pattern_type: { type: "string", enum: ["api", "event", "file", "database", "webhook"], description: "Type" },
+    pattern_type: { type: "string", enum: ["api", "event", "file", "database", "webhook", "adapter", "client_library", "host_embedding", "pipes_and_filters", "data_sync"], description: "Type. `adapter`, `client_library`, `host_embedding`, `pipes_and_filters`, `data_sync` added in 0.9.12." },
     protocol: { type: "string", description: "Communication protocol" }
   },
   // InteractionSpecProperties: Interaction specification.
@@ -11046,6 +11176,12 @@ var UPG_PROPERTY_SCHEMA = {
     tier_order: { type: "number", description: "Display ordering (1 = first tier shown)" },
     is_highlighted: { type: "boolean", description: "Highlighted as recommended / most popular" }
   },
+  // PrimitiveProperties: A foundational compositional unit a specification defines: the noun products
+  primitive: {
+    primitive_kind: { type: "string", enum: ["data_type", "object", "block", "unit"], description: "The shape of the thing products pass around." },
+    defined_by: { type: "string", description: "The `specification/<slug>` this primitive comes from; nullable for spec-less internal primitives. Mirrors the `primitive_defined_by_specification` edge for quick lookup." },
+    since: { type: "string", description: "Year or version the primitive was introduced." }
+  },
   // PrivacyPolicyProperties: Privacy policy.
   privacy_policy: {
     version: { type: "string", description: "Version identifier of the policy" },
@@ -11416,7 +11552,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // ServiceProperties: Service or microservice.
   service: {
-    service_type: { type: "string", enum: ["web", "api", "worker", "db", "queue", "library", "mobile", "docs", "lambda"], description: "Functional classification. Expanded from Backstage's component type vocabulary." },
+    service_type: { type: "string", enum: ["web", "api", "worker", "db", "queue", "library", "mobile", "docs", "lambda", "cli"], description: "Functional classification. Expanded from Backstage's component type vocabulary. `cli` added in 0.9.12." },
     tech_stack: { type: "string[]", description: 'Technologies used (e.g. ["TypeScript", "Postgres", "Redis"])' },
     owner: { type: "string", description: "Owning person or team. Backstage marks this required; strongly recommended." },
     lifecycle: { type: "string", enum: ["experimental", "production", "deprecated"], description: 'Service maturity. Answers "how mature is it?". `experimental` = early-stage. `production` = battle-tested. `deprecated` = being phased out.' },
@@ -11538,6 +11674,18 @@ var UPG_PROPERTY_SCHEMA = {
     },
     rice_score: { type: "number", description: "Computed: (reach \xD7 impact \xD7 confidence) / effort. @deprecated 0.9.0:computed by the `rice-scoring` framework on its application edge, not stored on the entity. Removed in 0.9.1." }
   },
+  // SpecificationProperties: A governed specification: a query language, protocol, data format, encoding,
+  specification: {
+    kind: { type: "string", enum: ["language", "protocol", "data_format", "encoding", "interface_contract", "object_model"], description: "What the artifact fundamentally is, independent of how it is governed." },
+    language_flavor: { type: "string", enum: ["query", "programming", "markup", "styling", "schema", "template"], description: "Set only when `kind` is `language`: the kind of language." },
+    governance: { type: "string", enum: ["open_spec_stewarded", "open_standard_consortium", "proprietary_open", "internal_primitive", "de_facto"], description: "How the specification is governed (its ratification status, and whether it counts as a `standard`). `open_standard_consortium` is a formal standard (W3C, IETF, ISO); `de_facto` and `internal_primitive` never became one." },
+    steward: { type: "string", description: "The governing body or organisation (may later become an `organization` ref)." },
+    openness: { type: "string", enum: ["open", "proprietary"], description: "Whether the specification itself is open or proprietary." },
+    spec_url: { type: "string", description: "URL of the published specification." },
+    current_version: { type: "string", description: "Latest published version string." },
+    since: { type: "string", description: "Year or version the specification was introduced." },
+    conformance: { type: "string", description: "How conformance is tested (test suite, certification program). Optional." }
+  },
   // StakeholderProperties: Stakeholder entity.
   stakeholder: {
     stakeholder_type: { type: "string", enum: ["internal", "external", "investor", "regulator"], description: "Relationship of the stakeholder to the organisation" },
@@ -19523,6 +19671,30 @@ var OPERATIONS_QUALITY_PLAYBOOK = {
     )
   ]
 };
+var FOUNDATIONS_PLAYBOOK = {
+  id: "playbook:foundations",
+  name: "Foundations",
+  version: "0.9.12",
+  description: "Register the specifications your products implement and expose, and the primitives those specs define, as canonical entities instead of scattered per-product features.",
+  region: "foundations",
+  is_canonical: true,
+  related_framework_ids: [],
+  target_anchor_entity: "specification",
+  creation_sequence: [
+    seqStep(
+      1,
+      "Specifications",
+      ["specification"],
+      "Define each governed spec your products implement, expose, or conform to (a query language, protocol, or format) as one canonical specification, not a per-product feature."
+    ),
+    seqStep(
+      2,
+      "Primitives",
+      ["primitive"],
+      "Define the compositional units those specs define (a block, a reference, a query value) as primitives, each linked to its specification."
+    )
+  ]
+};
 var UPG_PLAYBOOKS = [
   // Region 1 - strategy_outcomes
   STRATEGY_OUTCOMES_PLAYBOOK,
@@ -19545,7 +19717,9 @@ var UPG_PLAYBOOKS = [
   // Region 9 - analytics_data
   ANALYTICS_DATA_PLAYBOOK,
   // Region 10 - operations_quality
-  OPERATIONS_QUALITY_PLAYBOOK
+  OPERATIONS_QUALITY_PLAYBOOK,
+  // Region 11 - foundations
+  FOUNDATIONS_PLAYBOOK
 ];
 
 // src/step-sequence.ts
@@ -20287,7 +20461,7 @@ var UPG_DOMAIN_RINGS = [
     id: "build",
     label: "Build",
     description: "How do we construct it?",
-    domain_ids: ["engineering", "ai", "automation", "data_analytics", "testing", "devops", "security", "accessibility"]
+    domain_ids: ["engineering", "foundations", "ai", "automation", "data_analytics", "testing", "devops", "security", "accessibility"]
   },
   {
     id: "grow",
@@ -21202,10 +21376,30 @@ var WORKSPACE_GUIDE = {
     { description: "Workspace content is transient by default: promote discoveries to the graph, do not leave them in the workspace" }
   ]
 };
+var FOUNDATIONS_GUIDE = {
+  domain_id: "foundations",
+  anchor_entity: "specification",
+  creation_sequence: ["specification", "primitive"],
+  patterns: [
+    {
+      name: "Specification defines primitives",
+      description: "A specification governs one or more primitives; each primitive is defined_by the spec and may compose other primitives",
+      entity_types: ["specification", "primitive"],
+      edge_chain: ["primitive_defined_by_specification", "primitive_composes_primitive"]
+    }
+  ],
+  required_bridges: [],
+  anti_patterns: [
+    { description: "A specification scattered as duplicate features across products instead of one canonical with instance_of links" },
+    { description: "Modelling a governed spec as a product: it has no single owner, P&L, or buyer; it is the rulebook products point at" }
+  ]
+};
 var UPG_DOMAIN_GUIDES = [
   // Nucleus
   PORTFOLIO_GUIDE,
   WORKSPACE_GUIDE,
+  // Foundations (0.9.12)
+  FOUNDATIONS_GUIDE,
   // Ring 1: Understand
   USER_GUIDE,
   USER_RESEARCH_GUIDE,
@@ -26498,6 +26692,45 @@ var UPG_REGIONS = [
         crosses_into: "users_needs"
       }
     ]
+  },
+  {
+    id: "foundations",
+    label: "Foundations",
+    order: 11,
+    shape: "polymorphic-target",
+    mental_model: "Shared specs and primitives that many products implement, expose, and conform to.",
+    operators: [
+      "platform architect",
+      "standards author",
+      "staff engineer",
+      "API designer"
+    ],
+    composes_atomic_domains: [
+      "foundations"
+    ],
+    entities: [
+      {
+        type: "specification",
+        role: "anchor"
+      },
+      {
+        type: "primitive",
+        role: "container"
+      }
+    ],
+    anchor: {
+      type: "specification",
+      rationale: "The specification is the rulebook many products point at: they implement, expose, and conform to it, and primitives are defined by it. It is the high-inbound canonical of the Foundations region.",
+      outbound_cross_edge_count: 0,
+      inbound_cross_edge_count: 6
+    },
+    intra_edges: [
+      "specification_extends_specification",
+      "specification_competes_with_specification",
+      "primitive_defined_by_specification",
+      "primitive_composes_primitive"
+    ],
+    boundary_edges: []
   }
 ];
 var UPG_REGION_MAP = Object.fromEntries(UPG_REGIONS.map((r) => [r.id, r]));
@@ -27004,7 +27237,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.11";
+var UPG_VERSION = "0.9.12";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -27076,6 +27309,7 @@ export {
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
+  FOUNDATIONS_PLAYBOOK,
   LEGACY_PRODUCT_STAGES,
   MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK,