@unified-product-graph/core 0.17.5 → 0.17.7

package/README.md

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

package/dist/index.cjs

@@ -1386,7 +1386,13 @@ var UPG_EDGE_CATALOG = {
   research_study_collects_survey_response: { forward_verb: "collects", reverse_verb: "collected_in", classification: "hierarchy", source_type: "research_study", target_type: "survey_response" },
   observation_evidenced_by_quote: { forward_verb: "evidenced_by", reverse_verb: "evidences", classification: "hierarchy", source_type: "observation", target_type: "quote" },
   affinity_cluster_synthesises_insight: { forward_verb: "synthesises", reverse_verb: "synthesised_from", classification: "hierarchy", source_type: "affinity_cluster", target_type: "insight" },
-  insight_informs_opportunity: { forward_verb: "informs", reverse_verb: "informed_by", classification: "cross-domain", source_type: "insight", target_type: "opportunity" },
+  // deliberate_only (0.17.6): "this insight informs that opportunity" is a
+  // PM-judgment link — which of many opportunities a finding actually feeds is
+  // authored, never inferred from a source's hierarchy. Auto-nest / adapter
+  // parentage resolvers decline to materialise it (fall through to a
+  // node_informs_node link or a decline+warn); explicit create_edge /
+  // resolve_edge_for_pair still return it. Fixes the latent auto-emission.
+  insight_informs_opportunity: { forward_verb: "informs", reverse_verb: "informed_by", classification: "cross-domain", source_type: "insight", target_type: "opportunity", deliberate_only: true },
   // 1.5 Market Intelligence Domain
   // product → competitive_analysis closes the parallel gap to
   // product → persona. competitive_analysis is the anchor of the
@@ -7064,6 +7070,8 @@ var PROPERTY_SCALE_MAP = {
   // validation/experiment_run
   bug_severity: "severity_5",
   // product-spec/bug (UPG-579 Option C collapse)
+  magnitude: "severity_5",
+  // user/switching_cost barrier size (0.17.7; restores the documented UPG-579 intent that a missing entry had silently overridden to scale_5)
   risk_level: "severity_5",
   // compliance/risk (UPG-579 Option B)
   scarcity_risk: "severity_5",
@@ -10751,8 +10759,6 @@ var UPG_PROPERTY_SCHEMA = {
     framework_id: { type: "string", description: "Framework ID (references `UPGFramework.id`)" },
     stage: { type: "string", enum: ["draft", "validated", "active"], description: "Maturity" },
     pattern: { type: "string", enum: ["freemium", "marketplace", "saas", "subscription", "transactional", "advertising", "licensing", "hybrid"], description: "Canonical pattern. Useful for benchmarking against peer businesses with the same shape." }
-    // monetisation_basis removed in 0.12.0 (P14 Bucket C) — categorical rollup of revenue_stream.billing_model.
-    // north_star_metric removed in 0.12.0 (P14) → `business_model_guided_by_metric` edge.
   },
   // CapabilityProperties: Capability entity.
   capability: {
@@ -10969,7 +10975,7 @@ var UPG_PROPERTY_SCHEMA = {
   // ConstraintProperties: Constraint: a named limitation or boundary on product creation.
   constraint: {
     constraint_kind: { type: "string", enum: ["resource", "technical", "regulatory", "temporal", "compliance", "other"], description: "Limitation category" },
-    constraint_origin: { type: "string", enum: ["internal", "external"], description: "Provenance: internal (a self-imposed principle or operating tenet) or external (a limit, requirement, or ceiling imposed from outside)." },
+    constraint_origin: { type: "string", enum: ["internal", "external"], description: "Provenance: a self-imposed tenet (`internal`) or an imposed-on-us limit/requirement (`external`)." },
     constraint_status: { type: "string", enum: ["binding", "advisory", "lifted"], description: "Whether binding, advisory, or lifted" },
     rule_strength: { type: "string", enum: ["must", "must_not", "exception", "warning", "guideline"], description: "Enforcement strictness. Reuses the governance/guideline rule vocabulary." },
     source: { type: "string", description: "Free-text origin: policy document, regulation, stakeholder, technical doc." },
@@ -11586,7 +11592,7 @@ var UPG_PROPERTY_SCHEMA = {
   // FeatureFlagProperties: Feature flag.
   feature_flag: {
     key: { type: "string", description: 'Required. Stable flag key used in code (e.g. "new-checkout-flow").' },
-    rollout_pct: { type: "number", description: "Percentage enabled (0\u2013100). Meaningful when `flag_status === 'rollout'`.", modifier: "snapshot" },
+    rollout_pct: { type: "number", description: "Percentage enabled (0\u2013100). Meaningful when the flag's `status === 'rollout'`.", modifier: "snapshot" },
     targeting_rules: { type: "string", description: "Human-readable targeting rules. Full rule evaluation happens in the flag service." },
     owner: { type: "string", description: "Owning person or team responsible for the flag's lifecycle. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     flag_type: { type: "string", enum: ["temporary", "permanent", "experiment"], description: "Lifecycle classification. `temporary` = should be removed after rollout (kill switch, gradual rollout). `permanent` = long-lived feature gate (entitlement flag). `experiment` = A/B test with a defined end condition." },
@@ -12356,7 +12362,7 @@ var UPG_PROPERTY_SCHEMA = {
     is_highlighted: { type: "boolean", description: "Flagged as a highlight. Absorbed from the deprecated Highlight entity." },
     highlight_tag: { type: "string", description: 'Free-form highlight type tag. @example "pain", "delight", "behaviour", "moment of clarity"' },
     sentiment: { type: "string", enum: ["positive", "neutral", "negative", "mixed"], description: "Structured sentiment. Tools like Dovetail and EnjoyHQ converge on these four values. More precise than `highlight_tag` for aggregation." },
-    source_url: { type: "string", description: "Stable deep-link to the exact moment this observation was captured in the originating recording or transcript. A per-moment locator, not a study-level link. Distinct from `session_ref`, which holds an opaque session ID.", modifier: "volatile" }
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this observation was captured in the originating recording or transcript. A per-moment locator, not a study-level link. Distinct from `session_ref`, which holds an opaque session ID for AI inference. Rot-prone external pointer; treat as `volatile`.", modifier: "volatile" }
   },
   // OnCallRotationProperties: On-call rotation.
   on_call_rotation: {
@@ -12365,10 +12371,18 @@ var UPG_PROPERTY_SCHEMA = {
     rotation_cadence: { type: "string", enum: ["daily", "weekly", "biweekly", "custom"], description: "Cycle cadence. `weekly` for standard team rotations. `daily` for high-incident-volume teams." },
     handoff_time: { type: "string", description: 'Shift handoff time. Affects team coordination and sleep. @example "09:00 UTC", "17:00 local"' }
   },
+  // OperatingLifecycleProperties: An operating_lifecycle: a canonical, ordered (often cyclic) operating process
+  operating_lifecycle: {
+    cyclic: { type: "boolean", description: "True if the process loops (e.g. Analyze \u2192 Extend \u2192 Plan). The sequence is fully expressed by the stages' `stage_order`; `cyclic` adds the wrap from the last stage back to the first." },
+    source: { type: "string", description: 'Origin of the canonical model (e.g. "Sanity official content-ops lifecycle"). Optional provenance; promote to an edge if it names a real `specification`/`document`.' }
+  },
+  // OperatingStageProperties: An operating_stage: one ordered stage of an `operating_lifecycle`. A product's
+  operating_stage: {
+    stage_order: { type: "number", description: "Ordered position within the lifecycle, 0-indexed. The source of truth for sequence (pairs with `phase_order`/`step_order`/`action_order`)." },
+    goal: { type: "string", description: "What this stage accomplishes." },
+    owner_role: { type: "string", description: "Role that owns the stage (free-text role label). Optional; promote to a `node_owned_by_role` edge if ownership must be queryable across stages." }
+  },
   // OpportunityProperties: A problem worth solving, grounded in user need and business value.
-  // No intrinsic scalar properties — defined by edges + framework-scoped scoring
-  // (reach/frequency/pain/opportunity_score live on the `opportunity-sizing`
-  // framework_exercise edge). Former props removed in 0.14.0 (UPG-574).
   opportunity: {},
   // OrganizationProperties: Organization entity.
   organization: {
@@ -12401,7 +12415,7 @@ var UPG_PROPERTY_SCHEMA = {
     alias: { type: "string", description: 'Anonymous alias for privacy (e.g. "P01")' },
     recruit_source: { type: "string", description: "How the participant was recruited" },
     consent_status: { type: "string", enum: ["pending", "given", "withdrawn"], description: "Current consent status for data usage" },
-    source_url: { type: "string", description: "Stable deep-link to the exact moment this participant appears in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this participant appears in the originating recording or transcript. A per-moment locator, not a study-level link. Rot-prone external pointer; treat as `volatile`.", modifier: "volatile" }
   },
   // PartnerProgramProperties: Partner program.
   partner_program: {
@@ -12471,7 +12485,7 @@ var UPG_PROPERTY_SCHEMA = {
     tech_comfort: { type: "string", enum: ["low", "medium", "high", "expert", "other"], description: "Tech comfort. Closed set so personas across products compare on the same axis. Free-text colour belongs in `context` or `motivation`." },
     domain_expertise: { type: "string", description: 'Industry or domain knowledge this persona brings @example "10+ years SaaS experience", "New to healthcare IT"' },
     audience_role: { type: "string", enum: ["buyer", "user", "champion", "influencer", "partner"], description: 'Role in the buying / adoption decision (the decision-making-unit split): who signs (buyer) vs who uses (user) vs who advocates internally (champion) vs who shapes the choice (influencer) vs who delivers / implements (partner). A portfolio must separate the economic buyer from the practitioner user; they are distinct personas with distinct jobs. Closed set so roles compare across products. @example "buyer"' },
-    actor_kind: { type: "string", enum: ["human", "agent", "system"], description: "Who performs the work: a human archetype (default; absent = human, no migration), an autonomous AI agent (e.g. Content Agent), or a non-agentic platform service. An agent persona participates in journeys via the same persona machinery and is delegated to via persona_delegates_to_persona. Human-coverage / segmentation metrics count human only; agent/system opt-in." }
+    actor_kind: { type: "string", enum: ["human", "agent", "system"], description: 'Who performs the work: a human archetype (default), an autonomous AI agent (e.g. Content Agent), or a non-agentic platform service. Absent = `human`, so existing personas need no migration. An `agent` persona is a first-class actor that participates in journeys via the same persona machinery and that humans delegate to via `persona_delegates_to_persona`. Human-coverage / segmentation metrics count `human` only; agent/system are opt-in. @example "agent"' }
   },
   // PipelineSalesProperties: Sales pipeline.
   pipeline_sales: {
@@ -12534,17 +12548,6 @@ var UPG_PROPERTY_SCHEMA = {
     defined_by: { type: "string", description: "The `specification/<slug>` this primitive comes from; nullable for spec-less internal primitives. Mirrors the `primitive_defined_by_specification` edge for quick lookup." },
     since: { type: "string", description: "Year or version the primitive was introduced." }
   },
-  // OperatingLifecycleProperties: a canonical ordered (often cyclic) operating process products' journey phases map onto.
-  operating_lifecycle: {
-    cyclic: { type: "boolean", description: "True if the process loops (e.g. Analyze \u2192 Extend \u2192 Plan). The sequence is expressed by the stages' stage_order; cyclic adds the wrap from last stage back to first." },
-    source: { type: "string", description: 'Origin of the canonical model (e.g. "Sanity official content-ops lifecycle"). Optional provenance; promote to an edge if it names a real specification/document.' }
-  },
-  // OperatingStageProperties: one ordered stage of an operating_lifecycle.
-  operating_stage: {
-    stage_order: { type: "number", description: "Ordered position within the lifecycle, 0-indexed. Source of truth for sequence." },
-    goal: { type: "string", description: "What this stage accomplishes." },
-    owner_role: { type: "string", description: "Role that owns the stage (free-text role label). Optional; promote to a node_owned_by_role edge if ownership must be queryable." }
-  },
   // PrivacyPolicyProperties: Privacy policy.
   privacy_policy: {
     version: { type: "string", description: "Version identifier of the policy" },
@@ -12625,7 +12628,7 @@ var UPG_PROPERTY_SCHEMA = {
   quote: {
     text: { type: "string", description: "Quoted text" },
     timestamp: { type: "string", description: "When said (ISO timestamp or session offset)" },
-    source_url: { type: "string", description: "Stable deep-link to the exact moment this quote was spoken in the originating recording or transcript. A per-moment locator, not a study-level link.", modifier: "volatile" }
+    source_url: { type: "string", description: "Stable deep-link to the exact moment this quote was spoken in the originating recording or transcript. A per-moment locator, not a study-level link. Rot-prone external pointer; treat as `volatile`.", modifier: "volatile" }
   },
   // QuoteDocumentProperties: Quote document.
   quote_document: {
@@ -12654,7 +12657,7 @@ var UPG_PROPERTY_SCHEMA = {
       },
       required: ["value", "label"]
     },
-    evidence_refs: { type: "string[]", description: "References to supporting evidence" }
+    evidence_refs: { type: "string[]", description: "References to supporting evidence (e.g. interview or observation ids)." }
   },
   // RegionalPricingProperties: Regional pricing.
   regional_pricing: {
@@ -12826,7 +12829,6 @@ var UPG_PROPERTY_SCHEMA = {
     cause_confidence: { type: "string", enum: ["hypothesised", "likely", "confirmed"], description: "Team certainty about this cause. `hypothesised` = educated guess. `likely` = evidence points here. `confirmed` = reproduced. Renamed from `confidence` in v0.4.0 to disambiguate from the entity-wide `UPGAssessment`-typed epistemic confidence used elsewhere. The 3-tier shape stays as a discrete RCA-lifecycle marker." },
     evidence_summary: { type: "string", description: "One-paragraph evidence summary. Log lines, traces, repro steps. Detailed artefacts go on linked `evidence` nodes." },
     affected_area: { type: "string", description: "Affected area of the system" }
-    // `category` (legacy, -> `cause_category`) and `verified` (= `cause_confidence === 'confirmed'`) removed in 0.14.0 (UPG-574).
   },
   // RunbookProperties: Runbook.
   runbook: {
@@ -12978,10 +12980,7 @@ var UPG_PROPERTY_SCHEMA = {
     post_type: { type: "string", enum: ["text", "image", "video", "carousel", "story"], description: "Format of the post" },
     scheduled_date: { type: "string", description: "Date the post is scheduled to publish (ISO format)" }
   },
-  // SolutionProperties: A proposed response to an opportunity.
-  // RICE scoring inputs (reach/impact/confidence/effort) + computed rice_score
-  // were framework-scoped from 0.9.0 and removed in 0.14.0 (UPG-574): they live
-  // on the `rice-scoring` framework_exercise edge, not the entity.
+  // SolutionProperties: A proposed response to an opportunity
   solution: {
     timeline: { type: "string", description: "Estimated delivery or target timeline" }
   },
@@ -13040,18 +13039,14 @@ var UPG_PROPERTY_SCHEMA = {
     time_horizon: { type: "string", description: 'Standing / multi-year horizon, often open-ended (a pillar is durable). @example "3 years", "2026-2028", "ongoing"' },
     success_indicator: { type: "string", description: "How the business knows this durable pillar is on track. Narrative, not a metric edge. A strategic_theme deliberately has no success_indicator: it is measured through its child objectives, not on its own." }
   },
-  // StrategicQuestionProperties: StrategicQuestion entity. An open coordination or
-  // ownership question a plan is exposed to (strategy sibling of research_question /
-  // design_question). `status` is the node lifecycle (open -> resolved).
+  // StrategicQuestionProperties: StrategicQuestion entity.
   strategic_question: {
     question: { type: "string", description: "The question itself. Primary content." },
     context: { type: "string", description: "Context that surfaced the question: the reorg, the boundary, the unowned area." },
     resolution: { type: "string", description: "The answer, captured when the question moves to `resolved`." },
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Importance to resolve relative to other open questions." }
   },
-  // StrategicThemeProperties: StrategicTheme entity. A time-bound thrust WITHIN a
-  // strategic_pillar (distinct cascade level, UPG-692 T3.3) — measured through its
-  // child objectives, so it carries no success_indicator of its own.
+  // StrategicThemeProperties: StrategicTheme entity.
   strategic_theme: {
     owner: { type: "string", description: "Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable." },
     time_horizon: { type: "string", description: 'Bounded period this theme is active (a theme is time-bound, within a pillar). @example "Q1 2026", "FY26"' },
@@ -13104,7 +13099,7 @@ var UPG_PROPERTY_SCHEMA = {
     magnitude: {
       type: "assessment",
       scale_id: "severity_5",
-      description: "How large the switching barrier is (UPGAssessment on the `severity_5` scale). Steered onto the canonical scale to match sibling assessments. Migrated from the `high | medium | low` enum (UPG-579 Option C): map `high` -> 4, `medium` -> 3, `low` -> 2; carry the old word in `label`.",
+      description: "How large the barrier is (UPGAssessment on the `severity_5` scale).",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -13151,7 +13146,6 @@ var UPG_PROPERTY_SCHEMA = {
     priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Relative importance against other tasks" },
     due_date: { type: "string", description: "ISO date due. Typically bounded by the containing story's due date." },
     labels: { type: "string[]", description: "Free-form classification tags. Applied uniformly across work item types." }
-    // `estimate` (story_task collapse relic, duplicated `effort`) removed in 0.14.0 (UPG-574).
   },
   // TeamProperties: Team entity.
   team: {
@@ -13300,7 +13294,7 @@ var UPG_PROPERTY_SCHEMA = {
     methodology: { type: "string", enum: ["stride", "dread", "pasta", "attack_tree", "other"], description: 'Methodology. `stride` = Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege (OWASP standard). `dread` = Damage, Reproducibility, Exploitability, Affected users, Discoverability (numeric scoring). `pasta` = Process for Attack Simulation and Threat Analysis (7-stage). `attack_tree` = hierarchical tree of attack paths. @example "stride" is the most widely used methodology for web applications' },
     scope: { type: "string", description: 'What system, feature, or data flow is being analysed. @example "user authentication", "payment processing", "admin API"' },
     last_reviewed: { type: "string", description: 'ISO date last reviewed. Models become stale as systems evolve. @example "2026-03-01"' },
-    participants: { type: "string", description: 'Participants in the exercise. @example "Alice Chen (security lead), Bob Park (backend engineer), Carol Liu (architect)". Promote individuals to `node_owned_by_person` edges if participation must be queryable.' },
+    participants: { type: "string", description: 'Participants in the exercise. Promote individuals to `node_owned_by_person` edges if participation must be queryable. @example "Alice Chen (security lead), Bob Park (backend engineer), Carol Liu (architect)"' },
     threat_count: { type: "number", description: "Threats identified. Key metric for scope and completeness. @example 12", modifier: "derived" }
   },
   // TouchpointProperties: Customer touchpoint.
@@ -13395,7 +13389,7 @@ var UPG_PROPERTY_SCHEMA = {
   // VisionProperties: Vision entity.
   vision: {
     timeframe: { type: "string", description: 'Target timeframe. @example "3 years"' },
-    north_star: { type: "string", description: "Single north-star metric or statement" },
+    north_star: { type: "string", description: "The north-star statement: a prose slogan of the future the product steers toward. Legitimately free-text (graph-vs-prose). To link the *metric* a vision optimises for, use the `vision_anchored_by_metric` edge (P14 0.12.0)." },
     success_looks_like: { type: "string", description: "Narrative of what success looks like" }
   },
   // VulnerabilityProperties: Vulnerability.
@@ -29981,7 +29975,7 @@ function isCanonical(text) {
 }
 
 // src/index.ts
-var UPG_VERSION = "0.17.5";
+var UPG_VERSION = "0.17.7";
 var UPG_FORMAT_VERSION = "0.4.0";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();