feat(stats): add bounded path and hash-width analytics (#159)

docs/swagger.yaml

@@ -966,6 +966,68 @@ definitions:
       nextCursor:
         type: integer
     type: object
+  github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth:
+    properties:
+      bytes:
+        type: integer
+      receptions:
+        type: integer
+    type: object
+  github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour:
+    properties:
+      empty:
+        type: integer
+      hour:
+        type: integer
+      oneByte:
+        type: integer
+      receptions:
+        type: integer
+      threeByte:
+        type: integer
+      trace:
+        type: integer
+      twoByte:
+        type: integer
+      unclassified:
+        type: integer
+    type: object
+  github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin:
+    properties:
+      entries:
+        type: integer
+      receptions:
+        type: integer
+    type: object
+  github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats:
+    properties:
+      empty:
+        type: integer
+      hashWidths:
+        items:
+          $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHashWidth'
+        type: array
+      hashed:
+        type: integer
+      hourly:
+        items:
+          $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathHour'
+        type: array
+      pathLengths:
+        items:
+          $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathLengthBin'
+        type: array
+      receptions:
+        type: integer
+      since:
+        type: integer
+      trace:
+        type: integer
+      unclassified:
+        type: integer
+      until:
+        type: integer
+    type: object
   github_com_MeshCore-Beacon_beacon-server_internal_api.PayloadBreakdownItem:
     properties:
       count:
@@ -3039,6 +3101,63 @@ paths:
       summary: Network overview stats (last 24h)
       tags:
       - Stats
+  /stats/paths:
+    get:
+      description: Counts stored receptions in [since, until), at most 30 days. Hash
+        widths count only validated nonempty ordinary header paths (1/2/3 bytes).
+        Empty paths do not vote for a width. TRACE header paths contain signal readings
+        and are separate. Missing payload type or inconsistent/unsupported path metadata
+        is unclassified. The four categories partition total receptions. Flood paths
+        accumulate entries; direct paths contain remaining entries, so counts do not
+        measure distance or a complete traversed route. Both boundaries round down
+        to UTC hours and the response reports that effective window. Reads use materialized
+        snapshots refreshed by background.view_refresh; the current partial hour is
+        excluded and missing hours are omitted.
+      parameters:
+      - description: Inclusive start, epoch milliseconds (0 through 253402300799999)
+        in: query
+        name: since
+        required: true
+        type: integer
+      - description: Exclusive end, epoch milliseconds; at most 30 days after since
+        in: query
+        name: until
+        required: true
+        type: integer
+      - description: Comma-separated reception IATA codes
+        in: query
+        name: iatas
+        type: string
+      - description: Region ID, expands to member IATAs
+        in: query
+        name: regionId
+        type: integer
+      - description: Region slug, expands to member IATAs
+        in: query
+        name: region
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/github_com_MeshCore-Beacon_beacon-server_internal_api.PathStats'
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/internal_api_handlers.APIError'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/internal_api_handlers.APIError'
+        "503":
+          description: Service Unavailable
+          schema:
+            $ref: '#/definitions/internal_api_handlers.APIError'
+      summary: Received path-entry and hash-width distributions
+      tags:
+      - Stats
   /stats/payload-breakdown:
     get:
       parameters: