@unified-product-graph/core 0.34.0 → 0.36.0

package/dist/index.js

@@ -1199,6 +1199,19 @@ var UPG_EDGE_CATALOG = {
   product_contains_research_study: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "product", target_type: "research_study" },
   research_study_enrolls_participant: { forward_verb: "enrolls", reverse_verb: "enrolled_in", classification: "hierarchy", source_type: "research_study", target_type: "participant" },
   research_study_captures_observation: { forward_verb: "captures", reverse_verb: "captured_in", classification: "hierarchy", source_type: "research_study", target_type: "observation" },
+  // (0.35.0) Provenance for a verbatim quote: which study produced it. The
+  // quote card wanted an outbound `quote_from_research_study`; canon answers it
+  // study-first, matching the whole `research_study_*` family (enrolls ·
+  // captures · clusters_into · produces · investigates · follows · collects),
+  // so the quote renders it INBOUND on its connections rail. The `captures`
+  // verb is deliberately reused from the observation twin above: the F3
+  // duplicate gate is on the (source, target) pair, which is new, and a study
+  // captures raw material by one verb regardless of which raw shape it is.
+  // Companion: `UPG_VALID_CHILDREN.research_study` gains 'quote'. A quote may
+  // now hang from observation (raw-capture parent), insight (synthesis parent)
+  // or research_study (provenance parent) — multi-parent grammar is explicitly
+  // sanctioned, and per-INSTANCE parentage stays single via `parent_id`.
+  research_study_captures_quote: { forward_verb: "captures", reverse_verb: "captured_in", classification: "hierarchy", source_type: "research_study", target_type: "quote" },
   research_study_clusters_into_affinity_cluster: { forward_verb: "clusters_into", reverse_verb: "clustered_from", classification: "hierarchy", source_type: "research_study", target_type: "affinity_cluster" },
   research_study_produces_insight: { forward_verb: "produces", reverse_verb: "produced_by", classification: "hierarchy", source_type: "research_study", target_type: "insight" },
   research_study_investigates_research_question: { forward_verb: "investigates", reverse_verb: "investigated_by", classification: "hierarchy", source_type: "research_study", target_type: "research_question" },
