@unified-product-graph/core 0.29.0 → 0.30.0

package/dist/index.cjs

@@ -30,11 +30,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ACTIVE_WHEN_PROPERTY: () => ACTIVE_WHEN_PROPERTY,
   ANALYTICS_DATA_PLAYBOOK: () => ANALYTICS_DATA_PLAYBOOK,
   BUSINESS_GROWTH_METRIC_DRIVEN_PLAYBOOK: () => BUSINESS_GROWTH_METRIC_DRIVEN_PLAYBOOK,
   BUSINESS_GTM_GROWTH_PLAYBOOK: () => BUSINESS_GTM_GROWTH_PLAYBOOK,
   BUSINESS_MARKETING_AUDIENCE_FIRST_PLAYBOOK: () => BUSINESS_MARKETING_AUDIENCE_FIRST_PLAYBOOK,
   CLASSIFICATION_EDGE_PROPERTY_SCHEMA: () => CLASSIFICATION_EDGE_PROPERTY_SCHEMA,
+  CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA: () => CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA,
+  CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA: () => CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA,
   CONTENT_DEPTH_WARNING_RULES: () => CONTENT_DEPTH_WARNING_RULES,
   COVERAGE_ANTI_PATTERNS: () => COVERAGE_ANTI_PATTERNS,
   DEFAULT_ENTITY_EMOJI: () => DEFAULT_ENTITY_EMOJI,
