@unified-product-graph/core 0.9.10 → 0.9.12

package/CHANGELOG.md

@@ -7,12 +7,50 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.9.12] - 2026-06-10
+
+**Foundations: a first-class `specification` and `primitive` entity, plus a technical-domain enum widening.** Two governance moats that product orgs usually mismodel as products or scatter across features now have a home, and four engineering enums that real authoring outgrew are widened.
+
+### Added
+- **`specification` and `primitive` entity types** (entity count 313 to 315) in a new **`foundations`** domain and region. A `specification` is a governed spec a product implements, exposes, or conforms to (a query language, protocol, data format, encoding); a `primitive` is the compositional unit a specification defines (a block, a reference, a query value). Both are registry-hostable canonicals (`define_canonical_entity` accepts them), so a spec scattered across N products becomes one canonical that product instances link to via `instance_of`. `specification` carries a lifecycle (draft, active, deprecated, superseded); `primitive` is lifecycle-free. Both ship at `proposed` maturity, with a canonical playbook and a domain guide.
+- **11 foundations edges.** Four registry-internal catalogue edges: `specification_extends_specification` (a dialect or superset), `specification_competes_with_specification`, `primitive_defined_by_specification`, `primitive_composes_primitive`. Seven portfolio cross-edges from a product-graph entity to a registry canonical (the `instance_of` shape): `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`.
+- **`data_flow.orientation`** (`inbound`, `outbound`, `internal`): a separate axis from `direction` (cardinality), so a flow can be one-way and inbound at once.
+- **A `remap_property_value` migration kind** that remaps a properties-bag enum value in place, optionally splitting it into a sibling property.
+
+### Changed
+- **Four engineering enums widened** to fit real authoring: `service.service_type` gains `cli`; `api_contract.protocol` gains `SSE`; `integration_pattern.pattern_type` gains `adapter`, `client_library`, `host_embedding`, `pipes_and_filters`, `data_sync`.
+
+### Migrations (`UPG_PROPERTY_MIGRATIONS['0.9.12']`, dual-read on load)
+- `data_flow.direction` values `inbound` / `outbound` / `internal` move to the new `orientation` property; `direction` resets to `unidirectional`.
+- `integration_pattern.pattern_type`: `"data sync"` to `data_sync`, `backend_client` to `client_library`.
+- `service.service_type`: `backend` to `api`.
+- `api_contract.protocol`: `HTTP` to `REST`, `HTTP/SSE` to `SSE`.
+
+Edge-catalogue count 975 to 979; region count 10 to 11; domain count 36 to 37. No new tools (119).
+
+---
+
+## [0.9.11] - 2026-06-10
+
+**Tooling DX (batch 6, part 2): status pre-flight + anti-pattern visibility.** Two discoverability fixes from the same real portfolio session, plus a self-trip fix.
+
+### Added
+- **`list_status_values(entity_type)`** (tools 118 to 119, on both the local and cloud servers): the valid `status` values a type can hold, as a focused pre-flight lookup so an author no longer learns the set only from a rejected write. Returns lifecycle phases as `{ status, label, terminal }` plus `initial_status` / `terminal_statuses`, or `lifecycle_free: true` with empty `values`. Sourced from `UPG_LIFECYCLES` (exactly what the write validator checks): the low-token sibling of `get_lifecycle`.
+- **Anti-pattern version tracking.** `UPGCuratedAntiPattern` gains an optional `since` field, and `get_spec_version` now reports `anti_patterns: { total, versioned }`. A consumer can see which validators are newer than the version a graph was authored under, so a spec upgrade no longer silently flips a clean graph invalid with no heads-up.
+
+### Changed
+- **A drafted hypothesis is auto-promoted to `active`** when it gains a `hypothesis_requires_experiment_plan` edge (via `create_edge` / `batch_create_edges`). Pairing a hypothesis with a plan is what activates it; this stops the documented structural-spine recipe (hypotheses paired with plans) from self-tripping the `untested-hypothesis-pile-up` anti-pattern. Best-effort: a promotion failure never fails the edge.
+
+No entity, domain, or edge-catalogue count change (tool count 118 to 119).
+
+---
+
 ## [0.9.10] - 2026-06-10
 
 **Tooling DX + a born-valid product (batch 6, part 1) + a release-test gate.** Polish from a real multi-graph portfolio session: parity and discoverability fixes, one model correction, and — the headline — the release train now runs the unit suites, after they were found to have been silently red across a release.
 
 ### Changed
