@unified-product-graph/core 0.27.0 → 0.28.0

package/README.md

@@ -7,7 +7,7 @@
 
 The TypeScript core for the **Unified Product Graph (UPG)**, an open specification that gives product tools a shared vocabulary for entities, edges, and frameworks.
 
-321 entity types across 37 domains. 1068 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
+321 entity types across 37 domains. 1069 typed edges. 46 canonical framework definitions, with more added as each is reviewed.
 
 ## Install
 

package/dist/index.cjs

@@ -104,6 +104,7 @@ __export(index_exports, {
   UPG_POLYMORPHIC_EDGE_KEYS: () => UPG_POLYMORPHIC_EDGE_KEYS,
   UPG_PORTFOLIO_KINDS: () => UPG_PORTFOLIO_KINDS,
   UPG_PORTFOLIO_SHARED_TYPES: () => UPG_PORTFOLIO_SHARED_TYPES,
+  UPG_PRESENCE_EXCEPT_SPECS: () => UPG_PRESENCE_EXCEPT_SPECS,
   UPG_PRODUCT_STAGES: () => UPG_PRODUCT_STAGES,
   UPG_PRODUCT_STAGE_COERCION_MAP: () => UPG_PRODUCT_STAGE_COERCION_MAP,
   UPG_PROPERTY_MIGRATIONS: () => UPG_PROPERTY_MIGRATIONS,
@@ -240,6 +241,7 @@ __export(index_exports, {
   normalizeDocument: () => normalizeDocument,
   parseUpg: () => parseUpg,
   pickCanonicalEdge: () => pickCanonicalEdge,
+  presenceExceptKey: () => presenceExceptKey,
   resolveAllEdges: () => resolveAllEdges,
   resolveContainmentEdge: () => resolveContainmentEdge,
   resolveEntityType: () => resolveEntityType,
@@ -1800,9 +1802,10 @@ var UPG_EDGE_CATALOG = {
   journey_action_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_action", target_type: "feature" },
   // ── surface (0.27.0): the place inside a screen ─────────────────────────
   // `screen` is route-level; `surface` is the contested place within it. The
-  // ten edges below give a surface its spine (nesting), its guest list, its
+  // eleven edges below give a surface its spine (nesting), its guest list, its
   // purpose, its governing rule, its rendering vocabulary, its measurement,
-  // and its replacement path.
+  // its replacement path, and (0.28.0) the gap between what it intends and
+  // what it actually does.
   //
   // Classification adjudications, each anchored on the nearest precedent:
   //   contains        → hierarchy   (feature_area_contains_feature_area, planning_cycle_contains_planning_cycle)
@@ -1838,6 +1841,35 @@ var UPG_EDGE_CATALOG = {
   surface_renders_design_component: { forward_verb: "renders", reverse_verb: "rendered_on", classification: "hierarchy", source_type: "surface", target_type: "design_component", cross_product_eligible: true },
   surface_measured_by_metric: { forward_verb: "measured_by", reverse_verb: "measures", classification: "semantic", source_type: "surface", target_type: "metric", cross_product_eligible: true },
   surface_supersedes_surface: { forward_verb: "supersedes", reverse_verb: "superseded_by", classification: "semantic", source_type: "surface", target_type: "surface" },
+  // ── surface, 0.28.0 addition: intent versus reality ─────────────────────────
+  // Every surface property records what the design INTENDS. `capacity: 1` on a
+  // banner region is an assertion, and a real product will eventually be found
+  // rendering four. Without somewhere to put that fact, the only ways to record
+  // it are to edit `capacity` up to 4 (which destroys the intent, and with it
+  // any evidence that a gap exists) or to leave the graph quietly wrong.
+  //
+  // This edge is the third option, and it is what lets `capacity` mean intent
+  // unconditionally: the deviation hangs off a `technical_debt_item`, which is
+  // already a trackable, assignable, prioritisable entity with an owner and a
+  // remediation cost. The gap becomes work rather than a discrepancy.
+  //
+  //   classification → cross-domain (ux_design → technical_debt). Crossing INTO
+  //     the debt domain from another ring is the established shape:
+  //     risk_manifests_as_technical_debt_item is cross-domain on exactly that
+  //     reasoning. NOT `causal`: `decision_incurs_technical_debt_item` is causal
+  //     because a decision BRINGS the debt into existence, whereas a surface
+  //     does not cause its own drift, it exhibits it. NOT `hierarchy`: that
+  //     would oblige a surface → technical_debt_item containment pair in
+  //     UPG_VALID_CHILDREN (guardrail G2b), and a surface does not own the debt
+  //     that afflicts it — service_carries_technical_debt_item can be hierarchy
+  //     because a service genuinely owns its backlog.
+  //   verbs → `deviates_via` / `causes_deviation_in`. The forward verb names
+  //     what the SOURCE does (the surface deviates), qualified by the debt that
+  //     accounts for it, so the edge key reads as the sentence it asserts. The
+  //     reverse says what the debt does to the place.
+  //   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" },
   // 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
@@ -13437,8 +13469,12 @@ 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 the surface holds at once, as a non-negative count. 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".' },
+    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." },
     arbitration_rule: { type: "string", description: 'Who wins when more occupants want the surface than `capacity` allows, and why. ABSENCE IS MEANINGFUL: a null or empty `arbitration_rule` on a contested surface means nobody decided, which is exactly what the `contended-surface-without-arbitration` anti-pattern detects. Do not fill this in with a placeholder to silence the check. @example "Highest priority wins; ties break to the most recently updated."' },
+    arbitration_state: { type: "string", enum: ["enforced_documented", "enforced_undocumented", "safe_by_coincidence", "none"], description: 'Whether the arbitration answer is enforced, written down, both, or neither. Separates "enforced in code but never transcribed" (ten minutes of typing) from "never decided" (a design meeting) from "safe only because nothing has collided yet" (the dangerous one).' },
     extensibility: { type: "string", enum: ["closed", "plugin_registerable", "user_configurable"], description: "Who may add occupants to the surface." },
     mutates_content: { type: "boolean", description: "Whether occupying this surface can change the underlying content, as opposed to only selecting or revealing it. The selector-versus-mutator distinction: a gutter that toggles a value is a mutator, a gutter that jumps the cursor is not." },
     dimensional_constraint: { type: "string", description: 'The hard spatial budget the surface imposes on its occupants, in whatever unit the design system speaks. @example "292px wide", "25px per field", "two grid columns"' }
@@ -27275,7 +27311,44 @@ 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, but at least one surface carries no arbitration_rule. A surface is a place features compete for; the arbitration rule is the recorded answer to "who wins here, and why". Left blank, that answer lives in whoever remembers the last argument.',
+    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.',
+    // 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:
+    //
+    //  (a) rule-absence, EXCEPT chained. `composition_mode: 'chained'` means each
+    //      occupant wraps the next rather than competing with it. Many occupants
+    //      and no arbitration rule is the designed shape, so the reporter's 14
+    //      chained slots were 14 standing false positives — and because
+    //      `get_anti_pattern_violations_for` attributes by TYPE, they kept the
+    //      whole surface roster lit no matter how diligently the genuinely
+    //      contended surfaces were documented. The check could never be silenced
+    //      by correct modelling, which is the property a check has to have.
+    //      Exemption is DECLARE-TO-EARN: an unset `composition_mode` still fires,
+    //      so the default posture stays suspicious and silence must be claimed.
+    //  (b) `safe_by_coincidence` fires on its own, with no chained exemption. It
+    //      is the one state that a written `arbitration_rule` can mask: the field
+    //      audit found surfaces whose prose described disjoint enum values doing
+    //      the arbitrating with nothing guarding them. Branch (a) cannot see
+    //      those, because the rule text is present.
+    //  (c) `none` fires on its own too. A graph that says "nobody decided" while
+    //      carrying rule text is contradicting itself, and the admission is the
+    //      half to believe.
+    //
+    // `enforced_undocumented` deliberately gets NO branch and NO suppression. It
+    // needs none: a surface enforcing an untranscribed rule has no
+    // `arbitration_rule`, so branch (a) already fires. Nor does it earn a
+    // downgrade — severity is per-anti-pattern, not per-violation, so there is
+    // nowhere to put one; and the harm this pattern names is that the settlement
+    // is unrecorded, which is exactly what `enforced_undocumented` admits. The
+    // graph is the record; code is not. What the state buys is triage, so the
+    // remediation text below names the two costs separately.
+    //
+    // No new anti-pattern was minted for `safe_by_coincidence`. It is a value of
+    // the arbitration question, not a different question, and a second detector
+    // would fire on the same graphs and double-report through type-keyed
+    // 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.
     structured_condition: {
       operator: "and",
       checks: [
@@ -27290,17 +27363,43 @@ var UPG_ANTI_PATTERNS = [
           }
         },
         {
-          check: {
-            type: "entity_count",
-            entity_type: "surface",
-            filter: { property: "arbitration_rule", present: false },
-            comparison: "nonzero"
-          }
+          operator: "or",
+          checks: [
+            {
+              check: {
+                type: "entity_count",
+                entity_type: "surface",
+                filter: {
+                  property: "arbitration_rule",
+                  present: false,
+                  except_property: "composition_mode",
+                  except_value: "chained"
+                },
+                comparison: "nonzero"
+              }
+            },
+            {
+              check: {
+                type: "entity_count",
+                entity_type: "surface",
+                filter: { property: "arbitration_state", value: "safe_by_coincidence" },
+                comparison: "nonzero"
+              }
+            },
+            {
+              check: {
+                type: "entity_count",
+                entity_type: "surface",
+                filter: { property: "arbitration_state", value: "none" },
+                comparison: "nonzero"
+              }
+            }
+          ]
         }
       ]
     },
-    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.",
-    remediation: "For each surface with more than one `feature_occupies_surface` edge, write the rule that settles contention into `arbitration_rule`, and record the constraint it works within (`capacity`, `dimensional_constraint`). Where a design system already answers it, link the source with `surface_governed_by_design_guideline`.",
+    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.",
     stages: ["build", "beta", "launch", "growth", "mature", "maintenance"],
     severity: "medium",
     source: { kind: "fundamental" }
@@ -27358,6 +27457,38 @@ var UPG_ANTI_PATTERNS = [
     source: { kind: "fundamental" }
   }
 ];
+function walkForExceptSpecs(cond, out) {
+  if ("operator" in cond) {
+    for (const child of cond.checks) walkForExceptSpecs(child, out);
+    return;
+  }
+  const check = cond.check;
+  if (check.type !== "entity_count" || !check.filter) return;
+  const f = check.filter;
+  if (typeof f.property !== "string" || typeof f.except_property !== "string" || typeof f.except_value !== "string") {
+    return;
+  }
+  const spec = {
+    entity_type: check.entity_type,
+    property: f.property,
+    except_property: f.except_property,
+    except_value: f.except_value
+  };
+  const seen = out.some(
+    (s) => s.entity_type === spec.entity_type && s.property === spec.property && s.except_property === spec.except_property && s.except_value === spec.except_value
+  );
+  if (!seen) out.push(spec);
+}
+var UPG_PRESENCE_EXCEPT_SPECS = (() => {
+  const out = [];
+  for (const ap of UPG_ANTI_PATTERNS) {
+    if (ap.structured_condition) walkForExceptSpecs(ap.structured_condition, out);
+  }
+  return out;
+})();
+function presenceExceptKey(property, exceptProperty, exceptValue) {
+  return `${property}!${exceptProperty}=${exceptValue}`;
+}
 function getAntiPatternById(id) {
   return UPG_ANTI_PATTERNS.find((ap) => ap.id === id);
 }
@@ -27505,7 +27636,13 @@ function compareNumber(value, comparison, threshold) {
 function evaluateEntityCount(check, inputs) {
   const filter = check.filter;
   let count = 0;
-  if (filter && typeof filter.property === "string" && typeof filter.present === "boolean") {
+  if (filter && typeof filter.property === "string" && typeof filter.present === "boolean" && typeof filter.except_property === "string" && typeof filter.except_value === "string") {
+    const key = presenceExceptKey(filter.property, filter.except_property, filter.except_value);
+    const exempt = inputs.countsByTypeAndProperty?.[check.entity_type]?.[filter.except_property]?.[filter.except_value] ?? 0;
+    const eligible = Math.max(0, (inputs.countsByType[check.entity_type] ?? 0) - exempt);
+    const withValue = inputs.countsByTypeAndPropertyPresenceExcept?.[check.entity_type]?.[key] ?? 0;
+    count = filter.present ? Math.min(withValue, eligible) : Math.max(0, eligible - withValue);
+  } else if (filter && typeof filter.property === "string" && typeof filter.present === "boolean") {
     const withValue = inputs.countsByTypeAndPropertyPresence?.[check.entity_type]?.[filter.property] ?? 0;
     count = filter.present ? withValue : Math.max(0, (inputs.countsByType[check.entity_type] ?? 0) - withValue);
   } else if (filter && typeof filter.property === "string" && typeof filter.value === "string") {
@@ -30626,7 +30763,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.27.0";
+var UPG_VERSION = "0.28.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30765,6 +30902,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   UPG_POLYMORPHIC_EDGE_KEYS,
   UPG_PORTFOLIO_KINDS,
   UPG_PORTFOLIO_SHARED_TYPES,
+  UPG_PRESENCE_EXCEPT_SPECS,
   UPG_PRODUCT_STAGES,
   UPG_PRODUCT_STAGE_COERCION_MAP,
   UPG_PROPERTY_MIGRATIONS,
@@ -30901,6 +31039,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   normalizeDocument,
   parseUpg,
   pickCanonicalEdge,
+  presenceExceptKey,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,