// Hierarchical aggregation summaries for Peat Protocol
// Version: 2.0.0 — abstract hierarchy vocabulary per ADR-066
//
// Defines aggregated state summaries for hierarchical formations.
// Four-tier model: Node → Cell → Cohort → Federation → Coalition.
// Tier 5+ is reserved for a future parametric N-tier ADR (see ADR-066).

syntax = "proto3";

package cap.hierarchy.v1;

import "common.proto";
import "capability.proto";
import "node.proto";

// Cell-level aggregated state summary
//
// Represents the aggregated state of a cell (smallest aggregation unit):
// - 1 cell leader
// - 1..N cell members
//
// Published by cell leaders for consumption by cohort coordinators.
// Reduces N individual NodeState messages to 1 aggregated summary.
message CellSummary {
  // Cell identifier (matches cell_id in NodeState)
  string cell_id = 1;

  // Cell leader node ID
  string leader_id = 2;

  // Member node IDs (for reference, not full state)
  repeated string member_ids = 3;

  // Total member count
  uint32 member_count = 4;

  // Aggregated Position (centroid of member positions)
  common.v1.Position position_centroid = 5;

  // Average fuel remaining across cell (minutes)
  float avg_fuel_minutes = 6;

  // Worst health status in cell (min of all members)
  // Uses LWW semantics - worst health wins for situational awareness
  node.v1.HealthStatus worst_health = 7;

  // Operational member count (health >= DEGRADED)
  uint32 operational_count = 8;

  // Aggregated capabilities (from CapabilityAggregator)
  // These are cell-level emergent capabilities, not individual node capabilities
  repeated capability.v1.Capability aggregated_capabilities = 9;

  // Cell readiness score (0.0-1.0)
  // Computed by CapabilityAggregator.calculate_readiness_score()
  float readiness_score = 10;

  // Cell bounding box (for spatial queries)
  BoundingBox bounding_box = 11;

  // Last aggregation timestamp
  common.v1.Timestamp aggregated_at = 12;
}

// Cohort-level aggregated state summary
//
// Represents the aggregated state of a cohort (a set of cells sharing a
// mission, role, region, or time window).
//
// Published by cohort coordinators for consumption by federation coordinators.
// Reduces N CellSummary messages to 1 cohort-level summary.
message CohortSummary {
  // Cohort identifier
  string cohort_id = 1;

  // Cohort coordinator node ID
  string leader_id = 2;

  // Cell IDs in this cohort
  repeated string cell_ids = 3;

  // Total cell count
  uint32 cell_count = 4;

  // Total member count across all cells
  uint32 total_member_count = 5;

  // Aggregated position (centroid of cell centroids)
  common.v1.Position position_centroid = 6;

  // Average fuel across all cells (minutes)
  float avg_fuel_minutes = 7;

  // Worst health status across all cells
  node.v1.HealthStatus worst_health = 8;

  // Total operational member count
  uint32 operational_count = 9;

  // Cohort-level aggregated capabilities
  // Composition of cell-level capabilities
  repeated capability.v1.Capability aggregated_capabilities = 10;

  // Cohort readiness score (0.0-1.0)
  // Weighted average of cell readiness scores
  float readiness_score = 11;

  // Cohort bounding box
  BoundingBox bounding_box = 12;

  // Last aggregation timestamp
  common.v1.Timestamp aggregated_at = 13;
}

// Federation-level aggregated state summary
//
// Represents the aggregated state of a federation — an autonomous alliance
// of cohorts coordinating without a central authority.
//
// Enables higher-level coordinators to see federation-level summaries without
// processing N individual node states or N cohort summaries.
message FederationSummary {
  // Federation identifier
  string federation_id = 1;

  // Federation coordinator node ID
  string leader_id = 2;

  // Cohort IDs in this federation
  repeated string cohort_ids = 3;

  // Total cohort count
  uint32 cohort_count = 4;

  // Total member count across all cohorts
  uint32 total_member_count = 5;

  // Aggregated position (centroid of cohort centroids)
  common.v1.Position position_centroid = 6;

  // Average fuel across all cohorts (minutes)
  float avg_fuel_minutes = 7;

  // Worst health status across all cohorts
  node.v1.HealthStatus worst_health = 8;

  // Total operational member count
  uint32 operational_count = 9;

  // Federation-level aggregated capabilities
  repeated capability.v1.Capability aggregated_capabilities = 10;

  // Federation readiness score (0.0-1.0)
  float readiness_score = 11;

  // Federation bounding box
  BoundingBox bounding_box = 12;

  // Last aggregation timestamp
  common.v1.Timestamp aggregated_at = 13;
}

// Coalition-level aggregated state summary
//
// Top-tier aggregation under the four-tier rigid-schema model (ADR-066).
// Represents a coalition — an alliance of federations for combined action.
// Targets deployments at ~1000+ peer scale where federation-only aggregation
// would saturate higher-level coordinators.
//
// Tier 5+ requires a future parametric N-tier model (see ADR-066 §Tier-count
// extensibility).
message CoalitionSummary {
  // Coalition identifier
  string coalition_id = 1;

  // Coalition coordinator node ID
  string leader_id = 2;

  // Federation IDs in this coalition
  repeated string federation_ids = 3;

  // Total federation count
  uint32 federation_count = 4;

  // Total member count across all federations
  uint32 total_member_count = 5;

  // Aggregated position (centroid of federation centroids)
  common.v1.Position position_centroid = 6;

  // Average fuel across all federations (minutes)
  float avg_fuel_minutes = 7;

  // Worst health status across all federations
  node.v1.HealthStatus worst_health = 8;

  // Total operational member count
  uint32 operational_count = 9;

  // Coalition-level aggregated capabilities
  repeated capability.v1.Capability aggregated_capabilities = 10;

  // Coalition readiness score (0.0-1.0)
  float readiness_score = 11;

  // Coalition bounding box
  BoundingBox bounding_box = 12;

  // Last aggregation timestamp
  common.v1.Timestamp aggregated_at = 13;
}

// Spatial bounding box for formation
//
// Defines the geographic extent of any tier (cell/cohort/federation/coalition).
// Useful for spatial queries and situational awareness.
message BoundingBox {
  // Southwest corner (minimum lat/lon)
  common.v1.Position southwest = 1;

  // Northeast corner (maximum lat/lon)
  common.v1.Position northeast = 2;

  // Maximum altitude in formation
  float max_altitude = 3;

  // Minimum altitude in formation
  float min_altitude = 4;

  // Approximate radius in meters (from centroid to furthest member)
  float radius_m = 5;
}

// Aggregation metadata
//
// Provides context about how an aggregation was performed.
// Useful for debugging and understanding data staleness.
message AggregationMetadata {
  // Number of source documents aggregated
  uint32 source_count = 1;

  // Number of sources excluded (e.g., non-operational nodes)
  uint32 excluded_count = 2;

  // Aggregation method used
  string aggregation_method = 3;

  // Timestamp when aggregation was performed
  common.v1.Timestamp performed_at = 4;

  // Oldest source document timestamp (for staleness detection)
  common.v1.Timestamp oldest_source = 5;

  // Newest source document timestamp
  common.v1.Timestamp newest_source = 6;
}
