@unified-product-graph/core 0.26.0 → 0.27.0

package/dist/index.js

@@ -74,8 +74,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",
@@ -641,6 +641,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" },
@@ -1533,6 +1538,57 @@ 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
+  // ten 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.
+  //
+  // 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" },
+  // 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" },
@@ -4054,8 +4110,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",
@@ -5127,6 +5199,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",
@@ -6328,6 +6442,7 @@ var UPG_LIFECYCLES = [
   DESIGN_CONCEPT_LIFECYCLE,
   BRAND_IDENTITY_LIFECYCLE,
   SCREEN_LIFECYCLE,
+  SURFACE_LIFECYCLE,
   // Engineering & Operations
   SERVICE_LIFECYCLE,
   DEPLOYMENT_LIFECYCLE,
@@ -13057,6 +13172,17 @@ 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 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".' },
+    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."' },
+    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" },
@@ -20033,6 +20159,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}",
@@ -20656,6 +20783,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"] },
@@ -23237,22 +23365,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." }
@@ -26867,6 +27003,99 @@ 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, 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.',
+    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"
+          }
+        },
+        {
+          check: {
+            type: "entity_count",
+            entity_type: "surface",
+            filter: { property: "arbitration_rule", present: false },
+            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`.",
+    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 getAntiPatternById(id) {
@@ -26911,7 +27140,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) {
@@ -27009,7 +27245,10 @@ 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") {
+    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;
@@ -27914,6 +28153,10 @@ var UPG_REGIONS = [
         type: "screen_state",
         role: "leaf"
       },
+      {
+        type: "surface",
+        role: "container"
+      },
       {
         type: "wireframe",
         role: "leaf"
@@ -28022,7 +28265,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: [
       {
@@ -28030,6 +28275,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",
@@ -29905,6 +30160,28 @@ function portfolioBody(doc) {
     ...doc.signals && doc.signals.length > 0 ? { signals: sortNodes(doc.signals).map(canonicalNode) } : {}
   };
 }
+function deriveSingleCounts(doc) {
+  return { nodes: doc.nodes?.length ?? 0, edges: doc.edges?.length ?? 0 };
+}
+function derivePortfolioCounts(doc) {
+  const members = doc.products ?? [];
+  const memberKindOf = (p) => p.member_kind ?? "product";
+  const watchedCount = members.filter((p) => memberKindOf(p) === "watched").length;
+  const rollupCount = members.filter((p) => memberKindOf(p) === "org_rollup").length;
+  const operatingFunctionCount = members.filter((p) => memberKindOf(p) === "operating_function").length;
+  return {
+    products: members.filter((p) => memberKindOf(p) === "product").length,
+    ...watchedCount > 0 ? { watched_products: watchedCount } : {},
+    ...rollupCount > 0 ? { org_rollups: rollupCount } : {},
+    ...operatingFunctionCount > 0 ? { operating_functions: operatingFunctionCount } : {},
+    product_areas: doc.product_areas?.length ?? 0,
+    portfolios: doc.portfolios?.length ?? 0,
+    cross_edges: doc.cross_edges?.length ?? 0
+  };
+}
+function deriveCounts(doc) {
+  return isPortfolio(doc) ? derivePortfolioCounts(doc) : deriveSingleCounts(doc);
+}
 function computeBodyChecksum(doc) {
   const body = isPortfolio(doc) ? portfolioBody(doc) : singleBody(doc);
   const content = JSON.stringify(body);
@@ -29944,7 +30221,7 @@ function serializeSingleWithHeader(doc, opts) {
   };
   const summary = deriveSummary(product.description);
   if (summary) header.summary = summary;
-  header.counts = { nodes: doc.nodes?.length ?? 0, edges: doc.edges?.length ?? 0 };
+  header.counts = deriveSingleCounts(doc);
   if (doc.member_kind === "org_rollup" || doc.member_kind === "watched" || doc.member_kind === "operating_function") {
     header.member_kind = doc.member_kind;
   }
@@ -29967,20 +30244,7 @@ function serializePortfolioWithHeader(doc, opts) {
   };
   const summary = deriveSummary(org.description);
   if (summary) header.summary = summary;
-  const members = doc.products ?? [];
-  const memberKindOf = (p) => p.member_kind ?? "product";
-  const watchedCount = members.filter((p) => memberKindOf(p) === "watched").length;
-  const rollupCount = members.filter((p) => memberKindOf(p) === "org_rollup").length;
-  const operatingFunctionCount = members.filter((p) => memberKindOf(p) === "operating_function").length;
-  header.counts = {
-    products: members.filter((p) => memberKindOf(p) === "product").length,
-    ...watchedCount > 0 ? { watched_products: watchedCount } : {},
-    ...rollupCount > 0 ? { org_rollups: rollupCount } : {},
-    ...operatingFunctionCount > 0 ? { operating_functions: operatingFunctionCount } : {},
-    product_areas: doc.product_areas?.length ?? 0,
-    portfolios: doc.portfolios?.length ?? 0,
-    cross_edges: doc.cross_edges?.length ?? 0
-  };
+  header.counts = derivePortfolioCounts(doc);
   header.provenance = buildProvenance(doc, opts);
   header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
   return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
@@ -30048,9 +30312,61 @@ function isCanonical(text) {
   const parsed = parseUpg(text);
   return text === serializeCanonical(parsed);
 }
+function checkHeaderSeal(obj) {
+  const raw = obj;
+  const header = raw?.$upg;
+  const report = {
+    header_present: !!header,
+    counts_checked: false,
+    integrity_checked: false,
+    counts_drift: [],
+    integrity_drift: []
+  };
+  if (!header) return report;
+  if (header.format_version !== UPG_CANONICAL_FORMAT_VERSION) {
+    report.skipped_reason = `format_version "${header.format_version}" is not this serialiser's "${UPG_CANONICAL_FORMAT_VERSION}"; counts keys and body layout are format-version contracts, so neither seal can be judged here.`;
+    return report;
+  }
+  const doc = normalizeDocument(raw);
+  const declaredCounts = header.counts ?? {};
+  const actualCounts = deriveCounts(doc);
+  if (header.counts === void 0) {
+    report.skipped_reason = "header has no `counts` block to compare.";
+  } else {
+    report.counts_checked = true;
+    const fields = /* @__PURE__ */ new Set([...Object.keys(declaredCounts), ...Object.keys(actualCounts)]);
+    for (const field of [...fields].sort()) {
+      const declaredRaw = declaredCounts[field];
+      const declared = typeof declaredRaw === "number" ? declaredRaw : 0;
+      const actual = actualCounts[field] ?? 0;
+      if (declared !== actual) report.counts_drift.push({ field, declared, actual });
+    }
+  }
+  const integrity = header.integrity;
+  if (!integrity || typeof integrity.body !== "string") {
+    report.skipped_reason = report.skipped_reason ?? "header has no `integrity.body` seal to compare.";
+  } else if (integrity.algorithm !== INTEGRITY_ALGORITHM) {
+    report.skipped_reason = report.skipped_reason ?? `integrity.algorithm "${integrity.algorithm}" is not "${INTEGRITY_ALGORITHM}"; the declared digest cannot be recomputed here.`;
+  } else {
+    report.integrity_checked = true;
+    const computed = computeBodyChecksum(doc);
+    if (computed !== integrity.body) {
+      report.integrity_drift.push({
+        algorithm: integrity.algorithm,
+        declared: integrity.body,
+        computed
+      });
+    }
+  }
+  return report;
+}
+function checkHeaderSealText(text) {
+  const noBom = text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+  return checkHeaderSeal(JSON.parse(noBom));
+}
 
 // src/index.ts
-var UPG_VERSION = "0.26.0";
+var UPG_VERSION = "0.27.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -30219,6 +30535,8 @@ export {
   backfillSlug,
   buildTypeAliases,
   canBeChildOf,
+  checkHeaderSeal,
+  checkHeaderSealText,
   coerceProductStage,
   collectSlugsForType,
   compareVersions,
@@ -30227,6 +30545,9 @@ export {
   concernFor,
   concernGatesFor,
   crossProductScope,
+  deriveCounts,
+  derivePortfolioCounts,
+  deriveSingleCounts,
   describeTreePattern,
   edgeCarriesProperties,
   evaluateAntiPatterns,