@@ -1480,6 +1493,22 @@ var UPG_EDGE_CATALOG = {
   // the work into `task`; v0.7.0/UPG-571 re-canonicalised the statement
   // story_statement → user_story; see UPG_EDGE_MIGRATIONS['0.7.0'].)
   epic_specified_by_user_story: { forward_verb: "specified_by", reverse_verb: "specifies", classification: "hierarchy", source_type: "epic", target_type: "user_story" },
+  // (0.35.0) The feature-level rung of the same ladder. `epic` is OPTIONAL in
+  // UPG — `feature_decomposed_into_epic` is not mandatory — so a feature that
+  // skips the epic level had no way to reach the stories that specify it, and
+  // `user_story` had exactly one declared parent. Verb pair is cloned verbatim
+  // from the epic rung above so the two rungs read identically; it is NOT
+  // `groups`, which would invent a second verb for one relationship.
+  //
+  // This is also the reason `feature_contains_acceptance_criterion` is NOT
+  // here: with this rung the path is feature → user_story → acceptance_
+  // criterion, and a direct containment edge would be the "X_contains_Y verb
+  // that duplicates the parent link" ARCHITECTURE.md forbids.
+  //
+  // Companion: `UPG_VALID_CHILDREN.feature` gains 'user_story'. Per-instance
+  // parentage stays single (`parent_id`), so the dual declared parent is a
+  // grammar widening, not a dual-parent instance.
+  feature_specified_by_user_story: { forward_verb: "specified_by", reverse_verb: "specifies", classification: "hierarchy", source_type: "feature", target_type: "user_story" },
   user_story_verified_by_acceptance_criterion: { forward_verb: "verified_by", reverse_verb: "verifies", classification: "hierarchy", source_type: "user_story", target_type: "acceptance_criterion" },
   task_implements_user_story: { forward_verb: "implements", reverse_verb: "implemented_by", classification: "cross-domain", source_type: "task", target_type: "user_story" },
   feature_affected_by_bug: { forward_verb: "affected_by", reverse_verb: "affects", classification: "hierarchy", source_type: "feature", target_type: "bug" },
@@ -1578,6 +1607,25 @@ var UPG_EDGE_CATALOG = {
   // (graph traversal) treat 'semantic' as the catch-all for non-causal,
   // non-hierarchical relationships.
   journey_step_precedes_journey_step: { forward_verb: "precedes", reverse_verb: "follows", classification: "semantic", source_type: "journey_step", target_type: "journey_step" },
+  // (0.36.0, UPG feedback 510c4bfa) A user_flow states which user_journey it
+  // maps onto (`user_flow_maps_user_journey`) but not which of that journey's
+  // steps, in what order, it actually walks — the only recovery without this
+  // edge is inferring scope from shared screens, which both over-matches
+  // (co-located read-only steps) and under-matches (steps rendered off-screen).
+  // `journey_step` stays owned by its journey via `user_journey_contains_journey_step`;
+  // this is a reference into that ownership, not a second containment.
+  // `semantic`, not `cross-domain`: both `user_flow` and `journey_step` are in
+  // the ux_design domain, and T1.7's guardrail treats same-domain
+  // `cross-domain` edges as reclassification debt to pay down, not a pattern
+  // to extend — `journey_phase_spans_journey_step` carries that debt already;
+  // this edge does not repeat it. Same reasoning as `journey_step_precedes_journey_step`:
+  // 'semantic' is the catch-all for a non-causal, non-hierarchical, in-domain
+  // relationship. No `carries_properties`: the walked steps' own `step_order`
+  // is already the source of truth for sequence, so ordering is read off the
+  // target, not a second order system that could drift from the journey's. A
+  // flow walking steps out of journey order is a future `carries_properties`
+  // widening, not this one.
+  user_flow_walks_journey_step: { forward_verb: "walks", reverse_verb: "walked_by", classification: "semantic", source_type: "user_flow", target_type: "journey_step" },
   user_flow_routes_through_screen: { forward_verb: "routes_through", reverse_verb: "routed_in", classification: "hierarchy", source_type: "user_flow", target_type: "screen" },
   screen_renders_as_screen_state: { forward_verb: "renders_as", reverse_verb: "rendered_by", classification: "hierarchy", source_type: "screen", target_type: "screen_state" },
   need_reframed_as_design_question: { forward_verb: "reframed_as", reverse_verb: "reframes", classification: "causal", source_type: "need", target_type: "design_question" },
@@ -2576,6 +2624,16 @@ var UPG_EDGE_CATALOG = {
   team_decides_decision: { forward_verb: "decides", reverse_verb: "decided_by", classification: "hierarchy", source_type: "team", target_type: "decision" },
   decision_references_decision: { forward_verb: "references", reverse_verb: "referenced_by", classification: "cross-domain", source_type: "decision", target_type: "decision" },
   stakeholder_maps_to_persona: { forward_verb: "maps_to", reverse_verb: "mapped_by", classification: "cross-domain", source_type: "stakeholder", target_type: "persona" },
+  // (0.35.0) The stakeholder-map relation: who cares about which outcome.
+  // Deliberately a verb-only edge and NOT a `kind: 'scale'` property on a
+  // generic `stakeholder_relates_to_node` — UPG edges are payload-free outside
+  // the gated `carries_properties` set, and the MAGNITUDE of the stake is
+  // already `influence` / `interest` on the stakeholder itself. The reverse
+  // reading is what makes the pair right: "outcome matters_to stakeholder".
+  // Sits beside `persona_pursues_outcome` (the persona twin) and
+  // `product_influenced_by_stakeholder`. Retires the manifest's denormalised
+  // `stake_in` string: the subtitle renders the target outcome's title.
+  stakeholder_invested_in_outcome: { forward_verb: "invested_in", reverse_verb: "matters_to", classification: "cross-domain", source_type: "stakeholder", target_type: "outcome" },
   team_okr_aligns_with_objective: { forward_verb: "aligns_with", reverse_verb: "aligned_by", classification: "cross-domain", source_type: "team_okr", target_type: "objective" },
   team_okr_aligns_with_key_result: { forward_verb: "aligns_with", reverse_verb: "aligned_by", classification: "cross-domain", source_type: "team_okr", target_type: "key_result" },
   ceremony_involves_team: { forward_verb: "involves", reverse_verb: "involved_in", classification: "cross-domain", source_type: "ceremony", target_type: "team" },
@@ -2654,6 +2712,27 @@ var UPG_EDGE_CATALOG = {
   compliance_requirement_constrains_feature: { forward_verb: "constrains", reverse_verb: "constrained_by", classification: "cross-domain", source_type: "compliance_requirement", target_type: "feature" },
   compliance_requirement_constrains_decision: { forward_verb: "constrains", reverse_verb: "constrained_by", classification: "cross-domain", source_type: "compliance_requirement", target_type: "decision" },
   risk_manifests_as_technical_debt_item: { forward_verb: "manifests_as", reverse_verb: "manifested_by", classification: "cross-domain", source_type: "risk", target_type: "technical_debt_item" },
+  // ── Risk exposure (0.35.0) ──────────────────────────────────────────────────
+  // Typed source, wildcard target: the 16th registered polymorphic family, and
+  // structurally the "decision-to-anything" construction with `risk` in the
+  // source slot. Both are `cross-domain`, so neither enters UPG_VALID_CHILDREN
+  // and neither can be walked as containment.
+  //
+  // Why wildcard rather than typed-per-target: what a risk puts at stake is
+  // genuinely unbounded (outcome, key_result, release, service, contract,
+  // launch, metric, feature), and so is what mitigates it (decision, feature,
+  // experiment, security_control, compliance_requirement). Enumerating either
+  // side balloons the catalogue across two open sets while the endpoint carries
+  // no structural role — the exact condition ARCHITECTURE.md admits polymorphism
+  // for. The typed `security_control_mitigates_threat` stays as the
+  // security-domain edge; `risk_mitigated_by_node` is the product generalisation.
+  //
+  // These two replace three manifest fields that were properties pretending to
+  // be relations: `scope_entities` (an entity-reference list) is
+  // risk_threatens_node, and `mitigation_actions` (a top-list of action
+  // strings) is risk_mitigated_by_node. The prose `mitigation?: string` stays.
+  risk_threatens_node: { forward_verb: "threatens", reverse_verb: "threatened_by", classification: "cross-domain", source_type: "risk", target_type: "node" },
+  risk_mitigated_by_node: { forward_verb: "mitigated_by", reverse_verb: "mitigates", classification: "cross-domain", source_type: "risk", target_type: "node" },
   data_contract_governs_data_source: { forward_verb: "governs", reverse_verb: "governed_by", classification: "cross-domain", source_type: "data_contract", target_type: "data_source" },
   compliance_framework_requires_security_control: { forward_verb: "requires", reverse_verb: "required_by", classification: "cross-domain", source_type: "compliance_framework", target_type: "security_control" },
   security_audit_validates_compliance_framework: { forward_verb: "validates", reverse_verb: "validated_by", classification: "cross-domain", source_type: "security_audit", target_type: "compliance_framework" },
@@ -3940,7 +4019,12 @@ var UPG_POLYMORPHIC_EDGE_KEYS = [
   // Document transclusion (0.34.0): a document embeds any renderable node's live
   // value at a position in its prose. Open by nature rather than by an
   // enumeration nobody wanted to write out.
-  "document_transcludes_node"
+  "document_transcludes_node",
+  // Risk exposure (0.35.0): what a risk threatens, and what mitigates it.
+  // Typed source, wildcard target — the decision-to-anything construction with
+  // `risk` in the source slot. Both cross-domain, so containment is untouched.
+  "risk_threatens_node",
+  "risk_mitigated_by_node"
 ];
 var UPG_POLYMORPHIC_EDGE_FAMILIES = {
   "universal semantic verbs": ["node_informs_node", "node_constrains_node", "node_inspires_node"],
@@ -3979,7 +4063,14 @@ var UPG_POLYMORPHIC_EDGE_FAMILIES = {
   // `document_describes_*` set, which is not polymorphic at all: those are
   // enumerated edges saying a document is ABOUT a thing. Transclusion says it
   // RENDERS the thing, and the difference is the whole reason the edge exists.
-  "document transclusion": ["document_transcludes_node"]
+  "document transclusion": ["document_transcludes_node"],
+  // 0.35.0. Its own family and deliberately NOT merged into
+  // 'decision-to-anything', which it mirrors structurally. The two say different
+  // things: a decision INFLUENCES what it touches, a risk ENDANGERS what it
+  // threatens, and a partition that merged them on shape alone would assert
+  // those are one relation. Two members because exposure has two directions,
+  // and collapsing them would lose which way an edge points.
+  "risk exposure": ["risk_threatens_node", "risk_mitigated_by_node"]
 };
 var _POLY_KEY_SET = new Set(UPG_POLYMORPHIC_EDGE_KEYS);
 function isPolymorphicEdge(key) {
@@ -6544,6 +6635,378 @@ function isLegacyProductStage(stage) {
   return typeof stage === "string" && stage.toLowerCase() in LEGACY_PRODUCT_STAGES;
 }
 
+// src/catalog/entity-descriptions.ts
+var UPG_ENTITY_DESCRIPTIONS = Object.freeze({
+  // Strategy
+  product: "The product being created, the root of the graph",
+  outcome: "A desired business or user outcome",
+  objective: "A strategic goal (OKR)",
+  key_result: "A measurable result tied to an objective",
+  metric: "A unified metric that measures progress, health, or behaviour across the product",
+  metric_quality_assessment: "An assessment of whether a metric is well-defined, measurable, and aligned to a meaningful outcome.",
+  vision: "A long-term aspirational statement of the future state",
+  mission: "The purpose and reason the product exists",
+  strategic_theme: "A high-level strategic focus area for a planning period. Its own time_horizon is now deprecated: promote the period to a planning_cycle and link the two with strategic_theme_scoped_to_planning_cycle, so themes share one dated, nestable interval instead of a drifting per-theme label.",
+  initiative: "A large coordinated effort to achieve a strategic goal",
+  capability: "An ability that enables value delivery",
+  value_stream: "An end-to-end flow delivering value to the customer",
+  strategic_pillar: "A foundational principle that guides decisions",
+  strategic_question: "An open strategic question a plan must resolve (of coordination, ownership, sequencing, or which bet to place), held explicitly until a decision retires it; the strategy sibling of research_question and design_question",
+  assumption: "A belief taken as true that underpins a strategy",
+  decision: "A recorded decision with context, rationale, and consequences",
+  constraint: "A limit, requirement, or ceiling the product must respect, whether a self-imposed principle or an externally imposed boundary",
+  // User
+  persona: "An archetype representing a user segment",
+  job: "Job To Be Done: what the user is trying to accomplish",
+  need: "A user need, pain, desire, or constraint",
+  desired_outcome: "What the user hopes to achieve",
+  job_step: "A discrete step within a Job To Be Done",
+  switching_cost: "A barrier preventing users from switching alternatives",
+  // Discovery
+  opportunity: "A validated gap worth solving",
+  solution: "A proposed approach to address an opportunity",
+  feasibility_study: "An assessment of technical or business viability",
+  design_sprint: "A time-boxed sprint to prototype and validate ideas",
+  // Validation
+  hypothesis: "A testable belief about a solution",
+  experiment: "A test designed to validate a hypothesis",
+  experiment_plan: "An experiment plan describing the hypothesis, setup, success criteria, and methodology before a test runs.",
+  experiment_run: "An execution instance of an experiment that records actual conditions, observations, and raw results.",
+  learning: "An insight gained from an experiment",
+  test_plan: "A structured plan for testing a hypothesis",
+  evidence: "Data supporting or refuting a hypothesis",
+  research_plan: "A plan for gathering evidence to validate a draft entity",
+  // Market Intelligence
+  competitor: "A competing product or company",
+  competitor_feature: "A feature offered by a competitor",
+  market_trend: "An emerging trend in the market",
+  market_segment: "A distinct group of potential customers",
+  competitive_analysis: "A structured analysis of the competitive landscape",
+  classification_axis: "A single dimension in a competitive classification matrix that defines one axis of comparison across alternatives.",
+  classification_value: "A position or value on a classification axis, representing where one option lands on that dimension.",
+  competitor_signal: "An observed competitor move or datapoint (a pricing change, launch, or hire) that feeds competitive analysis",
+  // User Research
+  research_study: "A planned research activity",
+  insight: "A synthesised finding from research",
+  participant: "A person participating in research",
+  observation: "A specific behaviour or statement observed",
+  quote: "A direct quote from a research participant",
+  affinity_cluster: "A group of related observations",
+  research_question: "A question guiding a research study",
+  interview_guide: "A structured guide for conducting interviews",
+  survey_response: "A response to a survey instrument",
+  // Experience Design
+  user_journey: "An end-to-end map of a user experience",
+  journey_step: "A single step in a user journey",
+  journey_phase: "A named phase in a user journey that groups a sequence of actions the user performs to reach a milestone.",
+  journey_action: "A single step a user takes within a journey phase, the atomic unit of observable user behaviour.",
+  user_flow: "A navigation path through the product",
+  screen: "A distinct screen or view in the product",
+  screen_state: "A specific state of a screen (e.g., empty, loading, error)",
+  surface: "A place inside a screen, the features that occupy it, and the rule that decides who wins it",
+  design_question: "An open design problem to explore",
+  design_concept: "A possible design direction or approach",
+  prototype: "An interactive mockup for testing",
+  wireframe: "A low-fidelity structural layout",
+  annotation: "A note or markup on a design artifact",
+  interaction_spec: "A specification for an interaction behaviour",
+  // Design System
+  design_component: "A reusable UI component",
+  design_token: "A design token (colour, spacing, typography)",
+  design_system: "The root design system entity",
+  design_pattern: "A documented design pattern",
+  design_guideline: "A design usage guideline",
+  // Brand Identity
+  brand_identity: "The root brand identity entity",
+  brand_colour: "A brand colour definition",
+  brand_typography: "Brand typography specifications",
+  brand_voice: "Brand voice and tone guidelines",
+  brand_logo: "A brand logo or mark",
+  brand_imagery: "Brand imagery and photography guidelines",
+  // Product Specification
+  feature: "A product capability or feature",
+  feature_area: "A grouping of related features",
+  epic: "A large body of work that can be broken into stories",
+  user_story: `A user's goal and the value they expect, in the "As a\u2026 I want\u2026 So that\u2026" format. Now also a first-class plannable unit (priority, effort, assignee, due_date) that schedules into a planning_cycle, and it round-trips an external board's column via workflow_state.`,
+  acceptance_criterion: "A condition that must be met for a story to be done",
+  release: "A shipped version of the product",
+  task: "A unit of work within a story or epic",
+  bug: "A defect or unexpected behaviour",
+  roadmap: "A strategic plan of features and milestones",
+  roadmap_item: "An item on the product roadmap",
+  theme: "A strategic grouping of related features",
+  roadmap_theme: "A customer problem used as the organising unit of a roadmap",
+  changelog: "A record of changes shipped in a release",
+  planning_cycle: "The cadence axis of a plan: a dated interval a team plans in, be it a sprint, iteration, quarter, or program increment. Cycles self-nest, so a fine iteration sits inside a coarse period to form a granularity ladder.",
+  configuration_axis: "A named dimension along which the product's composition differs: a feature flag, a plan tier, a permission level, a beta programme. The stored graph is the union of the family; one configuration is a projection of it.",
+  // Engineering
+  bounded_context: "A DDD bounded context defining a service boundary",
+  service: "A deployable service or microservice",
+  domain_event: "An event published when something happens in the domain",
+  api_contract: "An API contract or specification",
+  technical_debt_item: "A known piece of technical debt",
+  feature_flag: "A feature toggle for controlled rollout",
+  deployment: "A deployment event",
+  aggregate: "A DDD aggregate root",
+  domain_entity: "A DDD domain entity: a core object with a distinct identity and lifecycle inside a bounded context",
+  value_object: "A DDD value object",
+  command: "A DDD command (write operation)",
+  read_model: "A DDD read model (query projection)",
+  api_endpoint: "A specific API endpoint",
+  database_schema: "A database schema definition",
+  queue_topic: "A message queue topic",
+  build_artifact: "A build output (binary, container image)",
+  code_repository: "A source code repository",
+  library_dependency: "A third-party library dependency",
+  integration_pattern: "An integration pattern (saga, event sourcing, etc.)",
+  external_api: "An external API consumed by the product",
+  data_flow: "A data flow between systems",
+  investigation: "An investigation into an issue or incident",
+  root_cause: "An identified root cause of an issue",
+  symptom: "A symptom of a problem",
+  fix: "A fix applied to resolve an issue",
+  // Growth
+  funnel: "A conversion funnel tracking user progression",
+  funnel_step: "A stage within a conversion funnel",
+  acquisition_channel: "A channel through which users are acquired",
+  growth_campaign: "A growth-focused campaign",
+  cohort: "A group of users sharing a common characteristic",
+  behavioral_segment: "A user segment based on behaviour",
+  growth_loop: "A self-reinforcing growth cycle",
+  variant: "A variant in an A/B test",
+  attribution_model: "A model for attributing conversions to touchpoints",
+  // Business Model
+  business_model: "The business model canvas or definition",
+  value_proposition: "A unique value offered to customers",
+  revenue_stream: "A source of revenue",
+  pricing_tier: "A pricing tier or plan",
+  cost_structure: "A cost category or structure",
+  unit_economics: "Per-unit economic metrics (CAC, LTV, etc.)",
+  partnership: "A strategic partnership",
+  key_resource: "A key resource required by the business",
+  key_activity: "A key activity the business performs",
+  target_customer_segment: "A target customer segment",
+  customer_relationship: "A type of customer relationship",
+  distribution_channel: "A channel for delivering value to customers",
+  // Go-To-Market
+  gtm_strategy: "A go-to-market strategy",
+  ideal_customer_profile: "The ideal customer profile (ICP)",
+  positioning: "Product positioning statement",
+  messaging: "Messaging framework and key messages",
+  launch: "A product launch event",
+  content_strategy: "A content strategy for thought leadership",
+  sales_motion: "A repeatable sales motion",
+  competitive_battle_card: "A competitive battle card for sales enablement",
+  demand_gen_program: "A demand generation program",
+  territory: "A sales territory",
+  objection: "A common sales objection",
+  rebuttal: "A rebuttal to a sales objection",
+  proof_point: "Evidence supporting a sales claim",
+  // Team & Organisation
+  team: "A cross-functional team",
+  role: "A role within a team",
+  stakeholder: "A person with influence over the product",
+  team_okr: "A team-level OKR",
+  retrospective: "A team retrospective",
+  dependency: "A cross-team or system dependency",
+  department: "An organisational department",
+  skill: "A skill or competency within a team",
+  ceremony: "A recurring team ritual (standup, planning)",
+  capacity_plan: "A plan for allocating team capacity",
+  person: "A named individual (owner, stakeholder, or participant) referenced across the graph",
+  // Data & Analytics
+  data_source: "A data source or integration",
+  event_schema: "An event schema for tracking",
+  dashboard: "An analytics dashboard",
+  data_model: "A data model or schema",
+  data_quality_rule: "A data quality validation rule",
+  data_product: "A curated, reusable data asset",
+  data_pipeline: "An automated pipeline for data transformation",
+  data_lineage: "A record of data origin and transformations",
+  glossary_term: "A defined term for shared understanding",
+  data_domain: "A logical grouping of related data assets",
+  report: "A structured analytical report",
+  // Customer Success
+  support_ticket: "Customer support request or issue",
+  customer_feedback: "Voice-of-customer input",
+  churn_reason: "Why a customer left",
+  customer_health_score: "A composite health score for a customer",
+  playbook: "A standard operating procedure for CS",
+  service_level_agreement: "A service level agreement with customers",
+  customer_journey_stage: "A stage in the post-sale customer journey",
+  touchpoint: "A customer interaction touchpoint",
+  success_milestone: "A customer success milestone",
+  service_blueprint: "A blueprint of the full service delivery",
+  // Content & Knowledge
+  content_piece: "A piece of content (article, video, etc.)",
+  knowledge_base_article: "A knowledge base article",
+  brand_asset: "A brand asset (logo, image, etc.)",
+  internal_doc: "An internal documentation page",
+  prompt_template: "A reusable prompt template",
+  content_calendar: "A content publication calendar",
+  content_theme: "A thematic grouping for content",
+  documentation_template: "A template for documentation",
+  document: "A general-purpose document",
+  // Legal
+  legal_entity: "A legal entity (company, subsidiary)",
+  ip_asset: "An intellectual property asset",
+  contract: "A legal contract",
+  contract_clause: "A clause within a contract",
+  privacy_policy: "A privacy policy",
+  // Compliance
+  compliance_requirement: "A compliance requirement",
+  risk: "A risk to the product or business",
+  data_contract: "A data-sharing contract",
+  audit_log_policy: "An audit logging policy",
+  compliance_framework: "A compliance framework (SOC 2, GDPR, etc.)",
+  security_audit: "A security audit",
+  // DevOps & Platform
+  service_level_indicator: "A service level indicator (SLI)",
+  service_level_objective: "A service level objective (SLO)",
+  error_budget: "An error budget for a service",
+  incident: "A production incident",
+  postmortem: "A post-incident review",
+  runbook: "A runbook for incident response",
+  monitor: "A monitoring check",
+  alert_rule: "An alerting rule",
+  ci_pipeline: "A CI/CD pipeline",
+  release_strategy: "A release strategy (canary, blue-green, etc.)",
+  on_call_rotation: "An on-call rotation schedule",
+  infrastructure_component: "An infrastructure component (server, CDN, etc.)",
+  // Security
+  threat_model: "A threat model for the system",
+  threat: "A specific security threat",
+  vulnerability: "A known vulnerability",
+  security_control: "A security control or mitigation",
+  security_policy: "A security policy",
+  penetration_test: "A penetration test",
+  security_review: "A security review",
+  data_classification: "A data classification level",
+  access_policy: "An access control policy",
+  // Accessibility
+  a11y_standard: "An accessibility standard (WCAG, Section 508)",
+  a11y_guideline: "An accessibility guideline",
+  a11y_audit: "An accessibility audit",
+  a11y_issue: "An accessibility issue",
+  a11y_annotation: "An accessibility annotation on a design",
+  // Quality Assurance
+  test_suite: "A suite of related tests",
+  test_case: "An individual test case",
+  qa_session: "An exploratory QA session",
+  regression_test: "A regression test",
+  test_coverage_report: "A test coverage report",
+  test_environment: "A testing environment",
+  test_result: "A test execution result",
+  // Customer Feedback
+  feedback_program: "A structured feedback collection program",
+  feature_request: "A user-submitted feature request",
+  feedback_vote: "A vote on a feature request or feedback item",
+  nps_campaign: "A Net Promoter Score survey campaign",
+  user_advisory_board: "A panel of users providing ongoing feedback",
+  beta_program: "A beta testing program",
+  feedback_theme: "A recurring theme across feedback items",
+  // Pricing & Packaging
+  pricing_strategy: "An overarching pricing strategy",
+  package: "A bundled package of features at a price point",
+  discount_strategy: "A strategy for offering discounts",
+  trial_config: "Configuration for a free trial",
+  paywall: "A paywall gating premium features",
+  // AI & Machine Learning
+  ai_model: "An AI or ML model used within the product",
+  prompt_version: "A version of a prompt template",
+  eval_benchmark: "A benchmark for evaluating AI quality",
+  eval_run: "An evaluation run against a benchmark",
+  ai_cost_tracker: "A tracker for AI inference costs",
+  hallucination_report: "A report of an AI hallucination",
+  ai_guardrail: "A guardrail for AI safety",
+  model_comparison: "A comparison between AI models",
+  ai_experiment: "An AI-focused experiment",
+  ai_dataset: "A dataset for AI training or evaluation",
+  ai_trace: "An AI inference trace",
+  // Workflows & Agents
+  workflow_template: "A reusable workflow template",
+  workflow_run: "An execution of a workflow",
+  agent_definition: "An autonomous agent definition",
+  agent_session: "An agent working session",
+  review_gate: "A human review checkpoint in a workflow",
+  approval_record: "A record of an approval decision",
+  agent_skill: "A capability of an agent",
+  agent_hook: "A trigger connecting an agent to an event",
+  workflow_artifact: "An output artifact from a workflow run",
+  agent_task: "A discrete unit of agent work",
+  // Portfolio
+  organization: "The top-level organisational entity",
+  portfolio: "A grouping of products by strategic axis",
+  product_area: "A grouping of products by organisational axis",
+  // Sales & Revenue
+  account: "A customer account",
+  contact: "A person within an account",
+  lead: "An inbound lead",
+  deal: "An active sales opportunity",
+  pipeline_sales: "A sales pipeline",
+  pipeline_stage: "A stage in the sales pipeline",
+  quote_document: "A formal quote document",
+  subscription: "A recurring subscription",
+  invoice: "An invoice for billing",
+  forecast: "A revenue forecast",
+  // Program Management
+  program: "A program coordinating multiple projects",
+  project: "A project within a program",
+  milestone: "A key date or achievement",
+  risk_register: "A register of project risks",
+  change_request: "A request to change project scope",
+  deliverable: "A deliverable from a project",
+  resource_allocation: "An allocation of team capacity",
+  status_report: "A project status report",
+  // Marketing
+  marketing_strategy: "A marketing strategy",
+  marketing_channel: "A marketing channel",
+  marketing_campaign_plan: "A marketing campaign plan",
+  email_sequence: "An email nurture sequence",
+  social_post: "A social media post",
+  seo_keyword: "An SEO keyword target",
+  ad_creative: "An ad creative",
+  press_release: "A press release",
+  event: "A marketing event",
+  community_initiative: "A community engagement initiative",
+  // Localisation
+  locale: "A supported locale (language + region)",
+  translation_key: "A translatable string key",
+  translation_bundle: "A bundle of translation keys",
+  locale_config: "Per-locale configuration settings",
+  cultural_adaptation: "A region-specific cultural adaptation",
+  regional_pricing: "Location-based pricing",
+  // Customer Education
+  education_program: "A customer education program",
+  tutorial: "A step-by-step tutorial",
+  walkthrough: "A guided product walkthrough",
+  webinar: "A live or recorded webinar",
+  certification: "A certification program",
+  help_video: "A help video",
+  learning_path: "A structured learning path",
+  // Partners & Ecosystem
+  partner_program: "A partner program",
+  partner_tier: "A partner tier level",
+  api_ecosystem: "An API ecosystem",
+  marketplace_listing: "A marketplace listing",
+  developer_portal: "A developer portal",
+  integration_partner: "An integration partner",
+  partner_revenue_share: "A partner revenue sharing arrangement",
+  // Foundations
+  operating_lifecycle: "A canonical, ordered (often cyclic) operating process a product's journey phases map onto",
+  operating_stage: "One ordered stage of an operating_lifecycle",
+  specification: "A canonical open standard or specification that primitives and products conform to",
+  primitive: "A canonical reusable building block defined by a specification",
+  // Workspace
+  workspace: "A spatial thinking space for arranging entities",
+  framework_exercise: "A recorded run of a product framework (RICE, OST, and the like) over specific entities, holding its inputs and outputs",
+  composition: "A published arrangement of graph entities that has an identity of its own: a gallery, a board, a deck. Membership can be derived by running its query, position is authored by a person, and both are stored because both are real.",
+  capture: "A dated, hashed rendition of something already in the graph: a screenshot of a surface, a PDF of a report, an export of a canvas. The subject stays a graph node; the capture records what it looked like at one moment, and the content hash says whether it still does."
+});
+function getEntityDescription(type) {
+  return UPG_ENTITY_DESCRIPTIONS[type];
+}
+
 // src/shapes/base-node.ts
 var BASE_NODE_FIELD_PRESENCE = {
   id: true,
@@ -6970,6 +7433,11 @@ var UPG_VALID_CHILDREN = {
   competitor: ["competitor_feature", "competitor_signal"],
   classification_axis: ["classification_value"],
   // ── UX Research hierarchy ───────────────────────────────────────────────────
+  // (0.35.0) 'quote' added: a study is the provenance parent of the verbatim
+  // quotes it captured, pairing with `research_study_captures_quote`. A quote
+  // now has three declared parents — observation (raw capture), insight
+  // (synthesis) and research_study (provenance) — which is multi-parent
+  // GRAMMAR; per-instance parentage stays single via `parent_id`.
   research_study: [
     "participant",
     "observation",
@@ -6977,7 +7445,8 @@ var UPG_VALID_CHILDREN = {
     "research_question",
     "interview_guide",
     "insight",
-    "survey_response"
+    "survey_response",
+    "quote"
   ],
   observation: ["quote"],
   // F6 (UPG-672): affinity_cluster owns the observations it groups, in addition
@@ -7034,7 +7503,12 @@ var UPG_VALID_CHILDREN = {
   // story_task collapsed into canonical task. feature now owns
   // task directly; story-derived tasks implement user_story via
   // task_implements_user_story edge.
-  feature: ["epic", "bug", "task"],
+  // (0.35.0) 'user_story' added, pairing with `feature_specified_by_user_story`.
+  // The epic rung is optional in UPG, so a feature that skips it could not
+  // reach the stories that specify it and `user_story` had a single declared
+  // parent. Same widening shape as the 0.23.0 epic twins: an existing leaf type
+  // gains a second, SHALLOWER parent, verbs inherited from the deeper edge.
+  feature: ["epic", "bug", "task", "user_story"],
   feature_area: ["feature", "feature_area"],
   // epic owns user_story (the templated promise) and, mirroring feature, may
   // also directly contain bug/task — heterogeneous imported tickets that belong
@@ -7820,6 +8294,37 @@ var UPG_SCALES = {
     // the existing classify-edge population, so nothing needs re-stamping.
     friendly_aliases: { low: 2, medium: 3, high: 4 }
   },
+  // ── Likelihood ─────────────────────────────────────────────────────────────
+  /**
+   * (0.35.0) How likely a future event is to occur.
+   *
+   * Added because the nine pre-existing ladders had no probability ladder, and
+   * `likelihood` was resolving to `confidence_5` — which is EPISTEMIC. Confidence
+   * says how sure you are of a judgment ("Guessing → Data-backed"); likelihood
+   * says how probable the event is. A risk you are certain about and a risk that
+   * is certain to happen are different facts, and one ladder cannot hold both.
+   *
+   * Vocabulary is ISO 31000's, which is also what `risk.likelihood`,
+   * `threat.likelihood` and the Notion fixtures already say in prose.
+   *
+   * Polarity is `low-is-good` (rendered by the design system's direction map,
+   * which is where numeric-scale polarity lives): 5 on this ladder is bad news.
+   */
+  likelihood_5: {
+    id: "likelihood_5",
+    label: "Likelihood (5-point)",
+    description: "How likely this event is to occur",
+    min: 1,
+    max: 5,
+    steps: 5,
+    points: [
+      { value: 1, label: "Rare", description: "Would be surprising; no known precedent" },
+      { value: 2, label: "Unlikely", description: "Could happen, but not expected" },
+      { value: 3, label: "Possible", description: "Might happen; roughly even odds" },
+      { value: 4, label: "Likely", description: "Expected to happen absent intervention" },
+      { value: 5, label: "Almost certain", description: "Expected to happen; plan for it" }
+    ]
+  },
   // ── Effort ─────────────────────────────────────────────────────────────────
   effort_5: {
     id: "effort_5",
@@ -7892,12 +8397,17 @@ var PROPERTY_SCALE_MAP = {
   // discovery, validation, sales, product-spec
   current_confidence: "confidence_5",
   // validation/hypothesis (UPG-579 Option B)
-  likelihood: "confidence_5",
-  // market/risk (UPG-579 Option B)
   probability: "confidence_5",
   // sales/forecast (UPG-579 Option B)
   qualification_score: "confidence_5",
   // sales/deal — how confident the qualification is (0.24.0)
+  // ── Likelihood ───────────────────────────────────────────────────────────
+  // (0.35.0) Moved off confidence_5. `likelihood` is how probable the event is,
+  // not how well-evidenced the judgment is; the two were sharing one ladder
+  // because no probability ladder existed. Carries market/risk (`risk`,
+  // `market_trend`) and `security.threat.likelihood` in one line.
+  likelihood: "likelihood_5",
+  // compliance/risk, security/threat, market
   // ── Effort ───────────────────────────────────────────────────────────────
   effort: "effort_5",
   // discovery
@@ -7927,9 +8437,18 @@ var PROPERTY_SCALE_MAP = {
   //   rarity   : VRIO distinctiveness; no canonical named scale fits.
   //   strength : deprecated (validation/evidence; superseded by weight).
 };
+var PROPERTY_SCALE_MAP_BY_ENTITY = {
+  risk: {
+    // Severity of consequences, not magnitude of benefit. See above.
+    impact: "severity_5",
+    // The DEPRECATED spelling of `likelihood`, held on the same ladder as its
+    // replacement for the length of the deprecation window. See above.
+    probability: "likelihood_5"
+  }
+};
 var DEFAULT_SCALE_ID = "scale_5";
-function getPropertyDefaultScale(_entityType, propertyName) {
-  return PROPERTY_SCALE_MAP[propertyName] ?? DEFAULT_SCALE_ID;
+function getPropertyDefaultScale(entityType, propertyName) {
+  return PROPERTY_SCALE_MAP_BY_ENTITY[entityType]?.[propertyName] ?? PROPERTY_SCALE_MAP[propertyName] ?? DEFAULT_SCALE_ID;
 }
 function getPropertiesForScale(scaleId) {
   return Object.entries(PROPERTY_SCALE_MAP).filter(([, id]) => id === scaleId).map(([property]) => property);
@@ -8020,6 +8539,29 @@ var UPG_ENUM_SCALES = {
       { value: "guideline", label: "Guideline", description: "Recommendation: encouraged and expected in most cases, but not enforced." }
     ]
   },
+  // ── EngagementPosture ────────────────────────────────────────────────
+  /**
+   * (0.35.0) The third axis of stakeholder canon, beside the power/interest
+   * grid `influence` / `interest` carry. Those two say how much weight a
+   * stakeholder has and how much they care; neither says which WAY they lean,
+   * and "who blocks this?" is the question a stakeholder map is drawn to answer.
+   *
+   * `tone_direction: 'high-is-good'` reading champion → blocker: the first
+   * value is the desirable end, matching HealthStatus's convention.
+   */
+  EngagementPosture: {
+    id: "EngagementPosture",
+    label: "Engagement posture",
+    description: "Which way a stakeholder leans on the thing at hand: actively for it, against it, or neither.",
+    tone_direction: "high-is-good",
+    values: [
+      { value: "champion", label: "Champion", description: "Actively advocates for it and spends their own capital doing so." },
+      { value: "supporter", label: "Supporter", description: "In favour and will say so when asked, but does not drive it." },
+      { value: "neutral", label: "Neutral", description: "No position taken; neither helps nor hinders." },
+      { value: "skeptic", label: "Skeptic", description: "Unconvinced and voices objections, but is not blocking." },
+      { value: "blocker", label: "Blocker", description: "Actively opposes, and holds enough leverage to stop it." }
+    ]
+  },
   // ── ProxyConfidence ─────────────────────────────────────────────────
   ProxyConfidence: {
     id: "ProxyConfidence",
@@ -8532,6 +9074,62 @@ function getDeprecatedTypes() {
   return deprecated;
 }
 var UPG_PROPERTY_MIGRATIONS = {
+  // ── v0.35.0: risk.probability → risk.likelihood, STAGED ─────────────────────
+  //
+  // Deliberately EMPTY, and the emptiness is the design rather than an omission.
+  // The rename is staged: `RiskProperties.probability` is kept, marked
+  // `@deprecated since="0.35.0" removeIn="1.0.0"`, and still read. 0.35.0 changes
+  // what writers emit (`likelihood`) and what readers prefer; it changes no
+  // stored bytes, so there is nothing for a load-time rule to do. A graph
+  // written before 0.35.0 carries `probability` and no `likelihood` and reads
+  // correctly — which is what staging BUYS, and a rule here would spend it.
+  //
+  // Three reasons there is no executable rule, in order of weight:
+  //
+  //  1. A staged deprecation that rewrites data is not staged. The point of the
+  //     `epic.estimate` → `effort` pattern this follows is that both names live
+  //     through the window and the consumer chooses; migrating the key on load
+  //     would end the window on the first read and break any reader still
+  //     asking for the old name.
+  //  2. The executable step belongs at the REMOVAL version, not here. That is
+  //     the two-step the `removeIn="0.5.0"` properties followed: declared
+  //     deprecated with a deadline at 0.4.0, dropped by `drop_props` rules in
+  //     the '0.5.0' block below. `probability` is scheduled for the same
+  //     treatment at 1.0.0.
+  //  3. No kind fits, and inventing one would be the larger change. Checked
+  //     against the APPLIER, not just the type union:
+  //       - `drop_props` deletes, which is the 1.0.0 step, not this one.
+  //       - `lift_property_to_top_level` targets `UPGBaseNode`, and `likelihood`
+  //         is a property, not a top-level field.
+  //       - `rename_top_level` renames a top-level field, same mismatch.
+  //       - `remap_property_value` is the near miss and still misses twice: it
+  //         `break`s unless `typeof oldValue === 'string'` (these values are
+  //         `UPGAssessment` objects, or bare numbers in older graphs), and its
+  //         `to_property` split OVERWRITES the source with `reset_value`, which
+  //         is precisely the staging this release is buying.
+  //       - `reshape_value_to_assessment` wraps a bare number on a named scale;
+  //         it does not move a key.
+  //     The edge-side `kind: 'rename'` (UPG_EDGE_MIGRATIONS, e.g. 0.8.0's
+  //     `theme_groups_feature` -> `roadmap_theme_groups_feature`) renames an
+  //     EDGE TYPE across instances and has no property-key analogue. Adding one
+  //     is new spec surface: a ratified decision, not a side effect of one
+  //     property rename.
+  //
+  // The scale moves ride along and need no rule either. `PROPERTY_SCALE_MAP`
+  // resolves `likelihood` to `likelihood_5` (which carries `threat.likelihood`
+  // off `confidence_5` in the same line, since the map is keyed by name) and
+  // `PROPERTY_SCALE_MAP_BY_ENTITY` resolves `risk.impact` to `severity_5`. Both
+  // resolve at READ time, and an assessment only overrides them by PINNING a
+  // `scale_id` on the stored value. Measured across all 36 `.upg` files in the
+  // repo: zero assessments pin a `scale_id` on `likelihood`, `probability` or
+  // `impact`, so there is nothing stamped to re-stamp. One that does pin a
+  // `scale_id` keeps it, by the existing contract.
+  //
+  // What lands at 1.0.0, written down now so it is not rediscovered:
+  //   { kind: 'drop_props', type: 'risk', drop_props: ['probability'],
+  //     reason: '1.0.0: risk.probability was @deprecated since 0.35.0 with
+  //              removeIn="1.0.0"; superseded by `likelihood` on likelihood_5.' }
+  "0.35.0": [],
   "0.32.0": [
     // C3 — archive becomes a base-node axis. WorkspaceProperties.archived /
     // archived_at shipped the orthogonal-archive idea for exactly one type;
@@ -13936,10 +14534,23 @@ var UPG_PROPERTY_SCHEMA = {
   // RiskProperties: Risk.
   risk: {
     risk_type: { type: "string", enum: ["technical", "business", "legal", "security", "operational", "program"], description: "Domain the risk belongs to. The single kind axis for `risk`: there is no second classification vocabulary. `program` added in v0.26.0 so the retired `risk_item` (Program Management) type has a home on the canonical `risk` after consolidation, rather than a parallel `risk_domain` field free to drift from this one." },
+    likelihood: {
+      type: "assessment",
+      scale_id: "likelihood_5",
+      description: "How likely this risk is to materialise. Rated on `likelihood_5` (Rare \u2192 Almost certain).",
+      notes: 'Canonical name since 0.35.0, superseding `probability` below. Three reasons, in order of weight. (1) `probability` was one name for two incompatible types (`UPGAssessment` here, a bare `number` on `forecast.probability`), and `PROPERTY_SCALE_MAP` is keyed by name alone, so a sales percentage and a risk judgment resolved to the same ladder. (2) `likelihood` is already the spec\'s own word: the RISK_ITEM lifecycle prose says "Likelihood and impact have been evaluated", and `threat.likelihood` has been a `UPGAssessment` all along: one name, one type, one ladder. (3) ISO 31000 says likelihood. The ladder moved with the name: `likelihood_5` is new in 0.35.0 because no probability ladder existed and `confidence_5` is epistemic. It says how sure the assessor is, not how likely the event is.',
+      properties: {
+        value: { type: "number", description: "The numeric value, used for computation." },
+        label: { type: "string", description: "The qualitative label (what the assessor meant)." },
+        scale_id: { type: "string", description: "Which assessment scale this was rated on (optional)." },
+        normalized: { type: "number", description: "Normalized 0-1 value for cross-tool comparison (optional)." }
+      },
+      required: ["value", "label"]
+    },
     probability: {
       type: "assessment",
-      scale_id: "confidence_5",
-      description: "How likely this risk is to materialise (1 = unlikely, 5 = near certain)",
+      scale_id: "likelihood_5",
+      description: 'How likely this risk is to materialise (1 = unlikely, 5 = near certain). @deprecated since="0.35.0" removeIn="1.0.0". Use `likelihood`, which is the spec\'s own word for this in the risk lifecycle and on `threat`. Both names resolve to the same `likelihood_5` ladder for the length of the deprecation window (`PROPERTY_SCALE_MAP_BY_ENTITY.risk.probability`, Captain-ratified 2026-08-22): a deprecated field that renders on a DIFFERENT ladder from its replacement would make one stored 4 read "Confident" under the old name and "Likely" under the new one, which is the data changing meaning at the rename, which is the exact thing staging exists to prevent. `forecast.probability` is untouched and stays on `confidence_5`. STAGED, not renamed. The field is KEPT and still read: 0.35.0 changes what writers emit and what readers prefer, and changes NO stored bytes. A graph written before 0.35.0 carries `probability` and no `likelihood`, and reads correctly, which is the whole point of staging it. Writers: emit `likelihood`. Readers: prefer `likelihood`, fall back to `probability`. The fallback is a CONTRACT on consumers, not executable spec machinery, exactly as it is for `epic.estimate` \u2192 `effort`. `removeIn="1.0.0"` is a deadline, not a wish: at 1.0.0 this field is dropped by a `drop_props` rule in `UPG_PROPERTY_MIGRATIONS`, the same two-step the `removeIn="0.5.0"` properties followed (declared at 0.4.0, dropped by the 0.5.0 rules). Until then there is deliberately no executable rule: see the `\'0.35.0\'` block in `grammar/migrations.ts`.',
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -13950,8 +14561,9 @@ var UPG_PROPERTY_SCHEMA = {
     },
     impact: {
       type: "assessment",
-      scale_id: "impact_5",
-      description: "Severity of consequences if the risk materialises (1 = negligible, 5 = catastrophic)",
+      scale_id: "severity_5",
+      description: "Severity of consequences if the risk materialises. Rated on `severity_5` (Mild inconvenience \u2192 Blocker), NOT the benefit-framed `impact_5`.",
+      notes: "The ladder is set by `PROPERTY_SCALE_MAP_BY_ENTITY.risk.impact` (0.35.0), the per-entity override layer. `impact` legitimately means magnitude of BENEFIT on discovery and market entities, where high is good; on a risk it means severity of harm, where high is bad. Sharing `impact_5` rendered a catastrophic risk green.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -13960,7 +14572,7 @@ var UPG_PROPERTY_SCHEMA = {
       },
       required: ["value", "label"]
     },
-    mitigation: { type: "string", description: "Planned or implemented mitigation strategy" }
+    mitigation: { type: "string", description: "Planned or implemented mitigation strategy, as prose.", notes: "Prose only. A structured list of mitigating ACTIONS is a set of edges: `risk_mitigated_by_node` (0.35.0), pointing at the decisions, features and experiments that actually do the mitigating; a string array of them is unqueryable by construction. Likewise, what the risk puts at stake is `risk_threatens_node`, not a scope-list property." }
   },
   // RiskRegisterProperties: Risk register.
   risk_register: {
@@ -14214,7 +14826,9 @@ var UPG_PROPERTY_SCHEMA = {
         normalized: { type: "number", description: "Normalized 0-1 value for cross-tool comparison (optional)." }
       },
       required: ["value", "label"]
-    }
+    },
+    engagement_posture: { type: "string", enum: ["champion", "supporter", "neutral", "skeptic", "blocker"], description: "Which way this stakeholder leans: actively for, actively against, or neither. The third axis of the stakeholder model (0.35.0), beside the power/interest grid `influence` and `interest` describe.", notes: "`influence` and `interest` are magnitudes and carry no direction: a high-influence, high-interest stakeholder can be the strongest champion or the one who kills it, and the grid renders them identically. This closed enum is what makes \"who blocks this?\" a query rather than a reading exercise. Pairs with `UPG_ENUM_SCALES.EngagementPosture`. Posture is about the person's stance; it is NOT delivery health, which belongs to work items, and NOT the relationship's operational state." },
+    engagement_cadence: { type: "string", enum: ["continuous", "hourly", "daily", "weekly", "monthly", "quarterly", "yearly", "on_demand", "other"], description: "How often this stakeholder is engaged. Uses the shared `Cadence` scale.", notes: 'Typed as `Cadence` rather than free text on purpose: v0.4.0 introduced that enum precisely to retire strings like `"2x/week"`, and a cadence that cannot be compared across stakeholders cannot answer "who have we not spoken to this quarter?". WHERE you meet them (the channel) is an app-level concern and is deliberately not modelled here.' }
   },
   // StatusReportProperties: Status report.
   status_report: {
@@ -14290,7 +14904,11 @@ var UPG_PROPERTY_SCHEMA = {
     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: on a contested surface it means nobody decided. @example "Highest priority wins; ties break to the most recently updated."', notes: "An empty or absent rule on a contested surface is exactly what `contended-surface-without-arbitration` detects. Do not fill it in with a placeholder to silence the check: the check exists to find the unrecorded decision, and a placeholder hides it without settling anything. The field is overloaded across composition modes, which is worth knowing before writing one. On an `exclusive` surface it records DISPLACEMENT (who is not rendered). On an `additive` surface everyone fits, so what it records is ORDER. Only the displacement reading is what the contention detector reads." },
     arbitration_state: { type: "string", enum: ["enforced_documented", "enforced_undocumented", "safe_by_coincidence", "none", "no_contention_by_design"], description: "Whether the arbitration answer is enforced, written down, both, neither, or not owed at all. Leaving the field unset means unassessed, and always did.", notes: 'The separations are the whole point of the field, because absence alone conflates four situations with four different remediations: "enforced in code but never transcribed" is ten minutes of typing, "never decided" is a design meeting, "safe only because nothing has collided yet" is the dangerous one, and "nothing to decide, the occupants never compete" is a chained surface, which owes no arbitration rule at all.' },
-    extensibility: { type: "string", enum: ["closed", "plugin_registerable", "user_configurable"], description: "Who may add occupants to the surface." },
+    extensibility: { type: "string", enum: ["closed", "plugin_registerable", "user_configurable"], description: "Who may add occupants to the surface. @deprecated since 0.36.0, removeIn 1.0.0. Use `extension_mechanism` / `extension_audience` / `extension_scope` / `extension_point`: this single enum collapses four independent facts (mechanism, audience, scope, and the named API entry point) into one value, which forces false `closed` readings on surfaces that are overridable through a mechanism the enum has no room to name. STAGED, not renamed: the field is kept and still read, no stored bytes change. There is no `PROPERTY_SCALE_MAP_BY_ENTITY` entry for this one: unlike `risk.probability` \u2192 `likelihood_5`, this is a structural split with no scale to remap onto, so no machine migration ships; re-modelling a surface's real mechanism/audience/scope is a judgement call, same as promoting `objective.timeframe` to a `planning_cycle` node." },
+    extension_mechanism: { type: "string", enum: ["none", "component_wrap", "component_replace", "list_resolve", "register", "config_flag", "render_callback"], description: "The mechanism by which this surface is customized: e.g. `component_wrap` for a `renderDefault`-style override, `list_resolve` for a filter/append resolver, `register` for named-collection registration. Independent of `extension_audience` and `extension_scope`. `none` means not customizable by this mechanism, not unassessed.", notes: "A surface can be `component_wrap`-able by a schema author globally and `register`-able by a plugin author per type at the same time, which is exactly the shape `extensibility` could not hold: it named only a mechanism-or-audience, never both." },
+    extension_audience: { type: "string[]", enum: ["config_author", "schema_author", "plugin_author", "end_user"], description: "WHO may customize the surface through the declared `extension_mechanism`: the studio config author, the schema author, a plugin author, or the end user. Multi-valued because the same surface is often overridable by more than one audience through different entry points (e.g. globally by a config author, per-type by a schema author)." },
+    extension_scope: { type: "string[]", enum: ["global", "per_type", "per_field", "per_instance"], description: "AT WHAT SCOPE the customization applies: the whole surface, one type, one field, or one instance. Multi-valued: a form field surface can be overridable globally and per type at once.", notes: 'This is the fact `extensibility: \'closed\'` got wrong most often: "has no registration list of its own" (no per-instance entry, e.g. `form.components.field` has none) does not mean "cannot be customized" (it is still overridable globally and per type via a schema-level `components` declaration).' },
+    extension_point: { type: "string", description: 'The named API entry point through which the customization happens. @example "form.components.field", "document.actions", "studio.tools"', notes: "A durable, checkable link from the model to the code, in the same spirit as recording a DOM selector: it makes the customization fact verifiable against the real API rather than asserted from memory." },
     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"' }
   },
@@ -14472,7 +15090,7 @@ var UPG_PROPERTY_SCHEMA = {
     category: { type: "string", description: 'Attack or threat scenario. @example "injection", "misconfiguration", "social engineering", "supply chain"' },
     likelihood: {
       type: "assessment",
-      scale_id: "confidence_5",
+      scale_id: "likelihood_5",
       description: "Likelihood (1 = theoretical, 5 = actively exploited). @example value 5 for a known, exploitable, commonly targeted pattern",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
@@ -21457,10 +22075,16 @@ function validateUPGDocument(doc) {
   }
   const d = doc;
   if (!d.upg_version || typeof d.upg_version !== "string") {
-    errors.push({ path: "$.upg_version", message: "upg_version is required and must be a string" });
+    errors.push({
+      path: "$upg.spec_version",
+      message: "spec_version is required and must be a string"
+    });
   }
   if (!d.exported_at || typeof d.exported_at !== "string") {
-    errors.push({ path: "$.exported_at", message: "exported_at is required and must be an ISO 8601 string" });
+    errors.push({
+      path: "$upg.provenance.exported_at",
+      message: "provenance.exported_at is required and must be an ISO 8601 string"
+    });
   }
   if (!d.source || typeof d.source !== "object") {
     errors.push({ path: "$.source", message: "source is required and must be an object" });
@@ -33228,7 +33852,7 @@ function checkHeaderSealText(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.34.0";
+var UPG_VERSION = "0.36.0";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -33330,6 +33954,7 @@ export {
   PROPERTY_MODIFIERS,
   PROPERTY_MODIFIER_SEMANTICS,
   PROPERTY_SCALE_MAP,
+  PROPERTY_SCALE_MAP_BY_ENTITY,
   QUALIFIABLE_EDGE_TYPES,
   RECORD_ENTITY_TYPES,
   REFLECT_MODES,
@@ -33366,6 +33991,7 @@ export {
   UPG_EDGE_PAIR_MAP,
   UPG_EDGE_TYPES,
   UPG_ENTITY_COUNT,
+  UPG_ENTITY_DESCRIPTIONS,
   UPG_ENTITY_FILTER_SPECS,
   UPG_ENTITY_META,
   UPG_ENTITY_META_BY_ID,
@@ -33467,6 +34093,7 @@ export {
   getDomainIdForType,
   getDomainsInRing,
   getEdgePropertySchema,
+  getEntityDescription,
   getEntityModifierSummary,
   getEnumScale,
   getEnumValueMeta,