@unified-product-graph/core 0.28.0 → 0.29.0

package/dist/index.js

@@ -12679,7 +12679,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: {
@@ -13207,7 +13208,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." },
@@ -27049,7 +27050,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:
     //
@@ -27087,6 +27088,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: [
@@ -27105,14 +27168,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"
               }
             },
@@ -27137,7 +27202,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" }
@@ -27227,6 +27292,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);
 }
@@ -27303,7 +27457,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) => {
@@ -27313,6 +27471,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);
@@ -27332,6 +27509,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":
@@ -27392,6 +27571,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}`;
 }
@@ -27474,7 +27665,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);
@@ -30501,7 +30692,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.28.0";
+var UPG_VERSION = "0.29.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30615,10 +30806,12 @@ export {
   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,
@@ -30673,8 +30866,11 @@ export {
   canBeChildOf,
   checkHeaderSeal,
   checkHeaderSealText,
+  checkToEdgeCountSpec,
+  classifyEntityFilter,
   coerceProductStage,
   collectSlugsForType,
+  collectTargetEntities,
   compareVersions,
   computeBodyChecksum,
   concernEvaluatedFor,
@@ -30686,6 +30882,8 @@ export {
   deriveSingleCounts,
   describeTreePattern,
   edgeCarriesProperties,
+  edgeCountSpecKey,
+  entityFilterKey,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,