-- **Product `properties.stage` is canonical.** The stale `UPG_PROPERTY_MIGRATIONS['0.2.13']` lift of a product node's `properties.stage` to top-level `status` is retired: it contradicted the UPG-654/661 convention the whole runtime uses, so a freshly-created product read as `property_drift` against its own validator. A new product is now born valid. Legacy values are still normalised on read by `coerceProductStage`. Decision: `2026-06-10-product-stage-properties-canonical.md`.
+- **Product `properties.stage` is canonical.** The stale `UPG_PROPERTY_MIGRATIONS['0.2.13']` lift of a product node's `properties.stage` to top-level `status` is retired: it contradicted the current convention the whole runtime uses (a product node's lifecycle stage lives in `properties.stage`), so a freshly-created product read as `property_drift` against its own validator. A new product is now born valid. Legacy values are still normalised on read by `coerceProductStage`. Decision: `2026-06-10-product-stage-properties-canonical.md`.
 - **`get_nodes` resolves cross-product ids.** A qualified `{product_id}/{node_id}` (the form `list_registry` / `export_edges` / cross-edges return) now reads that product's graph (read-only for non-active products), so a connective pass fetches node content across the portfolio without a `switch_product` sweep. Results carry a `product_id`.
 - **`create_edge` / `batch_create_edges` accept the `p_` product-header** where the in-graph product node is expected, resolving it to the `type:"product"` node (older graphs carry a distinct `n_…` product node).
 - **`did_you_mean` for a mistyped edge type** now falls back to the closest catalogue key by name (edit distance) when the endpoints don't resolve to a canonical pair — so a typo always gets a concrete suggestion.

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK: () => DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK: () => ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK: () => EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
+  FOUNDATIONS_PLAYBOOK: () => FOUNDATIONS_PLAYBOOK,
   LEGACY_PRODUCT_STAGES: () => LEGACY_PRODUCT_STAGES,
   MARKDOWN_FORMAT_VERSION: () => MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK: () => MARKET_COMPETITIVE_PLAYBOOK,
@@ -683,6 +684,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(
@@ -702,6 +709,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" },
@@ -3120,7 +3130,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
@@ -3187,7 +3204,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";
 
@@ -3251,6 +3275,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
@@ -6171,9 +6202,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,
@@ -6281,6 +6345,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",
@@ -7352,6 +7419,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
@@ -7845,6 +7956,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;
+        }
       }
     }
   }
@@ -9298,7 +9428,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." }
   },
@@ -9779,7 +9909,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.
@@ -10535,7 +10666,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.
@@ -11240,6 +11371,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" },
@@ -11610,7 +11747,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.' },
@@ -11732,6 +11869,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" },
@@ -19717,6 +19866,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,
@@ -19739,7 +19912,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
@@ -20481,7 +20656,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",
@@ -21396,10 +21571,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,
@@ -24093,6 +24288,7 @@ var UPG_ANTI_PATTERNS = [
   // RelationshipCheck (edge presence/absence) and are promoted here.
   {
     id: "insights-without-evidence",
+    since: "0.9.7",
     name: "Insights without evidence",
     description: "The graph has insight entities but none are backed by a primary-evidence link: no observation yields them (`observation_yields_insight`), no survey response evidences them (`survey_response_evidences_insight`), and no quote is attached (`insight_evidenced_by_quote`). An insight with no evidence behind it is an opinion wearing a research label.",
     structured_condition: {
@@ -24136,6 +24332,7 @@ var UPG_ANTI_PATTERNS = [
   },
   {
     id: "feature-requests-without-provenance",
+    since: "0.9.7",
     name: "Feature requests without provenance",
     description: "The graph has feature_request entities but none trace back to a source: no feedback program collects them (`feedback_program_collects_feature_request`), no customer feedback becomes one (`customer_feedback_becomes_feature_request`), and none originate from a behavioural segment (`feature_request_from_behavioral_segment`). A request with no provenance cannot be weighed against who asked or how many.",
     structured_condition: {
@@ -26690,6 +26887,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]));
@@ -27196,7 +27432,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.9.10";
+var UPG_VERSION = "0.9.12";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -27269,6 +27505,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   DISCOVERY_RESEARCH_VALIDATION_PLAYBOOK,
   ENGINEERING_PLATFORM_PLAYBOOK,
   EXPERIENCE_DESIGN_BRAND_PLAYBOOK,
+  FOUNDATIONS_PLAYBOOK,
   LEGACY_PRODUCT_STAGES,
   MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK,