own tree shape

2 files changed, 25 insertions, 2 deletions

diff --git a/docs/measurements.md b/docs/measurements.md
index daf8008..81ca0fc 100644
--- a/docs/measurements.md
+++ b/docs/measurements.md
@@ -98,6 +98,9 @@ or caught up over many small messages.
 | `topology.view.stable` | `stable_members` | Members whose registry entry says `stable`. |
 | `topology.view.neighbours` | `neighbours` | Current neighbours: peers this node keeps alive and syncs with on its own. At least `k` (links chosen by either end count); well above `k` on a stable member that many others chose, bounded at about 8 × k. |
 | `topology.view.stableNeighbours` | `stable_neighbours` | Of those, stable members. |
+| `topology.view.ownTree.members` | `own_tree_members` | Other members in this node's own writer's tree: what its writes go along ([`peers.md`](peers.md)), as this node computes it (what members beyond its neighbours reach is taken from the member list's graph). |
+| `topology.view.ownTree.depth`, `.meanDepth` | `own_tree_depth`, `own_tree_mean_depth` | The most hops along it from this node to one of them, and the mean. |
+| `topology.view.ownTree.offTree` | `own_tree_off_members` | Members it doesn't reach: no member they reach comes before them, they are below one such, or the member list's graph doesn't connect them to this node. They get its writes by announcement. |
 
 `view` is absent until the node is ready and knows the member list; until then
 everyone counts as a neighbour.
@@ -105,7 +108,9 @@ everyone counts as a neighbour.
 **Interpretation.** `members − reachable − 1` is how many members are offline or
 unreachable from here; if it is half or more of the electorate, no remake can commit.
 `neighbours` far above `k` on one node means it is a hub (a stable member among few),
-which is by design but costs it bandwidth.
+which is by design but costs it bandwidth. A deep own tree, or members off it, means this node's
+writes take long to reach everyone: a writer behind NAT (one member reached), or
+transports bridged by few members.
 
 ## Stability
 
diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index a1b9969..3d74746 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -2069,7 +2069,7 @@ components:
               oneOf:
                 - type: 'null'
                 - type: object
-                  required: [members, reachable, stable, neighbours, stableNeighbours]
+                  required: [members, reachable, stable, neighbours, stableNeighbours, ownTree]
                   properties:
                     members:
                       type: integer
@@ -2083,6 +2083,24 @@ components:
                       type: integer
                     stableNeighbours:
                       type: integer
+                    ownTree:
+                      description: This node's own writer's tree; null while it isn't in the member list's graph.
+                      oneOf:
+                        - type: 'null'
+                        - type: object
+                          required: [members, depth, meanDepth, offTree]
+                          properties:
+                            members:
+                              type: integer
+                              description: Other members in it.
+                            depth:
+                              type: integer
+                              description: The most hops along it to one of them.
+                            meanDepth:
+                              type: number
+                            offTree:
+                              type: integer
+                              description: Members it doesn't reach; they get this node's writes by announcement.
         stability:
           type: object
           required: [tier, connectedFraction, observedSecs]