@unified-product-graph/core 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.29.0] - 2026-08-15
+
+**The contention check learns to read `capacity`, violations learn to name their nodes, and a batch write learns to un-say a property.** All three came from the same field reporter measuring the check on a real 43-surface graph: 10 surfaces flagged, 7 correctly, 3 falsely — and every false positive had an occupant count at or below its stated capacity. A surface whose occupants all fit is partitioned, not contended. Additive; no breaking change.
+
+### Changed
+- **`contended-surface-without-arbitration` is capacity-aware.** The rule-absence branch now fires per surface only when `occupancy > (capacity ?? 1)` — occupants within a stated capacity are partitioned by design, and an unbounded surface (absent capacity) with several occupants still fires, because no stated limit means no stated answer. Contention is *displacement* (who is not rendered), which capacity settles; *ordering* of coexisting occupants remains guidance on `composition_mode: 'additive'`, deliberately not a second detector.
+- **Violations carry `target_node_ids`.** Attribution rides the same collector aggregates as the verdicts: a fired check names the offending nodes instead of only the entity types, and `get_anti_pattern_violations_for` matches by id exactly for the types the id list covers (`matched_by: 'node' | 'type'`), keeping type-level reach for types never attributed. The payload reserves an empty `configurations` field for per-projection attribution (0.30.0).
+
+### Added
+- **`edge_count_vs_property` check form** — a general per-node comparison of an edge count against a numeric property with a declared absence default. Deliberately not a one-off: the form fits any place the graph states a numeric intent.
+- **`unset_properties` on `batch_update_nodes`** — batch parity with `update_node`'s existing affordance, so returning a property to *absent* no longer requires literal nulls. For `capacity` the distinction is load-bearing: absent (unbounded), `0` (reserved), and `null` are three different states.
+- **`product.described_configuration`** (optional string) — names the configuration a graph describes, the typed home for the one-named-configuration convention published alongside this release. Naming, not configuring: a label for readers, read by no tool.
+
+### Notes
+- Backfilled below: 0.28.0 shipped 2026-08-13 without a changelog entry; it is recorded now so this entry does not sit on a gap.
+
+---
+
+## [0.28.0] - 2026-08-13
+
+**Four field-data additions teach `surface` to tell the truth about multiplicity, composition, arbitration, and drift.** All four came from one reporter populating 0.27.0's `surface` against a real 30-surface product (three parallel code audits, 329 file:line citations) before writing a single node. Additive; no breaking change. *(Backfilled 2026-08-15 — this release shipped without an entry.)*
+
+### Added
+- **`cardinality`** (`1 | 0..1 | 1..n | 0..n`) and **`instance_scope`** (`global | per_parent`) — `capacity` counts occupants per instance; these count instances. Without them the graph says "the product has an inspector panel" when the truth is "each document pane has its own."
+- **`composition_mode`** (`exclusive | additive | chained`) — how co-occupants relate. `chained` (each occupant wraps the next) is a trust model, not contention, and is exempt from `contended-surface-without-arbitration` — declare-to-earn: an unset `composition_mode` still fires.
+- **`arbitration_state`** (`enforced_documented | enforced_undocumented | safe_by_coincidence | none`) — routes remediation instead of guessing it. `safe_by_coincidence` and `none` fire the contention check on their own admission; a written rule cannot mask them.
+- **`surface_deviates_via_technical_debt_item`** edge — `capacity` always means *intent*, and drift from it becomes a trackable, assignable debt item instead of a lie or an endorsement.
+- **Except-form on the presence filter** — `filter: { property, present, except_property, except_value }`, needed because the chained exemption is an intersection the marginal forms could not express.
+
+---
+
 ## [0.27.0] - 2026-08-12
 
 **A `surface` entity gives the UI a place: what occupies it, and who wins when two things want it.** The catalog could say who OWNS a thing (`feature_area`) and what ARCHITECTURE it belongs to (`bounded_context`), but nothing answered *what else occupies the same place?*. `screen` is route-level (route / viewport / access_level) and too coarse for a shell, a pane, a slot, a field gutter, an action bar, or an overlay. Those places are contested, and the arbitration rule is decided constantly and then rediscovered forever, because prose is where it lands. `surface` records the place, its guest list, and the rule. Additive; no breaking change.

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

