@unified-product-graph/core 0.28.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,
@@ -80,10 +85,12 @@ __export(index_exports, {
   UPG_DOMAIN_RINGS: () => UPG_DOMAIN_RINGS,
   UPG_EDGE_CATALOG: () => UPG_EDGE_CATALOG,
   UPG_EDGE_COUNT: () => UPG_EDGE_COUNT,
+  UPG_EDGE_COUNT_SPECS: () => UPG_EDGE_COUNT_SPECS,
   UPG_EDGE_MIGRATIONS: () => UPG_EDGE_MIGRATIONS,
   UPG_EDGE_PAIR_MAP: () => UPG_EDGE_PAIR_MAP,
   UPG_EDGE_TYPES: () => UPG_EDGE_TYPES,
   UPG_ENTITY_COUNT: () => UPG_ENTITY_COUNT,
+  UPG_ENTITY_FILTER_SPECS: () => UPG_ENTITY_FILTER_SPECS,
   UPG_ENTITY_META: () => UPG_ENTITY_META,
   UPG_ENTITY_META_BY_ID: () => UPG_ENTITY_META_BY_ID,
   UPG_ENTITY_META_BY_NAME: () => UPG_ENTITY_META_BY_NAME,
@@ -133,13 +140,18 @@ __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,
+  classifyEntityFilter: () => classifyEntityFilter,
   coerceProductStage: () => coerceProductStage,
   collectSlugsForType: () => collectSlugsForType,
+  collectTargetEntities: () => collectTargetEntities,
   compareVersions: () => compareVersions,
   computeBodyChecksum: () => computeBodyChecksum,
   concernEvaluatedFor: () => concernEvaluatedFor,
@@ -151,6 +163,9 @@ __export(index_exports, {
   deriveSingleCounts: () => deriveSingleCounts,
   describeTreePattern: () => describeTreePattern,
   edgeCarriesProperties: () => edgeCarriesProperties,
+  edgeCountSpecKey: () => edgeCountSpecKey,
+  entityFilterKey: () => entityFilterKey,
+  enumerateProjections: () => enumerateProjections,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
   formatUpgText: () => formatUpgText,
@@ -242,6 +257,9 @@ __export(index_exports, {
   parseUpg: () => parseUpg,
   pickCanonicalEdge: () => pickCanonicalEdge,
   presenceExceptKey: () => presenceExceptKey,
+  projectGraph: () => projectGraph,
+  readActiveWhen: () => readActiveWhen,
+  readStringArray: () => readStringArray,
   resolveAllEdges: () => resolveAllEdges,
   resolveContainmentEdge: () => resolveContainmentEdge,
   resolveEntityType: () => resolveEntityType,
@@ -368,7 +386,8 @@ var UPG_DOMAINS = [
       "roadmap_item",
       "roadmap_theme",
       "changelog",
-      "planning_cycle"
+      "planning_cycle",
+      "configuration_axis"
     ]
   },
   {
@@ -908,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" },
@@ -1309,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
@@ -1835,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 },
@@ -1870,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
@@ -3940,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",
@@ -4563,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",
@@ -6813,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",
@@ -11322,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" },
@@ -12941,7 +13323,8 @@ var UPG_PROPERTY_SCHEMA = {
     health_status: { type: "string", enum: ["on_track", "at_risk", "off_track"], description: "Overall health" },
     url: { type: "string", description: "Where the product lives. Marketing site, app store URL, etc.", modifier: "volatile" },
     logo_url: { type: "string", description: "Logo or icon URL. Used to render product cards and lists.", modifier: "volatile" },
-    launched_at: { type: "string", description: "When the product became generally available (ISO 8601)" }
+    launched_at: { type: "string", description: "When the product became generally available (ISO 8601)" },
+    described_configuration: { type: "string", description: `The product configuration this graph describes, named in plain language. A product's composition often differs by feature flag, plan tier, permission level or beta programme: surfaces appear, disappear, or are replaced by different surfaces with different occupants. A graph that models one of those without saying which is qualified by a condition nobody wrote down, and every fact in it inherits that silence. NAMING, NOT CONFIGURING. This is a label for readers. Nothing reads it to gate, filter, or alter how a tool interprets the graph, and it makes no claim about which configuration most customers are on. @example "Enterprise plan, split-navigation flag on" @example "Default: free tier, all flags off"` }
   },
   // ProductAreaProperties: ProductArea entity.
   product_area: {
@@ -13469,7 +13852,7 @@ var UPG_PROPERTY_SCHEMA = {
     surface_kind: { type: "string", enum: ["shell", "tool", "pane", "region", "slot", "gutter", "action_bar", "overlay", "ambient"], description: "Structural kind. Determines what may legally nest inside this surface." },
     persistence: { type: "string", enum: ["always", "conditional", "on_demand", "transient"], description: "How reliably the surface is present." },
     visibility_condition: { type: "string", description: 'When the surface appears, in plain language. Pairs with `persistence: \'conditional\'`, which states *that* it is conditional; this states *what* the condition is. @example "A node is selected", "Only for workspace admins"' },
-    capacity: { type: "number", description: 'How many occupants ONE INSTANCE of the surface holds at once, as a non-negative count. Count the instances themselves with `cardinality`. CAPACITY IS ALWAYS INTENT, NEVER OBSERVED BEHAVIOUR. It records the cap the design asserts, so a banner region declared `capacity: 1` keeps saying 1 even after someone finds it rendering four. Reality that has drifted from the declared intent is recorded as a trackable, assignable debt item on `surface_deviates_via_technical_debt_item`, not by quietly editing this number up to match the bug. Editing it to match would destroy the only record that a gap exists. ABSENT MEANS UNBOUNDED. UPG has no union-typed property primitive (`PropertyDefinition.type` is a single scalar kind), so the proposed `integer | unbounded` shape is expressed as an optional number whose absence carries the "no cap" reading, rather than a magic sentinel value that every consumer would have to special-case. `0` is a real cap meaning "nothing may occupy this surface" (a reserved place), not "unbounded".' },
+    capacity: { type: "number", description: 'How many occupants ONE INSTANCE of the surface holds at once, as a non-negative count. Count the instances themselves with `cardinality`. CAPACITY IS ALWAYS INTENT, NEVER OBSERVED BEHAVIOUR. It records the cap the design asserts, so a banner region declared `capacity: 1` keeps saying 1 even after someone finds it rendering four. Reality that has drifted from the declared intent is recorded as a trackable, assignable debt item on `surface_deviates_via_technical_debt_item`, not by quietly editing this number up to match the bug. Editing it to match would destroy the only record that a gap exists. ABSENT MEANS UNBOUNDED. UPG has no union-typed property primitive (`PropertyDefinition.type` is a single scalar kind), so the proposed `integer | unbounded` shape is expressed as an optional number whose absence carries the "no cap" reading, rather than a magic sentinel value that every consumer would have to special-case. `0` is a real cap meaning "nothing may occupy this surface" (a reserved place), not "unbounded". THREE STATES, AND THEY ARE ALL DIFFERENT. Absent = unbounded, no cap stated. `0` = a reserved place nothing may occupy. `null` = neither of those, and nothing this field defines; it is what you get by writing an explicit null rather than removing the key, and no consumer reads it as a cap. To return this property to ABSENT, remove the key with `update_node`\'s or `batch_update_nodes`\' `unset_properties`, since a property merge preserves anything you omit. UNBOUNDED IS NOT AN EXEMPTION FROM SCRUTINY. The contention detector reads an absent capacity as a threshold of 1, on the reasoning that a surface which states no limit has stated no answer either, so several occupants is exactly the unrecorded decision worth naming. Declaring a real capacity is therefore the way to quiet the check honestly, and the only way that also records something true.' },
     cardinality: { type: "string", enum: ["1", "0..1", "1..n", "0..n"], description: "How many instances of this surface exist. `capacity` counts occupants within one instance; this counts the instances." },
     instance_scope: { type: "string", enum: ["global", "per_parent"], description: 'What an instance is scoped to: one shared instance for the product, or one per containing surface. Decides whether "the product has this surface" is a true sentence or a per-parent one.' },
     composition_mode: { type: "string", enum: ["exclusive", "additive", "chained"], description: "How the occupants relate: one wins (`exclusive`), all coexist (`additive`), or each wraps the next (`chained`). Declaring `chained` exempts the surface from `contended-surface-without-arbitration`; leaving this unset does not." },
@@ -20189,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;
 }
@@ -20407,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}",
@@ -21101,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"] },
@@ -23622,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",
@@ -27311,7 +27734,7 @@ var UPG_ANTI_PATTERNS = [
     id: "contended-surface-without-arbitration",
     since: "0.27.0",
     name: "Contended surface without arbitration",
-    description: 'Features occupy surfaces in this graph, and at least one surface has no recorded answer to "who wins here, and why". Either it carries no arbitration_rule and has not declared itself `chained`, or it admits through arbitration_state that the answer is absent (`none`) or accidental (`safe_by_coincidence`). Left unrecorded, that answer lives in whoever remembers the last argument.',
+    description: 'At least one surface in this graph has no recorded answer to "who wins here, and why". Either it holds more occupants than its stated `capacity` allows (or holds several while stating no limit at all) and carries no arbitration_rule, or it admits through arbitration_state that the answer is absent (`none`) or accidental (`safe_by_coincidence`). Left unrecorded, that answer lives in whoever remembers the last argument.',
     // 0.28.0 (feedback 852a9721, from a 30-surface field audit). Three changes,
     // each earned by a reported false positive or a reported blind spot:
     //
@@ -27349,6 +27772,68 @@ var UPG_ANTI_PATTERNS = [
     // attribution — making this family noisier on its first real deployment,
     // which is the exact failure (a) exists to fix. If field evidence later shows
     // it needs its own severity, mint it then.
+    //
+    // 0.29.0 (feedback af9ae4c2, the same reporter's measured follow-up: 43
+    // surfaces, 10 flagged, 7 rightly and 3 wrongly). Branch (a) moved from an
+    // aggregate presence count to the per-node `edge_count_vs_property` form.
+    //
+    //  (d) CAPACITY IS NOW READ. The old branch was a pure edge count: any
+    //      surface with more than one occupant and no rule. That flags a header
+    //      row declaring room for four and holding exactly four, which is not
+    //      contended but PARTITIONED — everyone fits, by design, so nothing is
+    //      displaced and there is nothing to decide. All three of the reporter's
+    //      false positives were this, and all three had occupancy at or below a
+    //      stated capacity. The rule is now `occupancy > (capacity ?? 1)`.
+    //
+    //      ABSENT CAPACITY BEHAVES AS 1, NOT AS INFINITY. Absence means
+    //      unbounded, and it is tempting to read unbounded as "never flag". The
+    //      opposite is right: a surface that states no limit has stated no
+    //      answer, so two or more occupants is precisely the unrecorded decision
+    //      this pattern names. That keeps all four of the reporter's unbounded
+    //      true positives (7, 7, 10 and 3 occupants) firing.
+    //
+    //      The check had to become per-node rather than two ANDed aggregates:
+    //      "some surface is over capacity" and "some surface has no rule" are
+    //      both true when they are DIFFERENT surfaces, which would have kept
+    //      every false positive alive. See `EdgeCountVsPropertyCheck.node_filter`.
+    //
+    // ADJUDICATED: DOES A CAPACITY-SATISFIED `additive` SURFACE STILL NEED AN
+    // ORDERING RULE? The reporter's capacity rule and their own earlier report
+    // pull in opposite directions here: 0.28.0 documented that `additive`
+    // occupants raise a question of ORDER rather than victory and that the order
+    // belongs in `arbitration_rule`, while the capacity rule says a surface
+    // where everyone fits has nothing to settle. Ruling: BOTH ARE RIGHT, because
+    // they are about different failures, and this detector owns only one of them.
+    //
+    //   - Contention is about DISPLACEMENT: who is not rendered. Capacity settles
+    //     it. If everyone fits, nobody is displaced, and "who wins" is genuinely
+    //     moot. That is why reading capacity removes real false positives rather
+    //     than merely quieting the check.
+    //   - Ordering is about ARRANGEMENT: in what sequence coexisting occupants
+    //     appear. Capacity says nothing about it. The reporter's own four-occupant
+    //     header row, positioned by runtime width measurement, has a live ordering
+    //     question and no displacement question at all.
+    //
+    // So this check reads capacity and stops at displacement. The ordering concern
+    // stays documented on `composition_mode: 'additive'` as guidance, NOT as a
+    // detector: minting `additive-surface-without-ordering` today would repeat the
+    // 0.28.0 mistake of shipping a second detector on no field evidence, and it
+    // would double-report against this one. Mint it when a graph shows unrecorded
+    // ordering causing a real defect, with its own severity and remediation.
+    //
+    // Known consequence, recorded rather than papered over: `arbitration_rule` is
+    // now visibly OVERLOADED. It holds a displacement rule for `exclusive`
+    // surfaces and an ordering rule for `additive` ones, and this check reads it
+    // for only the first. Splitting it (`arbitration_rule` vs `ordering_rule`) is
+    // the natural move if the ordering detector is ever minted; it is not worth a
+    // breaking property change before then.
+    //
+    // STILL OPEN (banked at 0.28.0, deliberately NOT changed here): a `chained`
+    // slot that honestly declares `arbitration_state: 'none'` re-fires through
+    // branch (c), which carries no chained exemption. Current guidance stands:
+    // leave `arbitration_state` unset on chained surfaces. Changing (b)/(c) was
+    // out of scope for this release and still awaits the field confirmation the
+    // reporter will produce populating their 14 chained slots.
     structured_condition: {
       operator: "and",
       checks: [
@@ -27367,14 +27852,16 @@ var UPG_ANTI_PATTERNS = [
           checks: [
             {
               check: {
-                type: "entity_count",
+                type: "edge_count_vs_property",
                 entity_type: "surface",
-                filter: {
-                  property: "arbitration_rule",
-                  present: false,
-                  except_property: "composition_mode",
-                  except_value: "chained"
-                },
+                edge_type: "feature_occupies_surface",
+                direction: "inbound",
+                property: "capacity",
+                property_absent_default: 1,
+                node_comparison: "gt",
+                node_filter: { property: "arbitration_rule", present: false },
+                except_property: "composition_mode",
+                except_value: "chained",
                 comparison: "nonzero"
               }
             },
@@ -27399,7 +27886,7 @@ var UPG_ANTI_PATTERNS = [
       ]
     },
     why_it_matters: "Contention over a UI place is settled every time it comes up, and an unrecorded settlement is re-argued at the next feature. The cost is paid in repeated decisions, not in a visible defect. A surface that is safe only by coincidence pays it all at once instead, the first time an occupant is added.",
-    remediation: "Read `arbitration_state` first: it says what the work actually is. `enforced_undocumented` means the rule already exists in code and needs transcribing into `arbitration_rule`: ten minutes, no meeting. `none` means nobody has decided and someone has to. `safe_by_coincidence` means nothing is enforcing anything and the surface only looks settled; that one wants a guard in code, not just prose. Record the constraint the rule works within (`capacity`, `dimensional_constraint`), and where a design system already answers it, link the source with `surface_governed_by_design_guideline`. Surfaces whose occupants wrap one another rather than compete should declare `composition_mode: 'chained'`, which exempts them: that is a factual claim about how the code composes, not a way to quiet the check.",
+    remediation: "The violation names the offending surfaces in `target_node_ids`; start there rather than re-reading the whole roster. Read `arbitration_state` first: it says what the work actually is. `enforced_undocumented` means the rule already exists in code and needs transcribing into `arbitration_rule`: ten minutes, no meeting. `none` means nobody has decided and someone has to. `safe_by_coincidence` means nothing is enforcing anything and the surface only looks settled; that one wants a guard in code, not just prose. If a flagged surface genuinely holds everything it was designed to hold, the honest fix is to state its `capacity`, not to invent a rule: a surface whose occupancy is at or below a stated capacity is partitioned rather than contended, and it stops firing. Where a design system already answers the question, link the source with `surface_governed_by_design_guideline`. Surfaces whose occupants wrap one another rather than compete should declare `composition_mode: 'chained'`, which exempts them: that is a factual claim about how the code composes, not a way to quiet the check.",
     stages: ["build", "beta", "launch", "growth", "mature", "maintenance"],
     severity: "medium",
     source: { kind: "fundamental" }
@@ -27489,6 +27976,95 @@ var UPG_PRESENCE_EXCEPT_SPECS = (() => {
 function presenceExceptKey(property, exceptProperty, exceptValue) {
   return `${property}!${exceptProperty}=${exceptValue}`;
 }
+function edgeCountSpecKey(spec) {
+  const filter = spec.node_filter ? `${spec.node_filter.property}=${spec.node_filter.present ? "present" : "absent"}` : "*";
+  const except = spec.except_property !== void 0 && spec.except_value !== void 0 ? `${spec.except_property}=${spec.except_value}` : "*";
+  return [
+    spec.entity_type,
+    spec.edge_type,
+    spec.direction,
+    spec.property,
+    String(spec.property_absent_default),
+    spec.node_comparison,
+    filter,
+    except
+  ].join("|");
+}
+function entityFilterKey(entityType, filter) {
+  const kind = classifyEntityFilter(filter);
+  switch (kind) {
+    case "presence":
+      return `${entityType}|${filter.property}=${filter.present ? "present" : "absent"}`;
+    case "value":
+      return `${entityType}|${filter.property}=${filter.value}`;
+    case "status":
+      return `${entityType}|status=${filter.status}`;
+    case "unrecognized":
+      return `${entityType}|<unrecognized>`;
+  }
+}
+function classifyEntityFilter(filter) {
+  const hasProperty = typeof filter.property === "string";
+  if (hasProperty && typeof filter.present === "boolean") return "presence";
+  if (hasProperty && typeof filter.value === "string") return "value";
+  if (typeof filter.status === "string") return "status";
+  return "unrecognized";
+}
+function walkForEntityFilterSpecs(cond, out) {
+  if ("operator" in cond) {
+    for (const child of cond.checks) walkForEntityFilterSpecs(child, out);
+    return;
+  }
+  const check = cond.check;
+  if (check.type !== "entity_count" || !check.filter) return;
+  const kind = classifyEntityFilter(check.filter);
+  if (kind === "unrecognized") {
+    throw new Error(
+      `Unrecognized entity_count filter shape on "${check.entity_type}": ${JSON.stringify(check.filter)}. Recognised shapes are { property, present }, { property, value } and { status }. Teach classifyEntityFilter + the collector before declaring a new one.`
+    );
+  }
+  const key = entityFilterKey(check.entity_type, check.filter);
+  if (out.some((s) => entityFilterKey(s.entity_type, s.filter) === key)) return;
+  out.push({ entity_type: check.entity_type, filter: check.filter, kind });
+}
+var UPG_ENTITY_FILTER_SPECS = (() => {
+  const out = [];
+  for (const ap of UPG_ANTI_PATTERNS) {
+    if (ap.structured_condition) walkForEntityFilterSpecs(ap.structured_condition, out);
+  }
+  return out;
+})();
+function checkToEdgeCountSpec(check) {
+  return {
+    entity_type: check.entity_type,
+    edge_type: check.edge_type,
+    direction: check.direction ?? "inbound",
+    property: check.property,
+    property_absent_default: check.property_absent_default,
+    node_comparison: check.node_comparison,
+    node_filter: check.node_filter,
+    except_property: check.except_property,
+    except_value: check.except_value
+  };
+}
+function walkForEdgeCountSpecs(cond, out) {
+  if ("operator" in cond) {
+    for (const child of cond.checks) walkForEdgeCountSpecs(child, out);
+    return;
+  }
+  const check = cond.check;
+  if (check.type !== "edge_count_vs_property") return;
+  const spec = checkToEdgeCountSpec(check);
+  const key = edgeCountSpecKey(spec);
+  if (!out.some((s) => edgeCountSpecKey(s) === key)) out.push(spec);
+}
+var UPG_EDGE_COUNT_SPECS = (() => {
+  const out = [];
+  for (const ap of UPG_ANTI_PATTERNS) {
+    if (ap.structured_condition) walkForEdgeCountSpecs(ap.structured_condition, out);
+  }
+  return out;
+})();
 function getAntiPatternById(id) {
   return UPG_ANTI_PATTERNS.find((ap) => ap.id === id);
 }
@@ -27565,7 +28141,11 @@ function evaluateAntiPatterns(inputs, options) {
     const concern = concernFor(ap.id);
     if (!concernEvaluatedFor(inputs.memberKind, concern)) continue;
     if (evaluateCondition(ap.structured_condition, inputs)) {
-      fires.push(buildViolation(ap, concern));
+      const ids = /* @__PURE__ */ new Set();
+      collectAttribution(ap.structured_condition, inputs, ids);
+      const violation = buildViolation(ap, concern);
+      if (ids.size > 0) violation.target_node_ids = [...ids].sort();
+      fires.push(violation);
     }
   }
   fires.sort((a, b) => {
@@ -27575,6 +28155,25 @@ function evaluateAntiPatterns(inputs, options) {
   });
   return fires;
 }
+function collectAttribution(cond, inputs, out) {
+  if ("operator" in cond) {
+    for (const child of cond.checks) {
+      if (cond.operator === "or" && !evaluateCondition(child, inputs)) continue;
+      collectAttribution(child, inputs, out);
+    }
+    return;
+  }
+  const check = cond.check;
+  if (check.type === "edge_count_vs_property") {
+    const key = edgeCountSpecKey(checkToEdgeCountSpec(check));
+    for (const id of inputs.nodesByEdgeCountSpec?.[key] ?? []) out.add(id);
+    return;
+  }
+  if (check.type === "entity_count" && check.filter) {
+    const key = entityFilterKey(check.entity_type, check.filter);
+    for (const id of inputs.nodesByEntityFilter?.[key] ?? []) out.add(id);
+  }
+}
 function evaluateCondition(cond, inputs) {
   if ("check" in cond) {
     return evaluateLeaf(cond.check, inputs);
@@ -27594,6 +28193,8 @@ function evaluateLeaf(check, inputs) {
   switch (check.type) {
     case "entity_count":
       return evaluateEntityCount(check, inputs);
+    case "edge_count_vs_property":
+      return evaluateEdgeCountVsProperty(check, inputs);
     case "relationship":
       return evaluateRelationship(check, inputs);
     case "benchmark":
@@ -27654,6 +28255,18 @@ function evaluateEntityCount(check, inputs) {
   }
   return compareNumber(count, check.comparison, check.threshold);
 }
+function evaluateEdgeCountVsProperty(check, inputs) {
+  const key = edgeCountSpecKey(checkToEdgeCountSpec(check));
+  const matched = inputs.nodesByEdgeCountSpec?.[key];
+  if (matched === void 0) {
+    return compareNumber(
+      inputs.countsByType[check.entity_type] ?? 0,
+      check.comparison,
+      check.threshold
+    );
+  }
+  return compareNumber(matched.length, check.comparison, check.threshold);
+}
 function relationshipKey(source_type, edge_type, target_type) {
   return `${source_type}|${edge_type}|${target_type}`;
 }
@@ -27736,7 +28349,7 @@ function collectTargetEntities(cond) {
   function walk(c) {
     if ("check" in c) {
       const leaf = c.check;
-      if (leaf.type === "entity_count" || leaf.type === "benchmark") {
+      if (leaf.type === "entity_count" || leaf.type === "benchmark" || leaf.type === "edge_count_vs_property") {
         types.add(leaf.entity_type);
       } else if (leaf.type === "relationship") {
         types.add(leaf.source_type);
@@ -28847,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: {
@@ -30763,7 +31381,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.28.0";
+var UPG_VERSION = "0.30.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30828,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,
@@ -30847,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,
@@ -30878,10 +31501,12 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_DOMAIN_RINGS,
   UPG_EDGE_CATALOG,
   UPG_EDGE_COUNT,
+  UPG_EDGE_COUNT_SPECS,
   UPG_EDGE_MIGRATIONS,
   UPG_EDGE_PAIR_MAP,
   UPG_EDGE_TYPES,
   UPG_ENTITY_COUNT,
+  UPG_ENTITY_FILTER_SPECS,
   UPG_ENTITY_META,
   UPG_ENTITY_META_BY_ID,
   UPG_ENTITY_META_BY_NAME,
@@ -30931,13 +31556,18 @@ 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,
+  classifyEntityFilter,
   coerceProductStage,
   collectSlugsForType,
+  collectTargetEntities,
   compareVersions,
   computeBodyChecksum,
   concernEvaluatedFor,
@@ -30949,6 +31579,9 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   deriveSingleCounts,
   describeTreePattern,
   edgeCarriesProperties,
+  edgeCountSpecKey,
+  entityFilterKey,
+  enumerateProjections,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,
@@ -31040,6 +31673,9 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   parseUpg,
   pickCanonicalEdge,
   presenceExceptKey,
+  projectGraph,
+  readActiveWhen,
+  readStringArray,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,