@unified-product-graph/core 0.26.1 → 0.28.0

package/CHANGELOG.md

@@ -7,6 +7,22 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [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.
+
+### Added
+- **`surface` entity** (`proposed`, `ent_359`) — a place in the UI, in the `ux_design` domain beside `screen`. Reached through the screen that renders it and self-nesting from there (shell holds panes, panes hold regions, regions hold slots). Lifecycle `draft → in_design → built → shipped → deprecated`, shared verbatim with `screen` so a screen and the surfaces inside it report progress on one vocabulary. Eight properties: `surface_kind` (shell / tool / pane / region / slot / gutter / action_bar / overlay / ambient), `persistence`, `visibility_condition`, `capacity`, `arbitration_rule`, `extensibility`, `mutates_content`, `dimensional_constraint`.
+- **Ten surface edges.** Outbound: `surface_contains_surface` (hierarchy, the nesting spine), `surface_serves_job` (cross-domain), `surface_governed_by_design_guideline` (cross-domain, cross-product-eligible), `surface_renders_design_component` (hierarchy, cross-product-eligible), `surface_measured_by_metric` (semantic, cross-product-eligible), `surface_supersedes_surface` (semantic). Inbound: `feature_occupies_surface` (cross-domain, the guest list), `screen_renders_surface` (hierarchy), `decision_affects_surface` (cross-domain), `journey_step_occurs_on_surface` (semantic, the finer-grained sibling of `journey_step_shown_on_screen`).
+- **Three anti-patterns.** `contended-surface-without-arbitration` (medium) fires when features occupy surfaces and at least one carries no `arbitration_rule`. `surface-without-job` and `surface-without-measurement` (low, both thin-graph advisory) are its coverage companions.
+- **Property-presence filter on `EntityCheck`** — `filter: { property, present }` counts entities that do or do not carry a value for a named property, backed by a new optional `countsByTypeAndPropertyPresence` input. The pre-existing value-keyed filter cannot express absence, because a collector only indexes values that exist; without this, a detector keyed on an unfilled field could never fire.
+
+### Notes
+- `surface_measured_by_metric` is `semantic`, not `hierarchy`. The `*_measured_by_metric` convention splits on ownership: `outcome` / `objective` / `strategic_pillar` are `hierarchy` because they own their metrics as children, and each carries a matching `UPG_VALID_CHILDREN` entry. A surface owns no metric, so it takes the `revenue_stream` / `cost_structure` half of the convention.
+- `capacity` is a plain optional number whose ABSENCE means unbounded. `PropertyDefinition.type` is a single scalar kind with no union form, so a sentinel value was the alternative, and a sentinel every consumer must special-case is worse than a documented absence.
+
+---
+
 ## [0.20.1] - 2026-07-04
 
 **Three edges close the alignment-sheet seam: an initiative can now reach directly into the OKR ladder and the roadmap, and a strategic pillar gets its own north-star metric.** Composed flat region surfaces spanning org/team/product altitudes surfaced two gaps in the strategic cascade: an initiative's only path to a key result or a roadmap theme ran through its parent `strategic_theme`, and `strategic_pillar` — durable, multi-year, org-wide — had no measuring metric of its own, unlike every other rung of the cascade (`objective_measured_by_metric`, `key_result_quantified_by_metric`). 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.
 
-320 entity types across 37 domains. 1058 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,
@@ -334,8 +336,8 @@ var UPG_DOMAINS = [
   {
     id: "ux_design",
     label: "Experience Design",
-    description: "How users experience and interact with your product. User journeys map end-to-end experiences, broken into journey steps. User flows chart navigation paths. Screens and screen states define what users see. Design questions frame open problems. Design concepts explore possible solutions. Prototypes and wireframes make ideas tangible. Connects User (who) to Product Specification (what) through Design System (how).",
-    types: ["user_journey", "journey_step", "journey_phase", "journey_action", "user_flow", "screen", "screen_state", "design_question", "design_concept", "prototype", "wireframe"]
+    description: "How users experience and interact with your product. User journeys map end-to-end experiences, broken into journey steps. User flows chart navigation paths. Screens and screen states define what users see. Surfaces name the places inside a screen, who may occupy them, and the rule that settles contention. Design questions frame open problems. Design concepts explore possible solutions. Prototypes and wireframes make ideas tangible. Connects User (who) to Product Specification (what) through Design System (how).",
+    types: ["user_journey", "journey_step", "journey_phase", "journey_action", "user_flow", "screen", "screen_state", "surface", "design_question", "design_concept", "prototype", "wireframe"]
   },
   {
     id: "design_system",
@@ -901,6 +903,11 @@ var UPG_ENTITY_META = [
   { name: "user_flow", type_id: "ent_068", maturity: "stable", since: "0.1.0" },
   { name: "screen", type_id: "ent_069", maturity: "stable", since: "0.1.0" },
   { name: "screen_state", type_id: "ent_070", maturity: "stable", since: "0.1.0" },
+  // surface (0.27.0): the place inside a screen. `screen` is route-level
+  // (route / viewport / access_level); `surface` is the contested slot within
+  // 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: "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" },
@@ -1793,6 +1800,87 @@ var UPG_EDGE_CATALOG = {
   // edge mirrors `journey_step_realised_by_feature` one level deeper.
   journey_action_surfaces_need: { forward_verb: "surfaces", reverse_verb: "surfaced_in", classification: "cross-domain", source_type: "journey_action", target_type: "need" },
   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
+  // eleven edges below give a surface its spine (nesting), its guest list, its
+  // purpose, its governing rule, its rendering vocabulary, its measurement,
+  // 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)
+  //   serves job      → cross-domain (ux_design → users_needs; cf. user_journey_addresses_job).
+  //                     Verb is `serves`, not `addresses`: a feature ADDRESSES a job
+  //                     (it satisfies the struggle); a surface SERVES it (it is the
+  //                     place where the job gets done). `serves`/`served_by` is an
+  //                     established house pair (service_serves_api_endpoint,
+  //                     api_endpoint_serves_feature, product_serves_account).
+  //   governed_by     → cross-domain (ux_design → design_system). The verb precedent
+  //                     design_component_governed_by_design_guideline is `hierarchy`,
+  //                     but both of its endpoints sit inside design_system; once the
+  //                     seam is crossed the catalog uses cross-domain
+  //                     (insight_informs_design_guideline). cross_product_eligible:
+  //                     the guideline usually lives in the shared design-system graph.
+  //   renders comp.   → hierarchy + cross_product_eligible, matching its direct
+  //                     sibling screen_renders_design_component verbatim.
+  //   measured_by     → semantic + cross_product_eligible. The enumerated
+  //                     *_measured_by_metric convention splits on OWNERSHIP, not on the
+  //                     verb: outcome / objective / strategic_pillar are `hierarchy`
+  //                     because those entities own their metrics as children (each has a
+  //                     UPG_VALID_CHILDREN entry to match, which the hierarchy-integrity
+  //                     guardrail enforces). A surface does not own a metric any more
+  //                     than a revenue_stream does, so it takes the `semantic` half of
+  //                     the convention (revenue_stream / cost_structure). It stays
+  //                     cross_product_eligible with the rest: a metric DEFINITION is
+  //                     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_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 },
+  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
+  // running the other way.
+  feature_occupies_surface: { forward_verb: "occupies", reverse_verb: "occupied_by", classification: "cross-domain", source_type: "feature", target_type: "surface" },
+  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
+  // a PLACE, not just a route. Same semantic classification as that edge (a step
+  // is not contained by the surface; it references where it happens).
+  journey_step_occurs_on_surface: { forward_verb: "occurs_on", reverse_verb: "hosts", classification: "semantic", source_type: "journey_step", target_type: "surface" },
   // 2.5 UI System Domain
   product_systematised_in_design_system: { forward_verb: "systematised_in", reverse_verb: "systematises", classification: "hierarchy", source_type: "product", target_type: "design_system" },
   product_built_with_design_component: { forward_verb: "built_with", reverse_verb: "built_for", classification: "hierarchy", source_type: "product", target_type: "design_component" },
@@ -4314,8 +4402,24 @@ var UPG_VALID_CHILDREN = {
     "user_flow",
     "insight"
   ],
-  screen: ["screen_state", "screen", "design_component", "wireframe"],
-  // self-nesting + components + wireframes
+  screen: ["screen_state", "screen", "surface", "design_component", "wireframe"],
+  // self-nesting + surfaces + components + wireframes
+  // surface (0.27.0): the place inside a screen. Self-nests, so a shell holds
+  // panes, a pane holds regions, a region holds slots. A surface is reached
+  // through the screen that renders it (`screen: [... 'surface']`), never as a
+  // top-level product child: every UPG_VALID_CHILDREN pair must be backed by a
+  // hierarchy-classified edge (guardrail G2b), and the ratified ten do not
+  // include a product-to-surface verb. An app-shell surface therefore hangs off
+  // the screen that mounts it.
+  //
+  // NOTE: `surface_kind` narrows this further than UPG_VALID_CHILDREN can
+  // express. UPG_VALID_CHILDREN is keyed on entity TYPE, so it can only say
+  // "a surface may contain a surface"; the kind ordering (shell > tool > pane >
+  // region > slot / gutter / action_bar, with overlay and ambient parented by
+  // whatever raises them) is a property-level rule documented on `SurfaceKind`
+  // and enforced by validators, not by this table. Precedent: the same split
+  // applies to `planning_cycle`, whose `cadence_kind` narrows its self-nesting.
+  surface: ["surface", "design_component"],
   // ── Marketing & Communications hierarchy ────────────────────────────────────
   marketing_strategy: [
     "marketing_channel",
@@ -5387,6 +5491,48 @@ var SCREEN_LIFECYCLE = {
     }
   ]
 };
+var SURFACE_LIFECYCLE = {
+  entity_type: "surface",
+  initial_phase: "draft",
+  terminal_phases: ["deprecated"],
+  phases: [
+    {
+      id: "draft",
+      status_category: "started",
+      label: "Draft",
+      description: "The surface is a rough idea: named and scoped, but not yet worked in a design tool. Its occupants and arbitration rule are usually still undecided.",
+      transitions_to: ["in_design"]
+    },
+    {
+      id: "in_design",
+      status_category: "started",
+      label: "In Design",
+      description: "The surface is being designed: its dimensions, occupants, and arbitration rule are being settled. May fall back to `draft` if the approach is rethought from scratch.",
+      transitions_to: ["built", "draft"]
+    },
+    {
+      id: "built",
+      status_category: "started",
+      label: "Built",
+      description: "The surface has been implemented in code. It exists in a build but is not yet live for users. May return to `in_design` if implementation surfaces a layout or contention gap.",
+      transitions_to: ["shipped", "in_design"]
+    },
+    {
+      id: "shipped",
+      status_category: "completed",
+      label: "Shipped",
+      description: "The surface is live in production and reachable by users. Its occupants are the real guest list.",
+      transitions_to: ["deprecated"]
+    },
+    {
+      id: "deprecated",
+      status_category: "completed",
+      label: "Deprecated",
+      description: "The surface has been retired. Its occupants have moved elsewhere, or a replacement has taken the place; record the replacement with `surface_supersedes_surface`.",
+      transitions_to: []
+    }
+  ]
+};
 var SERVICE_LIFECYCLE = {
   entity_type: "service",
   initial_phase: "development",
@@ -6588,6 +6734,7 @@ var UPG_LIFECYCLES = [
   DESIGN_CONCEPT_LIFECYCLE,
   BRAND_IDENTITY_LIFECYCLE,
   SCREEN_LIFECYCLE,
+  SURFACE_LIFECYCLE,
   // Engineering & Operations
   SERVICE_LIFECYCLE,
   DEPLOYMENT_LIFECYCLE,
@@ -13317,6 +13464,21 @@ var UPG_PROPERTY_SCHEMA = {
     signal_channel: { type: "string", description: "Channel through which the signal was received" },
     signal_urgency: { type: "string", enum: ["low", "medium", "high", "critical"], description: "Perceived urgency of the customer's request" }
   },
+  // SurfaceProperties: A place in the UI, its occupants, and the rule that arbitrates between them.
+  surface: {
+    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".' },
+    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"' }
+  },
   // SurveyResponseProperties: Aggregated survey response data.
   survey_response: {
     response_count: { type: "number", description: "Total responses", modifier: "snapshot" },
@@ -20293,6 +20455,7 @@ var ENTITY_EMOJI = {
   sales_motion: "\u{1F501}",
   screen: "\u{1F5A5}\uFE0F",
   screen_state: "\u{1F533}",
+  surface: "\u{1FA9F}",
   security_audit: "\u{1F6C3}",
   security_control: "\u{1F39A}\uFE0F",
   security_policy: "\u{1F510}",
@@ -20916,6 +21079,7 @@ var STANDARD_LABELS = {
   design_system: { alt_labels: ["component library", "style system", "ui kit"] },
   screen: { alt_labels: ["page", "view", "route", "ui state"] },
   screen_state: { alt_labels: ["view state", "empty state", "loading state", "error state"] },
+  surface: { alt_labels: ["slot", "pane", "region", "zone", "shell", "panel", "placement", "ui surface"] },
   // Brand layer
   brand_identity: { alt_labels: ["brand", "brand guidelines", "brand book"] },
   brand_imagery: { alt_labels: ["brand image", "visual asset", "brand photo"] },
@@ -23497,22 +23661,30 @@ var UX_DESIGN_GUIDE = {
   // of a journey_step, so the step must precede the action. The journey is the
   // anchor; phases are the band overlay; steps are the timeline; actions
   // decompose a step into service-blueprint rows.
-  creation_sequence: ["user_journey", "journey_phase", "journey_step", "journey_action", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
+  creation_sequence: ["user_journey", "journey_phase", "journey_step", "journey_action", "screen", "screen_state", "surface", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
   patterns: [
     {
       name: "Journey to Screen Flow",
       description: "Journeys map the experience, journey steps are shown on screens, prototypes simulate screens so the design can be tested",
       entity_types: ["user_journey", "journey_step", "screen", "prototype"],
       edge_chain: ["persona_experiences_user_journey", "user_journey_contains_journey_step", "journey_step_shown_on_screen", "prototype_simulates_screen"]
+    },
+    {
+      name: "Surface Contention",
+      description: "A screen renders surfaces, features occupy them, and the surface records the rule that settles who wins. Nest the place (shell, pane, region, slot), list the occupants, then write the arbitration rule down once so it is not re-argued at the next feature.",
+      entity_types: ["screen", "surface", "feature"],
+      edge_chain: ["screen_renders_surface", "surface_contains_surface", "feature_occupies_surface", "surface_serves_job"]
     }
   ],
   required_bridges: [
     { edge_type: "persona_experiences_user_journey", target_domain: "user", when: "Every journey must be anchored to a persona" },
+    { edge_type: "feature_occupies_surface", target_domain: "product_spec", when: "A surface should list the features that occupy it; the guest list is what makes contention visible" },
     { edge_type: "prototype_tests_hypothesis", target_domain: "validation", when: "Prototypes should test design hypotheses before building" },
     { edge_type: "screen_surfaces_feature", target_domain: "product_spec", when: "Screens should connect to the features they surface" }
   ],
   anti_patterns: [
     { description: "Screens without journeys: isolated screens miss the experience context" },
+    { description: "Surfaces without an arbitration rule: a place two features both want, with no recorded answer for who wins, is a decision that gets made again every time it comes up. Fill `arbitration_rule`, or link the design guideline that already answers it via surface_governed_by_design_guideline." },
     { description: "Prototypes without testing: if nobody tests the prototype, it is just art" },
     { description: "Design questions left open: exploration status should progress to resolved or parked" },
     { description: "Touchpoints stuffed in the deprecated journey_step.touchpoint string (UPG-675). Touchpoints belong in one of two layers: journey_action is the in-product blueprint layer (the finest band of a journey_step), and the touchpoint entity is the cross-channel customer-success layer (touchpoint_occurs_in_journey_step). Pick the layer; do not duplicate the touch as a free-text string." }
@@ -27127,8 +27299,196 @@ var UPG_ANTI_PATTERNS = [
     stages: ["concept", "validation", "build", "beta", "launch", "growth", "mature", "maintenance", "sunset"],
     severity: "medium",
     source: { kind: "fundamental" }
+  },
+  // ── surface (0.27.0): the place, its guest list, and its arbitration rule ──
+  // Three patterns, calibrated so the contention one leads and the two coverage
+  // companions sit a tier below it. Like every entry in this file, each detector
+  // is a WHOLE-GRAPH approximation of a per-node rule (cf. personas-without-jobs,
+  // which fires on "no persona anywhere links to a job", not per persona): the
+  // `IntelligenceCondition` language composes aggregate counts, not per-node
+  // predicates.
+  {
+    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.',
+    // 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: [
+        { check: { type: "entity_count", entity_type: "surface", comparison: "nonzero" } },
+        {
+          check: {
+            type: "relationship",
+            source_type: "feature",
+            edge_type: "feature_occupies_surface",
+            target_type: "surface",
+            comparison: "exists"
+          }
+        },
+        {
+          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. 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" }
+  },
+  {
+    id: "surface-without-job",
+    since: "0.27.0",
+    name: "Surface without a job",
+    description: "The graph has surfaces, but none links to the job it exists to serve. A surface with no job is a place that survives on precedent: it is there because it has always been there.",
+    structured_condition: {
+      operator: "and",
+      checks: [
+        { check: { type: "entity_count", entity_type: "surface", comparison: "nonzero" } },
+        {
+          check: {
+            type: "relationship",
+            source_type: "surface",
+            edge_type: "surface_serves_job",
+            target_type: "job",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "Without a job, there is no test for whether a surface still earns its space. Places accumulate, and the layout argument becomes a matter of taste rather than of purpose.",
+    remediation: "Link each surface to the job it serves with `surface_serves_job`. A surface that cannot name one is a candidate for removal or for merging into its parent.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "low",
+    source: { kind: "practitioner", attribution: "Clayton Christensen, Jobs to Be Done" }
+  },
+  {
+    id: "surface-without-measurement",
+    since: "0.27.0",
+    name: "Surface without measurement",
+    description: "The graph has surfaces, but none links to a metric. Nothing reports whether the place is used, ignored, or in the way.",
+    structured_condition: {
+      operator: "and",
+      checks: [
+        { check: { type: "entity_count", entity_type: "surface", comparison: "nonzero" } },
+        {
+          check: {
+            type: "relationship",
+            source_type: "surface",
+            edge_type: "surface_measured_by_metric",
+            target_type: "metric",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "An unmeasured surface cannot be retired on evidence. It is defended by whoever built it and challenged by whoever wants its space, with no reading to settle the question.",
+    remediation: "Attach the reading that would justify keeping the place with `surface_measured_by_metric`. Engagement, or the rate at which its occupants are actually invoked, is usually the honest one.",
+    stages: ["build", "beta", "launch", "growth", "mature"],
+    severity: "low",
+    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);
 }
@@ -27171,7 +27531,14 @@ function concernGatesFor(kind, concern) {
 var COVERAGE_ANTI_PATTERNS = /* @__PURE__ */ new Set([
   "single-domain-graph",
   "persona-count-below-stage-benchmark",
-  "competitors-missing-past-validation"
+  "competitors-missing-past-validation",
+  // surface companions (0.27.0): both presuppose the graph has grown past the
+  // point where a place is worth justifying and measuring. A stub that has
+  // sketched one surface has not yet drifted. `contended-surface-without-
+  // arbitration` is deliberately NOT here: it only fires once features actually
+  // occupy surfaces, which is itself the evidence that the graph has grown.
+  "surface-without-job",
+  "surface-without-measurement"
 ]);
 var THIN_GRAPH_THRESHOLD = 8;
 function isThinCoverageAdvisory(antiPatternId, totalEntityCount) {
@@ -27269,7 +27636,16 @@ function compareNumber(value, comparison, threshold) {
 function evaluateEntityCount(check, inputs) {
   const filter = check.filter;
   let count = 0;
-  if (filter && typeof filter.property === "string" && typeof filter.value === "string") {
+  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") {
     count = inputs.countsByTypeAndProperty?.[check.entity_type]?.[filter.property]?.[filter.value] ?? 0;
   } else if (filter && typeof filter.status === "string") {
     count = inputs.countsByTypeAndStatus?.[check.entity_type]?.[filter.status] ?? 0;
@@ -28174,6 +28550,10 @@ var UPG_REGIONS = [
         type: "screen_state",
         role: "leaf"
       },
+      {
+        type: "surface",
+        role: "container"
+      },
       {
         type: "wireframe",
         role: "leaf"
@@ -28282,7 +28662,9 @@ var UPG_REGIONS = [
       "user_journey_contains_journey_step",
       "design_system_contains_design_component",
       "brand_identity_coloured_with_brand_colour",
-      "design_component_composes_design_component"
+      "design_component_composes_design_component",
+      "screen_renders_surface",
+      "surface_contains_surface"
     ],
     boundary_edges: [
       {
@@ -28290,6 +28672,16 @@ var UPG_REGIONS = [
         edge_id: "need_reframed_as_design_question",
         crosses_into: "users_needs"
       },
+      {
+        direction: "import",
+        edge_id: "feature_occupies_surface",
+        crosses_into: "product_delivery"
+      },
+      {
+        direction: "export",
+        edge_id: "surface_serves_job",
+        crosses_into: "users_needs"
+      },
       {
         direction: "import",
         edge_id: "opportunity_explores_via_design_concept",
@@ -30371,7 +30763,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.26.1";
+var UPG_VERSION = "0.28.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30510,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,
@@ -30646,6 +31039,7 @@ var UPG_META_COUNT = UPG_ENTITY_META.length;
   normalizeDocument,
   parseUpg,
   pickCanonicalEdge,
+  presenceExceptKey,
   resolveAllEdges,
   resolveContainmentEdge,
   resolveEntityType,