@@ -80,10 +80,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,
@@ -104,6 +106,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,
@@ -137,8 +140,11 @@ __export(index_exports, {
   canBeChildOf: () => canBeChildOf,
   checkHeaderSeal: () => checkHeaderSeal,
   checkHeaderSealText: () => checkHeaderSealText,
+  checkToEdgeCountSpec: () => checkToEdgeCountSpec,
+  classifyEntityFilter: () => classifyEntityFilter,
   coerceProductStage: () => coerceProductStage,
   collectSlugsForType: () => collectSlugsForType,
+  collectTargetEntities: () => collectTargetEntities,
   compareVersions: () => compareVersions,
   computeBodyChecksum: () => computeBodyChecksum,
   concernEvaluatedFor: () => concernEvaluatedFor,
@@ -150,6 +156,8 @@ __export(index_exports, {
   deriveSingleCounts: () => deriveSingleCounts,
   describeTreePattern: () => describeTreePattern,
   edgeCarriesProperties: () => edgeCarriesProperties,
+  edgeCountSpecKey: () => edgeCountSpecKey,
+  entityFilterKey: () => entityFilterKey,
   evaluateAntiPatterns: () => evaluateAntiPatterns,
   findInvalidStatusMigrationTargets: () => findInvalidStatusMigrationTargets,
   formatUpgText: () => formatUpgText,
@@ -240,6 +248,7 @@ __export(index_exports, {
   normalizeDocument: () => normalizeDocument,
   parseUpg: () => parseUpg,
   pickCanonicalEdge: () => pickCanonicalEdge,
+  presenceExceptKey: () => presenceExceptKey,
   resolveAllEdges: () => resolveAllEdges,
   resolveContainmentEdge: () => resolveContainmentEdge,
   resolveEntityType: () => resolveEntityType,
@@ -1800,9 +1809,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 +1848,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
@@ -12909,7 +12948,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: {
@@ -13437,8 +13477,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". 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." },
     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 +27319,106 @@ 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: '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:
+    //
+    //  (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.
+    //
+    // 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: [
@@ -27290,17 +27433,45 @@ var UPG_ANTI_PATTERNS = [
           }
         },
         {
-          check: {
-            type: "entity_count",
-            entity_type: "surface",
-            filter: { property: "arbitration_rule", present: false },
-            comparison: "nonzero"
-          }
+          operator: "or",
+          checks: [
+            {
+              check: {
+                type: "edge_count_vs_property",
+                entity_type: "surface",
+                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"
+              }
+            },
+            {
+              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: "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" }
@@ -27358,6 +27529,127 @@ 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 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);
 }
@@ -27434,7 +27726,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) => {
@@ -27444,6 +27740,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);
@@ -27463,6 +27778,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":
@@ -27505,7 +27822,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") {
@@ -27517,6 +27840,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}`;
 }
@@ -27599,7 +27934,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);
@@ -30626,7 +30961,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.27.0";
+var UPG_VERSION = "0.29.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30741,10 +31076,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,
@@ -30765,6 +31102,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,
@@ -30798,8 +31136,11 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   canBeChildOf,
   checkHeaderSeal,
   checkHeaderSealText,
+  checkToEdgeCountSpec,
+  classifyEntityFilter,
   coerceProductStage,
   collectSlugsForType,
+  collectTargetEntities,
   compareVersions,
   computeBodyChecksum,
   concernEvaluatedFor,
@@ -30811,6 +31152,8 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   deriveSingleCounts,
   describeTreePattern,
   edgeCarriesProperties,
+  edgeCountSpecKey,
+  entityFilterKey,
   evaluateAntiPatterns,
   findInvalidStatusMigrationTargets,
   formatUpgText,
@@ -30901,6 +31244,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   normalizeDocument,
   parseUpg,
   pickCanonicalEdge,
+  presenceExceptKey,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,