Merge remote-tracking branch 'origin/dev' into codex/post20-base-20261002

docs/docs.go

@@ -2835,7 +2835,7 @@ const docTemplate = `{
         },
         "/stats/scopes": {
             "get": {
-                "description": "Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.",
+                "description": "Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. hourly splits packetCount by UTC hour and adds the distinct observers and advertising nodes active in the scope each hour (empty hours omitted; outage gaps come from /stats/series hour status). With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.",
                 "produces": [
                     "application/json"
                 ],
@@ -4872,6 +4872,10 @@ const docTemplate = `{
                 "hour": {
                     "type": "integer"
                 },
+                "maxEntries": {
+                    "description": "longest path received that hour across the requested IATAs; 0 if only empty paths",
+                    "type": "integer"
+                },
                 "oneByte": {
                     "type": "integer"
                 },
@@ -5205,9 +5209,36 @@ const docTemplate = `{
                 }
             }
         },
+        "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour": {
+            "type": "object",
+            "properties": {
+                "hour": {
+                    "description": "epoch ms, start of the UTC hour",
+                    "type": "integer"
+                },
+                "nodes": {
+                    "description": "distinct nodes whose adverts were heard in the scope that hour",
+                    "type": "integer"
+                },
+                "observers": {
+                    "description": "distinct observers that heard the scope's packets that hour",
+                    "type": "integer"
+                },
+                "packets": {
+                    "type": "integer"
+                }
+            }
+        },
         "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats": {
             "type": "object",
             "properties": {
+                "hourly": {
+                    "description": "packetCount by hour, oldest first; hours with none omitted",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour"
+                    }
+                },
                 "name": {
                     "description": "normalized scope name e.g. \"#bc\"",
                     "type": "string"

docs/historical-stats.md

@@ -48,6 +48,7 @@ sub-hour observer activity.
 | Observations, receptions, payload counts | Sum |
 | Unique packets, adverts, messages, scoped packets | Sum of hourly IATA-set counts: each is counted once per hour it was heard, so one heard across an hour boundary counts twice (measured +1.1%) |
 | Active observers, IATAs, scopes | Distinct across the window |
+| Active scope observers and nodes (per scope, per hour) | Distinct within the hour, across the requested IATAs |
 | Max path entries | Max |
 | SNR / RSSI averages | Σ sum / Σ samples, never an average of averages |
 

docs/swagger.json

@@ -2833,7 +2833,7 @@
         },
         "/stats/scopes": {
             "get": {
-                "description": "Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.",
+                "description": "Packets are those heard since the window start, each counted once per hour however many of the requested IATAs heard it. Observers and nodes are current memberships: observers filter by the IATA they last reported from, nodes by their IATA memberships. hourly splits packetCount by UTC hour and adds the distinct observers and advertising nodes active in the scope each hour (empty hours omitted; outage gaps come from /stats/series hour status). With filters, lists only manual scopes configured for a matching region and imported scopes whose current MeshMapper catalogue includes a matching IATA; those remain listed with zero counts. An empty region returns an empty array.",
                 "produces": [
                     "application/json"
                 ],
@@ -4870,6 +4870,10 @@
                 "hour": {
                     "type": "integer"
                 },
+                "maxEntries": {
+                    "description": "longest path received that hour across the requested IATAs; 0 if only empty paths",
+                    "type": "integer"
+                },
                 "oneByte": {
                     "type": "integer"
                 },
@@ -5203,9 +5207,36 @@
                 }
             }
         },
+        "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour": {
+            "type": "object",
+            "properties": {
+                "hour": {
+                    "description": "epoch ms, start of the UTC hour",
+                    "type": "integer"
+                },
+                "nodes": {
+                    "description": "distinct nodes whose adverts were heard in the scope that hour",
+                    "type": "integer"
+                },
+                "observers": {
+                    "description": "distinct observers that heard the scope's packets that hour",
+                    "type": "integer"
+                },
+                "packets": {
+                    "type": "integer"
+                }
+            }
+        },
         "github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats": {
             "type": "object",
             "properties": {
+                "hourly": {
+                    "description": "packetCount by hour, oldest first; hours with none omitted",
+                    "type": "array",
+                    "items": {
+                        "$ref": "#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour"
+                    }
+                },
                 "name": {
                     "description": "normalized scope name e.g. \"#bc\"",
                     "type": "string"

docs/swagger.yaml

@@ -1021,6 +1021,10 @@ definitions:
         type: integer
       hour:
         type: integer
+      maxEntries:
+        description: longest path received that hour across the requested IATAs; 0
+          if only empty paths
+        type: integer
       oneByte:
         type: integer
       receptions:
@@ -1242,8 +1246,27 @@ definitions:
       packetCount:
         type: integer
     type: object
+  github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour:
+    properties:
+      hour:
+        description: epoch ms, start of the UTC hour
+        type: integer
+      nodes:
+        description: distinct nodes whose adverts were heard in the scope that hour
+        type: integer
+      observers:
+        description: distinct observers that heard the scope's packets that hour
+        type: integer
+      packets:
+        type: integer
+    type: object
   github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeStats:
     properties:
+      hourly:
+        description: packetCount by hour, oldest first; hours with none omitted
+        items:
+          $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.ScopeHour'
+        type: array
       name:
         description: normalized scope name e.g. "#bc"
         type: string
@@ -3576,10 +3599,12 @@ paths:
       description: 'Packets are those heard since the window start, each counted once
         per hour however many of the requested IATAs heard it. Observers and nodes
         are current memberships: observers filter by the IATA they last reported from,
-        nodes by their IATA memberships. With filters, lists only manual scopes configured
-        for a matching region and imported scopes whose current MeshMapper catalogue
-        includes a matching IATA; those remain listed with zero counts. An empty region
-        returns an empty array.'
+        nodes by their IATA memberships. hourly splits packetCount by UTC hour and
+        adds the distinct observers and advertising nodes active in the scope each
+        hour (empty hours omitted; outage gaps come from /stats/series hour status).
+        With filters, lists only manual scopes configured for a matching region and
+        imported scopes whose current MeshMapper catalogue includes a matching IATA;
+        those remain listed with zero counts. An empty region returns an empty array.'
       parameters:
       - description: Comma-separated IATA codes
         in: query