@@ -49,10 +52,12 @@ __export(index_exports, {
   MARKDOWN_FORMAT_VERSION: () => MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK: () => MARKET_COMPETITIVE_PLAYBOOK,
   OPERATIONS_QUALITY_PLAYBOOK: () => OPERATIONS_QUALITY_PLAYBOOK,
+  PRESENT_UNDER_PROPERTY: () => PRESENT_UNDER_PROPERTY,
   PRODUCT_DELIVERY_PLAYBOOK: () => PRODUCT_DELIVERY_PLAYBOOK,
   PROPERTY_MODIFIERS: () => PROPERTY_MODIFIERS,
   PROPERTY_MODIFIER_SEMANTICS: () => PROPERTY_MODIFIER_SEMANTICS,
   PROPERTY_SCALE_MAP: () => PROPERTY_SCALE_MAP,
+  QUALIFIABLE_EDGE_TYPES: () => QUALIFIABLE_EDGE_TYPES,
   RECORD_ENTITY_TYPES: () => RECORD_ENTITY_TYPES,
   REFLECT_MODES: () => REFLECT_MODES,
   REGISTRY_PRODUCT_ID: () => REGISTRY_PRODUCT_ID,
@@ -135,9 +140,11 @@ __export(index_exports, {
   UPG_WILDCARD_ENDPOINT: () => UPG_WILDCARD_ENDPOINT,
   USERS_NEEDS_PLAYBOOK: () => USERS_NEEDS_PLAYBOOK,
   UnknownEntityTypeError: () => UnknownEntityTypeError,
+  VARIES_BY_EDGE: () => VARIES_BY_EDGE,
   backfillSlug: () => backfillSlug,
   buildTypeAliases: () => buildTypeAliases,
   canBeChildOf: () => canBeChildOf,
+  checkConfigurationDrift: () => checkConfigurationDrift,
   checkHeaderSeal: () => checkHeaderSeal,
   checkHeaderSealText: () => checkHeaderSealText,
   checkToEdgeCountSpec: () => checkToEdgeCountSpec,
@@ -158,6 +165,7 @@ __export(index_exports, {
   edgeCarriesProperties: () => edgeCarriesProperties,
   edgeCountSpecKey: () => edgeCountSpecKey,
   entityFilterKey: () => entityFilterKey,
+  enumerateProjections: () => enumerateProjections,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
   formatUpgText: () => formatUpgText,
@@ -249,6 +257,9 @@ __export(index_exports, {
   parseUpg: () => parseUpg,
   pickCanonicalEdge: () => pickCanonicalEdge,
   presenceExceptKey: () => presenceExceptKey,
+  projectGraph: () => projectGraph,
+  readActiveWhen: () => readActiveWhen,
+  readStringArray: () => readStringArray,
   resolveAllEdges: () => resolveAllEdges,
   resolveContainmentEdge: () => resolveContainmentEdge,
   resolveEntityType: () => resolveEntityType,
@@ -375,7 +386,8 @@ var UPG_DOMAINS = [
       "roadmap_item",
       "roadmap_theme",
       "changelog",
-      "planning_cycle"
+      "planning_cycle",
+      "configuration_axis"
     ]
   },
   {
@@ -915,6 +927,7 @@ var UPG_ENTITY_META = [
   // it, carrying its occupants and the rule that arbitrates between them.
   // Enters `proposed` per the maturity rubric (precedent: planning_cycle 0.20.0).
   { name: "surface", type_id: "ent_359", maturity: "proposed", since: "0.27.0" },
+  { name: "configuration_axis", type_id: "ent_360", maturity: "proposed", since: "0.30.0" },
   { name: "journey_phase", type_id: "ent_330", maturity: "proposed", since: "0.2.0" },
   { name: "journey_action", type_id: "ent_331", maturity: "proposed", since: "0.2.0" },
   { name: "design_decision", type_id: "ent_319", maturity: "deprecated", since: "0.2.0", deprecated_in: "0.2.0", replacement: "decision" },
@@ -1316,6 +1329,29 @@ var DEFER_EDGE_PROPERTY_SCHEMA = {
     description: 'Target period the parked work is deferred to. Freeform, mirroring strategic_theme.time_horizon. @example "Q4 2026", "FY27", "next release".'
   }
 };
+var CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA = {
+  present_under: {
+    type: "string[]",
+    description: 'Values of the axis under which this surface exists. Every entry must name a member of the axis\'s closed `values` list, and an empty list is a modelling error rather than a way to say "never" (a surface that exists under no configuration should be deleted, not declared). Omitting the edge entirely is how a surface says it is present in every configuration. @example ["legacy_nav"]'
+  }
+};
+var CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA = {
+  active_when: {
+    type: "object",
+    description: 'Configuration condition under which this relationship holds. The edge is present in a projection that sets `axis` to one of `values`, and absent otherwise. Omit the key entirely for an invariant relationship: absence means "always", never "unknown".',
+    properties: {
+      axis: {
+        type: "string",
+        description: "Node id of the `configuration_axis` this condition reads."
+      },
+      values: {
+        type: "string[]",
+        description: "Values of that axis under which the relationship holds. Every entry must be a member of the axis's closed `values` list."
+      }
+    },
+    required: ["axis", "values"]
+  }
+};
 var UPG_EDGE_CATALOG = {
   // ── Part 1: Core Narrative Spine (Ring 1) ──────────────────────────────────
   // 1.1 User Domain
@@ -1842,7 +1878,7 @@ var UPG_EDGE_CATALOG = {
   //                     portfolio_shared, so the reading it names commonly lives in the
   //                     registry rather than in the product graph.
   //   supersedes      → semantic (prompt_version_supersedes_prompt_version).
-  surface_contains_surface: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "surface", target_type: "surface" },
+  surface_contains_surface: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "surface", target_type: "surface", carries_properties: true, property_schema: CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA },
   surface_serves_job: { forward_verb: "serves", reverse_verb: "served_by", classification: "cross-domain", source_type: "surface", target_type: "job" },
   surface_governed_by_design_guideline: { forward_verb: "governed_by", reverse_verb: "governs", classification: "cross-domain", source_type: "surface", target_type: "design_guideline", cross_product_eligible: true },
   surface_renders_design_component: { forward_verb: "renders", reverse_verb: "rendered_on", classification: "hierarchy", source_type: "surface", target_type: "design_component", cross_product_eligible: true },
@@ -1877,11 +1913,53 @@ var UPG_EDGE_CATALOG = {
   //   not cross_product_eligible → a deviation is a fact about one product's
   //     code, and `surface` is not portfolio_shared in the first place.
   surface_deviates_via_technical_debt_item: { forward_verb: "deviates_via", reverse_verb: "causes_deviation_in", classification: "cross-domain", source_type: "surface", target_type: "technical_debt_item" },
+  // ── surface, 0.30.0: composition that varies by configuration ───────────────
+  // A product's surface tree is not one tree; it is a family of trees selected
+  // by a configuration lever. The stored graph is the UNION of that family and
+  // a single configuration is a PROJECTION of it, so these two edges are how a
+  // graph says which member a fact belongs to. Silence still means "every
+  // member", which is why a graph written before 0.30.0 needs no migration.
+  //
+  //   varies_by   — CONDITIONAL EXISTENCE. The surface exists only under the
+  //                 values in `present_under`. An edge qualifier cannot say
+  //                 this: the reported case was a set of named chips REPLACED
+  //                 by one generic badge, where which surface EXISTS changes,
+  //                 and the two carry different capacities and occupants.
+  //   alternates  — "one of these, depending" as distinct from "both,
+  //                 together". Semantic, matching its sibling
+  //                 `surface_supersedes_surface`: neither surface owns the
+  //                 other, and a hierarchy classification would demand a
+  //                 UPG_VALID_CHILDREN pair that would be false. Explicit and
+  //                 validator-checked (same axis, disjoint present_under);
+  //                 never auto-derived, because disjointness is necessary for
+  //                 alternation and nowhere near sufficient.
+  //
+  // Direction on `alternates_with` is a CONVENTION, not an enforcement: declare
+  // it once, sourced from the surface present under the axis's `default_value`.
+  // An axis with no default is legal modelling, so a check keyed on the
+  // convention would fire on a correct graph, which is the one thing a check
+  // must never do.
+  // ── configuration_axis, 0.30.0: the lever itself ───────────────────────────
+  // Three layers, three owners, and keeping them apart is what makes the model
+  // honest: `engineering` owns the MECHANISM (`feature_flag`, with its key and
+  // rollout percentage), `product_spec` owns the LEVER (the named dimension
+  // along which what-you-ship differs), `ux_design` owns the PLACE (`surface`).
+  // Two code flags that move together are ONE lever with two values.
+  //
+  // `defines` is hierarchy so the axis has a home in `get_tree`. It earns the
+  // UPG_VALID_CHILDREN.product pair (guardrail G2b) on an honest verb: an axis
+  // exists only within the product whose composition it varies. The rejected
+  // alternative mirrors `classification_axis_owned_by_product`, a cross-domain
+  // ownership edge that leaves the node unparented and invisible in every tree.
+  product_defines_configuration_axis: { forward_verb: "defines", reverse_verb: "defined_by", classification: "hierarchy", source_type: "product", target_type: "configuration_axis" },
+  feature_flag_drives_configuration_axis: { forward_verb: "drives", reverse_verb: "driven_by", classification: "cross-domain", source_type: "feature_flag", target_type: "configuration_axis" },
+  surface_varies_by_configuration_axis: { forward_verb: "varies_by", reverse_verb: "varies", classification: "cross-domain", source_type: "surface", target_type: "configuration_axis", carries_properties: true, property_schema: CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA },
+  surface_alternates_with_surface: { forward_verb: "alternates_with", reverse_verb: "alternates_with", classification: "semantic", source_type: "surface", target_type: "surface" },
   // Inbound. `feature_occupies_surface` is the guest list: the edge that makes
   // "what else lives here?" answerable, and the one the contention anti-pattern
   // counts. cross-domain (product_spec → ux_design), like screen_surfaces_feature
   // running the other way.
-  feature_occupies_surface: { forward_verb: "occupies", reverse_verb: "occupied_by", classification: "cross-domain", source_type: "feature", target_type: "surface" },
+  feature_occupies_surface: { forward_verb: "occupies", reverse_verb: "occupied_by", classification: "cross-domain", source_type: "feature", target_type: "surface", carries_properties: true, property_schema: CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA },
   screen_renders_surface: { forward_verb: "renders", reverse_verb: "rendered_by", classification: "hierarchy", source_type: "screen", target_type: "surface" },
   decision_affects_surface: { forward_verb: "affects", reverse_verb: "affected_by", classification: "cross-domain", source_type: "decision", target_type: "surface" },
   // The finer-grained sibling of journey_step_shown_on_screen: a step happens on
@@ -3947,6 +4025,10 @@ var UPG_VALID_CHILDREN = {
     "roadmap",
     "roadmap_theme",
     "planning_cycle",
+    // Configuration (0.30.0): the levers whose values select which surface tree
+    // the product renders. Few per product, and top-level because an axis is a
+    // product-wide fact rather than a child of any one feature or surface.
+    "configuration_axis",
     // Engineering
     "bounded_context",
     "code_repository",
@@ -4570,6 +4652,289 @@ function isContainmentFreeType(entityType) {
   return UPG_CONTAINMENT_FREE_TYPES.has(entityType);
 }
 
+// src/grammar/projection.ts
+var VARIES_BY_EDGE = "surface_varies_by_configuration_axis";
+var PRESENT_UNDER_PROPERTY = "present_under";
+var ACTIVE_WHEN_PROPERTY = "active_when";
+var QUALIFIABLE_EDGE_TYPES = [
+  "surface_contains_surface",
+  "feature_occupies_surface"
+];
+function readStringArray(properties, key) {
+  const raw = properties?.[key];
+  if (!Array.isArray(raw)) return void 0;
+  return raw.filter((v) => typeof v === "string");
+}
+function readActiveWhen(edge) {
+  const raw = edge.properties?.[ACTIVE_WHEN_PROPERTY];
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const axis = raw.axis;
+  const values = readStringArray(raw, "values");
+  if (typeof axis !== "string" || axis.length === 0 || !values || values.length === 0) {
+    return void 0;
+  }
+  return { axis, values };
+}
+function projectGraph(nodes, edges, configuration) {
+  const axes = Object.keys(configuration);
+  if (axes.length === 0) {
+    return {
+      nodes: [...nodes],
+      edges: [...edges],
+      excluded_node_ids: [],
+      deactivated_edge_count: 0,
+      dangling_edge_count: 0
+    };
+  }
+  const excluded = /* @__PURE__ */ new Set();
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const chosen = configuration[edge.target];
+    if (chosen === void 0) continue;
+    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
+    if (!presentUnder) continue;
+    if (!presentUnder.includes(chosen)) excluded.add(edge.source);
+  }
+  const survivingNodes = excluded.size === 0 ? [...nodes] : nodes.filter((n) => !excluded.has(n.id));
+  let deactivated = 0;
+  let dangling = 0;
+  const survivingEdges = [];
+  for (const edge of edges) {
+    const qualifier = readActiveWhen(edge);
+    if (qualifier) {
+      const chosen = configuration[qualifier.axis];
+      if (chosen !== void 0 && !qualifier.values.includes(chosen)) {
+        deactivated++;
+        continue;
+      }
+    }
+    if (excluded.has(edge.source) || excluded.has(edge.target)) {
+      dangling++;
+      continue;
+    }
+    survivingEdges.push(edge);
+  }
+  return {
+    nodes: survivingNodes,
+    edges: survivingEdges,
+    excluded_node_ids: [...excluded].sort(),
+    deactivated_edge_count: deactivated,
+    dangling_edge_count: dangling
+  };
+}
+function enumerateProjections(nodes) {
+  const out = [
+    { configuration: {} }
+  ];
+  for (const node of nodes) {
+    if (node.type !== "configuration_axis") continue;
+    const values = readStringArray(node.properties, "values");
+    if (!values) continue;
+    for (const value of values) {
+      out.push({ axis: node.id, value, configuration: { [node.id]: value } });
+    }
+  }
+  return out;
+}
+
+// src/grammar/configuration-drift.ts
+var ALTERNATES_EDGE = "surface_alternates_with_surface";
+var PARENT_EDGE_TYPES = /* @__PURE__ */ new Set(["surface_contains_surface", "screen_renders_surface"]);
+function edgeLabel(edge) {
+  return edge.id ?? `${edge.source} -> ${edge.target}`;
+}
+function checkConfigurationDrift(nodes, edges) {
+  const findings = [];
+  const axisValues = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    if (node.type !== "configuration_axis") continue;
+    const values = readStringArray(node.properties, "values");
+    if (!values || values.length === 0) {
+      findings.push({
+        kind: "axis_values_empty",
+        severity: "error",
+        node_id: node.id,
+        axis_id: node.id,
+        message: "Configuration axis declares no values. An axis with no values selects nothing, so no projection can be taken along it."
+      });
+      axisValues.set(node.id, []);
+      continue;
+    }
+    axisValues.set(node.id, values);
+    const rawDefault = node.properties?.default_value;
+    if (typeof rawDefault === "string" && rawDefault.length > 0 && !values.includes(rawDefault)) {
+      findings.push({
+        kind: "axis_default_not_a_value",
+        severity: "error",
+        node_id: node.id,
+        axis_id: node.id,
+        message: `default_value "${rawDefault}" is not one of the axis values [${values.join(", ")}]. It names a value of this axis, so it has to be one the axis declares.`
+      });
+    }
+  }
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const values = axisValues.get(edge.target);
+    const presentUnder = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY);
+    if (!presentUnder || presentUnder.length === 0) {
+      findings.push({
+        kind: "present_under_empty",
+        severity: "error",
+        edge_id: edge.id,
+        node_id: edge.source,
+        axis_id: edge.target,
+        message: `${edgeLabel(edge)} declares variance without a non-empty present_under. A surface that exists under no configuration should be deleted rather than declared; a surface that exists under all of them should carry no varies_by edge at all.`
+      });
+      continue;
+    }
+    if (!values) continue;
+    for (const value of presentUnder) {
+      if (!values.includes(value)) {
+        findings.push({
+          kind: "present_under_unknown_value",
+          severity: "error",
+          edge_id: edge.id,
+          node_id: edge.source,
+          axis_id: edge.target,
+          message: `present_under names "${value}", which the axis does not declare. Its values are [${values.join(", ")}].`
+        });
+      }
+    }
+  }
+  for (const edge of edges) {
+    const hasQualifierKey = edge.properties !== void 0 && Object.prototype.hasOwnProperty.call(edge.properties, ACTIVE_WHEN_PROPERTY);
+    if (!hasQualifierKey) continue;
+    if (edge.type !== void 0 && !QUALIFIABLE_EDGE_TYPES.includes(edge.type)) {
+      findings.push({
+        kind: "qualifier_on_illegal_edge",
+        severity: "error",
+        edge_id: edge.id,
+        message: `active_when is not legal on ${edge.type}. The qualifier is scoped to [${QUALIFIABLE_EDGE_TYPES.join(", ")}] deliberately: conditional composition is the question this release answers, and a general modality system is not.`
+      });
+      continue;
+    }
+    const qualifier = readActiveWhen(edge);
+    if (!qualifier) {
+      const rawQualifier = edge.properties?.[ACTIVE_WHEN_PROPERTY];
+      const rawValues = rawQualifier && typeof rawQualifier === "object" && !Array.isArray(rawQualifier) ? rawQualifier.values : void 0;
+      if (Array.isArray(rawValues) && rawValues.length === 0) {
+        findings.push({
+          kind: "qualifier_values_empty",
+          severity: "error",
+          edge_id: edge.id,
+          message: `${edgeLabel(edge)} carries an active_when with an empty values list. Read literally that would remove the relationship from every configuration, which is a way to delete an edge by writing a property; it is treated as absent instead. To say a relationship never holds, delete the edge.`
+        });
+        continue;
+      }
+      findings.push({
+        kind: "qualifier_axis_unresolved",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} carries a malformed active_when. It must be an object with an axis id and a non-empty values array; anything else reads as absent, which silently makes the relationship invariant.`
+      });
+      continue;
+    }
+    const values = axisValues.get(qualifier.axis);
+    if (!values) {
+      findings.push({
+        kind: "qualifier_axis_unresolved",
+        severity: "error",
+        edge_id: edge.id,
+        axis_id: qualifier.axis,
+        message: `active_when names axis "${qualifier.axis}", which is not a configuration_axis node in this graph.`
+      });
+      continue;
+    }
+    for (const value of qualifier.values) {
+      if (!values.includes(value)) {
+        findings.push({
+          kind: "qualifier_unknown_value",
+          severity: "error",
+          edge_id: edge.id,
+          axis_id: qualifier.axis,
+          message: `active_when names value "${value}", which axis "${qualifier.axis}" does not declare. Its values are [${values.join(", ")}].`
+        });
+      }
+    }
+  }
+  const varianceBySource = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.type !== VARIES_BY_EDGE) continue;
+    const values = readStringArray(edge.properties, PRESENT_UNDER_PROPERTY) ?? [];
+    const list = varianceBySource.get(edge.source) ?? [];
+    list.push({ axis: edge.target, values });
+    varianceBySource.set(edge.source, list);
+  }
+  for (const edge of edges) {
+    if (edge.type !== ALTERNATES_EDGE) continue;
+    const left = varianceBySource.get(edge.source) ?? [];
+    const right = varianceBySource.get(edge.target) ?? [];
+    if (left.length === 0 || right.length === 0) {
+      findings.push({
+        kind: "alternation_axis_mismatch",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} declares an alternation, but at least one endpoint declares no variance at all. Two surfaces that are both always present are not alternatives; they co-exist.`
+      });
+      continue;
+    }
+    const sharedAxes = left.filter((l) => right.some((r) => r.axis === l.axis)).map((l) => l.axis);
+    if (sharedAxes.length === 0) {
+      findings.push({
+        kind: "alternation_axis_mismatch",
+        severity: "error",
+        edge_id: edge.id,
+        message: `${edgeLabel(edge)} declares an alternation between surfaces that vary on different axes. Alternatives are selected by ONE lever; surfaces on different levers can both be present at once.`
+      });
+      continue;
+    }
+    for (const axis of sharedAxes) {
+      const leftValues = left.find((l) => l.axis === axis)?.values ?? [];
+      const rightValues = right.find((r) => r.axis === axis)?.values ?? [];
+      const overlap = leftValues.filter((v) => rightValues.includes(v));
+      if (overlap.length > 0) {
+        findings.push({
+          kind: "alternation_overlap",
+          severity: "error",
+          edge_id: edge.id,
+          axis_id: axis,
+          message: `${edgeLabel(edge)} declares an alternation, but both surfaces are present under [${overlap.join(", ")}] on axis "${axis}". They co-exist there, so the graph is asserting "one of these" and "both, together" about the same pair.`
+        });
+      }
+    }
+  }
+  const parentsByChild = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
+      parentsByChild.set(edge.target, (parentsByChild.get(edge.target) ?? 0) + 1);
+    }
+  }
+  for (const [axisId, values] of axisValues) {
+    for (const value of values) {
+      const projected = projectGraph(nodes, edges, { [axisId]: value });
+      const survivingParents = /* @__PURE__ */ new Map();
+      for (const edge of projected.edges) {
+        if (edge.type && PARENT_EDGE_TYPES.has(edge.type)) {
+          survivingParents.set(edge.target, (survivingParents.get(edge.target) ?? 0) + 1);
+        }
+      }
+      for (const node of projected.nodes) {
+        if (node.type !== "surface") continue;
+        if ((parentsByChild.get(node.id) ?? 0) === 0) continue;
+        if ((survivingParents.get(node.id) ?? 0) > 0) continue;
+        findings.push({
+          kind: "orphaned_under_projection",
+          severity: "warning",
+          node_id: node.id,
+          axis_id: axisId,
+          message: `Surface is present under ${axisId} = "${value}" but every containment parent it has is absent there. Either it needs a parent in that configuration, or it should declare that it is absent from it too.`
+        });
+      }
+    }
+  }
+  return findings;
+}
+
 // src/grammar/lifecycles.ts
 var PRODUCT_LIFECYCLE = {
   entity_type: "product",
@@ -6820,6 +7185,10 @@ var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
   "market_segment",
   "classification_axis",
   "classification_value",
+  // ── Product Specification (1): a configuration_axis is a structural
+  //    DECLARATION (a lever and its closed value set), not a thing that
+  //    progresses through states. Same reading as classification_axis above.
+  "configuration_axis",
   // ── User Research (5 of 8): participants, quotes, observations,
   //    clusters, survey responses are immutable data points ────────────────
   "participant",
@@ -11329,6 +11698,12 @@ var UPG_PROPERTY_SCHEMA = {
     regulation: { type: "string", enum: ["gdpr", "ccpa", "hipaa", "soc2", "iso27001", "pci_dss", "other"], description: "Regulation or standard this requirement derives from" },
     compliance_status: { type: "string", enum: ["compliant", "non_compliant", "in_progress", "not_applicable"], description: "Current compliance posture" }
   },
+  // ConfigurationAxisProperties: A named dimension along which the product's composition differs.
+  configuration_axis: {
+    values: { type: "string[]", description: "The closed set of values this axis can take. Required: an axis with no values selects nothing and cannot be projected along. Two values is the common case and three is not unusual (a plan ladder). Order is not significant; the axis is categorical, not ordinal. Where the ordering does matter (an entitlement ladder in which each tier includes the one below), that is a classification question, and `classification_axis` with `axis_kind: 'ordinal'` is the instrument for it." },
+    default_value: { type: "string", description: "The value this axis is understood to sit at when nobody says otherwise. Must be a member of `values`. NOTHING APPLIES IT AUTOMATICALLY. Omitting `configuration` on a read returns the UNION, not this projection, because the union is the honest answer to an unqualified question: it is every configuration at once, and silently substituting one of them would hide the others from a reader who did not know to ask. What the field does carry is the declaration convention for `surface_alternates_with_surface` (declare the edge from the surface present under the default) and a documented anchor for tools that later want to offer a starting configuration. It is a claim about the model, not about deployment: it says which value most of the graph was written against, not which configuration most customers are on." },
+    kind: { type: "string", enum: ["feature_flag", "plan_tier", "permission_level", "beta_program", "other"], description: "What kind of lever this is. Names the mechanism family." }
+  },
   // ConstraintProperties: Constraint: a named limitation or boundary on product creation.
   constraint: {
     constraint_kind: { type: "string", enum: ["resource", "technical", "regulatory", "temporal", "compliance", "other"], description: "Limitation category" },
@@ -20197,6 +20572,44 @@ function validateValue(key, def, val) {
       }
       break;
     }
+    case "string[]": {
+      if (!Array.isArray(val)) {
+        errors.push(`property "${key}" must be an array of strings`);
+        break;
+      }
+      if (val.some((v) => typeof v !== "string")) {
+        errors.push(`property "${key}" must contain only strings`);
+      }
+      if (val.length === 0) {
+        errors.push(`property "${key}" must not be empty`);
+      }
+      break;
+    }
+    case "object": {
+      if (typeof val !== "object" || val === null || Array.isArray(val)) {
+        errors.push(`property "${key}" must be an object`);
+        break;
+      }
+      const obj = val;
+      for (const req2 of def.required ?? []) {
+        if (obj[req2] === void 0 || obj[req2] === null) {
+          errors.push(`property "${key}" is missing required key "${req2}"`);
+        }
+      }
+      for (const [subKey, subDef] of Object.entries(def.properties ?? {})) {
+        const subVal = obj[subKey];
+        if (subVal === void 0 || subVal === null) continue;
+        errors.push(...validateValue(`${key}.${subKey}`, subDef, subVal));
+      }
+      for (const presentKey of Object.keys(obj)) {
+        if (def.properties && !(presentKey in def.properties)) {
+          errors.push(
+            `property "${key}" has unknown key "${presentKey}" (allowed: ${Object.keys(def.properties).join(", ")})`
+          );
+        }
+      }
+      break;
+    }
   }
   return errors;
 }
@@ -20415,6 +20828,7 @@ var ENTITY_EMOJI = {
   pipeline_sales: "\u{1FA88}",
   pipeline_stage: "\u{1F9FD}",
   planning_cycle: "\u{1F5D3}\uFE0F",
+  configuration_axis: "\u{1F39A}\uFE0F",
   playbook: "\u{1F4D2}",
   portfolio: "\u{1F9F8}",
   positioning: "\u{1F3AA}",
@@ -21109,6 +21523,7 @@ var STANDARD_LABELS = {
   roadmap_theme: { alt_labels: ["product theme", "roadmap theme"] },
   // UPG-660: renamed from bare 'theme' (N6 lineage)
   planning_cycle: { alt_labels: ["sprint", "iteration", "cycle", "program increment", "pi", "cadence", "time-box", "cooldown", "quarter"] },
+  configuration_axis: { alt_labels: ["configuration", "config axis", "lever", "variant axis", "plan axis", "flag axis", "entitlement axis"] },
   // Engineering layer
   bounded_context: { alt_labels: ["context", "domain boundary", "module boundary"] },
   service: { alt_labels: ["microservice", "backend service", "api service"] },
@@ -23630,7 +24045,7 @@ var PRODUCT_SPEC_GUIDE = {
   // registered to product_spec but missing from the navigation order).
   // `changelog` lives here because it is a structural product-shipping
   // artefact; content domain references it only via cross-domain bridges.
-  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "roadmap_theme", "changelog", "planning_cycle"],
+  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "roadmap_theme", "changelog", "planning_cycle", "configuration_axis"],
   patterns: [
     {
       name: "Feature Decomposition",
@@ -29045,6 +29460,11 @@ var UPG_REGIONS = [
         type: "planning_cycle",
         role: "container",
         notes: "self-nesting cadence axis"
+      },
+      {
+        type: "configuration_axis",
+        role: "leaf",
+        notes: "the configuration lever whose values select which surface tree the product renders"
       }
     ],
     anchor: {
@@ -30961,7 +31381,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.29.0";
+var UPG_VERSION = "0.30.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -31026,11 +31446,14 @@ var UPG_EDGE_COUNT = UPG_EDGE_TYPES.length;
 var UPG_META_COUNT = UPG_ENTITY_META.length;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ACTIVE_WHEN_PROPERTY,
   ANALYTICS_DATA_PLAYBOOK,
   BUSINESS_GROWTH_METRIC_DRIVEN_PLAYBOOK,
   BUSINESS_GTM_GROWTH_PLAYBOOK,
   BUSINESS_MARKETING_AUDIENCE_FIRST_PLAYBOOK,
   CLASSIFICATION_EDGE_PROPERTY_SCHEMA,
+  CONFIGURATION_QUALIFIER_EDGE_PROPERTY_SCHEMA,
+  CONFIGURATION_VARIANCE_EDGE_PROPERTY_SCHEMA,
   CONTENT_DEPTH_WARNING_RULES,
   COVERAGE_ANTI_PATTERNS,
   DEFAULT_ENTITY_EMOJI,
@@ -31045,10 +31468,12 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   MARKDOWN_FORMAT_VERSION,
   MARKET_COMPETITIVE_PLAYBOOK,
   OPERATIONS_QUALITY_PLAYBOOK,
+  PRESENT_UNDER_PROPERTY,
   PRODUCT_DELIVERY_PLAYBOOK,
   PROPERTY_MODIFIERS,
   PROPERTY_MODIFIER_SEMANTICS,
   PROPERTY_SCALE_MAP,
+  QUALIFIABLE_EDGE_TYPES,
   RECORD_ENTITY_TYPES,
   REFLECT_MODES,
   REGISTRY_PRODUCT_ID,
@@ -31131,9 +31556,11 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_WILDCARD_ENDPOINT,
   USERS_NEEDS_PLAYBOOK,
   UnknownEntityTypeError,
+  VARIES_BY_EDGE,
   backfillSlug,
   buildTypeAliases,
   canBeChildOf,
+  checkConfigurationDrift,
   checkHeaderSeal,
   checkHeaderSealText,
   checkToEdgeCountSpec,
@@ -31154,6 +31581,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   edgeCarriesProperties,
   edgeCountSpecKey,
   entityFilterKey,
+  enumerateProjections,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,
@@ -31245,6 +31673,9 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   parseUpg,
   pickCanonicalEdge,
   presenceExceptKey,
+  projectGraph,
+  readActiveWhen,
+  readStringArray,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,