@unified-product-graph/core 0.12.2 → 0.12.4

package/dist/index.d.cts

@@ -10003,7 +10003,7 @@ interface ProductAreaProperties {
     strategic_priority?: Priority;
     /** Narrative description of what this area covers */
     description?: string;
-    /** Person or team that owns this area */
+    /** Person or team that owns this area. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
 }
 
@@ -10089,7 +10089,7 @@ interface MissionProperties {
  * }
  */
 interface StrategicThemeProperties {
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Planning horizon.
@@ -10123,7 +10123,7 @@ interface InitiativeProperties {
     end_date?: ISODate;
     /** Budget allocated (base currency units) */
     budget?: number;
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Capability entity.
@@ -10198,7 +10198,7 @@ interface ValueStreamProperties {
  * }
  */
 interface StrategicPillarProperties {
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Narrative of the pillar's intent */
     description?: string;
@@ -10260,7 +10260,7 @@ interface DecisionProperties {
     decision_outcome?: string;
     /** Known positive and negative consequences. Mirrors MADR's "Consequences" section. */
     consequences?: string;
-    /** People who made the decision. Mirrors MADR's "Deciders" field. */
+    /** People who made the decision. Mirrors MADR's "Deciders" field. Promote to `node_owned_by_person` edges (one per name) if ownership must be queryable. */
     decision_makers?: string[];
     /**
      * Forces, constraints, and goals that shaped the decision. Mirrors MADR's
@@ -10463,15 +10463,15 @@ interface JobStepProperties {
  * @example
  * const properties: SwitchingCostProperties = {
  *   cost_type: 'financial',
- *   magnitude: 'high',
+ *   magnitude: { value: 4, label: 'high' },
  *   barrier_description: 'Extensive Notion workspace with years of history; migration feels daunting.',
  * }
  */
 interface SwitchingCostProperties {
     /** Type of switching cost */
     cost_type?: 'financial' | 'learning' | 'data' | 'relationship' | 'procedural';
-    /** How large the barrier is */
-    magnitude?: 'high' | 'medium' | 'low';
+    /** How large the barrier is (UPGAssessment on the `severity_5` scale). */
+    magnitude?: UPGAssessment;
     /** Free-text description of the barrier */
     barrier_description?: string;
 }
@@ -11701,7 +11701,7 @@ interface JourneyStepProperties {
     friction_score?: UPGAssessment;
     /** What the user is thinking */
     thought?: string;
-    /** Responsible owner */
+    /** Responsible owner. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Discrete action at a journey step, classified by service layer.
@@ -11824,7 +11824,7 @@ interface DesignConceptProperties {
     concept_status?: 'exploring' | 'validated' | 'selected' | 'rejected';
     /** Development stage, from rough idea to presentation-ready */
     maturity?: 'sketch' | 'refined' | 'final';
-    /** Shepherding designer or researcher */
+    /** Shepherding designer or researcher. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Prototype.
@@ -12042,7 +12042,7 @@ interface DesignSystemProperties {
     version?: string;
     /** Code repository or package path */
     repo_path?: string;
-    /** Maintaining person or team */
+    /** Maintaining person or team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     maintainer?: string;
     /** Open-source license, if public */
     license?: string;
@@ -12373,7 +12373,7 @@ interface BrandImageryProperties {
 interface OutcomeProperties {
     /** Target timeframe (e.g. "Q2 2026", "12 months") */
     timeline?: string;
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * What "achieved" looks like, concretely. Pairs with `measurement_method`.
@@ -12466,7 +12466,7 @@ interface FeatureAreaProperties {
     owning_team?: string;
     /** Approximate feature count under this area. Snapshot; `feature_area_contains_feature` edges are the source of truth. */
     feature_count?: number;
-    /** Area owner (handle or email) */
+    /** Area owner (handle or email). Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** Importance to the product overall */
     priority?: Priority;
@@ -12491,7 +12491,7 @@ interface FeatureAreaProperties {
 interface FeatureProperties {
     /** Task-level priority */
     priority?: Priority;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** ISO date work begins */
     start_date?: ISODate;
@@ -12514,7 +12514,7 @@ interface EpicProperties {
     estimate?: string;
     /** Task-level priority */
     priority?: Priority;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** ISO date work begins */
     start_date?: ISODate;
@@ -12592,7 +12592,7 @@ interface ReleaseProperties {
     version?: string;
     /** ISO date work begins */
     start_date?: ISODate;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Task: a discrete unit of work, smaller than a story.
@@ -12604,7 +12604,7 @@ interface ReleaseProperties {
  * }
  */
 interface TaskProperties {
-    /** Assigned person */
+    /** Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     assignee?: string;
     /** Effort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team. */
     effort?: string;
@@ -12644,7 +12644,7 @@ interface BugProperties {
     environment?: string;
     /** Urgency relative to other work. Independent of `bug_severity` (a critical bug can have low priority if rare). */
     priority?: Priority;
-    /** Assigned person */
+    /** Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     assignee?: string;
     /** ISO date due. Often tied to a release gate or SLA. */
     due_date?: ISODate;
@@ -12665,7 +12665,7 @@ interface RoadmapProperties {
     roadmap_type?: 'now_next_later' | 'quarterly' | 'release_based' | 'theme_based';
     /** Covered timeframe */
     timeframe?: string;
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Roadmap item.
@@ -12825,7 +12825,7 @@ interface MetricProperties {
      * `'realtime'` migrates to `'continuous'`; all other values 1:1.
      */
     cadence?: Cadence;
-    /** Person or team responsible for tracking this metric */
+    /** Person or team responsible for tracking this metric. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Universal health rollup. Orthogonal to lifecycle and `guardrail_status`.
@@ -12908,7 +12908,7 @@ interface MetricQualityAssessmentProperties {
  * }
  */
 interface BoundedContextProperties {
-    /** Owning team */
+    /** Owning team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     team_owner?: string;
     /** Technologies used within this context */
     tech_stack?: string[];
@@ -12928,7 +12928,7 @@ interface ServiceProperties {
     service_type?: 'web' | 'api' | 'worker' | 'db' | 'queue' | 'library' | 'mobile' | 'docs' | 'lambda' | 'cli';
     /** Technologies used (e.g. ["TypeScript", "Postgres", "Redis"]) */
     tech_stack?: string[];
-    /** Owning person or team. Backstage marks this required; strongly recommended. */
+    /** Owning person or team. Backstage marks this required; strongly recommended. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Service maturity. Answers "how mature is it?".
@@ -12977,7 +12977,7 @@ interface ApiContractProperties {
     protocol?: 'REST' | 'GraphQL' | 'gRPC' | 'AsyncAPI' | 'SOAP' | 'WebSocket' | 'MQTT' | 'SSE' | 'other';
     /** API version */
     version?: string;
-    /** Maintaining person or team. */
+    /** Maintaining person or team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Technical debt item.
@@ -13001,7 +13001,7 @@ interface TechnicalDebtItemProperties {
     severity?: UPGAssessment;
     /** Estimated effort to resolve. Requires team knowledge of the codebase. */
     effort_to_fix?: UPGAssessment;
-    /** Owning person or team responsible for paydown. */
+    /** Owning person or team responsible for paydown. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Codebase location, service, or module.
@@ -13043,7 +13043,7 @@ interface FeatureFlagProperties {
     rollout_pct?: number;
     /** Human-readable targeting rules. Full rule evaluation happens in the flag service. */
     targeting_rules?: string;
-    /** Owning person or team responsible for the flag's lifecycle. */
+    /** Owning person or team responsible for the flag's lifecycle. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Lifecycle classification.
@@ -13080,7 +13080,7 @@ interface DeploymentProperties {
     sha?: string;
     /** Wall-clock duration in seconds. Tracks deployment speed trends. */
     duration_seconds?: number;
-    /** Triggering person or system. */
+    /** Triggering person or system. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     deployer?: string;
 }
 /** DDD aggregate.
@@ -13188,7 +13188,7 @@ interface DatabaseSchemaProperties {
     schema_version?: string;
     /** Pending-migration status */
     migration_status?: 'current' | 'pending' | 'failed';
-    /** Owning person or team responsible for design and migrations. */
+    /** Owning person or team responsible for design and migrations. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** Tables or collections in this schema. Useful for migration scope estimation. */
     table_count?: number;
@@ -13382,7 +13382,7 @@ interface InvestigationProperties {
     started_at?: ISODateTime;
     /** ISO timestamp the investigation was concluded. Pairs with `status === 'resolved' | 'abandoned'`. */
     resolved_at?: ISODateTime;
-    /** Lead investigator (email or handle). Distinct from the team owning the affected service. */
+    /** Lead investigator (email or handle). Distinct from the team owning the affected service. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     lead_investigator?: string;
     /** Originating session */
     session_id?: string;
@@ -14253,7 +14253,7 @@ interface ThreatModelProperties {
      */
     last_reviewed?: string;
     /**
-     * Participants in the exercise.
+     * 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)"
      */
     participants?: string;
@@ -14996,7 +14996,7 @@ interface GlossaryTermProperties {
  * }
  */
 interface DataDomainProperties {
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     steward?: string;
     /**
      * Domain contents classification.
@@ -15130,7 +15130,7 @@ interface DocumentProperties {
     platform?: 'markdown' | 'notion' | 'figma' | 'google_docs' | 'confluence' | 'github' | 'linear' | 'other';
     /** Purpose classification */
     document_type?: 'vision' | 'plan' | 'decision' | 'research' | 'spec' | 'audit' | 'session' | 'feedback' | 'case-study' | 'narrative' | 'bug-report' | 'archive-collection' | 'rfc' | 'runbook' | 'guide' | 'onboarding' | 'brief' | 'report' | 'reference';
-    /** Author (free-form: name, email, or handle) */
+    /** Author (free-form: name, email, or handle). Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     author?: string;
     /** ISO 8601 last-meaningful-update */
     last_updated?: ISODateTime;
@@ -15601,7 +15601,7 @@ interface DepartmentProperties {
     budget?: number;
     /** Charter / purpose statement for the department */
     department_mission?: string;
-    /** Department leader (person or role reference) */
+    /** Department leader (person or role reference). Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     leader?: string;
     /** Fiscal year the headcount / budget numbers apply to */
     fiscal_year?: string;
@@ -15643,7 +15643,7 @@ interface CeremonyProperties {
     cadence?: Cadence;
     /** Typical duration of the meeting in minutes */
     duration_minutes?: number;
-    /** People or roles who attend */
+    /** People or roles who attend. Promote individuals to `node_owned_by_person` edges if participation must be queryable. */
     participants?: string;
 }
 /** CapacityPlan entity.
@@ -16293,7 +16293,7 @@ interface AgentTaskProperties {
 interface ReviewGateProperties {
     /** Kind of review required at this gate */
     gate_type?: 'human_review' | 'automated_check' | 'approval';
-    /** People or roles that must approve */
+    /** People or roles that must approve. Promote to `node_owned_by_person` edges (one per name) if ownership must be queryable. */
     required_approvers?: string[];
     /** Current approval status of the gate */
     gate_status?: 'pending' | 'approved' | 'rejected' | 'bypassed';
@@ -16531,7 +16531,7 @@ interface PartnershipProperties {
     partnership_tier?: 'strategic' | 'preferred' | 'standard' | 'trial';
     /** Exposure if the partnership fails (concentration risk, IP risk, etc.) */
     risk_level?: UPGAssessment;
-    /** Internal owner */
+    /** Internal owner. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Date the partnership became effective (ISO 8601) */
     start_date?: ISODate;
@@ -16550,7 +16550,7 @@ interface KeyResourceProperties {
     resource_type?: 'physical' | 'intellectual' | 'human' | 'financial';
     /** Criticality to the business model */
     criticality?: Priority;
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Replacement difficulty */
     scarcity_risk?: UPGAssessment;
@@ -16581,7 +16581,7 @@ interface KeyActivityProperties {
     frequency_period?: Duration;
     /** Qualitative tier. Use when an exact rate is unknown. */
     frequency_rating?: FrequencyRating;
-    /** Operationally accountable team or individual */
+    /** Operationally accountable team or individual. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     operational_owner?: string;
     /** Bottleneck or scaling constraint */
     capacity_constraint?: string;
@@ -17755,7 +17755,7 @@ interface ServiceLevelAgreementProperties {
     effective_date?: ISODate;
     /** ISO date expires. Pairs with `agreement_term` for renewal logic. */
     expiry_date?: ISODate;
-    /** Party accountable on the service provider side */
+    /** Party accountable on the service provider side. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** What happens if the SLA is breached (credits, penalties, escalation path) */
     consequence_of_breach?: string;
@@ -21822,7 +21822,7 @@ declare function isCanonical(text: string): boolean;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.12.2";
+declare const UPG_VERSION: "0.12.4";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).

package/dist/index.d.ts

@@ -10003,7 +10003,7 @@ interface ProductAreaProperties {
     strategic_priority?: Priority;
     /** Narrative description of what this area covers */
     description?: string;
-    /** Person or team that owns this area */
+    /** Person or team that owns this area. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
 }
 
@@ -10089,7 +10089,7 @@ interface MissionProperties {
  * }
  */
 interface StrategicThemeProperties {
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Planning horizon.
@@ -10123,7 +10123,7 @@ interface InitiativeProperties {
     end_date?: ISODate;
     /** Budget allocated (base currency units) */
     budget?: number;
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Capability entity.
@@ -10198,7 +10198,7 @@ interface ValueStreamProperties {
  * }
  */
 interface StrategicPillarProperties {
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Narrative of the pillar's intent */
     description?: string;
@@ -10260,7 +10260,7 @@ interface DecisionProperties {
     decision_outcome?: string;
     /** Known positive and negative consequences. Mirrors MADR's "Consequences" section. */
     consequences?: string;
-    /** People who made the decision. Mirrors MADR's "Deciders" field. */
+    /** People who made the decision. Mirrors MADR's "Deciders" field. Promote to `node_owned_by_person` edges (one per name) if ownership must be queryable. */
     decision_makers?: string[];
     /**
      * Forces, constraints, and goals that shaped the decision. Mirrors MADR's
@@ -10463,15 +10463,15 @@ interface JobStepProperties {
  * @example
  * const properties: SwitchingCostProperties = {
  *   cost_type: 'financial',
- *   magnitude: 'high',
+ *   magnitude: { value: 4, label: 'high' },
  *   barrier_description: 'Extensive Notion workspace with years of history; migration feels daunting.',
  * }
  */
 interface SwitchingCostProperties {
     /** Type of switching cost */
     cost_type?: 'financial' | 'learning' | 'data' | 'relationship' | 'procedural';
-    /** How large the barrier is */
-    magnitude?: 'high' | 'medium' | 'low';
+    /** How large the barrier is (UPGAssessment on the `severity_5` scale). */
+    magnitude?: UPGAssessment;
     /** Free-text description of the barrier */
     barrier_description?: string;
 }
@@ -11701,7 +11701,7 @@ interface JourneyStepProperties {
     friction_score?: UPGAssessment;
     /** What the user is thinking */
     thought?: string;
-    /** Responsible owner */
+    /** Responsible owner. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Discrete action at a journey step, classified by service layer.
@@ -11824,7 +11824,7 @@ interface DesignConceptProperties {
     concept_status?: 'exploring' | 'validated' | 'selected' | 'rejected';
     /** Development stage, from rough idea to presentation-ready */
     maturity?: 'sketch' | 'refined' | 'final';
-    /** Shepherding designer or researcher */
+    /** Shepherding designer or researcher. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Prototype.
@@ -12042,7 +12042,7 @@ interface DesignSystemProperties {
     version?: string;
     /** Code repository or package path */
     repo_path?: string;
-    /** Maintaining person or team */
+    /** Maintaining person or team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     maintainer?: string;
     /** Open-source license, if public */
     license?: string;
@@ -12373,7 +12373,7 @@ interface BrandImageryProperties {
 interface OutcomeProperties {
     /** Target timeframe (e.g. "Q2 2026", "12 months") */
     timeline?: string;
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * What "achieved" looks like, concretely. Pairs with `measurement_method`.
@@ -12466,7 +12466,7 @@ interface FeatureAreaProperties {
     owning_team?: string;
     /** Approximate feature count under this area. Snapshot; `feature_area_contains_feature` edges are the source of truth. */
     feature_count?: number;
-    /** Area owner (handle or email) */
+    /** Area owner (handle or email). Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** Importance to the product overall */
     priority?: Priority;
@@ -12491,7 +12491,7 @@ interface FeatureAreaProperties {
 interface FeatureProperties {
     /** Task-level priority */
     priority?: Priority;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** ISO date work begins */
     start_date?: ISODate;
@@ -12514,7 +12514,7 @@ interface EpicProperties {
     estimate?: string;
     /** Task-level priority */
     priority?: Priority;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** ISO date work begins */
     start_date?: ISODate;
@@ -12592,7 +12592,7 @@ interface ReleaseProperties {
     version?: string;
     /** ISO date work begins */
     start_date?: ISODate;
-    /** Responsible person or team */
+    /** Responsible person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Task: a discrete unit of work, smaller than a story.
@@ -12604,7 +12604,7 @@ interface ReleaseProperties {
  * }
  */
 interface TaskProperties {
-    /** Assigned person */
+    /** Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     assignee?: string;
     /** Effort estimate (e.g. "2h", "1d", "3 points"). Use a consistent unit within your team. */
     effort?: string;
@@ -12644,7 +12644,7 @@ interface BugProperties {
     environment?: string;
     /** Urgency relative to other work. Independent of `bug_severity` (a critical bug can have low priority if rare). */
     priority?: Priority;
-    /** Assigned person */
+    /** Assigned person. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     assignee?: string;
     /** ISO date due. Often tied to a release gate or SLA. */
     due_date?: ISODate;
@@ -12665,7 +12665,7 @@ interface RoadmapProperties {
     roadmap_type?: 'now_next_later' | 'quarterly' | 'release_based' | 'theme_based';
     /** Covered timeframe */
     timeframe?: string;
-    /** Owning person or team */
+    /** Owning person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Roadmap item.
@@ -12825,7 +12825,7 @@ interface MetricProperties {
      * `'realtime'` migrates to `'continuous'`; all other values 1:1.
      */
     cadence?: Cadence;
-    /** Person or team responsible for tracking this metric */
+    /** Person or team responsible for tracking this metric. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Universal health rollup. Orthogonal to lifecycle and `guardrail_status`.
@@ -12908,7 +12908,7 @@ interface MetricQualityAssessmentProperties {
  * }
  */
 interface BoundedContextProperties {
-    /** Owning team */
+    /** Owning team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     team_owner?: string;
     /** Technologies used within this context */
     tech_stack?: string[];
@@ -12928,7 +12928,7 @@ interface ServiceProperties {
     service_type?: 'web' | 'api' | 'worker' | 'db' | 'queue' | 'library' | 'mobile' | 'docs' | 'lambda' | 'cli';
     /** Technologies used (e.g. ["TypeScript", "Postgres", "Redis"]) */
     tech_stack?: string[];
-    /** Owning person or team. Backstage marks this required; strongly recommended. */
+    /** Owning person or team. Backstage marks this required; strongly recommended. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Service maturity. Answers "how mature is it?".
@@ -12977,7 +12977,7 @@ interface ApiContractProperties {
     protocol?: 'REST' | 'GraphQL' | 'gRPC' | 'AsyncAPI' | 'SOAP' | 'WebSocket' | 'MQTT' | 'SSE' | 'other';
     /** API version */
     version?: string;
-    /** Maintaining person or team. */
+    /** Maintaining person or team. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
 }
 /** Technical debt item.
@@ -13001,7 +13001,7 @@ interface TechnicalDebtItemProperties {
     severity?: UPGAssessment;
     /** Estimated effort to resolve. Requires team knowledge of the codebase. */
     effort_to_fix?: UPGAssessment;
-    /** Owning person or team responsible for paydown. */
+    /** Owning person or team responsible for paydown. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Codebase location, service, or module.
@@ -13043,7 +13043,7 @@ interface FeatureFlagProperties {
     rollout_pct?: number;
     /** Human-readable targeting rules. Full rule evaluation happens in the flag service. */
     targeting_rules?: string;
-    /** Owning person or team responsible for the flag's lifecycle. */
+    /** Owning person or team responsible for the flag's lifecycle. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /**
      * Lifecycle classification.
@@ -13080,7 +13080,7 @@ interface DeploymentProperties {
     sha?: string;
     /** Wall-clock duration in seconds. Tracks deployment speed trends. */
     duration_seconds?: number;
-    /** Triggering person or system. */
+    /** Triggering person or system. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     deployer?: string;
 }
 /** DDD aggregate.
@@ -13188,7 +13188,7 @@ interface DatabaseSchemaProperties {
     schema_version?: string;
     /** Pending-migration status */
     migration_status?: 'current' | 'pending' | 'failed';
-    /** Owning person or team responsible for design and migrations. */
+    /** Owning person or team responsible for design and migrations. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** Tables or collections in this schema. Useful for migration scope estimation. */
     table_count?: number;
@@ -13382,7 +13382,7 @@ interface InvestigationProperties {
     started_at?: ISODateTime;
     /** ISO timestamp the investigation was concluded. Pairs with `status === 'resolved' | 'abandoned'`. */
     resolved_at?: ISODateTime;
-    /** Lead investigator (email or handle). Distinct from the team owning the affected service. */
+    /** Lead investigator (email or handle). Distinct from the team owning the affected service. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     lead_investigator?: string;
     /** Originating session */
     session_id?: string;
@@ -14253,7 +14253,7 @@ interface ThreatModelProperties {
      */
     last_reviewed?: string;
     /**
-     * Participants in the exercise.
+     * 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)"
      */
     participants?: string;
@@ -14996,7 +14996,7 @@ interface GlossaryTermProperties {
  * }
  */
 interface DataDomainProperties {
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     steward?: string;
     /**
      * Domain contents classification.
@@ -15130,7 +15130,7 @@ interface DocumentProperties {
     platform?: 'markdown' | 'notion' | 'figma' | 'google_docs' | 'confluence' | 'github' | 'linear' | 'other';
     /** Purpose classification */
     document_type?: 'vision' | 'plan' | 'decision' | 'research' | 'spec' | 'audit' | 'session' | 'feedback' | 'case-study' | 'narrative' | 'bug-report' | 'archive-collection' | 'rfc' | 'runbook' | 'guide' | 'onboarding' | 'brief' | 'report' | 'reference';
-    /** Author (free-form: name, email, or handle) */
+    /** Author (free-form: name, email, or handle). Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     author?: string;
     /** ISO 8601 last-meaningful-update */
     last_updated?: ISODateTime;
@@ -15601,7 +15601,7 @@ interface DepartmentProperties {
     budget?: number;
     /** Charter / purpose statement for the department */
     department_mission?: string;
-    /** Department leader (person or role reference) */
+    /** Department leader (person or role reference). Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     leader?: string;
     /** Fiscal year the headcount / budget numbers apply to */
     fiscal_year?: string;
@@ -15643,7 +15643,7 @@ interface CeremonyProperties {
     cadence?: Cadence;
     /** Typical duration of the meeting in minutes */
     duration_minutes?: number;
-    /** People or roles who attend */
+    /** People or roles who attend. Promote individuals to `node_owned_by_person` edges if participation must be queryable. */
     participants?: string;
 }
 /** CapacityPlan entity.
@@ -16293,7 +16293,7 @@ interface AgentTaskProperties {
 interface ReviewGateProperties {
     /** Kind of review required at this gate */
     gate_type?: 'human_review' | 'automated_check' | 'approval';
-    /** People or roles that must approve */
+    /** People or roles that must approve. Promote to `node_owned_by_person` edges (one per name) if ownership must be queryable. */
     required_approvers?: string[];
     /** Current approval status of the gate */
     gate_status?: 'pending' | 'approved' | 'rejected' | 'bypassed';
@@ -16531,7 +16531,7 @@ interface PartnershipProperties {
     partnership_tier?: 'strategic' | 'preferred' | 'standard' | 'trial';
     /** Exposure if the partnership fails (concentration risk, IP risk, etc.) */
     risk_level?: UPGAssessment;
-    /** Internal owner */
+    /** Internal owner. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Date the partnership became effective (ISO 8601) */
     start_date?: ISODate;
@@ -16550,7 +16550,7 @@ interface KeyResourceProperties {
     resource_type?: 'physical' | 'intellectual' | 'human' | 'financial';
     /** Criticality to the business model */
     criticality?: Priority;
-    /** Accountable person or team */
+    /** Accountable person or team. Promote to a `node_owned_by_person` edge if ownership must be queryable. */
     owner?: string;
     /** Replacement difficulty */
     scarcity_risk?: UPGAssessment;
@@ -16581,7 +16581,7 @@ interface KeyActivityProperties {
     frequency_period?: Duration;
     /** Qualitative tier. Use when an exact rate is unknown. */
     frequency_rating?: FrequencyRating;
-    /** Operationally accountable team or individual */
+    /** Operationally accountable team or individual. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     operational_owner?: string;
     /** Bottleneck or scaling constraint */
     capacity_constraint?: string;
@@ -17755,7 +17755,7 @@ interface ServiceLevelAgreementProperties {
     effective_date?: ISODate;
     /** ISO date expires. Pairs with `agreement_term` for renewal logic. */
     expiry_date?: ISODate;
-    /** Party accountable on the service provider side */
+    /** Party accountable on the service provider side. Promote to a `node_owned_by_team` edge if ownership must be queryable. */
     owner?: string;
     /** What happens if the SLA is breached (credits, penalties, escalation path) */
     consequence_of_breach?: string;
@@ -21822,7 +21822,7 @@ declare function isCanonical(text: string): boolean;
  * it stamps the `upg_version` field of every `.upg` file written by the SDK.
  * The `check:version-lockstep` gate enforces this at release time.
  */
-declare const UPG_VERSION: "0.12.2";
+declare const UPG_VERSION: "0.12.4";
 /**
  * The `.upg` JSON document format version. Written to the `upg_version` field.
  * Evolves independently from `UPG_VERSION` (the catalogue version).