@peerbit/pubsub 5.2.11 → 5.3.1

package/dist/src/fanout-tree.js

@@ -1,15 +1,21 @@
-import { getPublicKeyFromPeerId, ready, sha256Sync, toBase64 } from "@peerbit/crypto";
 import { multiaddr } from "@multiformats/multiaddr";
+import { getPublicKeyFromPeerId, ready, sha256Sync, toBase64, } from "@peerbit/crypto";
 import { DirectStream, dontThrowIfDeliveryError, } from "@peerbit/stream";
 import { AnyWhere, DataMessage, } from "@peerbit/stream-interface";
 import { AbortError, TimeoutError, delay } from "@peerbit/time";
 import { anySignal } from "any-signal";
 import { Uint8ArrayList } from "uint8arraylist";
 import { normalizeUint8Array, toUint8Array } from "./bytes.js";
+import { JOIN_REJECT_LOW_BID, JOIN_REJECT_NO_CAPACITY, JOIN_REJECT_NOT_ATTACHED, JOIN_REJECT_REDIRECT_ADDR_MAX, JOIN_REJECT_REDIRECT_MAX, MSG_DATA, MSG_END, MSG_FETCH_REQ, MSG_IHAVE, MSG_JOIN_ACCEPT, MSG_JOIN_REJECT, MSG_JOIN_REQ, MSG_KICK, MSG_LEAVE, MSG_PARENT_PROBE_REPLY, MSG_PARENT_PROBE_REQ, MSG_PROVIDER_ANNOUNCE, MSG_PROVIDER_NOTIFY, MSG_PROVIDER_QUERY, MSG_PROVIDER_REPLY, MSG_PROVIDER_SUBSCRIBE, MSG_PROVIDER_UNSUBSCRIBE, MSG_PUBLISH_PROXY, MSG_REPAIR_REQ, MSG_ROUTE_QUERY, MSG_ROUTE_REPLY, MSG_TRACKER_ANNOUNCE, MSG_TRACKER_FEEDBACK, MSG_TRACKER_QUERY, MSG_TRACKER_REPLY, MSG_UNICAST, MSG_UNICAST_ACK, PARENT_PROBE_FLAG_ACCEPTING, PARENT_PROBE_FLAG_OVERLOADED, PARENT_PROBE_FLAG_REPAIRING, PARENT_PROBE_FLAG_ROOTED, TRACKER_FEEDBACK_DIAL_FAILED, TRACKER_FEEDBACK_JOINED, TRACKER_FEEDBACK_JOIN_REJECT, TRACKER_FEEDBACK_JOIN_TIMEOUT, UNICAST_ACK_DEFAULT_TIMEOUT_MS, clampU16, readU32BE, tsFanoutWireCodec, writeU32BE, } from "./fanout-tree-codec.js";
+import { evaluateParentUpgradeGate, normalizeParentUpgradePolicy, recordParentUpgradeSkip, } from "./fanout-tree-parent-upgrade.js";
 import { TopicRootControlPlane } from "./topic-root-control-plane.js";
 const CONTROL_PRIORITY = 10;
 const DATA_PRIORITY = 1;
 const ROUTE_PROXY_TIMEOUT_MS = 10_000;
+// Backstop bounds for the route-proxy machinery under query storms (#983):
+// each pending entry retains a live timer closure and a Set of child hashes.
+const ROUTE_PROXY_MAX_PENDING = 2_048;
+const ROUTE_PROXY_MAX_WAITERS = 512;
 const ROUTE_CACHE_MAX_ENTRIES_HARD_CAP = 100_000;
 const PEER_HINT_MAX_ENTRIES_HARD_CAP = 100_000;
 // Best-effort address cache for join candidates learned via trackers/redirects.
@@ -35,8 +41,15 @@ const OVERLOAD_KICK_MAX_PER_EVENT = 4;
 const DATA_WRITE_FAIL_KICK_STREAK_THRESHOLD = 3;
 const DATA_WRITE_FAIL_KICK_COOLDOWN_MS = 2_000;
 const DATA_WRITE_FAIL_KICK_MAX_PER_EVENT = 4;
-const JOIN_REJECT_REDIRECT_MAX = 4;
-const JOIN_REJECT_REDIRECT_ADDR_MAX = 8;
+const PARENT_REPAIR_DEAD_STREAK_THRESHOLD = 16;
+const PARENT_REPAIR_DEAD_MIN_LIVENESS_MS = 15_000;
+const REPAIR_RETRY_MIN_MS = 1_000;
+const REPAIR_RETRY_INTERVAL_FACTOR = 5;
+// A stream can remain locally readable/writable while silently dropping every
+// control frame. Repeated unanswered JOIN requests are end-to-end evidence that
+// the peer path needs to be rebuilt.
+const JOIN_TIMEOUT_RESET_STREAK_THRESHOLD = 3;
+const JOIN_TIMEOUT_RESET_COOLDOWN_MS = 10_000;
 const JOIN_REJECT_REDIRECT_QUEUE_MAX = 64;
 // When a relay loses its parent, pause before trying to rejoin so its children can
 // attach elsewhere (helps avoid disconnected components stabilizing).
@@ -45,622 +58,16 @@ const JOIN_REJECT_REDIRECT_QUEUE_MAX = 64;
 // This gives kicked children a window to reattach elsewhere (helps avoid stable
 // disconnected components). Leaf nodes (no children) rejoin immediately.
 const RELAY_REJOIN_COOLDOWN_MS = 3_000;
-const MSG_JOIN_REQ = 1;
-const MSG_JOIN_ACCEPT = 2;
-const MSG_JOIN_REJECT = 3;
-const MSG_KICK = 4;
-const MSG_DATA = 10;
-const MSG_END = 11;
-const MSG_UNICAST = 12;
-const MSG_ROUTE_QUERY = 13;
-const MSG_ROUTE_REPLY = 14;
-const MSG_PUBLISH_PROXY = 15;
-const MSG_LEAVE = 16;
-const MSG_UNICAST_ACK = 17;
-const MSG_REPAIR_REQ = 20;
-const MSG_FETCH_REQ = 21;
-const MSG_IHAVE = 22;
-const MSG_TRACKER_ANNOUNCE = 30;
-const MSG_TRACKER_QUERY = 31;
-const MSG_TRACKER_REPLY = 32;
-const MSG_TRACKER_FEEDBACK = 33;
-const MSG_PROVIDER_ANNOUNCE = 34;
-const MSG_PROVIDER_QUERY = 35;
-const MSG_PROVIDER_REPLY = 36;
-const MSG_PROVIDER_SUBSCRIBE = 37;
-const MSG_PROVIDER_UNSUBSCRIBE = 38;
-const MSG_PROVIDER_NOTIFY = 39;
-const JOIN_REJECT_NOT_ATTACHED = 1;
-const JOIN_REJECT_NO_CAPACITY = 2;
-const JOIN_REJECT_LOW_BID = 3;
-const TRACKER_FEEDBACK_JOINED = 1;
-const TRACKER_FEEDBACK_DIAL_FAILED = 2;
-const TRACKER_FEEDBACK_JOIN_TIMEOUT = 3;
-const TRACKER_FEEDBACK_JOIN_REJECT = 4;
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
-const writeU32BE = (buf, offset, value) => {
-    buf[offset + 0] = (value >>> 24) & 0xff;
-    buf[offset + 1] = (value >>> 16) & 0xff;
-    buf[offset + 2] = (value >>> 8) & 0xff;
-    buf[offset + 3] = value & 0xff;
-};
-const readU32BE = (buf, offset) => ((buf[offset + 0] << 24) |
-    (buf[offset + 1] << 16) |
-    (buf[offset + 2] << 8) |
-    buf[offset + 3]) >>> 0;
-const writeU64BE = (buf, offset, value) => {
-    let v = value & 0xffffffffffffffffn;
-    for (let i = 7; i >= 0; i--) {
-        buf[offset + i] = Number(v & 0xffn);
-        v >>= 8n;
-    }
-};
-const readU64BE = (buf, offset) => {
-    let v = 0n;
-    for (let i = 0; i < 8; i++) {
-        v = (v << 8n) | BigInt(buf[offset + i]);
-    }
-    return v;
-};
-const writeU16BE = (buf, offset, value) => {
-    buf[offset + 0] = (value >>> 8) & 0xff;
-    buf[offset + 1] = value & 0xff;
-};
-const readU16BE = (buf, offset) => ((buf[offset + 0] << 8) | buf[offset + 1]) >>> 0;
-const encodeJoinReq = (channelKey, reqId, bidPerByte) => {
-    const buf = new Uint8Array(1 + 32 + 4 + 4);
-    buf[0] = MSG_JOIN_REQ;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    writeU32BE(buf, 37, bidPerByte >>> 0);
-    return buf;
-};
-const MAX_ROUTE_HOPS = 32;
-const UNICAST_FLAG_ACK = 1;
-const UNICAST_ACK_DEFAULT_TIMEOUT_MS = 30_000;
-const encodeJoinAccept = (channelKey, reqId, level, parentRouteFromRoot) => {
-    const routeBytes = [];
-    let bytes = 1 + 32 + 4 + 2 + 1;
-    let count = 0;
-    for (const hop of parentRouteFromRoot ?? []) {
-        if (count >= MAX_ROUTE_HOPS)
-            break;
-        if (typeof hop !== "string")
-            continue;
-        const hb = textEncoder.encode(hop);
-        if (hb.length === 0 || hb.length > 255)
-            continue;
-        routeBytes.push(hb);
-        bytes += 1 + hb.length;
-        count += 1;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_JOIN_ACCEPT;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    writeU16BE(buf, 37, level & 0xffff);
-    buf[39] = count & 0xff;
-    let offset = 40;
-    for (const hb of routeBytes) {
-        buf[offset++] = hb.length & 0xff;
-        buf.set(hb, offset);
-        offset += hb.length;
-    }
-    return buf;
-};
-const encodeJoinReject = (channelKey, reqId, reason, redirects) => {
-    const encoded = [];
-    for (const r of redirects ?? []) {
-        if (!r?.hash)
-            continue;
-        const hashBytes = textEncoder.encode(r.hash);
-        if (hashBytes.length === 0 || hashBytes.length > 255)
-            continue;
-        const addrs = (r.addrs ?? [])
-            .filter((a) => a instanceof Uint8Array)
-            .filter((a) => a.length > 0 && a.length <= 0xffff)
-            .slice(0, JOIN_REJECT_REDIRECT_ADDR_MAX);
-        if (addrs.length === 0)
-            continue;
-        encoded.push({ hashBytes, addrs });
-        if (encoded.length >= JOIN_REJECT_REDIRECT_MAX)
-            break;
-    }
-    if (encoded.length === 0) {
-        const buf = new Uint8Array(1 + 32 + 4 + 1);
-        buf[0] = MSG_JOIN_REJECT;
-        buf.set(channelKey, 1);
-        writeU32BE(buf, 33, reqId >>> 0);
-        buf[37] = reason & 0xff;
-        return buf;
-    }
-    let bytes = 1 + 32 + 4 + 1 + 1;
-    for (const e of encoded) {
-        bytes += 1 + e.hashBytes.length + 1;
-        for (const a of e.addrs)
-            bytes += 2 + a.length;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_JOIN_REJECT;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = reason & 0xff;
-    buf[38] = Math.max(0, Math.min(255, encoded.length)) & 0xff;
-    let offset = 39;
-    for (const e of encoded) {
-        buf[offset++] = e.hashBytes.length & 0xff;
-        buf.set(e.hashBytes, offset);
-        offset += e.hashBytes.length;
-        buf[offset++] = Math.max(0, Math.min(255, e.addrs.length)) & 0xff;
-        for (const a of e.addrs) {
-            writeU16BE(buf, offset, a.length);
-            offset += 2;
-            buf.set(a, offset);
-            offset += a.length;
-        }
-    }
-    return buf;
-};
-const encodeKick = (channelKey) => {
-    const buf = new Uint8Array(1 + 32);
-    buf[0] = MSG_KICK;
-    buf.set(channelKey, 1);
-    return buf;
-};
-const encodeEnd = (channelKey, lastSeqExclusive) => {
-    const buf = new Uint8Array(1 + 32 + 4);
-    buf[0] = MSG_END;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, lastSeqExclusive >>> 0);
-    return buf;
-};
-const encodeRepairReq = (channelKey, reqId, missingSeqs) => {
-    const count = Math.max(0, Math.min(255, missingSeqs.length));
-    const buf = new Uint8Array(1 + 32 + 4 + 1 + count * 4);
-    buf[0] = MSG_REPAIR_REQ;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = count & 0xff;
-    for (let i = 0; i < count; i++) {
-        writeU32BE(buf, 38 + i * 4, missingSeqs[i] >>> 0);
-    }
-    return buf;
-};
-const encodeFetchReq = (channelKey, reqId, missingSeqs) => {
-    const count = Math.max(0, Math.min(255, missingSeqs.length));
-    const buf = new Uint8Array(1 + 32 + 4 + 1 + count * 4);
-    buf[0] = MSG_FETCH_REQ;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = count & 0xff;
-    for (let i = 0; i < count; i++) {
-        writeU32BE(buf, 38 + i * 4, missingSeqs[i] >>> 0);
-    }
-    return buf;
-};
-const encodeIHave = (channelKey, haveFrom, haveToExclusive) => {
-    const buf = new Uint8Array(1 + 32 + 4 + 4);
-    buf[0] = MSG_IHAVE;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, haveFrom >>> 0);
-    writeU32BE(buf, 37, haveToExclusive >>> 0);
-    return buf;
-};
-const encodeData = (payload) => {
-    const buf = new Uint8Array(1 + payload.length);
-    buf[0] = MSG_DATA;
-    buf.set(payload, 1);
-    return buf;
-};
-const encodePublishProxy = (channelKey, payload) => {
-    const buf = new Uint8Array(1 + 32 + payload.length);
-    buf[0] = MSG_PUBLISH_PROXY;
-    buf.set(channelKey, 1);
-    buf.set(payload, 33);
-    return buf;
-};
-const encodeLeave = (channelKey) => {
-    const buf = new Uint8Array(1 + 32);
-    buf[0] = MSG_LEAVE;
-    buf.set(channelKey, 1);
-    return buf;
-};
-const encodeUnicast = (channelKey, route, payload, options) => {
-    const wantsAck = options?.ackToken != null;
-    const flags = wantsAck ? UNICAST_FLAG_ACK : 0;
-    const toRouteBytes = [];
-    let bytes = 1 + 32 + 1 + (wantsAck ? 8 : 0) + 1;
-    let toCount = 0;
-    for (const hop of route ?? []) {
-        if (toCount >= MAX_ROUTE_HOPS)
-            break;
-        if (typeof hop !== "string")
-            continue;
-        const hb = textEncoder.encode(hop);
-        if (hb.length === 0 || hb.length > 255)
-            continue;
-        toRouteBytes.push(hb);
-        bytes += 1 + hb.length;
-        toCount += 1;
-    }
-    const replyRouteBytes = [];
-    let replyCount = 0;
-    if (wantsAck) {
-        bytes += 1; // replyRouteCount
-        for (const hop of options?.replyRoute ?? []) {
-            if (replyCount >= MAX_ROUTE_HOPS)
-                break;
-            if (typeof hop !== "string")
-                continue;
-            const hb = textEncoder.encode(hop);
-            if (hb.length === 0 || hb.length > 255)
-                continue;
-            replyRouteBytes.push(hb);
-            bytes += 1 + hb.length;
-            replyCount += 1;
-        }
-    }
-    bytes += payload.byteLength;
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_UNICAST;
-    buf.set(channelKey, 1);
-    buf[33] = flags & 0xff;
-    let offset = 34;
-    if (wantsAck) {
-        writeU64BE(buf, offset, options.ackToken);
-        offset += 8;
-    }
-    buf[offset++] = toCount & 0xff;
-    for (const hb of toRouteBytes) {
-        buf[offset++] = hb.length & 0xff;
-        buf.set(hb, offset);
-        offset += hb.length;
-    }
-    if (wantsAck) {
-        buf[offset++] = replyCount & 0xff;
-        for (const hb of replyRouteBytes) {
-            buf[offset++] = hb.length & 0xff;
-            buf.set(hb, offset);
-            offset += hb.length;
-        }
-    }
-    buf.set(payload, offset);
-    return buf;
-};
-const encodeUnicastAck = (channelKey, ackToken, route) => {
-    const routeBytes = [];
-    let bytes = 1 + 32 + 8 + 1;
-    let count = 0;
-    for (const hop of route ?? []) {
-        if (count >= MAX_ROUTE_HOPS)
-            break;
-        if (typeof hop !== "string")
-            continue;
-        const hb = textEncoder.encode(hop);
-        if (hb.length === 0 || hb.length > 255)
-            continue;
-        routeBytes.push(hb);
-        bytes += 1 + hb.length;
-        count += 1;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_UNICAST_ACK;
-    buf.set(channelKey, 1);
-    writeU64BE(buf, 33, ackToken);
-    buf[41] = count & 0xff;
-    let offset = 42;
-    for (const hb of routeBytes) {
-        buf[offset++] = hb.length & 0xff;
-        buf.set(hb, offset);
-        offset += hb.length;
-    }
-    return buf;
-};
-const encodeRouteQuery = (channelKey, reqId, targetHash) => {
-    const targetBytes = textEncoder.encode(targetHash);
-    const targetLen = Math.max(0, Math.min(255, targetBytes.length));
-    const buf = new Uint8Array(1 + 32 + 4 + 1 + targetLen);
-    buf[0] = MSG_ROUTE_QUERY;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = targetLen & 0xff;
-    buf.set(targetBytes.subarray(0, targetLen), 38);
-    return buf;
-};
-const encodeRouteReply = (channelKey, reqId, route) => {
-    const routeBytes = [];
-    let bytes = 1 + 32 + 4 + 1;
-    let count = 0;
-    for (const hop of route ?? []) {
-        if (count >= MAX_ROUTE_HOPS)
-            break;
-        if (typeof hop !== "string")
-            continue;
-        const hb = textEncoder.encode(hop);
-        if (hb.length === 0 || hb.length > 255)
-            continue;
-        routeBytes.push(hb);
-        bytes += 1 + hb.length;
-        count += 1;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_ROUTE_REPLY;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = count & 0xff;
-    let offset = 38;
-    for (const hb of routeBytes) {
-        buf[offset++] = hb.length & 0xff;
-        buf.set(hb, offset);
-        offset += hb.length;
-    }
-    return buf;
-};
-const decodeRoute = (data, offsetStart, routeCount) => {
-    let offset = offsetStart;
-    const route = [];
-    for (let i = 0; i < routeCount; i++) {
-        if (offset + 1 > data.length)
-            break;
-        const len = data[offset++];
-        if (len === 0)
-            break;
-        if (offset + len > data.length)
-            break;
-        if (route.length < MAX_ROUTE_HOPS) {
-            route.push(textDecoder.decode(data.subarray(offset, offset + len)));
-        }
-        offset += len;
-    }
-    return { route, offset };
-};
-const clampU16 = (v) => Math.max(0, Math.min(0xffff, v | 0));
-const encodeTrackerAnnounce = (channelKey, ttlMs, level, maxChildren, freeSlots, bidPerByte, addrs) => {
-    const addrCount = Math.max(0, Math.min(255, addrs.length));
-    let bytes = 1 + 32 + 4 + 2 + 2 + 2 + 4 + 1;
-    const addrBytes = new Array(addrCount);
-    for (let i = 0; i < addrCount; i++) {
-        const b = addrs[i].bytes;
-        addrBytes[i] = b;
-        bytes += 2 + b.length;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_TRACKER_ANNOUNCE;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, Math.max(0, Math.floor(ttlMs)) >>> 0);
-    writeU16BE(buf, 37, clampU16(level));
-    writeU16BE(buf, 39, clampU16(maxChildren));
-    writeU16BE(buf, 41, clampU16(freeSlots));
-    writeU32BE(buf, 43, Math.max(0, Math.floor(bidPerByte)) >>> 0);
-    buf[47] = addrCount & 0xff;
-    let offset = 48;
-    for (let i = 0; i < addrCount; i++) {
-        const b = addrBytes[i];
-        writeU16BE(buf, offset, b.length);
-        offset += 2;
-        buf.set(b, offset);
-        offset += b.length;
-    }
-    return buf;
-};
-const encodeTrackerQuery = (channelKey, reqId, want) => {
-    const buf = new Uint8Array(1 + 32 + 4 + 2);
-    buf[0] = MSG_TRACKER_QUERY;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    writeU16BE(buf, 37, clampU16(want));
-    return buf;
-};
-const encodeTrackerReply = (channelKey, reqId, entries) => {
-    const count = Math.max(0, Math.min(255, entries.length));
-    let bytes = 1 + 32 + 4 + 1;
-    const encoded = [];
-    for (let i = 0; i < count; i++) {
-        const e = entries[i];
-        const hashBytes = textEncoder.encode(e.hash);
-        if (hashBytes.length > 255)
-            continue;
-        const addrCount = Math.max(0, Math.min(255, e.addrs.length));
-        const addrs = e.addrs.slice(0, addrCount);
-        bytes += 1 + hashBytes.length + 2 + 2 + 4 + 1;
-        for (const a of addrs)
-            bytes += 2 + a.length;
-        encoded.push({
-            hashBytes,
-            level: e.level,
-            freeSlots: e.freeSlots,
-            bidPerByte: e.bidPerByte,
-            addrs,
-        });
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_TRACKER_REPLY;
-    buf.set(channelKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = Math.max(0, Math.min(255, encoded.length)) & 0xff;
-    let offset = 38;
-    for (const e of encoded) {
-        buf[offset++] = e.hashBytes.length & 0xff;
-        buf.set(e.hashBytes, offset);
-        offset += e.hashBytes.length;
-        writeU16BE(buf, offset, clampU16(e.level));
-        offset += 2;
-        writeU16BE(buf, offset, clampU16(e.freeSlots));
-        offset += 2;
-        writeU32BE(buf, offset, Math.max(0, Math.floor(e.bidPerByte)) >>> 0);
-        offset += 4;
-        buf[offset++] = Math.max(0, Math.min(255, e.addrs.length)) & 0xff;
-        for (const a of e.addrs) {
-            writeU16BE(buf, offset, a.length);
-            offset += 2;
-            buf.set(a, offset);
-            offset += a.length;
-        }
-    }
-    return buf;
-};
-const encodeTrackerFeedback = (channelKey, candidateHash, event, reason) => {
-    const hashBytes = textEncoder.encode(candidateHash);
-    const hashLen = Math.max(0, Math.min(255, hashBytes.length));
-    const buf = new Uint8Array(1 + 32 + 1 + hashLen + 1 + 1);
-    buf[0] = MSG_TRACKER_FEEDBACK;
-    buf.set(channelKey, 1);
-    buf[33] = hashLen & 0xff;
-    buf.set(hashBytes.subarray(0, hashLen), 34);
-    buf[34 + hashLen] = event & 0xff;
-    buf[34 + hashLen + 1] = reason & 0xff;
-    return buf;
-};
-const encodeProviderAnnounce = (namespaceKey, ttlMs, addrs) => {
-    const addrCount = Math.max(0, Math.min(255, addrs.length));
-    let bytes = 1 + 32 + 4 + 1;
-    const addrBytes = new Array(addrCount);
-    for (let i = 0; i < addrCount; i++) {
-        const b = addrs[i].bytes;
-        addrBytes[i] = b;
-        bytes += 2 + b.length;
-    }
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_PROVIDER_ANNOUNCE;
-    buf.set(namespaceKey, 1);
-    writeU32BE(buf, 33, Math.max(0, Math.floor(ttlMs)) >>> 0);
-    buf[37] = addrCount & 0xff;
-    let offset = 38;
-    for (let i = 0; i < addrCount; i++) {
-        const b = addrBytes[i];
-        writeU16BE(buf, offset, b.length);
-        offset += 2;
-        buf.set(b, offset);
-        offset += b.length;
-    }
-    return buf;
-};
-const encodeProviderQuery = (namespaceKey, reqId, want, seed) => {
-    const buf = new Uint8Array(1 + 32 + 4 + 2 + 4);
-    buf[0] = MSG_PROVIDER_QUERY;
-    buf.set(namespaceKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    writeU16BE(buf, 37, clampU16(want));
-    writeU32BE(buf, 39, seed >>> 0);
-    return buf;
-};
-const encodeProviderEntries = (entries) => {
-    const count = Math.max(0, Math.min(255, entries.length));
-    let bytes = 1;
-    const encoded = [];
-    for (let i = 0; i < count; i++) {
-        const e = entries[i];
-        const hashBytes = textEncoder.encode(e.hash);
-        if (hashBytes.length > 255)
-            continue;
-        const addrCount = Math.max(0, Math.min(255, e.addrs.length));
-        const addrs = e.addrs.slice(0, addrCount);
-        bytes += 1 + hashBytes.length + 1;
-        for (const a of addrs)
-            bytes += 2 + a.length;
-        encoded.push({ hashBytes, addrs });
-    }
-    return { bytes, encoded };
-};
-const encodeProviderReply = (namespaceKey, reqId, entries) => {
-    const { bytes: entryBytes, encoded } = encodeProviderEntries(entries);
-    let bytes = 1 + 32 + 4 + entryBytes;
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_PROVIDER_REPLY;
-    buf.set(namespaceKey, 1);
-    writeU32BE(buf, 33, reqId >>> 0);
-    buf[37] = Math.max(0, Math.min(255, encoded.length)) & 0xff;
-    let offset = 38;
-    for (const e of encoded) {
-        buf[offset++] = e.hashBytes.length & 0xff;
-        buf.set(e.hashBytes, offset);
-        offset += e.hashBytes.length;
-        buf[offset++] = Math.max(0, Math.min(255, e.addrs.length)) & 0xff;
-        for (const a of e.addrs) {
-            writeU16BE(buf, offset, a.length);
-            offset += 2;
-            buf.set(a, offset);
-            offset += a.length;
-        }
-    }
-    return buf;
-};
-const encodeProviderSubscribe = (namespaceKey, want, ttlMs) => {
-    const buf = new Uint8Array(1 + 32 + 2 + 4);
-    buf[0] = MSG_PROVIDER_SUBSCRIBE;
-    buf.set(namespaceKey, 1);
-    writeU16BE(buf, 33, clampU16(want));
-    writeU32BE(buf, 35, Math.max(0, Math.floor(ttlMs)) >>> 0);
-    return buf;
-};
-const encodeProviderUnsubscribe = (namespaceKey) => {
-    const buf = new Uint8Array(1 + 32);
-    buf[0] = MSG_PROVIDER_UNSUBSCRIBE;
-    buf.set(namespaceKey, 1);
-    return buf;
-};
-const encodeProviderNotify = (namespaceKey, entries) => {
-    const { bytes: entryBytes, encoded } = encodeProviderEntries(entries);
-    let bytes = 1 + 32 + entryBytes;
-    const buf = new Uint8Array(bytes);
-    buf[0] = MSG_PROVIDER_NOTIFY;
-    buf.set(namespaceKey, 1);
-    buf[33] = Math.max(0, Math.min(255, encoded.length)) & 0xff;
-    let offset = 34;
-    for (const e of encoded) {
-        buf[offset++] = e.hashBytes.length & 0xff;
-        buf.set(e.hashBytes, offset);
-        offset += e.hashBytes.length;
-        buf[offset++] = Math.max(0, Math.min(255, e.addrs.length)) & 0xff;
-        for (const a of e.addrs) {
-            writeU16BE(buf, offset, a.length);
-            offset += 2;
-            buf.set(a, offset);
-            offset += a.length;
-        }
-    }
-    return buf;
-};
-const decodeProviderEntries = (data, offsetStart, maxCount) => {
-    let offset = offsetStart;
-    const providers = [];
-    const limit = Math.min(maxCount, 255);
-    for (let i = 0; i < limit; i++) {
-        if (offset + 1 > data.length)
-            break;
-        const hashLen = data[offset++];
-        if (offset + hashLen > data.length)
-            break;
-        const hash = textDecoder.decode(data.subarray(offset, offset + hashLen));
-        offset += hashLen;
-        if (offset + 1 > data.length)
-            break;
-        const addrCount = data[offset++];
-        const addrs = [];
-        const addrMax = Math.min(addrCount, 16);
-        for (let j = 0; j < addrMax; j++) {
-            if (offset + 2 > data.length)
-                break;
-            const len = readU16BE(data, offset);
-            offset += 2;
-            if (offset + len > data.length)
-                break;
-            const bytes = data.subarray(offset, offset + len);
-            offset += len;
-            try {
-                addrs.push(multiaddr(bytes));
-            }
-            catch {
-                // ignore invalid
-            }
-        }
-        if (!hash)
-            continue;
-        providers.push({ hash, addrs });
+const PARENT_UPGRADE_ROOT_RESERVATION_TTL_MS = 5_000;
+const stableUnitInterval = (input) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
     }
-    return { providers, offset };
+    return (hash >>> 0) / 0x100000000;
 };
+const textEncoder = new TextEncoder();
 const createDeferred = () => {
     let resolve;
     let reject;
@@ -695,11 +102,50 @@ const createEmptyMetrics = () => ({
     joinAcceptReceived: 0,
     joinRejectSent: 0,
     joinRejectReceived: 0,
+    joinPeerResets: 0,
     kickSent: 0,
     kickReceived: 0,
     reparentDisconnect: 0,
     reparentStale: 0,
     reparentKicked: 0,
+    reparentUpgrade: 0,
+    reparentUpgradeSkipLeaf: 0,
+    reparentUpgradeSkipRepair: 0,
+    reparentUpgradeSkipData: 0,
+    reparentUpgradeSkipCooldown: 0,
+    reparentUpgradeSkipQuiet: 0,
+    reparentUpgradeSkipBudget: 0,
+    reparentUpgradeSkipCandidateLevel: 0,
+    reparentUpgradeSkipCandidateSlots: 0,
+    reparentUpgradeSkipCandidatePressure: 0,
+    reparentUpgradeSkipRootPressure: 0,
+    reparentUpgradeSkipProbeNoReply: 0,
+    reparentUpgradeSkipProbeNotRooted: 0,
+    reparentUpgradeSkipProbeRepair: 0,
+    reparentUpgradeSkipProbeLag: 0,
+    reparentUpgradeSkipProbeOverloaded: 0,
+    reparentUpgradeSkipProbeCooldown: 0,
+    parentProbeReqSent: 0,
+    parentProbeReqReceived: 0,
+    parentProbeReplySent: 0,
+    parentProbeReplyReceived: 0,
+    parentUpgradeRootReservationCreated: 0,
+    parentUpgradeRootReservationConsumed: 0,
+    parentUpgradeRootReservationRejected: 0,
+    parentUpgradeRootReservationMarginRejected: 0,
+    parentUpgradeRootReservationBlocked: 0,
+    parentUpgradeRootReservationExpired: 0,
+    parentShadowStart: 0,
+    parentShadowObserve: 0,
+    parentShadowPromote: 0,
+    parentShadowReset: 0,
+    parentShadowRejectNoReply: 0,
+    parentShadowRejectNotRooted: 0,
+    parentShadowRejectCapacity: 0,
+    parentShadowRejectRepair: 0,
+    parentShadowRejectLag: 0,
+    parentShadowRejectOverloaded: 0,
+    parentShadowRejectLevel: 0,
     endSent: 0,
     endReceived: 0,
     repairReqSent: 0,
@@ -727,6 +173,8 @@ const createEmptyMetrics = () => ({
     routeProxyQueries: 0,
     routeProxyTimeouts: 0,
     routeProxyFanout: 0,
+    routeProxyCoalesced: 0,
+    routeProxyRejected: 0,
 });
 const isDataId = (id) => id.length === 32 &&
     id[0] === ID_PREFIX[0] &&
@@ -737,6 +185,8 @@ export class FanoutTree extends DirectStream {
     channelsBySuffixKey = new Map();
     cachedSuffixKey = new WeakMap();
     metricsBySuffixKey = new Map();
+    joinTimeoutStreakByPeer = new Map();
+    joinResetCooldownUntilByPeer = new Map();
     bootstraps = [];
     trackerBySuffixKey = new Map();
     trackerNamespaceLru = new Map();
@@ -748,20 +198,33 @@ export class FanoutTree extends DirectStream {
     underlayPeerDisconnectHandler;
     pendingProviderQueryBySuffixKey = new Map();
     providerAnnounceBySuffixKey = new Map();
+    parentUpgradeShadowInFlightSuffixKey;
     defaultUploadOverheadBytes = 128;
     random;
     unicastAckNodeTag32;
     unicastAckSeq = 0;
     topicRootControlPlane;
+    // Native fanout components of the rust-core DirectStream engine
+    // (`@peerbit/network-rust`). When set, every frame encode/decode of the
+    // `/peerbit/fanout-tree/0.5.0` codec plus the parent-upgrade policy/gate
+    // decisions run natively (byte- and decision-identical, covered by the
+    // golden parity suite); the channel state machine, timers and events
+    // stay host-side. Unset (the default) leaves every code path as-is.
+    nativeFanout;
+    codec;
     constructor(components, opts) {
-        const { random, topicRootControlPlane, ...rest } = (opts ?? {});
+        const { random, topicRootControlPlane, ...rest } = (opts ??
+            {});
         super(components, FANOUT_PROTOCOLS, {
             canRelayMessage: false,
             ...rest,
         });
         this.random = typeof random === "function" ? random : Math.random;
+        this.nativeFanout = this.rustCore?.fanout;
+        this.codec = this.nativeFanout ?? tsFanoutWireCodec;
         this.unicastAckNodeTag32 = readU32BE(sha256Sync(textEncoder.encode(this.publicKeyHash)), 0);
-        this.topicRootControlPlane = topicRootControlPlane ?? new TopicRootControlPlane();
+        this.topicRootControlPlane =
+            topicRootControlPlane ?? new TopicRootControlPlane();
         const onPeerDisconnect = (ev) => {
             const peerId = ev?.detail;
             if (!peerId)
@@ -783,6 +246,8 @@ export class FanoutTree extends DirectStream {
             this.components.events.removeEventListener("peer:disconnect", this.underlayPeerDisconnectHandler);
             this.underlayPeerDisconnectHandler = undefined;
         }
+        this.joinTimeoutStreakByPeer.clear();
+        this.joinResetCooldownUntilByPeer.clear();
         return super.stop();
     }
     setBootstraps(addrs) {
@@ -878,6 +343,24 @@ export class FanoutTree extends DirectStream {
         }
         return cached;
     }
+    /** Decoded provider entries (raw multiaddr bytes) -> candidates. Invalid
+     * multiaddrs are dropped exactly like the historical inline parsing. */
+    toProviderCandidates(entries) {
+        const candidates = [];
+        for (const entry of entries) {
+            const addrs = [];
+            for (const bytes of entry.addrs) {
+                try {
+                    addrs.push(multiaddr(bytes));
+                }
+                catch {
+                    // ignore invalid multiaddrs
+                }
+            }
+            candidates.push({ hash: entry.hash, addrs });
+        }
+        return candidates;
+    }
     rememberProviderCandidates(id, candidates, expiresAt) {
         if (candidates.length === 0)
             return;
@@ -942,7 +425,7 @@ export class FanoutTree extends DirectStream {
                 addrs: candidate.addrs.map((a) => a.bytes),
                 expiresAt: now + 60_000,
             }));
-            void this._sendControl(hash, encodeProviderNotify(id.key, entries)).catch(dontThrowIfDeliveryError);
+            void this._sendControl(hash, this.codec.encodeProviderNotify(id.key, entries)).catch(dontThrowIfDeliveryError);
         }
         this.pruneProviderWatchersIfEmpty(id.suffixKey);
     }
@@ -1064,7 +547,7 @@ export class FanoutTree extends DirectStream {
             return;
         const ttlMs = ttlOverrideMs != null ? ttlOverrideMs : state.ttlMs;
         const addrs = this.getSelfAnnounceAddrs();
-        const bytes = encodeProviderAnnounce(state.id.key, ttlMs, addrs);
+        const bytes = this.codec.encodeProviderAnnounce(state.id.key, ttlMs, addrs);
         await this._sendControlMany(peers, bytes);
     }
     nextProviderReqId(suffixKey) {
@@ -1094,7 +577,7 @@ export class FanoutTree extends DirectStream {
             const shuffleInPlace = (arr, seed32) => {
                 if (arr.length <= 1)
                     return;
-                if ((seed32 >>> 0) === 0) {
+                if (seed32 >>> 0 === 0) {
                     for (let i = arr.length - 1; i > 0; i--) {
                         const j = Math.floor(this.random() * (i + 1));
                         const tmp = arr[i];
@@ -1143,7 +626,7 @@ export class FanoutTree extends DirectStream {
                 ? await this.ensureBootstrapPeers(bootstraps, dialTimeoutMs, signal, bootstrapMaxPeers)
                 : [];
             const perTrackerTimeout = Math.max(0, Math.floor(options.queryTimeoutMs ?? 1_000));
-            const overallTimeout = Math.max(0, Math.floor(options.timeoutMs ?? 5_000));
+            const overallTimeout = Math.max(0, Math.floor(options.timeoutMs ?? 8_000));
             const deadlineAt = overallTimeout > 0 ? Date.now() + overallTimeout : 0;
             const byReq = this.pendingProviderQueryBySuffixKey.get(id.suffixKey) ||
                 new Map();
@@ -1153,9 +636,13 @@ export class FanoutTree extends DirectStream {
                 const p = new Promise((resolve) => {
                     byReq.set(reqId, { resolve });
                 });
-                void this._sendControl(trackerHash, encodeProviderQuery(id.key, reqId, want, seed));
-                const remainingMs = deadlineAt > 0 ? Math.max(0, deadlineAt - Date.now()) : perTrackerTimeout;
-                const timeoutMs = deadlineAt > 0 ? Math.min(perTrackerTimeout, remainingMs) : perTrackerTimeout;
+                void this._sendControl(trackerHash, this.codec.encodeProviderQuery(id.key, reqId, want, seed));
+                const remainingMs = deadlineAt > 0
+                    ? Math.max(0, deadlineAt - Date.now())
+                    : perTrackerTimeout;
+                const timeoutMs = deadlineAt > 0
+                    ? Math.min(perTrackerTimeout, remainingMs)
+                    : perTrackerTimeout;
                 const res = await Promise.race([
                     p,
                     delay(timeoutMs, { signal }).then(() => null),
@@ -1252,7 +739,7 @@ export class FanoutTree extends DirectStream {
                 this.providerWatchesBySuffixKey.delete(id.suffixKey);
             }
             for (const trackerHash of watch.trackerPeers) {
-                void this._sendControl(trackerHash, encodeProviderUnsubscribe(id.key)).catch(dontThrowIfDeliveryError);
+                void this._sendControl(trackerHash, this.codec.encodeProviderUnsubscribe(id.key)).catch(dontThrowIfDeliveryError);
             }
             watch.trackerPeers = [];
         };
@@ -1272,12 +759,15 @@ export class FanoutTree extends DirectStream {
                         : [];
                     watch.trackerPeers = trackerPeers;
                     for (const trackerHash of trackerPeers) {
-                        void this._sendControl(trackerHash, encodeProviderSubscribe(id.key, watch.want, watch.ttlMs)).catch(dontThrowIfDeliveryError);
+                        void this._sendControl(trackerHash, this.codec.encodeProviderSubscribe(id.key, watch.want, watch.ttlMs)).catch(dontThrowIfDeliveryError);
                     }
                 }
                 catch (error) {
                     if (error instanceof AbortError ||
-                        (error && typeof error === "object" && "name" in error && error.name === "AbortError")) {
+                        (error &&
+                            typeof error === "object" &&
+                            "name" in error &&
+                            error.name === "AbortError")) {
                         return;
                     }
                 }
@@ -1337,9 +827,9 @@ export class FanoutTree extends DirectStream {
         const neighborRepair = opts.neighborRepair === true;
         const neighborRepairPeers = Math.max(0, Math.floor(opts.neighborRepairPeers ?? 2));
         const neighborMeshPeers = Math.max(0, Math.floor(opts.neighborMeshPeers ?? Math.max(0, neighborRepairPeers * 2)));
-        const neighborAnnounceIntervalMs = Math.max(0, Math.floor(opts.neighborAnnounceIntervalMs ?? 500));
-        const neighborMeshRefreshIntervalMs = Math.max(0, Math.floor(opts.neighborMeshRefreshIntervalMs ?? 2_000));
-        const neighborHaveTtlMs = Math.max(0, Math.floor(opts.neighborHaveTtlMs ?? 5_000));
+        const neighborAnnounceIntervalMs = Math.max(0, Math.floor(opts.neighborAnnounceIntervalMs ?? 800));
+        const neighborMeshRefreshIntervalMs = Math.max(0, Math.floor(opts.neighborMeshRefreshIntervalMs ?? 10_000));
+        const neighborHaveTtlMs = Math.max(0, Math.floor(opts.neighborHaveTtlMs ?? 8_000));
         const neighborRepairBudgetBps = Math.max(0, Math.floor(opts.neighborRepairBudgetBps ?? 0));
         const neighborRepairBurstMs = Math.max(0, Math.floor(opts.neighborRepairBurstMs ?? 1_000));
         const neighborRepairTokenCapacity = neighborRepairBudgetBps > 0 && neighborRepairBurstMs > 0
@@ -1364,6 +854,14 @@ export class FanoutTree extends DirectStream {
             parent: undefined,
             children: new Map(),
             rejoinCooldownUntil: 0,
+            parentUpgradeCount: 0,
+            parentUpgradeLastAt: 0,
+            parentUpgradeBackoffMs: 0,
+            parentUpgradeBackoffUntil: 0,
+            parentUpgradeRetryAfterSeq: -1,
+            parentUpgradeStaleRootProbeRound: 0,
+            parentUpgradeTrackerNoCapacityUntil: 0,
+            parentProbeRejectBackoffMsByHash: new Map(),
             joinedAtLeastOnce: opts.role === "root",
             routeFromRoot: opts.role === "root" ? [this.publicKeyHash] : undefined,
             routeByPeer: new Map(),
@@ -1413,22 +911,33 @@ export class FanoutTree extends DirectStream {
                 : undefined,
             nextExpectedSeq: 0,
             missingSeqs: new Set(),
+            repairRequestedAtBySeq: new Map(),
             endSeqExclusive: -1,
             lastRepairSentAt: 0,
+            parentRepairUnansweredStreak: 0,
             lastParentDataAt: 0,
+            lastParentUpgradeActivityAt: 0,
             receivedAnyParentData: false,
+            parentDataLatencySamples: 0,
+            parentDataLatencyEwmaMs: 0,
+            parentDataLatencyMaxMs: 0,
             channelPeers: new Map(),
             knownCandidateAddrs: new Map(),
             lazyPeers: new Set(),
             haveByPeer: new Map(),
             maxSeqSeen: -1,
             lastIHaveSentAt: 0,
+            cachedAnnounceTrackerPeers: undefined,
             lastIHaveSentMaxSeq: -1,
             pendingJoin: new Map(),
             pendingTrackerQuery: new Map(),
+            pendingParentProbe: new Map(),
+            parentUpgradeReservationsByHash: new Map(),
+            parentProbeRejectUntilByHash: new Map(),
             pendingRouteQuery: new Map(),
             pendingUnicastAck: new Map(),
             pendingRouteProxy: new Map(),
+            routeProxyByTarget: new Map(),
             bootstrapOverride: undefined,
             bootstrapDialTimeoutMs: 10_000,
             bootstrapMaxPeers: 0,
@@ -1487,24 +996,133 @@ export class FanoutTree extends DirectStream {
         }
         ch.pendingUnicastAck.clear();
     }
+    resetParentDataLatency(ch) {
+        ch.parentDataLatencySamples = 0;
+        ch.parentDataLatencyEwmaMs = 0;
+        ch.parentDataLatencyMaxMs = 0;
+    }
+    noteParentDataLatency(ch, timestamp) {
+        const sentAt = Number(timestamp);
+        if (!Number.isFinite(sentAt) || sentAt <= 0)
+            return;
+        const latencyMs = Date.now() - sentAt;
+        if (!Number.isFinite(latencyMs) || latencyMs < 0 || latencyMs > 60_000) {
+            return;
+        }
+        const samples = Math.min(0xffff, ch.parentDataLatencySamples + 1);
+        ch.parentDataLatencySamples = samples;
+        ch.parentDataLatencyEwmaMs =
+            samples <= 1
+                ? latencyMs
+                : ch.parentDataLatencyEwmaMs * 0.875 + latencyMs * 0.125;
+        ch.parentDataLatencyMaxMs = Math.max(ch.parentDataLatencyMaxMs, latencyMs);
+    }
+    clearParentUpgradeGrace(ch, notifyPreviousParent = false, notifyCandidateParent = false) {
+        const grace = ch.parentUpgradeGrace;
+        if (!grace)
+            return [];
+        clearTimeout(grace.timer);
+        ch.parentUpgradeGrace = undefined;
+        const sends = [];
+        if (notifyPreviousParent && grace.previousParent !== ch.parent) {
+            sends.push(this._sendControl(grace.previousParent, this.codec.encodeLeave(ch.id.key)).catch(() => { }));
+        }
+        if (notifyCandidateParent && grace.candidateParent !== ch.parent) {
+            sends.push(this._sendControl(grace.candidateParent, this.codec.encodeLeave(ch.id.key)).catch(() => { }));
+        }
+        return sends;
+    }
+    commitParentUpgradeGrace(ch) {
+        const grace = ch.parentUpgradeGrace;
+        if (!grace)
+            return;
+        clearTimeout(grace.timer);
+        ch.parentUpgradeGrace = undefined;
+        if (ch.closed || ch.parent !== grace.candidateParent)
+            return;
+        void this._sendControl(grace.previousParent, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+    }
+    rollbackParentUpgradeGrace(ch) {
+        const grace = ch.parentUpgradeGrace;
+        if (!grace)
+            return;
+        clearTimeout(grace.timer);
+        ch.parentUpgradeGrace = undefined;
+        if (ch.closed || ch.parent !== grace.candidateParent)
+            return;
+        ch.parent = grace.previousParent;
+        ch.level = grace.previousLevel;
+        ch.routeFromRoot = grace.previousRouteFromRoot
+            ? [...grace.previousRouteFromRoot]
+            : undefined;
+        ch.lastParentDataAt = grace.previousLastParentDataAt;
+        ch.lastParentUpgradeActivityAt =
+            grace.previousLastParentUpgradeActivityAt;
+        ch.receivedAnyParentData = grace.previousReceivedAnyParentData;
+        this.resetParentDataLatency(ch);
+        this.touchPeerHint(ch, grace.previousParent);
+        void this._sendControl(grace.candidateParent, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+        void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
+    }
+    startParentUpgradeGrace(ch, options) {
+        if (ch.closed || options.previousParent === options.candidateParent)
+            return;
+        void Promise.all(this.clearParentUpgradeGrace(ch, true, true)).catch(() => { });
+        const timeoutMs = Math.max(0, Math.floor(options.timeoutMs));
+        if (timeoutMs <= 0) {
+            void this._sendControl(options.previousParent, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+            return;
+        }
+        const timer = setTimeout(() => this.rollbackParentUpgradeGrace(ch), timeoutMs);
+        ch.parentUpgradeGrace = {
+            previousParent: options.previousParent,
+            candidateParent: options.candidateParent,
+            previousLevel: options.previousLevel,
+            previousRouteFromRoot: options.previousRouteFromRoot
+                ? [...options.previousRouteFromRoot]
+                : undefined,
+            previousLastParentDataAt: options.previousLastParentDataAt,
+            previousLastParentUpgradeActivityAt: options.previousLastParentUpgradeActivityAt,
+            previousReceivedAnyParentData: options.previousReceivedAnyParentData,
+            timer,
+            candidateFirstMessages: options.candidateFirstMessages,
+            previousFirstMessages: options.previousFirstMessages,
+            minCandidateFirstMessages: options.minCandidateFirstMessages,
+            minCandidateAdvantageMessages: options.minCandidateAdvantageMessages,
+            maxPreviousFirstMessages: options.maxPreviousFirstMessages,
+        };
+    }
     detachFromParent(ch) {
+        if (this.parentUpgradeShadowInFlightSuffixKey === ch.id.suffixKey) {
+            this.parentUpgradeShadowInFlightSuffixKey = undefined;
+        }
+        void Promise.all(this.clearParentUpgradeGrace(ch, true, true)).catch(() => { });
         ch.parent = undefined;
         ch.level = Number.POSITIVE_INFINITY;
         ch.routeFromRoot = undefined;
         ch.routeByPeer.clear();
         ch.lastParentDataAt = 0;
+        ch.lastParentUpgradeActivityAt = 0;
         ch.receivedAnyParentData = false;
+        this.resetParentDataLatency(ch);
         ch.pendingJoin.clear();
+        ch.pendingParentProbe.clear();
+        ch.parentShadow = undefined;
+        ch.parentUpgradeBackoffMs = 0;
+        ch.parentUpgradeBackoffUntil = 0;
+        ch.parentUpgradeRetryAfterSeq = -1;
+        ch.parentUpgradeStaleRootProbeRound = 0;
+        ch.parentUpgradeTrackerNoCapacityUntil = 0;
+        ch.parentProbeRejectUntilByHash.clear();
+        ch.parentProbeRejectBackoffMsByHash.clear();
         ch.pendingRouteQuery.clear();
         this.abortPendingUnicastAcks(ch, new AbortError("fanout channel detached"));
-        for (const pending of ch.pendingRouteProxy.values()) {
-            clearTimeout(pending.timer);
-        }
-        ch.pendingRouteProxy.clear();
+        this.clearRouteProxies(ch);
     }
     onPeerDisconnectedFromUnderlay(peerHash) {
         if (!peerHash)
             return;
+        this.joinTimeoutStreakByPeer.delete(peerHash);
         // Detach from a disconnected parent immediately, so children can rejoin.
         // This is more reliable than polling `getConnections()` because the underlay
         // can flap/reconnect faster than the join loop cadence.
@@ -1558,19 +1176,24 @@ export class FanoutTree extends DirectStream {
         const kickChildren = options?.kickChildren !== false;
         const pendingSends = [];
         if (notifyParent && !ch.isRoot && ch.parent) {
-            pendingSends.push(this._sendControl(ch.parent, encodeLeave(ch.id.key)).catch(() => { }));
+            pendingSends.push(this._sendControl(ch.parent, this.codec.encodeLeave(ch.id.key)).catch(() => { }));
         }
+        pendingSends.push(...this.clearParentUpgradeGrace(ch, notifyParent && !ch.isRoot, false));
         if (kickChildren && ch.children.size > 0) {
             pendingSends.push(this.kickChildren(ch).catch(() => { }));
         }
         ch.pendingJoin.clear();
         ch.pendingTrackerQuery.clear();
+        ch.pendingParentProbe.clear();
+        ch.parentProbeRejectUntilByHash.clear();
+        ch.parentProbeRejectBackoffMsByHash.clear();
+        ch.parentShadow = undefined;
+        if (this.parentUpgradeShadowInFlightSuffixKey === ch.id.suffixKey) {
+            this.parentUpgradeShadowInFlightSuffixKey = undefined;
+        }
         ch.pendingRouteQuery.clear();
         this.abortPendingUnicastAcks(ch, new AbortError("fanout channel closed"));
-        for (const pending of ch.pendingRouteProxy.values()) {
-            clearTimeout(pending.timer);
-        }
-        ch.pendingRouteProxy.clear();
+        this.clearRouteProxies(ch);
         ch.parent = undefined;
         ch.children.clear();
         ch.lazyPeers.clear();
@@ -1603,6 +1226,11 @@ export class FanoutTree extends DirectStream {
             routeCacheMaxEntries: ch.routeCacheMaxEntries,
         };
     }
+    /**
+     * Returns diagnostic counters for tests and simulation harnesses.
+     *
+     * @internal
+     */
     getChannelMetrics(topic, root) {
         const id = this.getChannelId(topic, root);
         return this.getMetricsForSuffixKey(id.suffixKey);
@@ -1662,11 +1290,23 @@ export class FanoutTree extends DirectStream {
         if (!ch.joinedOnce)
             ch.joinedOnce = createDeferred();
         if (!ch.joinLoop) {
-            ch.joinLoop = this._joinLoop(ch, joinOpts).catch((err) => {
+            const joinedOnce = ch.joinedOnce;
+            const joinLoop = this._joinLoop(ch, joinOpts)
+                .catch((err) => {
                 // Surface join errors to the caller without crashing the process
                 // via an unhandled rejection (joinLoop is not generally awaited).
-                ch.joinedOnce?.reject(err);
+                if (ch.joinLoop === joinLoop)
+                    ch.joinLoop = undefined;
+                if (ch.joinedOnce === joinedOnce && !ch.joinedAtLeastOnce) {
+                    ch.joinedOnce = undefined;
+                }
+                joinedOnce.reject(err);
+            })
+                .finally(() => {
+                if (ch.joinLoop === joinLoop)
+                    ch.joinLoop = undefined;
             });
+            ch.joinLoop = joinLoop;
         }
         return ch.joinedOnce.promise;
     }
@@ -1706,7 +1346,9 @@ export class FanoutTree extends DirectStream {
                 updatedAt: Date.now(),
             };
         }
-        const route = this.getCachedRoute(ch, targetHash);
+        // Speculative probe: a miss here says nothing about cache quality (the
+        // caller falls through to resolveRouteToken, which counts its own miss).
+        const route = this.getCachedRoute(ch, targetHash, { recordMiss: false });
         if (!route)
             return undefined;
         const entry = ch.routeByPeer.get(targetHash);
@@ -1751,8 +1393,7 @@ export class FanoutTree extends DirectStream {
         ch.knownCandidateAddrs.delete(hash);
         ch.knownCandidateAddrs.set(hash, limited);
         while (ch.knownCandidateAddrs.size > KNOWN_CANDIDATE_ADDRS_MAX_ENTRIES) {
-            const oldest = ch.knownCandidateAddrs.keys().next()
-                .value;
+            const oldest = ch.knownCandidateAddrs.keys().next().value;
             if (!oldest)
                 break;
             ch.knownCandidateAddrs.delete(oldest);
@@ -1833,23 +1474,27 @@ export class FanoutTree extends DirectStream {
             ch.metrics.routeCacheEvictions += 1;
         }
     }
-    getCachedRoute(ch, targetHash) {
+    getCachedRoute(ch, targetHash, opts) {
+        const recordMiss = opts?.recordMiss !== false;
         this.pruneRouteCache(ch);
         const entry = ch.routeByPeer.get(targetHash);
         if (!entry) {
-            ch.metrics.routeCacheMisses += 1;
+            if (recordMiss)
+                ch.metrics.routeCacheMisses += 1;
             return undefined;
         }
         const now = Date.now();
         if (ch.routeCacheTtlMs > 0 && now - entry.updatedAt > ch.routeCacheTtlMs) {
             ch.routeByPeer.delete(targetHash);
-            ch.metrics.routeCacheMisses += 1;
+            if (recordMiss)
+                ch.metrics.routeCacheMisses += 1;
             ch.metrics.routeCacheExpirations += 1;
             return undefined;
         }
         if (!this.isRouteValidForChannel(ch, entry.route)) {
             ch.routeByPeer.delete(targetHash);
-            ch.metrics.routeCacheMisses += 1;
+            if (recordMiss)
+                ch.metrics.routeCacheMisses += 1;
             return undefined;
         }
         // LRU touch
@@ -1883,14 +1528,92 @@ export class FanoutTree extends DirectStream {
         if (!proxy)
             return;
         ch.pendingRouteProxy.delete(proxyReqId);
+        const targetKey = `${proxy.direction}:${proxy.targetHash}`;
+        if (ch.routeProxyByTarget.get(targetKey) === proxyReqId) {
+            ch.routeProxyByTarget.delete(targetKey);
+        }
         clearTimeout(proxy.timer);
+        const reply = (requester, downstreamReqId) => {
+            void this._sendControl(requester, this.codec.encodeRouteReply(ch.id.key, downstreamReqId, route)).catch(() => { });
+        };
         if (proxy.localResolve) {
             proxy.localResolve(route);
-            return;
         }
-        void this._sendControl(proxy.requester, encodeRouteReply(ch.id.key, proxy.downstreamReqId, route)).catch(() => { });
+        else {
+            reply(proxy.requester, proxy.downstreamReqId);
+        }
+        if (proxy.waiters) {
+            for (const w of proxy.waiters) {
+                if ("localResolve" in w) {
+                    w.localResolve(route);
+                }
+                else {
+                    reply(w.requester, w.downstreamReqId);
+                }
+            }
+        }
+    }
+    /**
+     * Coalesce onto an in-flight same-target/same-direction proxy search, if one
+     * exists. Returns true when the requester was attached as a waiter (or
+     * answered empty on waiter overflow) and no new search should start.
+     */
+    coalesceRouteProxy(ch, targetHash, direction, waiter) {
+        const targetKey = `${direction}:${targetHash}`;
+        const existingId = ch.routeProxyByTarget.get(targetKey);
+        if (existingId == null)
+            return false;
+        const existing = ch.pendingRouteProxy.get(existingId);
+        if (!existing) {
+            ch.routeProxyByTarget.delete(targetKey);
+            return false;
+        }
+        if ((existing.waiters?.length ?? 0) >= ROUTE_PROXY_MAX_WAITERS) {
+            ch.metrics.routeProxyRejected += 1;
+            if ("localResolve" in waiter) {
+                waiter.localResolve(undefined);
+            }
+            else {
+                void this._sendControl(waiter.requester, this.codec.encodeRouteReply(ch.id.key, waiter.downstreamReqId)).catch(() => { });
+            }
+            return true;
+        }
+        (existing.waiters ??= []).push(waiter);
+        ch.metrics.routeProxyCoalesced += 1;
+        return true;
+    }
+    /**
+     * Drop all in-flight route-proxy state for a channel (detach/kick/close).
+     * Local resolvers are settled with `undefined` so root-origin
+     * `resolveRouteToken()` callers never hang; remote requesters time out on
+     * their own deadlines, as before.
+     */
+    clearRouteProxies(ch) {
+        for (const pending of ch.pendingRouteProxy.values()) {
+            clearTimeout(pending.timer);
+            pending.localResolve?.(undefined);
+            if (pending.waiters) {
+                for (const w of pending.waiters) {
+                    if ("localResolve" in w)
+                        w.localResolve(undefined);
+                }
+            }
+        }
+        ch.pendingRouteProxy.clear();
+        ch.routeProxyByTarget.clear();
     }
     proxyRouteQuery(ch, requester, downstreamReqId, targetHash, candidates, timeoutMs = ROUTE_PROXY_TIMEOUT_MS) {
+        // Direction matters for coalescing correctness: an upstream lookup and the
+        // root's downstream flood for the same target may legitimately transit the
+        // same node concurrently (e.g. the target lives in the requester's own
+        // branch), and merging them would make them wait on each other.
+        const direction = candidates.length === 1 && candidates[0] === ch.parent ? "up" : "down";
+        if (this.coalesceRouteProxy(ch, targetHash, direction, {
+            requester,
+            downstreamReqId,
+        })) {
+            return;
+        }
         const unique = [];
         const seen = new Set();
         for (const candidate of candidates) {
@@ -1903,7 +1626,12 @@ export class FanoutTree extends DirectStream {
             unique.push(candidate);
         }
         if (unique.length === 0) {
-            void this._sendControl(requester, encodeRouteReply(ch.id.key, downstreamReqId)).catch(() => { });
+            void this._sendControl(requester, this.codec.encodeRouteReply(ch.id.key, downstreamReqId)).catch(() => { });
+            return;
+        }
+        if (ch.pendingRouteProxy.size >= ROUTE_PROXY_MAX_PENDING) {
+            ch.metrics.routeProxyRejected += 1;
+            void this._sendControl(requester, this.codec.encodeRouteReply(ch.id.key, downstreamReqId)).catch(() => { });
             return;
         }
         ch.metrics.routeProxyQueries += 1;
@@ -1918,9 +1646,11 @@ export class FanoutTree extends DirectStream {
             downstreamReqId,
             timer,
             expectedReplies: new Set(unique),
+            targetHash,
+            direction,
         });
-        void this._sendControlMany(unique, encodeRouteQuery(ch.id.key, proxyReqId, targetHash))
-            .catch(() => {
+        ch.routeProxyByTarget.set(`${direction}:${targetHash}`, proxyReqId);
+        void this._sendControlMany(unique, this.codec.encodeRouteQuery(ch.id.key, proxyReqId, targetHash)).catch(() => {
             this.completeRouteProxy(ch, proxyReqId);
         });
     }
@@ -1950,14 +1680,47 @@ export class FanoutTree extends DirectStream {
             const timeoutMs = Math.max(1, Math.floor(options?.timeoutMs ?? 3_000));
             return await new Promise((resolve, reject) => {
                 let settled = false;
+                let proxyReqId;
                 const onAbort = () => {
                     if (settled)
                         return;
                     settled = true;
-                    ch.pendingRouteProxy.delete(proxyReqId);
-                    clearTimeout(timer);
+                    clearTimeout(backstop);
+                    if (proxyReqId != null) {
+                        // Tear the search down only if nobody else coalesced onto it;
+                        // otherwise let it finish for the waiters (our localResolve
+                        // is a no-op once settled).
+                        const entry = ch.pendingRouteProxy.get(proxyReqId);
+                        if (entry && (!entry.waiters || entry.waiters.length === 0)) {
+                            this.completeRouteProxy(ch, proxyReqId);
+                        }
+                    }
                     reject(new AbortError());
                 };
+                const localResolve = (route) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(backstop);
+                    if (options?.signal) {
+                        options.signal.removeEventListener("abort", onAbort);
+                    }
+                    if (this.isRouteValidForChannel(ch, route)) {
+                        this.cacheRoute(ch, route);
+                        resolve([...route]);
+                        return;
+                    }
+                    resolve(undefined);
+                };
+                // Per-caller timeout: when coalesced, the shared in-flight search
+                // may outlive this caller's own deadline.
+                const backstop = setTimeout(() => localResolve(undefined), timeoutMs);
+                if (options?.signal) {
+                    options.signal.addEventListener("abort", onAbort, { once: true });
+                }
+                if (this.coalesceRouteProxy(ch, targetHash, "down", { localResolve })) {
+                    return;
+                }
                 const unique = [];
                 const seen = new Set();
                 for (const candidate of candidates) {
@@ -1970,42 +1733,32 @@ export class FanoutTree extends DirectStream {
                     unique.push(candidate);
                 }
                 if (unique.length === 0) {
-                    resolve(undefined);
+                    localResolve(undefined);
+                    return;
+                }
+                if (ch.pendingRouteProxy.size >= ROUTE_PROXY_MAX_PENDING) {
+                    ch.metrics.routeProxyRejected += 1;
+                    localResolve(undefined);
                     return;
                 }
                 ch.metrics.routeProxyQueries += 1;
                 ch.metrics.routeProxyFanout += unique.length;
-                const proxyReqId = this.nextReqId(ch);
+                proxyReqId = this.nextReqId(ch);
                 const timer = setTimeout(() => {
                     ch.metrics.routeProxyTimeouts += 1;
                     this.completeRouteProxy(ch, proxyReqId);
                 }, timeoutMs);
-                if (options?.signal) {
-                    options.signal.addEventListener("abort", onAbort, { once: true });
-                }
                 ch.pendingRouteProxy.set(proxyReqId, {
                     requester: this.publicKeyHash,
                     downstreamReqId: 0,
                     timer,
                     expectedReplies: new Set(unique),
-                    localResolve: (route) => {
-                        if (settled)
-                            return;
-                        settled = true;
-                        clearTimeout(timer);
-                        if (options?.signal) {
-                            options.signal.removeEventListener("abort", onAbort);
-                        }
-                        if (this.isRouteValidForChannel(ch, route)) {
-                            this.cacheRoute(ch, route);
-                            resolve([...route]);
-                            return;
-                        }
-                        resolve(undefined);
-                    },
+                    targetHash,
+                    direction: "down",
+                    localResolve,
                 });
-                void this._sendControlMany(unique, encodeRouteQuery(ch.id.key, proxyReqId, targetHash))
-                    .catch(() => {
+                ch.routeProxyByTarget.set(`down:${targetHash}`, proxyReqId);
+                void this._sendControlMany(unique, this.codec.encodeRouteQuery(ch.id.key, proxyReqId, targetHash)).catch(() => {
                     this.completeRouteProxy(ch, proxyReqId);
                 });
             });
@@ -2052,8 +1805,7 @@ export class FanoutTree extends DirectStream {
                     resolve(undefined);
                 },
             });
-            void this._sendControl(ch.parent, encodeRouteQuery(ch.id.key, reqId, targetHash))
-                .catch((error) => {
+            void this._sendControl(ch.parent, this.codec.encodeRouteQuery(ch.id.key, reqId, targetHash)).catch((error) => {
                 if (settled)
                     return;
                 settled = true;
@@ -2101,7 +1853,7 @@ export class FanoutTree extends DirectStream {
             throw new Error("Unicast route token target mismatch");
         }
         if (target === this.publicKeyHash) {
-            const wire = encodeUnicast(ch.id.key, toRoute, payload);
+            const wire = this.codec.encodeUnicast(ch.id.key, toRoute, payload);
             const message = await this.createMessage(wire, {
                 mode: new AnyWhere(),
                 priority: CONTROL_PRIORITY,
@@ -2137,7 +1889,7 @@ export class FanoutTree extends DirectStream {
         if (replyRoute[replyRoute.length - 1] !== selfHash) {
             throw new Error("Cannot unicast with ACK: self route token target mismatch");
         }
-        const data = encodeUnicast(ch.id.key, toRoute, payload, {
+        const data = this.codec.encodeUnicast(ch.id.key, toRoute, payload, {
             ackToken,
             replyRoute,
         });
@@ -2231,7 +1983,7 @@ export class FanoutTree extends DirectStream {
         if (toRoute[0] !== ch.id.root) {
             throw new Error("Unicast route token root mismatch");
         }
-        const data = encodeUnicast(ch.id.key, toRoute, payload);
+        const data = this.codec.encodeUnicast(ch.id.key, toRoute, payload);
         if (ch.isRoot) {
             const target = toRoute[toRoute.length - 1];
             if (target === this.publicKeyHash) {
@@ -2314,7 +2066,7 @@ export class FanoutTree extends DirectStream {
         if (!ch.parent) {
             throw new Error(`Cannot proxy publish while not attached to a parent (topic=${topic} root=${root} self=${this.publicKeyHash})`);
         }
-        await this._sendControl(ch.parent, encodePublishProxy(ch.id.key, payload));
+        await this._sendControl(ch.parent, this.codec.encodePublishProxy(ch.id.key, payload));
     }
     async publishToChannelMaybe(topic, root, payload) {
         const id = this.getChannelId(topic, root);
@@ -2412,7 +2164,8 @@ export class FanoutTree extends DirectStream {
             return;
         if (!ch.isRoot)
             return;
-        await this._sendControlMany([...ch.children.keys()], encodeEnd(ch.id.key, lastSeqExclusive));
+        ch.endSeqExclusive = Math.max(ch.endSeqExclusive, lastSeqExclusive);
+        await this._sendControlMany([...ch.children.keys()], this.codec.encodeEnd(ch.id.key, lastSeqExclusive));
     }
     makeDataId(ch, seq) {
         const id = new Uint8Array(32);
@@ -2497,6 +2250,14 @@ export class FanoutTree extends DirectStream {
                 m.trackerFeedbackSent += transmissions;
                 m.controlBytesSentTracker += sentBytes;
                 break;
+            case MSG_PARENT_PROBE_REQ:
+                m.parentProbeReqSent += transmissions;
+                m.controlBytesSentJoin += sentBytes;
+                break;
+            case MSG_PARENT_PROBE_REPLY:
+                m.parentProbeReplySent += transmissions;
+                m.controlBytesSentJoin += sentBytes;
+                break;
             case MSG_PROVIDER_ANNOUNCE:
             case MSG_PROVIDER_QUERY:
             case MSG_PROVIDER_REPLY:
@@ -2562,6 +2323,14 @@ export class FanoutTree extends DirectStream {
                 m.trackerFeedbackReceived += 1;
                 m.controlBytesReceivedTracker += bytesReceived;
                 break;
+            case MSG_PARENT_PROBE_REQ:
+                m.parentProbeReqReceived += 1;
+                m.controlBytesReceivedJoin += bytesReceived;
+                break;
+            case MSG_PARENT_PROBE_REPLY:
+                m.parentProbeReplyReceived += 1;
+                m.controlBytesReceivedJoin += bytesReceived;
+                break;
             case MSG_PROVIDER_ANNOUNCE:
             case MSG_PROVIDER_QUERY:
             case MSG_PROVIDER_REPLY:
@@ -2590,6 +2359,38 @@ export class FanoutTree extends DirectStream {
             return;
         return ch.cachePayloads[idx];
     }
+    noteJoinResponse(peerHash) {
+        this.joinTimeoutStreakByPeer.delete(peerHash);
+    }
+    noteJoinTimeout(ch, peerHash) {
+        const streak = (this.joinTimeoutStreakByPeer.get(peerHash) ?? 0) + 1;
+        if (streak < JOIN_TIMEOUT_RESET_STREAK_THRESHOLD) {
+            this.joinTimeoutStreakByPeer.set(peerHash, streak);
+            return;
+        }
+        this.joinTimeoutStreakByPeer.delete(peerHash);
+        const now = Date.now();
+        for (const [hash, until] of this.joinResetCooldownUntilByPeer) {
+            if (until <= now)
+                this.joinResetCooldownUntilByPeer.delete(hash);
+        }
+        const resetCooldownUntil = this.joinResetCooldownUntilByPeer.get(peerHash) ?? 0;
+        if (resetCooldownUntil > now)
+            return;
+        const stream = this.peers.get(peerHash);
+        if (!stream)
+            return;
+        this.joinResetCooldownUntilByPeer.set(peerHash, now + JOIN_TIMEOUT_RESET_COOLDOWN_MS);
+        ch.metrics.joinPeerResets += 1;
+        try {
+            void this.components.connectionManager
+                .closeConnections(stream.peerId)
+                .catch(() => { });
+        }
+        catch {
+            // Best-effort reset. The join loop keeps retrying other candidates.
+        }
+    }
     async _sendControl(to, bytes) {
         const stream = this.peers.get(to);
         if (!stream)
@@ -2603,18 +2404,18 @@ export class FanoutTree extends DirectStream {
     }
     async _sendControlMany(to, bytes) {
         if (to.length === 0)
-            return;
+            return true;
         const streams = to
             .map((t) => this.peers.get(t))
             .filter((s) => Boolean(s));
         if (streams.length === 0)
-            return;
+            return false;
         this.recordControlSend(bytes, streams.length);
         const message = await this.createMessage(bytes, {
             mode: new AnyWhere(),
             priority: CONTROL_PRIORITY,
         });
-        await this.publishMessageMaybe(this.publicKey, message, streams);
+        return this.publishMessageMaybe(this.publicKey, message, streams);
     }
     refillUploadTokens(ch, now = Date.now()) {
         if (ch.uploadLimitBps <= 0)
@@ -2636,7 +2437,8 @@ export class FanoutTree extends DirectStream {
         if (elapsedMs <= 0)
             return;
         ch.neighborRepairLastRefillAt = now;
-        ch.neighborRepairTokens = Math.min(ch.neighborRepairTokenCapacity, ch.neighborRepairTokens + (elapsedMs * ch.neighborRepairBudgetBps) / 1_000);
+        ch.neighborRepairTokens = Math.min(ch.neighborRepairTokenCapacity, ch.neighborRepairTokens +
+            (elapsedMs * ch.neighborRepairBudgetBps) / 1_000);
     }
     takeIngressBudget(ch, kind, fromHash, costBytes, now = Date.now()) {
         if (!fromHash)
@@ -2673,7 +2475,7 @@ export class FanoutTree extends DirectStream {
     async _sendData(ch, to, seq, payload) {
         this.markCached(ch, seq, payload);
         ch.maxSeqSeen = Math.max(ch.maxSeqSeen, seq);
-        const framed = encodeData(payload);
+        const framed = this.codec.encodeData(payload);
         const message = await this.createMessage(framed, {
             mode: new AnyWhere(),
             priority: DATA_PRIORITY,
@@ -2742,14 +2544,12 @@ export class FanoutTree extends DirectStream {
                 });
                 const kickCount = Math.min(OVERLOAD_KICK_MAX_PER_EVENT, droppedCandidates.length);
                 if (kickCount > 0) {
-                    const toKick = droppedCandidates.slice(0, kickCount).map((c) => c.hash);
-                    for (const h of toKick) {
-                        ch.children.delete(h);
-                        ch.dataWriteFailStreakByChild.delete(h);
-                    }
+                    const toKick = droppedCandidates
+                        .slice(0, kickCount)
+                        .map((c) => c.hash);
                     ch.overloadStreak = 0;
                     ch.lastOverloadKickAt = now;
-                    void this._sendControlMany(toKick, encodeKick(ch.id.key));
+                    void this.kickChildHashes(ch, toKick).catch(() => { });
                     void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                 }
             }
@@ -2778,13 +2578,6 @@ export class FanoutTree extends DirectStream {
             const stream = c.stream;
             if (!stream.isWritable) {
                 writeDrops += 1;
-                if (ch.children.has(c.hash)) {
-                    const streak = (ch.dataWriteFailStreakByChild.get(c.hash) ?? 0) + 1;
-                    ch.dataWriteFailStreakByChild.set(c.hash, streak);
-                    if (streak >= DATA_WRITE_FAIL_KICK_STREAK_THRESHOLD) {
-                        writeFailKickCandidates.push(c.hash);
-                    }
-                }
                 continue;
             }
             try {
@@ -2831,12 +2624,8 @@ export class FanoutTree extends DirectStream {
             const kickCount = Math.min(DATA_WRITE_FAIL_KICK_MAX_PER_EVENT, unique.length);
             if (kickCount > 0) {
                 const toKick = unique.slice(0, kickCount);
-                for (const h of toKick) {
-                    ch.children.delete(h);
-                    ch.dataWriteFailStreakByChild.delete(h);
-                }
                 ch.lastDataWriteFailKickAt = now;
-                void this._sendControlMany(toKick, encodeKick(ch.id.key));
+                void this.kickChildHashes(ch, toKick, { resetPeerConnections: true }).catch(() => { });
                 void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
             }
         }
@@ -2915,14 +2704,12 @@ export class FanoutTree extends DirectStream {
                 });
                 const kickCount = Math.min(OVERLOAD_KICK_MAX_PER_EVENT, droppedCandidates.length);
                 if (kickCount > 0) {
-                    const toKick = droppedCandidates.slice(0, kickCount).map((c) => c.hash);
-                    for (const h of toKick) {
-                        ch.children.delete(h);
-                        ch.dataWriteFailStreakByChild.delete(h);
-                    }
+                    const toKick = droppedCandidates
+                        .slice(0, kickCount)
+                        .map((c) => c.hash);
                     ch.overloadStreak = 0;
                     ch.lastOverloadKickAt = now;
-                    void this._sendControlMany(toKick, encodeKick(ch.id.key));
+                    void this.kickChildHashes(ch, toKick).catch(() => { });
                     void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                 }
             }
@@ -2940,11 +2727,6 @@ export class FanoutTree extends DirectStream {
             const stream = c.stream;
             if (!stream.isWritable) {
                 writeDrops += 1;
-                const streak = (ch.dataWriteFailStreakByChild.get(c.hash) ?? 0) + 1;
-                ch.dataWriteFailStreakByChild.set(c.hash, streak);
-                if (streak >= DATA_WRITE_FAIL_KICK_STREAK_THRESHOLD) {
-                    writeFailKickCandidates.push(c.hash);
-                }
                 continue;
             }
             try {
@@ -2989,12 +2771,8 @@ export class FanoutTree extends DirectStream {
             const kickCount = Math.min(DATA_WRITE_FAIL_KICK_MAX_PER_EVENT, unique.length);
             if (kickCount > 0) {
                 const toKick = unique.slice(0, kickCount);
-                for (const h of toKick) {
-                    ch.children.delete(h);
-                    ch.dataWriteFailStreakByChild.delete(h);
-                }
                 ch.lastDataWriteFailKickAt = now;
-                void this._sendControlMany(toKick, encodeKick(ch.id.key));
+                void this.kickChildHashes(ch, toKick, { resetPeerConnections: true }).catch(() => { });
                 void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
             }
         }
@@ -3002,6 +2780,7 @@ export class FanoutTree extends DirectStream {
     noteReceivedSeq(ch, fromHash, seq) {
         if (!ch.repairEnabled)
             return;
+        ch.repairRequestedAtBySeq.delete(seq);
         if (!ch.parent || fromHash !== ch.parent) {
             // Neighbor-assisted repair may deliver payload from a peer other than the
             // current parent; treat it as a "hole fill" only.
@@ -3025,7 +2804,9 @@ export class FanoutTree extends DirectStream {
         }
         if (seq >= ch.nextExpectedSeq) {
             const maxBackfill = Math.max(0, ch.repairMaxBackfillMessages);
-            const start = maxBackfill > 0 ? Math.max(ch.nextExpectedSeq, Math.max(0, seq - maxBackfill)) : ch.nextExpectedSeq;
+            const start = maxBackfill > 0
+                ? Math.max(ch.nextExpectedSeq, Math.max(0, seq - maxBackfill))
+                : ch.nextExpectedSeq;
             for (let s = start; s < seq; s++)
                 ch.missingSeqs.add(s);
             ch.nextExpectedSeq = seq + 1;
@@ -3072,21 +2853,32 @@ export class FanoutTree extends DirectStream {
                     ch.missingSeqs.delete(s);
             }
         }
+        for (const s of ch.repairRequestedAtBySeq.keys()) {
+            if (!ch.missingSeqs.has(s))
+                ch.repairRequestedAtBySeq.delete(s);
+        }
         if (ch.missingSeqs.size === 0)
             return false;
-        if (ch.repairIntervalMs > 0 && now - ch.lastRepairSentAt < ch.repairIntervalMs) {
+        if (ch.repairIntervalMs > 0 &&
+            now - ch.lastRepairSentAt < ch.repairIntervalMs) {
             return false;
         }
-        ch.lastRepairSentAt = now;
-        const missing = [...ch.missingSeqs].sort((a, b) => a - b);
+        const repairRetryMs = Math.max(REPAIR_RETRY_MIN_MS, ch.repairIntervalMs * REPAIR_RETRY_INTERVAL_FACTOR);
+        const missing = [...ch.missingSeqs]
+            .filter((s) => now - (ch.repairRequestedAtBySeq.get(s) ?? 0) >= repairRetryMs)
+            .sort((a, b) => a - b);
         const count = Math.min(ch.repairMaxPerReq, missing.length, 255);
         if (count <= 0)
             return false;
+        ch.lastRepairSentAt = now;
         const reqId = (this.random() * 0xffffffff) >>> 0;
         const slice = missing.slice(0, count);
+        for (const s of slice)
+            ch.repairRequestedAtBySeq.set(s, now);
         let sent = false;
         if (ch.parent) {
-            await this._sendControl(ch.parent, encodeRepairReq(ch.id.key, reqId, slice));
+            await this._sendControl(ch.parent, this.codec.encodeRepairReq(ch.id.key, reqId, slice));
+            ch.parentRepairUnansweredStreak += 1;
             sent = true;
         }
         if (ch.neighborRepair && ch.neighborRepairPeers > 0) {
@@ -3136,35 +2928,25 @@ export class FanoutTree extends DirectStream {
                     updatedAt,
                 };
             });
-            scored.sort((a, b) => {
+            const viable = scored.filter((s) => s.coverage > 0);
+            viable.sort((a, b) => {
                 if (a.coverage !== b.coverage)
                     return b.coverage - a.coverage;
-                if (a.coverage > 0) {
-                    if (a.successRate !== b.successRate)
-                        return b.successRate - a.successRate;
-                    if (a.updatedAt !== b.updatedAt)
-                        return b.updatedAt - a.updatedAt;
-                    const al = ch.lazyPeers.has(a.peerHash) ? 1 : 0;
-                    const bl = ch.lazyPeers.has(b.peerHash) ? 1 : 0;
-                    if (al !== bl)
-                        return bl - al;
-                }
-                else {
-                    const al = ch.lazyPeers.has(a.peerHash) ? 1 : 0;
-                    const bl = ch.lazyPeers.has(b.peerHash) ? 1 : 0;
-                    if (al !== bl)
-                        return bl - al;
-                    if (a.successRate !== b.successRate)
-                        return b.successRate - a.successRate;
-                    if (a.updatedAt !== b.updatedAt)
-                        return b.updatedAt - a.updatedAt;
-                }
+                if (a.successRate !== b.successRate)
+                    return b.successRate - a.successRate;
+                if (a.updatedAt !== b.updatedAt)
+                    return b.updatedAt - a.updatedAt;
+                const al = ch.lazyPeers.has(a.peerHash) ? 1 : 0;
+                const bl = ch.lazyPeers.has(b.peerHash) ? 1 : 0;
+                if (al !== bl)
+                    return bl - al;
                 return a.peerHash < b.peerHash ? -1 : a.peerHash > b.peerHash ? 1 : 0;
             });
-            let peers = scored.slice(0, ch.neighborRepairPeers).map((s) => s.peerHash);
+            let peers = viable.slice(0, ch.neighborRepairPeers).map((s) => s.peerHash);
             if (peers.length > 0) {
-                const bytes = encodeFetchReq(ch.id.key, reqId, slice);
-                if (ch.neighborRepairBudgetBps > 0 && ch.neighborRepairTokenCapacity > 0) {
+                const bytes = this.codec.encodeFetchReq(ch.id.key, reqId, slice);
+                if (ch.neighborRepairBudgetBps > 0 &&
+                    ch.neighborRepairTokenCapacity > 0) {
                     this.refillNeighborRepairTokens(ch, now);
                     const costPerPeer = Math.max(1, bytes.byteLength);
                     const affordable = Math.floor(ch.neighborRepairTokens / costPerPeer);
@@ -3269,13 +3051,33 @@ export class FanoutTree extends DirectStream {
         const bootstraps = this.getBootstrapsForChannel(ch);
         if (bootstraps.length === 0)
             return;
-        const peers = await this.ensureBootstrapPeers(bootstraps, ch.bootstrapDialTimeoutMs, signal, ch.bootstrapMaxPeers);
+        // Announce to ALL trackers, not a random one per round: with B bootstraps
+        // and per-round random selection a given directory only refreshes an
+        // entry every ~announceIntervalMs * B on average, which starves
+        // directories (and exceeds the announce TTL entirely once B grows).
+        // Use already-connected tracker peers and only fall back to dialing when
+        // none are connected: serial dial timeouts here would otherwise make
+        // every announce tick glacial.
+        let peers = ch.cachedAnnounceTrackerPeers ?? [];
+        peers = peers.filter((h) => Boolean(this.peers.get(h)));
+        if (peers.length === 0) {
+            // Dial only when no tracker is connected at all: dialing every tick
+            // makes the announce loop glacial and starves everything behind it.
+            peers = await this.ensureBootstrapPeers(bootstraps, ch.bootstrapDialTimeoutMs, signal, 0);
+        }
+        ch.cachedAnnounceTrackerPeers = peers;
         if (peers.length === 0)
             return;
         this.pruneDisconnectedChildren(ch);
-        const freeSlots = Math.max(0, ch.effectiveMaxChildren - ch.children.size);
+        const parentUpgradeNoCapacity = ch.isRoot && ch.parentUpgradeTrackerNoCapacityUntil > now;
+        const freeSlots = parentUpgradeNoCapacity
+            ? 0
+            : Math.max(0, ch.effectiveMaxChildren - ch.children.size);
+        const announceTtlMs = parentUpgradeNoCapacity
+            ? Math.max(1_000, Math.min(ch.announceTtlMs, ch.parentUpgradeTrackerNoCapacityUntil - now))
+            : ch.announceTtlMs;
         const addrs = this.getSelfAnnounceAddrs();
-        const bytes = encodeTrackerAnnounce(ch.id.key, ch.announceTtlMs, Number.isFinite(ch.level) ? ch.level : 0xffff, ch.effectiveMaxChildren, freeSlots, ch.bidPerByte, addrs);
+        const bytes = this.codec.encodeTrackerAnnounce(ch.id.key, announceTtlMs, Number.isFinite(ch.level) ? ch.level : 0xffff, ch.effectiveMaxChildren, freeSlots, ch.bidPerByte, addrs);
         await this._sendControlMany(peers, bytes);
     }
     async _announceLoop(ch) {
@@ -3289,6 +3091,18 @@ export class FanoutTree extends DirectStream {
             catch {
                 // ignore
             }
+            try {
+                // Child watermark heartbeat first: it only writes to already
+                // connected peers (children/mesh) and must not starve behind the
+                // dial-bound tracker announce below. Parents (root included - it
+                // runs no repair/mesh loop) advertise their have-range to children
+                // so a child whose data writes were silently lost can detect the
+                // gap and repair.
+                await this.maybeSendIHave(ch, Date.now());
+            }
+            catch {
+                // ignore
+            }
             try {
                 await this.announceToTrackers(ch, signal);
             }
@@ -3408,27 +3222,62 @@ export class FanoutTree extends DirectStream {
         return { haveFrom, haveToExclusive };
     }
     async maybeSendIHave(ch, now = Date.now()) {
-        if (!ch.neighborRepair)
+        const meshEnabled = ch.neighborRepair && ch.neighborMeshPeers > 0;
+        const childWatermarkEnabled = ch.repairEnabled && ch.children.size > 0;
+        if (!meshEnabled && !childWatermarkEnabled) {
             return;
-        if (ch.neighborMeshPeers <= 0)
+        }
+        if (ch.neighborAnnounceIntervalMs <= 0) {
             return;
-        if (ch.neighborAnnounceIntervalMs <= 0)
+        }
+        if (now - ch.lastIHaveSentAt < ch.neighborAnnounceIntervalMs) {
             return;
-        if (ch.maxSeqSeen <= ch.lastIHaveSentMaxSeq)
+        }
+        const hasNewData = ch.maxSeqSeen > ch.lastIHaveSentMaxSeq;
+        // Children also need a periodic watermark even without new data: a burst
+        // of data writes can be lost on a not-yet-writable stream and a child
+        // that received nothing has no gap signal to trigger repair. A periodic
+        // IHAVE from the parent converts that silent loss into a repairable gap.
+        const heartbeatDue = childWatermarkEnabled &&
+            (ch.maxSeqSeen >= 0 || ch.endSeqExclusive > 0) &&
+            now - ch.lastIHaveSentAt >=
+                Math.max(ch.neighborAnnounceIntervalMs * 4, 2_000);
+        if (!hasNewData && !heartbeatDue) {
             return;
-        if (now - ch.lastIHaveSentAt < ch.neighborAnnounceIntervalMs)
+        }
+        const recipients = new Set();
+        if (meshEnabled) {
+            for (const h of ch.lazyPeers) {
+                if (this.peers.get(h))
+                    recipients.add(h);
+            }
+        }
+        if (childWatermarkEnabled) {
+            for (const h of ch.children.keys()) {
+                if (this.peers.get(h))
+                    recipients.add(h);
+            }
+        }
+        if (recipients.size === 0) {
             return;
-        const range = this.getHaveRange(ch);
-        if (!range)
-            return;
-        if (range.haveToExclusive <= range.haveFrom)
-            return;
-        const peers = [...ch.lazyPeers].filter((h) => Boolean(this.peers.get(h)));
-        if (peers.length === 0)
-            return;
-        await this._sendControlMany(peers, encodeIHave(ch.id.key, range.haveFrom, range.haveToExclusive));
-        ch.lastIHaveSentAt = now;
-        ch.lastIHaveSentMaxSeq = ch.maxSeqSeen;
+        }
+        let sent = false;
+        const range = this.getHaveRange(ch);
+        if (range && range.haveToExclusive > range.haveFrom) {
+            await this._sendControlMany([...recipients], this.codec.encodeIHave(ch.id.key, range.haveFrom, range.haveToExclusive));
+            sent = true;
+        }
+        if (childWatermarkEnabled && ch.endSeqExclusive > 0) {
+            const children = [...ch.children.keys()].filter((h) => this.peers.get(h));
+            if (children.length > 0) {
+                await this._sendControlMany(children, this.codec.encodeEnd(ch.id.key, ch.endSeqExclusive));
+                sent = true;
+            }
+        }
+        if (sent) {
+            ch.lastIHaveSentAt = now;
+            ch.lastIHaveSentMaxSeq = ch.maxSeqSeen;
+        }
     }
     async ensureMeshPeers(ch, signal) {
         if (ch.neighborMeshPeers <= 0)
@@ -3471,6 +3320,10 @@ export class FanoutTree extends DirectStream {
         }
     }
     async refreshMeshCandidates(ch, signal) {
+        if (ch.neighborMeshPeers <= 0)
+            return;
+        if (ch.lazyPeers.size >= ch.neighborMeshPeers)
+            return;
         const bootstraps = this.getBootstrapsForChannel(ch);
         if (bootstraps.length === 0)
             return;
@@ -3497,18 +3350,23 @@ export class FanoutTree extends DirectStream {
             try {
                 this.pruneLazyPeers(ch);
                 this.pruneHaveByPeer(ch, now);
+                await this.ensureMeshPeers(ch, signal);
                 const refreshMs = Math.max(0, ch.neighborMeshRefreshIntervalMs);
-                if (refreshMs === 0 || now - lastRefreshAt >= refreshMs) {
+                if (ch.lazyPeers.size < ch.neighborMeshPeers &&
+                    (refreshMs === 0 || now - lastRefreshAt >= refreshMs)) {
                     lastRefreshAt = now;
                     await this.refreshMeshCandidates(ch, signal);
+                    await this.ensureMeshPeers(ch, signal);
                 }
-                await this.ensureMeshPeers(ch, signal);
                 await this.maybeSendIHave(ch, now);
             }
             catch {
                 // ignore
             }
-            const intervals = [ch.neighborAnnounceIntervalMs, ch.neighborMeshRefreshIntervalMs].filter((v) => v > 0);
+            const intervals = [
+                ch.neighborAnnounceIntervalMs,
+                ch.neighborMeshRefreshIntervalMs,
+            ].filter((v) => v > 0);
             const sleepMs = intervals.length > 0 ? Math.min(...intervals) : 500;
             await delay(Math.max(50, sleepMs));
         }
@@ -3522,7 +3380,7 @@ export class FanoutTree extends DirectStream {
             const p = new Promise((resolve) => {
                 ch.pendingTrackerQuery.set(reqId, { resolve });
             });
-            void this._sendControl(trackerHash, encodeTrackerQuery(ch.id.key, reqId, want));
+            void this._sendControl(trackerHash, this.codec.encodeTrackerQuery(ch.id.key, reqId, want));
             const res = await Promise.race([
                 p,
                 delay(perTrackerTimeout, { signal }).then(() => null),
@@ -3552,7 +3410,11 @@ export class FanoutTree extends DirectStream {
                 return false;
             try {
                 await this.components.connectionManager.openConnection(a);
-                await this.waitFor(hash, { seek: "present", timeout: timeoutMs, signal });
+                await this.waitFor(hash, {
+                    seek: "present",
+                    timeout: timeoutMs,
+                    signal,
+                });
                 return true;
             }
             catch {
@@ -3567,7 +3429,9 @@ export class FanoutTree extends DirectStream {
             return [];
         try {
             const peer = await this.components.peerStore.get(stream.peerId);
-            const addresses = Array.isArray(peer?.addresses) ? peer.addresses : [];
+            const addresses = Array.isArray(peer?.addresses)
+                ? peer.addresses
+                : [];
             const out = [];
             for (const a of addresses) {
                 const ma = a?.multiaddr ?? a;
@@ -3634,7 +3498,10 @@ export class FanoutTree extends DirectStream {
                 if (out.length >= max)
                     break;
                 seen.add(e.hash);
-                out.push({ hash: e.hash, addrs: e.addrs.slice(0, JOIN_REJECT_REDIRECT_ADDR_MAX) });
+                out.push({
+                    hash: e.hash,
+                    addrs: e.addrs.slice(0, JOIN_REJECT_REDIRECT_ADDR_MAX),
+                });
             }
         }
         if (out.length >= max)
@@ -3665,12 +3532,166 @@ export class FanoutTree extends DirectStream {
     }
     async sendJoinReject(ch, toHash, reqId, reason) {
         const redirects = await this.pickJoinRejectRedirects(ch, toHash, JOIN_REJECT_REDIRECT_MAX);
-        await this._sendControl(toHash, encodeJoinReject(ch.id.key, reqId, reason, redirects));
+        await this._sendControl(toHash, this.codec.encodeJoinReject(ch.id.key, reqId, reason, redirects));
     }
     async sendTrackerFeedback(ch, trackerPeers, candidateHash, event, reason = 0) {
         if (trackerPeers.length === 0)
             return;
-        await this._sendControlMany(trackerPeers, encodeTrackerFeedback(ch.id.key, candidateHash, event, reason));
+        await this._sendControlMany(trackerPeers, this.codec.encodeTrackerFeedback(ch.id.key, candidateHash, event, reason));
+    }
+    pruneParentUpgradeReservations(ch, now = Date.now()) {
+        for (const [hash, reservation] of ch.parentUpgradeReservationsByHash) {
+            if (reservation.expiresAt <= now) {
+                ch.parentUpgradeReservationsByHash.delete(hash);
+                ch.metrics.parentUpgradeRootReservationExpired += 1;
+                continue;
+            }
+            if (ch.children.has(hash)) {
+                ch.parentUpgradeReservationsByHash.delete(hash);
+            }
+        }
+    }
+    parentUpgradeReservationCount(ch, excludeHash, now = Date.now()) {
+        this.pruneParentUpgradeReservations(ch, now);
+        let count = 0;
+        for (const hash of ch.parentUpgradeReservationsByHash.keys()) {
+            if (hash === excludeHash)
+                continue;
+            if (ch.children.has(hash))
+                continue;
+            count += 1;
+        }
+        return count;
+    }
+    createParentUpgradeReservation(ch, toHash, minFreeSlots = 0, now = Date.now()) {
+        if (!ch.isRoot || ch.children.has(toHash))
+            return 0;
+        const maxChildren = Math.max(0, Math.floor(ch.effectiveMaxChildren));
+        if (maxChildren <= 0)
+            return 0;
+        const reserved = this.parentUpgradeReservationCount(ch, toHash, now);
+        const requestedMinFreeSlots = Math.max(0, Math.floor(minFreeSlots));
+        const freeSlots = maxChildren - ch.children.size - reserved;
+        if (freeSlots <= 0 ||
+            (requestedMinFreeSlots > 0 && freeSlots < requestedMinFreeSlots)) {
+            ch.metrics.parentUpgradeRootReservationBlocked += 1;
+            return 0;
+        }
+        const token = (this.random() * 0xffffffff) >>> 0 || 1;
+        ch.parentUpgradeReservationsByHash.set(toHash, {
+            token,
+            expiresAt: now + PARENT_UPGRADE_ROOT_RESERVATION_TTL_MS,
+            minFreeSlots: requestedMinFreeSlots,
+        });
+        ch.metrics.parentUpgradeRootReservationCreated += 1;
+        return token;
+    }
+    consumeParentUpgradeReservation(ch, fromHash, token, now = Date.now()) {
+        if (!ch.isRoot || token <= 0)
+            return false;
+        this.pruneParentUpgradeReservations(ch, now);
+        const reservation = ch.parentUpgradeReservationsByHash.get(fromHash);
+        if (!reservation)
+            return false;
+        if (reservation.expiresAt <= now) {
+            ch.parentUpgradeReservationsByHash.delete(fromHash);
+            ch.metrics.parentUpgradeRootReservationExpired += 1;
+            return false;
+        }
+        if (reservation.token !== token)
+            return false;
+        const requestedMinFreeSlots = Math.max(0, Math.floor(reservation.minFreeSlots ?? 0));
+        if (requestedMinFreeSlots > 0) {
+            const maxChildren = Math.max(0, Math.floor(ch.effectiveMaxChildren));
+            const freeSlots = Math.max(0, maxChildren - ch.children.size);
+            if (freeSlots < requestedMinFreeSlots) {
+                ch.parentUpgradeReservationsByHash.delete(fromHash);
+                ch.metrics.parentUpgradeRootReservationMarginRejected += 1;
+                return false;
+            }
+        }
+        ch.parentUpgradeReservationsByHash.delete(fromHash);
+        ch.metrics.parentUpgradeRootReservationConsumed += 1;
+        return true;
+    }
+    isRootedForParentProbe(ch) {
+        if (ch.isRoot)
+            return true;
+        const route = ch.routeFromRoot;
+        return Boolean(ch.parent &&
+            Array.isArray(route) &&
+            route.length >= 2 &&
+            route[0] === ch.id.root &&
+            route[route.length - 1] === this.publicKeyHash);
+    }
+    encodeParentProbeReplyForChannel(ch, reqId, toHash, minFreeSlots = 0, reserveRootCapacity = true) {
+        this.pruneDisconnectedChildren(ch);
+        const rooted = this.isRootedForParentProbe(ch);
+        const requestedMinFreeSlots = Math.max(0, Math.floor(minFreeSlots));
+        const maxChildren = Math.max(0, Math.floor(ch.effectiveMaxChildren));
+        const reserved = ch.isRoot
+            ? this.parentUpgradeReservationCount(ch, toHash)
+            : 0;
+        const freeSlots = rooted
+            ? Math.max(0, maxChildren - ch.children.size - reserved)
+            : 0;
+        const requesterHasEnoughSlots = freeSlots > 0 &&
+            (requestedMinFreeSlots <= 0 || freeSlots >= requestedMinFreeSlots);
+        if (ch.isRoot &&
+            rooted &&
+            maxChildren > 0 &&
+            !ch.children.has(toHash) &&
+            !requesterHasEnoughSlots) {
+            ch.metrics.parentUpgradeRootReservationBlocked += 1;
+        }
+        const reservationToken = ch.isRoot && rooted && requesterHasEnoughSlots && reserveRootCapacity
+            ? this.createParentUpgradeReservation(ch, toHash, requestedMinFreeSlots)
+            : 0;
+        const repairing = ch.missingSeqs.size > 0;
+        const overloaded = ch.overloadStreak > 0;
+        let flags = 0;
+        if (rooted)
+            flags |= PARENT_PROBE_FLAG_ROOTED;
+        if (rooted &&
+            (reservationToken > 0 ||
+                (!ch.isRoot && requesterHasEnoughSlots) ||
+                (ch.isRoot && requesterHasEnoughSlots && !reserveRootCapacity))) {
+            flags |= PARENT_PROBE_FLAG_ACCEPTING;
+        }
+        if (repairing)
+            flags |= PARENT_PROBE_FLAG_REPAIRING;
+        if (overloaded)
+            flags |= PARENT_PROBE_FLAG_OVERLOADED;
+        return this.codec.encodeParentProbeReply(ch.id.key, reqId, {
+            flags,
+            level: Number.isFinite(ch.level) ? ch.level : 0xffff,
+            maxChildren,
+            freeSlots,
+            // For roots, expose reserved slots as child pressure so concurrent
+            // upgrade probes cannot all pass the load-ratio check from stale state.
+            children: ch.isRoot ? ch.children.size + reserved : ch.children.size,
+            haveToExclusive: ch.maxSeqSeen >= 0 ? ch.maxSeqSeen + 1 : 0,
+            missingSeqs: ch.missingSeqs.size,
+            dataWriteDrops: ch.metrics.dataWriteDrops,
+            droppedForwards: ch.droppedForwards,
+            reservationToken,
+        });
+    }
+    async probeParentCandidate(ch, parentHash, timeoutMs, signal, minFreeSlots = 0, reserveRootCapacity = true) {
+        if (!this.peers.get(parentHash))
+            return;
+        const reqId = (this.random() * 0xffffffff) >>> 0;
+        const p = new Promise((resolve) => {
+            ch.pendingParentProbe.set(reqId, { resolve });
+        });
+        await this._sendControl(parentHash, this.codec.encodeParentProbeReq(ch.id.key, reqId, minFreeSlots, reserveRootCapacity));
+        const res = await Promise.race([
+            p,
+            delay(Math.max(1, timeoutMs), { signal }).then(() => undefined),
+        ]);
+        if (!res)
+            ch.pendingParentProbe.delete(reqId);
+        return res;
     }
     async _joinLoop(ch, joinOpts) {
         const retryMs = Math.max(1, Math.floor(joinOpts.retryMs ?? 200));
@@ -3686,6 +3707,9 @@ export class FanoutTree extends DirectStream {
         const trackerQueryIntervalMs = Math.max(0, Math.floor(joinOpts.trackerQueryIntervalMs ?? ch.trackerQueryIntervalMs));
         const joinAttemptsPerRound = Math.max(1, Math.floor(joinOpts.joinAttemptsPerRound ?? 8));
         const candidateCooldownMs = Math.max(0, Math.floor(joinOpts.candidateCooldownMs ?? 2_000));
+        const parentUpgrade = this.nativeFanout
+            ? this.nativeFanout.normalizeParentUpgradePolicy(joinOpts)
+            : normalizeParentUpgradePolicy(joinOpts);
         const candidateScoringModeRaw = joinOpts.candidateScoringMode ?? "ranked-shuffle";
         const candidateScoringMode = candidateScoringModeRaw === "ranked-strict" ||
             candidateScoringModeRaw === "weighted" ||
@@ -3705,6 +3729,56 @@ export class FanoutTree extends DirectStream {
             ? anySignal([this.closeController.signal, joinOpts.signal])
             : this.closeController.signal;
         const signal = combinedSignal;
+        let nextParentUpgradeCheckAt = 0;
+        let parentUpgradeCheckSeq = 0;
+        let parentUpgradeActiveGuardBackoffMs = 0;
+        const scheduleNextParentUpgradeCheck = (now, first = false, minDelayMs = parentUpgrade.intervalMs) => {
+            if (parentUpgrade.intervalMs <= 0) {
+                nextParentUpgradeCheckAt = 0;
+                return;
+            }
+            const factor = first
+                ? stableUnitInterval(`${ch.id.suffixKey}:${this.publicKeyHash}:parent-upgrade-phase`)
+                : 0.75 +
+                    stableUnitInterval(`${ch.id.suffixKey}:${this.publicKeyHash}:parent-upgrade-interval:${parentUpgradeCheckSeq++}`) *
+                        0.5;
+            nextParentUpgradeCheckAt =
+                now +
+                    Math.max(1, Math.floor(parentUpgrade.intervalMs * factor), Math.floor(minDelayMs));
+        };
+        const resetParentUpgradeActiveGuardBackoff = () => {
+            parentUpgradeActiveGuardBackoffMs = 0;
+        };
+        const parentUpgradeGuardDelayMs = (reason, now) => {
+            const baseDelayMs = (() => {
+                switch (reason) {
+                    case "data":
+                        return Math.max(parentUpgrade.quietMs, parentUpgrade.repairQuietMs);
+                    case "repair":
+                        return parentUpgrade.repairQuietMs;
+                    case "quiet":
+                        return ch.lastParentUpgradeActivityAt > 0
+                            ? Math.max(0, parentUpgrade.quietMs -
+                                (now - ch.lastParentUpgradeActivityAt))
+                            : parentUpgrade.quietMs;
+                    case "cooldown":
+                        return Math.max(0, ch.parentUpgradeBackoffUntil - now, ch.parentUpgradeLastAt > 0
+                            ? parentUpgrade.cooldownMs - (now - ch.parentUpgradeLastAt)
+                            : 0);
+                    default:
+                        return parentUpgrade.intervalMs;
+                }
+            })();
+            if (reason !== "data" && reason !== "repair") {
+                resetParentUpgradeActiveGuardBackoff();
+                return baseDelayMs;
+            }
+            parentUpgradeActiveGuardBackoffMs =
+                parentUpgradeActiveGuardBackoffMs > 0
+                    ? Math.min(Math.max(parentUpgrade.failedBackoff.maxMs, baseDelayMs), Math.max(baseDelayMs, parentUpgradeActiveGuardBackoffMs * 2))
+                    : baseDelayMs;
+            return parentUpgradeActiveGuardBackoffMs;
+        };
         try {
             for (;;) {
                 if (ch.closed) {
@@ -3730,6 +3804,8 @@ export class FanoutTree extends DirectStream {
                         ch.metrics.reparentDisconnect += 1;
                         const hadChildren = ch.children.size > 0;
                         this.detachFromParent(ch);
+                        nextParentUpgradeCheckAt = 0;
+                        resetParentUpgradeActiveGuardBackoff();
                         // If we lose our parent, we are no longer on the rooted tree; detach children so
                         // they can rejoin as well (prevents stable disconnected components).
                         void this.kickChildren(ch).catch(() => { });
@@ -3742,50 +3818,130 @@ export class FanoutTree extends DirectStream {
                     const endedAndComplete = ch.endSeqExclusive > 0 &&
                         ch.missingSeqs.size === 0 &&
                         ch.nextExpectedSeq >= ch.endSeqExclusive;
-                    const expectingData = ch.missingSeqs.size > 0 || (ch.maxDataAgeMs > 0 && !endedAndComplete);
-                    if (staleAfterMs > 0 &&
-                        ch.receivedAnyParentData &&
-                        ch.lastParentDataAt > 0 &&
-                        Date.now() - ch.lastParentDataAt > staleAfterMs &&
-                        expectingData) {
+                    const expectingData = ch.missingSeqs.size > 0 ||
+                        (ch.repairEnabled && ch.maxSeqSeen >= 0 && ch.endSeqExclusive < 0) ||
+                        (ch.maxDataAgeMs > 0 && !endedAndComplete);
+                    // Repair requests travel child->parent on a direction that works
+                    // even when parent->child data writes silently fail. A repair that
+                    // does not fill a gap is not sufficient evidence by itself though:
+                    // the repair payload can be dropped or the parent cache can miss.
+                    // Re-parent only after both repeated unanswered repairs and a
+                    // quiet parent liveness window.
+                    const parentRepairDeadLivenessMs = Math.max(PARENT_REPAIR_DEAD_MIN_LIVENESS_MS, ch.repairIntervalMs * PARENT_REPAIR_DEAD_STREAK_THRESHOLD, ch.neighborAnnounceIntervalMs * 8);
+                    const parentRepairNow = Date.now();
+                    const parentLivenessQuietMs = ch.lastParentDataAt > 0 ? parentRepairNow - ch.lastParentDataAt : 0;
+                    const parentRepairDead = ch.repairEnabled &&
+                        ch.parentRepairUnansweredStreak >=
+                            PARENT_REPAIR_DEAD_STREAK_THRESHOLD &&
+                        parentLivenessQuietMs >= parentRepairDeadLivenessMs;
+                    if (parentRepairDead ||
+                        (staleAfterMs > 0 &&
+                            ch.receivedAnyParentData &&
+                            ch.lastParentDataAt > 0 &&
+                            Date.now() - ch.lastParentDataAt > staleAfterMs &&
+                            expectingData)) {
                         // Parent is "alive" at the stream layer but we're not receiving
                         // data at the expected rate; detach and try to re-parent.
                         ch.metrics.reparentStale += 1;
                         ch.parent = undefined;
+                        ch.parentRepairUnansweredStreak = 0;
                         ch.level = Number.POSITIVE_INFINITY;
                         ch.routeFromRoot = undefined;
                         ch.routeByPeer.clear();
                         ch.lastParentDataAt = 0;
+                        ch.lastParentUpgradeActivityAt = 0;
                         ch.receivedAnyParentData = false;
                         ch.pendingJoin.clear();
-                        ch.pendingRouteQuery.clear();
-                        for (const pending of ch.pendingRouteProxy.values()) {
-                            clearTimeout(pending.timer);
+                        ch.pendingParentProbe.clear();
+                        ch.parentShadow = undefined;
+                        void Promise.all(this.clearParentUpgradeGrace(ch, true, true)).catch(() => { });
+                        if (this.parentUpgradeShadowInFlightSuffixKey === ch.id.suffixKey) {
+                            this.parentUpgradeShadowInFlightSuffixKey = undefined;
                         }
-                        ch.pendingRouteProxy.clear();
+                        ch.parentUpgradeRetryAfterSeq = -1;
+                        ch.parentProbeRejectUntilByHash.clear();
+                        ch.parentProbeRejectBackoffMsByHash.clear();
+                        nextParentUpgradeCheckAt = 0;
+                        resetParentUpgradeActiveGuardBackoff();
+                        ch.pendingRouteQuery.clear();
+                        this.clearRouteProxies(ch);
                         void this.kickChildren(ch).catch(() => { });
-                        await delay(retryMs);
+                        await delay(retryMs, { signal });
                         continue;
                     }
+                    if (parentUpgrade.intervalMs > 0 && ch.level > 1) {
+                        const now = Date.now();
+                        if (nextParentUpgradeCheckAt === 0) {
+                            scheduleNextParentUpgradeCheck(now, true, parentUpgrade.dataGuard || parentUpgrade.repairGuard
+                                ? Math.max(parentUpgrade.quietMs, parentUpgrade.repairQuietMs)
+                                : parentUpgrade.intervalMs);
+                        }
+                        const due = now >= nextParentUpgradeCheckAt;
+                        if (due) {
+                            const gateOptions = {
+                                leafOnly: parentUpgrade.leafOnly,
+                                repairGuard: parentUpgrade.repairGuard,
+                                dataGuard: parentUpgrade.dataGuard,
+                                endedAndComplete,
+                                maxPerPeer: parentUpgrade.maxPerPeer,
+                                cooldownMs: parentUpgrade.cooldownMs,
+                                quietMs: parentUpgrade.quietMs,
+                                repairQuietMs: parentUpgrade.repairQuietMs,
+                                now,
+                            };
+                            const gate = this.nativeFanout
+                                ? this.nativeFanout.evaluateParentUpgradeGate(ch, gateOptions)
+                                : evaluateParentUpgradeGate(ch, gateOptions);
+                            if ("reason" in gate) {
+                                recordParentUpgradeSkip(ch.metrics, gate.reason);
+                                scheduleNextParentUpgradeCheck(now, false, parentUpgradeGuardDelayMs(gate.reason, now));
+                            }
+                            else {
+                                resetParentUpgradeActiveGuardBackoff();
+                                const improved = await this.maybeImproveParent(ch, {
+                                    signal,
+                                    candidateShuffleTopK,
+                                    candidateScoringMode,
+                                    candidateScoringWeights,
+                                    joinAttemptsPerRound,
+                                    joinReqTimeoutMs,
+                                    parentUpgrade,
+                                    trackerPeers: ch.cachedBootstrapPeers.filter((h) => Boolean(this.peers.get(h))),
+                                });
+                                scheduleNextParentUpgradeCheck(Date.now());
+                                if (improved) {
+                                    ch.metrics.reparentUpgrade += 1;
+                                    ch.parentUpgradeCount += 1;
+                                    ch.parentUpgradeLastAt = Date.now();
+                                    ch.parentUpgradeBackoffMs = 0;
+                                    ch.parentUpgradeBackoffUntil = 0;
+                                    ch.parentUpgradeRetryAfterSeq = -1;
+                                    ch.parentUpgradeStaleRootProbeRound = 0;
+                                }
+                            }
+                        }
+                    }
                     if (!ch.joinedOnce)
                         ch.joinedOnce = createDeferred();
                     ch.joinedOnce.resolve();
                     ch.joinedAtLeastOnce = true;
                     // Once attached, we don't need a fast retry cadence; keep polling coarse to
                     // avoid excessive timers when simulating many nodes in one process.
-                    await delay(Math.max(retryMs, 1_000));
+                    await delay(Math.max(retryMs, 1_000), { signal });
                     continue;
                 }
                 // `timeoutMs` is meant to bound the initial `joinChannel()` await, not to
                 // stop re-parenting attempts for long-running nodes.
-                if (!ch.joinedAtLeastOnce && timeoutMs > 0 && Date.now() - start > timeoutMs) {
+                if (!ch.joinedAtLeastOnce &&
+                    timeoutMs > 0 &&
+                    Date.now() - start > timeoutMs) {
                     const bootstrapsCount = this.getBootstrapsForChannel(ch).length;
                     const rootPeer = this.peers.get(ch.id.root);
                     const rootNeighbor = Boolean(rootPeer && rootPeer.isReadable && rootPeer.isWritable);
                     const bootstrapHint = bootstrapsCount === 0 && !rootNeighbor
                         ? " No fanout bootstraps are configured for this channel, and the root is not a direct neighbor. If this peer reached the network via a bootstrap or relay node, initialize it with Peerbit.bootstrap(...) instead of Peerbit.dial(...), or configure FanoutTree.setBootstraps(...) before joining sharded topics."
                         : "";
-                    throw new Error(`fanout join timed out after ${timeoutMs}ms (topic=${ch.id.topic} root=${ch.id.root} self=${this.publicKeyHash} rootNeighbor=${rootNeighbor} peers=${this.peers.size} bootstraps=${bootstrapsCount}).${bootstrapHint}`);
+                    throw new Error(`fanout join timed out after ${timeoutMs}ms (topic=${ch.id.topic} root=${ch.id.root} self=${this.publicKeyHash} rootNeighbor=${rootNeighbor} peers=${this.peers.size} bootstraps=${bootstrapsCount} joinReqSent=${ch.metrics.joinReqSent} joinAcceptReceived=${ch.metrics.joinAcceptReceived} joinRejectReceived=${ch.metrics.joinRejectReceived} peerResets=${ch.metrics.joinPeerResets}).${bootstrapHint}`);
                 }
                 const cooldownMs = ch.rejoinCooldownUntil - Date.now();
                 if (cooldownMs > 0) {
@@ -3881,12 +4037,19 @@ export class FanoutTree extends DirectStream {
                         source: 1,
                     });
                 }
-                // Fallback: try a bounded set of already-connected peers.
+                // Fallback: try a bounded set of already-connected peers. Bootstrap
+                // peers are often just trackers, but they can also be the only
+                // connected channel host and may not list themselves in tracker
+                // replies. Keep them as low-priority candidates unless tracker state
+                // already represented them above.
+                const bootstrapPeerSet = new Set(bootstrapPeers);
                 let connectedFallbackAdded = 0;
                 const connectedFallbackMax = 64;
                 for (const h of this.peers.keys()) {
                     if (h === this.publicKeyHash)
                         continue;
+                    if (bootstrapPeerSet.has(h) && candidatesByHash.has(h))
+                        continue;
                     upsertCandidate({
                         hash: h,
                         addrs: [],
@@ -3926,12 +4089,14 @@ export class FanoutTree extends DirectStream {
                             if (until != null && until > now)
                                 nextAt = Math.min(nextAt, until);
                         }
-                        const waitMs = nextAt !== Number.POSITIVE_INFINITY ? Math.max(1, nextAt - now) : retryMs;
+                        const waitMs = nextAt !== Number.POSITIVE_INFINITY
+                            ? Math.max(1, nextAt - now)
+                            : retryMs;
                         const capMs = Math.max(retryMs, trackerQueryIntervalMs > 0 ? trackerQueryIntervalMs : retryMs);
-                        await delay(Math.max(1, Math.min(waitMs, capMs)));
+                        await delay(Math.max(1, Math.min(waitMs, capMs)), { signal });
                         continue;
                     }
-                    await delay(retryMs);
+                    await delay(retryMs, { signal });
                     continue;
                 }
                 let ordered = [...candidates];
@@ -4097,6 +4262,7 @@ export class FanoutTree extends DirectStream {
                         }
                     }
                     if (res.timedOut) {
+                        this.noteJoinTimeout(ch, c.hash);
                         try {
                             await this.sendTrackerFeedback(ch, bootstrapPeers, c.hash, TRACKER_FEEDBACK_JOIN_TIMEOUT);
                         }
@@ -4137,26 +4303,922 @@ export class FanoutTree extends DirectStream {
                         const stream = this.peers.get(h);
                         if (!stream)
                             continue;
-                        void this.components.connectionManager.closeConnections(stream.peerId).catch(() => { });
+                        void this.components.connectionManager
+                            .closeConnections(stream.peerId)
+                            .catch(() => { });
                     }
                     continue;
                 }
-                await delay(retryMs);
+                await delay(retryMs, { signal });
             }
         }
         finally {
             signal.clear?.();
         }
     }
-    async tryJoinOnce(ch, parentHash, reqId, timeoutMs, signal) {
-        if (ch.parent)
+    async maybeImproveParent(ch, options) {
+        const parentUpgrade = options.parentUpgrade;
+        const currentParent = ch.parent;
+        if (!currentParent || ch.closed || ch.isRoot || ch.level <= 1)
+            return false;
+        if (parentUpgrade.mode === "shadow" &&
+            this.parentUpgradeShadowInFlightSuffixKey != null &&
+            this.parentUpgradeShadowInFlightSuffixKey !== ch.id.suffixKey) {
+            ch.metrics.reparentUpgradeSkipBudget += 1;
+            return false;
+        }
+        const staleRootProbeRound = Math.max(0, Math.floor(ch.parentUpgradeStaleRootProbeRound || 0));
+        ch.parentUpgradeStaleRootProbeRound = Math.min(0x7fffffff, staleRootProbeRound + 1);
+        const upgradeRandom = (scope) => stableUnitInterval(`${ch.id.suffixKey}:${this.publicKeyHash}:${currentParent}:${scope}`);
+        const clearFailedBackoff = () => {
+            ch.parentUpgradeBackoffMs = 0;
+            ch.parentUpgradeBackoffUntil = 0;
+        };
+        const clearShadowInFlight = () => {
+            if (this.parentUpgradeShadowInFlightSuffixKey === ch.id.suffixKey) {
+                this.parentUpgradeShadowInFlightSuffixKey = undefined;
+            }
+        };
+        const resetShadow = () => {
+            if (!ch.parentShadow)
+                return;
+            ch.parentShadow = undefined;
+            clearShadowInFlight();
+            ch.metrics.parentShadowReset += 1;
+        };
+        const deferParentUpgradeRetryUntilFreshData = (multiplier = 1) => {
+            const minFreshMessages = Math.max(1, parentUpgrade.shadow.dualPathMinMessages *
+                Math.max(1, Math.floor(multiplier)));
+            ch.parentUpgradeRetryAfterSeq = Math.max(ch.parentUpgradeRetryAfterSeq, ch.maxSeqSeen + minFreshMessages - 1);
+        };
+        const applyFailedBackoff = () => {
+            const minMs = parentUpgrade.failedBackoff.minMs;
+            const maxMs = parentUpgrade.failedBackoff.maxMs;
+            if (minMs <= 0 || maxMs <= 0) {
+                ch.parentUpgradeBackoffMs = 0;
+                ch.parentUpgradeBackoffUntil = 0;
+                return;
+            }
+            const nextMs = ch.parentUpgradeBackoffMs > 0
+                ? Math.min(maxMs, Math.max(minMs, ch.parentUpgradeBackoffMs * 2))
+                : minMs;
+            ch.parentUpgradeBackoffMs = nextMs;
+            const jitter = 0.75 + upgradeRandom(`failed-backoff:${nextMs}`) * 0.5;
+            ch.parentUpgradeBackoffUntil =
+                Date.now() + Math.max(1, Math.floor(nextMs * jitter));
+        };
+        const isDirectNeighbor = (hash) => {
+            const peer = this.peers.get(hash);
+            if (!peer)
+                return false;
+            try {
+                const conns = this.components.connectionManager.getConnections(peer.peerId);
+                return (conns?.length ?? 0) > 0;
+            }
+            catch {
+                return peer.isReadable || peer.isWritable;
+            }
+        };
+        const candidatesByHash = new Map();
+        const upsertCandidate = (c) => {
+            const prev = candidatesByHash.get(c.hash);
+            if (!prev) {
+                candidatesByHash.set(c.hash, { ...c });
+                return;
+            }
+            if (prev.addrs.length === 0 && c.addrs.length > 0)
+                prev.addrs = c.addrs;
+            prev.level = Math.min(prev.level, c.level);
+            prev.freeSlots = Math.max(prev.freeSlots, c.freeSlots);
+            prev.bidPerByte = Math.max(prev.bidPerByte, c.bidPerByte);
+            prev.source = Math.min(prev.source, c.source);
+        };
+        const nonRootMinLevelGain = Math.max(parentUpgrade.minLevelGain, parentUpgrade.nonRootMinLevelGain);
+        const rootMinLevelGain = Math.max(parentUpgrade.minLevelGain, parentUpgrade.rootMinLevelGain);
+        const rootMinSubtreeGain = Math.max(parentUpgrade.minLevelGain, parentUpgrade.rootMinSubtreeGain);
+        const levelGainFor = (parentLevel) => ch.level - (parentLevel + 1);
+        const impactedPeersForRoot = () => Math.max(1, 1 + ch.children.size);
+        const rootSubtreeGainFor = (parentLevel) => levelGainFor(parentLevel) * impactedPeersForRoot();
+        const isEnoughLevelGain = (hash, parentLevel) => {
+            const levelGain = levelGainFor(parentLevel);
+            if (hash !== ch.id.root)
+                return levelGain >= nonRootMinLevelGain;
+            if (levelGain >= rootMinLevelGain)
+                return true;
+            return rootSubtreeGainFor(parentLevel) >= rootMinSubtreeGain;
+        };
+        let localChannelCount = 1;
+        if (this.channelsBySuffixKey instanceof Map) {
+            localChannelCount = 0;
+            for (const localCh of this.channelsBySuffixKey.values()) {
+                if (localCh.closed)
+                    continue;
+                localChannelCount += 1;
+                if (localChannelCount > 1)
+                    break;
+            }
+        }
+        const singleChannelBranch = ch.children.size > 0 && localChannelCount <= 1;
+        const multiChannelBranch = ch.children.size > 0 && localChannelCount > 1;
+        const endedAndComplete = ch.endSeqExclusive > 0 &&
+            ch.missingSeqs.size === 0 &&
+            ch.nextExpectedSeq >= ch.endSeqExclusive;
+        const singleChannelSettledLeaf = ch.children.size === 0 && localChannelCount <= 1 && endedAndComplete;
+        const multiChannelSettledLeaf = ch.children.size === 0 && localChannelCount > 1 && endedAndComplete;
+        const knownChannelPeerCount = Math.max(1, ch.channelPeers?.size ?? 1);
+        const defaultStaleRootProbeProbability = 0.015625;
+        const configuredStaleRootProbeProbabilityRaw = Number(parentUpgrade.staleRootProbeProbability);
+        const staleRootProbeBaseProbability = Number.isFinite(configuredStaleRootProbeProbabilityRaw)
+            ? Math.max(0, Math.min(1, configuredStaleRootProbeProbabilityRaw))
+            : defaultStaleRootProbeProbability;
+        const defaultMultiChannelSettledLeafRootCandidate = parentUpgrade.leafOnly &&
+            multiChannelSettledLeaf &&
+            staleRootProbeBaseProbability <= defaultStaleRootProbeProbability;
+        const hasDefaultMultiChannelLeafRootSignal = () => {
+            if (!defaultMultiChannelSettledLeafRootCandidate)
+                return true;
+            if (!isEnoughLevelGain(ch.id.root, 0))
+                return false;
+            if ((ch.parentDataLatencySamples ?? 0) < 8)
+                return false;
+            if ((ch.parentDataLatencyEwmaMs ?? 0) < 64 &&
+                (ch.parentDataLatencyMaxMs ?? 0) < 256) {
+                return false;
+            }
+            if (staleRootProbeBaseProbability <= 0)
+                return false;
+            const sampleProbability = Math.min(1, staleRootProbeBaseProbability);
+            return (stableUnitInterval(`${ch.id.suffixKey}:${this.publicKeyHash}:${ch.id.root}:multi-channel-leaf-root-signal:${ch.maxSeqSeen}`) < sampleProbability);
+        };
+        const defaultMultiChannelLeafRootSignal = hasDefaultMultiChannelLeafRootSignal();
+        if (defaultMultiChannelSettledLeafRootCandidate &&
+            defaultMultiChannelLeafRootSignal &&
+            ch.id.root !== this.publicKeyHash &&
+            isDirectNeighbor(ch.id.root) &&
+            (options.trackerPeers?.length ?? 0) > 0) {
+            const rootMinFreeSlots = parentUpgrade.rootMinFreeSlots;
+            const cachedRoot = ch.cachedTrackerCandidates.find((c) => c.hash === ch.id.root);
+            if (!cachedRoot || cachedRoot.freeSlots < rootMinFreeSlots) {
+                const refreshed = await this.queryTrackers(ch, options.trackerPeers ?? [], Math.max(16, ch.cachedTrackerCandidates.length), parentUpgrade.probe.timeoutMs, options.signal).catch(() => []);
+                if (refreshed.length > 0) {
+                    ch.cachedTrackerCandidates = refreshed;
+                }
+            }
+        }
+        const configuredRejectCooldownMs = Math.max(0, parentUpgrade.probe.rejectCooldownMs);
+        const rejectCooldownMs = localChannelCount > 1
+            ? Math.max(configuredRejectCooldownMs, 20_000)
+            : configuredRejectCooldownMs;
+        const rejectCooldownMaxMs = Math.max(rejectCooldownMs, parentUpgrade.probe.rejectCooldownMaxMs);
+        const clearProbeRejectBackoff = (candidateHash) => {
+            ch.parentProbeRejectUntilByHash.delete(candidateHash);
+            ch.parentProbeRejectBackoffMsByHash.delete(candidateHash);
+        };
+        const rejectProbeCandidate = (candidateHash) => {
+            if (rejectCooldownMs <= 0)
+                return;
+            const nextBackoffMs = (ch.parentProbeRejectBackoffMsByHash.get(candidateHash) ?? 0) > 0
+                ? Math.min(rejectCooldownMaxMs, Math.max(rejectCooldownMs, (ch.parentProbeRejectBackoffMsByHash.get(candidateHash) ?? 0) *
+                    2))
+                : rejectCooldownMs;
+            ch.parentProbeRejectBackoffMsByHash.set(candidateHash, nextBackoffMs);
+            const jitter = 0.75 +
+                upgradeRandom(`probe-reject:${candidateHash}:${nextBackoffMs}`) * 0.5;
+            ch.parentProbeRejectUntilByHash.set(candidateHash, Date.now() + Math.max(1, Math.floor(nextBackoffMs * jitter)));
+            while (ch.parentProbeRejectBackoffMsByHash.size >
+                KNOWN_CANDIDATE_ADDRS_MAX_ENTRIES) {
+                const oldest = ch.parentProbeRejectBackoffMsByHash.keys().next()
+                    .value;
+                if (!oldest)
+                    break;
+                ch.parentProbeRejectBackoffMsByHash.delete(oldest);
+                ch.parentProbeRejectUntilByHash.delete(oldest);
+            }
+            while (ch.parentProbeRejectUntilByHash.size > KNOWN_CANDIDATE_ADDRS_MAX_ENTRIES) {
+                const oldest = ch.parentProbeRejectUntilByHash.keys().next().value;
+                if (!oldest)
+                    break;
+                ch.parentProbeRejectUntilByHash.delete(oldest);
+                ch.parentProbeRejectBackoffMsByHash.delete(oldest);
+            }
+        };
+        const minFreeSlotsFor = (hash) => hash === ch.id.root
+            ? parentUpgrade.rootMinFreeSlots
+            : parentUpgrade.minFreeSlots;
+        const refreshCachedTrackerCandidate = (hash, level, freeSlots) => {
+            const cached = ch.cachedTrackerCandidates.find((c) => c.hash === hash);
+            if (!cached)
+                return;
+            if (Number.isFinite(level))
+                cached.level = Math.max(0, Math.floor(level));
+            if (Number.isFinite(freeSlots)) {
+                cached.freeSlots = Math.max(0, Math.floor(freeSlots));
+            }
+        };
+        const sendProbeTrackerFeedback = (candidateHash, reason) => {
+            const trackerPeers = options.trackerPeers ?? [];
+            if (trackerPeers.length === 0)
+                return;
+            void this.sendTrackerFeedback(ch, trackerPeers, candidateHash, TRACKER_FEEDBACK_JOIN_REJECT, reason).catch(() => { });
+        };
+        for (const c of ch.cachedTrackerCandidates) {
+            if (c.hash === this.publicKeyHash)
+                continue;
+            if (!isDirectNeighbor(c.hash))
+                continue;
+            upsertCandidate({
+                hash: c.hash,
+                addrs: c.addrs,
+                level: c.level,
+                freeSlots: Number.isFinite(c.freeSlots)
+                    ? Math.max(0, Math.floor(c.freeSlots))
+                    : 0,
+                bidPerByte: c.bidPerByte,
+                source: 0,
+            });
+        }
+        if (ch.id.root !== this.publicKeyHash &&
+            isDirectNeighbor(ch.id.root) &&
+            !candidatesByHash.has(ch.id.root)) {
+            upsertCandidate({
+                hash: ch.id.root,
+                addrs: [],
+                level: 0,
+                freeSlots: 1,
+                bidPerByte: 0,
+                source: -1,
+            });
+        }
+        let connectedFallbackAdded = 0;
+        const connectedFallbackMax = 64;
+        for (const h of this.peers.keys()) {
+            if (h === this.publicKeyHash)
+                continue;
+            if (!isDirectNeighbor(h))
+                continue;
+            upsertCandidate({
+                hash: h,
+                addrs: [],
+                level: 0xffff,
+                freeSlots: 0,
+                bidPerByte: 0,
+                source: 2,
+            });
+            connectedFallbackAdded += 1;
+            if (connectedFallbackAdded >= connectedFallbackMax)
+                break;
+        }
+        const orderedCandidates = [];
+        for (const c of candidatesByHash.values()) {
+            if (c.hash === this.publicKeyHash || c.hash === currentParent)
+                continue;
+            const canVerifyRootCapacityLive = parentUpgrade.verifyStaleRootCapacity === true &&
+                parentUpgrade.mode === "shadow" &&
+                c.hash === ch.id.root;
+            const requiredMinFreeSlots = minFreeSlotsFor(c.hash);
+            if (c.hash === ch.id.root &&
+                defaultMultiChannelSettledLeafRootCandidate &&
+                !defaultMultiChannelLeafRootSignal) {
+                ch.metrics.reparentUpgradeSkipCandidateSlots += 1;
+                continue;
+            }
+            if (canVerifyRootCapacityLive && c.freeSlots < requiredMinFreeSlots) {
+                const staleRootProbeProbability = (() => {
+                    if (singleChannelBranch && staleRootProbeBaseProbability > 0) {
+                        const highValueBranch = rootSubtreeGainFor(c.level) >=
+                            Math.max(rootMinSubtreeGain + 1, 4);
+                        const branchCap = highValueBranch ? 0.25 : 0.2;
+                        return Math.max(staleRootProbeBaseProbability, Math.min(branchCap, staleRootProbeBaseProbability * 8));
+                    }
+                    if (multiChannelBranch && staleRootProbeBaseProbability > 0) {
+                        return Math.max(staleRootProbeBaseProbability, Math.min(0.03125, staleRootProbeBaseProbability * 2));
+                    }
+                    if (singleChannelSettledLeaf && staleRootProbeBaseProbability > 0) {
+                        return 0.5;
+                    }
+                    if (multiChannelSettledLeaf && parentUpgrade.leafOnly) {
+                        return staleRootProbeBaseProbability >
+                            defaultStaleRootProbeProbability
+                            ? Math.max(staleRootProbeBaseProbability, Math.min(0.125, 3 / knownChannelPeerCount))
+                            : 0;
+                    }
+                    return Math.min(1, staleRootProbeBaseProbability *
+                        Math.max(1, Math.min(4, staleRootProbeRound + 1)));
+                })();
+                const staleRootProbeScore = stableUnitInterval(`${ch.id.suffixKey}:${this.publicKeyHash}:${c.hash}:stale-root-probe:${staleRootProbeRound}`);
+                if (staleRootProbeScore >= staleRootProbeProbability) {
+                    ch.metrics.reparentUpgradeSkipCandidateSlots += 1;
+                    continue;
+                }
+            }
+            if (!canVerifyRootCapacityLive && c.freeSlots < requiredMinFreeSlots) {
+                ch.metrics.reparentUpgradeSkipCandidateSlots += 1;
+                continue;
+            }
+            if (!isEnoughLevelGain(c.hash, c.level)) {
+                ch.metrics.reparentUpgradeSkipCandidateLevel += 1;
+                continue;
+            }
+            orderedCandidates.push(c);
+        }
+        let ordered = orderedCandidates.sort((a, b) => {
+            if (a.level !== b.level)
+                return a.level - b.level;
+            if (a.freeSlots !== b.freeSlots)
+                return b.freeSlots - a.freeSlots;
+            if (a.bidPerByte !== b.bidPerByte)
+                return b.bidPerByte - a.bidPerByte;
+            if (a.source !== b.source)
+                return a.source - b.source;
+            return a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0;
+        });
+        if (ordered.length === 0) {
+            if (parentUpgrade.mode === "probe" || parentUpgrade.mode === "shadow") {
+                applyFailedBackoff();
+            }
+            return false;
+        }
+        if (options.candidateScoringMode === "ranked-shuffle") {
+            if (options.candidateShuffleTopK > 0 && ordered.length > 1) {
+                const k = Math.min(options.candidateShuffleTopK, ordered.length);
+                const shuffleScope = ordered.map((c) => c.hash).join(",");
+                for (let i = k - 1; i > 0; i--) {
+                    const j = Math.floor(upgradeRandom(`shuffle:${shuffleScope}:${i}`) * (i + 1));
+                    const tmp = ordered[i];
+                    ordered[i] = ordered[j];
+                    ordered[j] = tmp;
+                }
+            }
+        }
+        else if (options.candidateScoringMode === "weighted") {
+            const wLevel = Number.isFinite(options.candidateScoringWeights.level)
+                ? Math.max(0, options.candidateScoringWeights.level)
+                : 0;
+            const wSlots = Number.isFinite(options.candidateScoringWeights.freeSlots)
+                ? Math.max(0, options.candidateScoringWeights.freeSlots)
+                : 0;
+            const wConnected = Number.isFinite(options.candidateScoringWeights.connected)
+                ? Math.max(0, options.candidateScoringWeights.connected)
+                : 0;
+            const wBid = Number.isFinite(options.candidateScoringWeights.bidPerByte)
+                ? Math.max(0, options.candidateScoringWeights.bidPerByte)
+                : 0;
+            const wSource = Number.isFinite(options.candidateScoringWeights.source)
+                ? Math.max(0, options.candidateScoringWeights.source)
+                : 0;
+            const k = options.candidateShuffleTopK > 0
+                ? Math.min(options.candidateShuffleTopK, ordered.length)
+                : 0;
+            const hasWeightedSignal = wLevel > 0 || wSlots > 0 || wConnected > 0 || wBid > 0 || wSource > 0;
+            if (k > 1 && hasWeightedSignal) {
+                const head = ordered.slice(0, k);
+                const tail = ordered.slice(k);
+                const weightOf = (c) => {
+                    const level = Math.max(0, Math.floor(c.level));
+                    const freeSlots = Math.max(0, Math.floor(c.freeSlots));
+                    const bidPerByte = Math.max(0, Math.floor(c.bidPerByte));
+                    const source = Math.max(0, Math.floor(c.source));
+                    const connected = Boolean(this.peers.get(c.hash));
+                    let weight = 1;
+                    if (wLevel > 0)
+                        weight *= 1 / (1 + wLevel * level);
+                    if (wSlots > 0)
+                        weight *= 1 + wSlots * freeSlots;
+                    if (wConnected > 0 && connected)
+                        weight *= 1 + wConnected;
+                    if (wBid > 0)
+                        weight *= 1 + wBid * bidPerByte;
+                    if (wSource > 0)
+                        weight *= 1 / (1 + wSource * source);
+                    return weight;
+                };
+                const out = [];
+                const remaining = [...head];
+                while (remaining.length > 0) {
+                    let sum = 0;
+                    const weights = new Array(remaining.length);
+                    for (let i = 0; i < remaining.length; i++) {
+                        const w = weightOf(remaining[i]);
+                        const v = Number.isFinite(w) ? Math.max(0, w) : 0;
+                        weights[i] = v;
+                        sum += v;
+                    }
+                    if (sum <= 0) {
+                        out.push(...remaining);
+                        break;
+                    }
+                    let r = upgradeRandom(`weighted:${out.length}:${remaining
+                        .map((candidate) => candidate.hash)
+                        .join(",")}`) * sum;
+                    let pick = 0;
+                    for (; pick < weights.length; pick++) {
+                        r -= weights[pick];
+                        if (r <= 0)
+                            break;
+                    }
+                    if (pick >= remaining.length)
+                        pick = remaining.length - 1;
+                    out.push(remaining[pick]);
+                    remaining.splice(pick, 1);
+                }
+                ordered = out.concat(tail);
+            }
+        }
+        if (parentUpgrade.mode === "probe" || parentUpgrade.mode === "shadow") {
+            const mode = parentUpgrade.mode;
+            const probeLimit = parentUpgrade.mode === "shadow"
+                ? 1
+                : parentUpgrade.probe.maxPerRound;
+            const shadowObserveMsForGate = parentUpgrade.shadow.observeMs;
+            const shadowMinObservationsForGate = parentUpgrade.shadow.minObservations;
+            const probeTimeoutMs = parentUpgrade.probe.timeoutMs;
+            const maxLag = parentUpgrade.probe.maxLagMessages;
+            const now = Date.now();
+            const candidatesToProbe = [];
+            const shadowCandidate = mode === "shadow" && ch.parentShadow
+                ? ordered.find((candidate) => candidate.hash === ch.parentShadow?.hash)
+                : undefined;
+            if (mode === "shadow" &&
+                shadowCandidate &&
+                ch.parentShadow &&
+                shadowObserveMsForGate > 0 &&
+                now - ch.parentShadow.startedAt < shadowObserveMsForGate) {
+                return false;
+            }
+            const probeOrder = shadowCandidate
+                ? [
+                    shadowCandidate,
+                    ...ordered.filter((candidate) => candidate.hash !== shadowCandidate.hash),
+                ]
+                : ordered;
+            for (const candidate of probeOrder) {
+                const rejectUntil = ch.parentProbeRejectUntilByHash.get(candidate.hash);
+                if (rejectUntil != null && rejectUntil > now) {
+                    ch.metrics.reparentUpgradeSkipProbeCooldown += 1;
+                    continue;
+                }
+                if (rejectUntil != null)
+                    ch.parentProbeRejectUntilByHash.delete(candidate.hash);
+                candidatesToProbe.push(candidate);
+                if (candidatesToProbe.length >= probeLimit)
+                    break;
+            }
+            if (candidatesToProbe.length === 0) {
+                applyFailedBackoff();
+                return false;
+            }
+            const shouldReserveRootCapacityForProbe = (candidate) => {
+                if (candidate.hash !== ch.id.root)
+                    return true;
+                if (mode !== "shadow")
+                    return true;
+                if (endedAndComplete && candidate.level === 0)
+                    return true;
+                if (!ch.parentShadow || ch.parentShadow.hash !== candidate.hash) {
+                    return (shadowObserveMsForGate <= 0 && shadowMinObservationsForGate <= 1);
+                }
+                return (now - ch.parentShadow.startedAt >= shadowObserveMsForGate &&
+                    ch.parentShadow.observations + 1 >= shadowMinObservationsForGate);
+            };
+            const rejectShadowCandidate = (candidateHash, reason) => {
+                if (mode !== "shadow")
+                    return;
+                switch (reason) {
+                    case "noReply":
+                        ch.metrics.parentShadowRejectNoReply += 1;
+                        break;
+                    case "notRooted":
+                        ch.metrics.parentShadowRejectNotRooted += 1;
+                        break;
+                    case "capacity":
+                        ch.metrics.parentShadowRejectCapacity += 1;
+                        break;
+                    case "repair":
+                        ch.metrics.parentShadowRejectRepair += 1;
+                        break;
+                    case "lag":
+                        ch.metrics.parentShadowRejectLag += 1;
+                        break;
+                    case "overloaded":
+                        ch.metrics.parentShadowRejectOverloaded += 1;
+                        break;
+                    case "level":
+                        ch.metrics.parentShadowRejectLevel += 1;
+                        break;
+                }
+                if (ch.parentShadow?.hash === candidateHash)
+                    resetShadow();
+                deferParentUpgradeRetryUntilFreshData();
+            };
+            const probed = await Promise.all(candidatesToProbe.map(async (candidate) => ({
+                candidate,
+                reply: await this.probeParentCandidate(ch, candidate.hash, probeTimeoutMs, options.signal, minFreeSlotsFor(candidate.hash), shouldReserveRootCapacityForProbe(candidate)),
+            })));
+            const liveCandidates = [];
+            for (const { candidate, reply } of probed) {
+                if (!reply) {
+                    ch.metrics.reparentUpgradeSkipProbeNoReply += 1;
+                    rejectShadowCandidate(candidate.hash, "noReply");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                if (!reply.rooted) {
+                    ch.metrics.reparentUpgradeSkipProbeNotRooted += 1;
+                    refreshCachedTrackerCandidate(candidate.hash, reply.level, 0);
+                    sendProbeTrackerFeedback(candidate.hash, JOIN_REJECT_NOT_ATTACHED);
+                    rejectShadowCandidate(candidate.hash, "notRooted");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                const liveLevel = Number.isFinite(reply.level)
+                    ? Math.max(0, Math.floor(reply.level))
+                    : candidate.level;
+                const liveFreeSlots = Number.isFinite(reply.freeSlots)
+                    ? Math.max(0, Math.floor(reply.freeSlots))
+                    : 0;
+                refreshCachedTrackerCandidate(candidate.hash, liveLevel, liveFreeSlots);
+                const requiredMinFreeSlots = minFreeSlotsFor(candidate.hash);
+                if (!reply.accepting || liveFreeSlots < requiredMinFreeSlots) {
+                    ch.metrics.reparentUpgradeSkipCandidateSlots += 1;
+                    if (!reply.accepting || liveFreeSlots <= 0) {
+                        sendProbeTrackerFeedback(candidate.hash, JOIN_REJECT_NO_CAPACITY);
+                    }
+                    rejectShadowCandidate(candidate.hash, "capacity");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                const configuredMaxChildLoadRatioRaw = candidate.hash === ch.id.root
+                    ? parentUpgrade.rootMaxChildLoadRatio
+                    : parentUpgrade.maxChildLoadRatio;
+                const configuredMaxChildLoadRatio = candidate.hash === ch.id.root &&
+                    localChannelCount > 1 &&
+                    Number(configuredMaxChildLoadRatioRaw) > 0
+                    ? Math.min(0.2, Number(configuredMaxChildLoadRatioRaw))
+                    : configuredMaxChildLoadRatioRaw;
+                const maxChildLoadRatio = Math.max(0, Number(configuredMaxChildLoadRatio));
+                if (maxChildLoadRatio > 0 &&
+                    reply.maxChildren > 0 &&
+                    (reply.children + 1) / reply.maxChildren > maxChildLoadRatio) {
+                    ch.metrics.reparentUpgradeSkipCandidateSlots += 1;
+                    ch.metrics.reparentUpgradeSkipCandidatePressure += 1;
+                    if (candidate.hash === ch.id.root) {
+                        ch.metrics.reparentUpgradeSkipRootPressure += 1;
+                        refreshCachedTrackerCandidate(candidate.hash, liveLevel, 0);
+                        sendProbeTrackerFeedback(candidate.hash, JOIN_REJECT_NO_CAPACITY);
+                    }
+                    rejectShadowCandidate(candidate.hash, "capacity");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                if (reply.repairing || reply.missingSeqs > 0) {
+                    ch.metrics.reparentUpgradeSkipProbeRepair += 1;
+                    rejectShadowCandidate(candidate.hash, "repair");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                if (reply.overloaded) {
+                    ch.metrics.reparentUpgradeSkipProbeOverloaded += 1;
+                    rejectShadowCandidate(candidate.hash, "overloaded");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                if (ch.maxSeqSeen >= 0 &&
+                    reply.haveToExclusive + maxLag < ch.maxSeqSeen + 1) {
+                    ch.metrics.reparentUpgradeSkipProbeLag += 1;
+                    rejectShadowCandidate(candidate.hash, "lag");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                if (!isEnoughLevelGain(candidate.hash, liveLevel)) {
+                    ch.metrics.reparentUpgradeSkipCandidateLevel += 1;
+                    rejectShadowCandidate(candidate.hash, "level");
+                    rejectProbeCandidate(candidate.hash);
+                    continue;
+                }
+                clearProbeRejectBackoff(candidate.hash);
+                liveCandidates.push({
+                    ...candidate,
+                    level: liveLevel,
+                    freeSlots: liveFreeSlots,
+                    haveToExclusive: reply.haveToExclusive,
+                    reservationToken: reply.reservationToken,
+                });
+            }
+            ordered = liveCandidates.sort((a, b) => {
+                if (a.level !== b.level)
+                    return a.level - b.level;
+                if (a.freeSlots !== b.freeSlots)
+                    return b.freeSlots - a.freeSlots;
+                if (a.bidPerByte !== b.bidPerByte)
+                    return b.bidPerByte - a.bidPerByte;
+                if (a.source !== b.source)
+                    return a.source - b.source;
+                return a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0;
+            });
+            if (ordered.length === 0) {
+                applyFailedBackoff();
+                return false;
+            }
+            clearFailedBackoff();
+            if (mode === "shadow") {
+                const nowAfterProbe = Date.now();
+                const observeMs = parentUpgrade.shadow.observeMs;
+                const minObservations = shadowMinObservationsForGate;
+                const requireDataForShadowPromotion = parentUpgrade.shadow.dualPathMs > 0;
+                const selected = ch.parentShadow != null
+                    ? (ordered.find((candidate) => candidate.hash === ch.parentShadow?.hash) ?? ordered[0])
+                    : ordered[0];
+                if (!selected) {
+                    resetShadow();
+                    return false;
+                }
+                if (endedAndComplete &&
+                    selected.hash === ch.id.root &&
+                    selected.level === 0 &&
+                    !requireDataForShadowPromotion) {
+                    if (!ch.parentShadow || ch.parentShadow.hash !== selected.hash) {
+                        ch.parentShadow = {
+                            hash: selected.hash,
+                            startedAt: nowAfterProbe - observeMs,
+                            observations: minObservations,
+                            level: selected.level,
+                            freeSlots: selected.freeSlots,
+                            haveToExclusive: "haveToExclusive" in selected &&
+                                typeof selected.haveToExclusive === "number"
+                                ? selected.haveToExclusive
+                                : 0,
+                            liveDataMessages: 0,
+                            liveFirstDataMessages: 0,
+                            liveParentFirstDataMessages: 0,
+                            liveCandidateLeadSamples: 0,
+                            liveCandidateLeadMsTotal: 0,
+                            liveCandidateFirstAtBySeq: new Map(),
+                            liveParentFirstAtBySeq: new Map(),
+                            liveComparedSeqs: new Set(),
+                            liveMaxSeqSeen: -1,
+                            liveLastDataAt: 0,
+                        };
+                        this.parentUpgradeShadowInFlightSuffixKey = ch.id.suffixKey;
+                        ch.metrics.parentShadowStart += 1;
+                    }
+                    else {
+                        ch.parentShadow.observations += 1;
+                        ch.parentShadow.level = selected.level;
+                        ch.parentShadow.freeSlots = selected.freeSlots;
+                        ch.parentShadow.haveToExclusive =
+                            "haveToExclusive" in selected &&
+                                typeof selected.haveToExclusive === "number"
+                                ? selected.haveToExclusive
+                                : 0;
+                        ch.metrics.parentShadowObserve += 1;
+                    }
+                    ordered = [selected];
+                }
+                else {
+                    if (!ch.parentShadow || ch.parentShadow.hash !== selected.hash) {
+                        ch.parentShadow = {
+                            hash: selected.hash,
+                            startedAt: nowAfterProbe,
+                            observations: 1,
+                            level: selected.level,
+                            freeSlots: selected.freeSlots,
+                            haveToExclusive: "haveToExclusive" in selected &&
+                                typeof selected.haveToExclusive === "number"
+                                ? selected.haveToExclusive
+                                : 0,
+                            liveDataMessages: 0,
+                            liveFirstDataMessages: 0,
+                            liveParentFirstDataMessages: 0,
+                            liveCandidateLeadSamples: 0,
+                            liveCandidateLeadMsTotal: 0,
+                            liveCandidateFirstAtBySeq: new Map(),
+                            liveParentFirstAtBySeq: new Map(),
+                            liveComparedSeqs: new Set(),
+                            liveMaxSeqSeen: -1,
+                            liveLastDataAt: 0,
+                        };
+                        this.parentUpgradeShadowInFlightSuffixKey = ch.id.suffixKey;
+                        ch.metrics.parentShadowStart += 1;
+                        return false;
+                    }
+                    ch.parentShadow.observations += 1;
+                    ch.parentShadow.level = selected.level;
+                    ch.parentShadow.freeSlots = selected.freeSlots;
+                    ch.parentShadow.haveToExclusive =
+                        "haveToExclusive" in selected &&
+                            typeof selected.haveToExclusive === "number"
+                            ? selected.haveToExclusive
+                            : 0;
+                    ch.metrics.parentShadowObserve += 1;
+                    if (ch.parentShadow.observations < minObservations ||
+                        nowAfterProbe - ch.parentShadow.startedAt < observeMs) {
+                        return false;
+                    }
+                }
+                ordered = [selected];
+            }
+        }
+        let attempts = 0;
+        for (const candidate of ordered) {
+            if (options.signal.aborted)
+                break;
+            if (attempts >= options.joinAttemptsPerRound)
+                break;
+            attempts += 1;
+            if (!isDirectNeighbor(candidate.hash))
+                continue;
+            const previousParent = ch.parent;
+            const previousLevel = ch.level;
+            const previousRouteFromRoot = ch.routeFromRoot
+                ? [...ch.routeFromRoot]
+                : undefined;
+            const previousLastParentDataAt = ch.lastParentDataAt;
+            const previousLastParentUpgradeActivityAt = ch.lastParentUpgradeActivityAt;
+            const previousReceivedAnyParentData = ch.receivedAnyParentData;
+            const shadowDualPathMs = parentUpgrade.shadow.dualPathMs;
+            const shadowDualPathMinMessages = parentUpgrade.shadow.dualPathMinMessages;
+            const shadowDualPathMinAdvantageMessages = Math.max(1, Math.min(16, Math.ceil(shadowDualPathMinMessages / 2)));
+            const shadowDualPathMinLeadSamples = Math.max(1, Math.min(32, shadowDualPathMinMessages));
+            const shadowDualPathMaxParentFirstMessages = Math.max(0, Math.floor(shadowDualPathMinMessages / 8));
+            const shadowDualPathMinLeadMsAvg = shadowDualPathMinMessages <= 1 ? 0 : 128;
+            const useShadowDualPath = parentUpgrade.mode === "shadow" &&
+                shadowDualPathMs > 0 &&
+                previousParent != null &&
+                previousParent !== candidate.hash;
+            const seqAtShadowAttach = ch.maxSeqSeen;
+            const reqId = (this.random() * 0xffffffff) >>> 0;
+            const res = await this.tryJoinOnce(ch, candidate.hash, reqId, options.joinReqTimeoutMs, options.signal, {
+                allowReplace: true,
+                parentUpgradeReservationToken: candidate.hash === ch.id.root &&
+                    "reservationToken" in candidate &&
+                    typeof candidate.reservationToken === "number"
+                    ? candidate.reservationToken
+                    : 0,
+                shadowAttach: useShadowDualPath,
+            });
+            if (res.ok) {
+                if (useShadowDualPath) {
+                    const acceptedParentLevel = Number.isFinite(res.parentLevel)
+                        ? Math.max(0, Math.floor(res.parentLevel))
+                        : candidate.level;
+                    if (!isEnoughLevelGain(candidate.hash, acceptedParentLevel)) {
+                        void this._sendControl(candidate.hash, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+                        resetShadow();
+                        rejectProbeCandidate(candidate.hash);
+                        deferParentUpgradeRetryUntilFreshData(2);
+                        applyFailedBackoff();
+                        return false;
+                    }
+                    const shadow = ch.parentShadow;
+                    if (shadow?.hash === candidate.hash) {
+                        shadow.liveDataMessages = 0;
+                        shadow.liveFirstDataMessages = 0;
+                        shadow.liveParentFirstDataMessages = 0;
+                        shadow.liveCandidateLeadSamples = 0;
+                        shadow.liveCandidateLeadMsTotal = 0;
+                        shadow.liveCandidateFirstAtBySeq.clear();
+                        shadow.liveParentFirstAtBySeq.clear();
+                        shadow.liveComparedSeqs.clear();
+                        shadow.liveMaxSeqSeen = seqAtShadowAttach;
+                        shadow.liveLastDataAt = 0;
+                    }
+                    const deadline = Date.now() + shadowDualPathMs;
+                    for (;;) {
+                        if (options.signal.aborted)
+                            break;
+                        const currentShadow = ch.parentShadow;
+                        const observedFreshCandidateData = currentShadow?.hash === candidate.hash &&
+                            currentShadow.liveFirstDataMessages >=
+                                shadowDualPathMinMessages &&
+                            currentShadow.liveParentFirstDataMessages <=
+                                shadowDualPathMaxParentFirstMessages &&
+                            currentShadow.liveFirstDataMessages >=
+                                currentShadow.liveParentFirstDataMessages +
+                                    shadowDualPathMinAdvantageMessages &&
+                            currentShadow.liveCandidateLeadSamples >=
+                                shadowDualPathMinLeadSamples &&
+                            currentShadow.liveCandidateLeadMsTotal >=
+                                currentShadow.liveCandidateLeadSamples *
+                                    shadowDualPathMinLeadMsAvg &&
+                            currentShadow.liveMaxSeqSeen > seqAtShadowAttach;
+                        if (observedFreshCandidateData) {
+                            const parentRoute = res.parentRouteFromRoot;
+                            if (!parentRoute || parentRoute.length === 0)
+                                break;
+                            ch.parent = candidate.hash;
+                            ch.level = Math.max(1, Math.floor(res.parentLevel ?? candidate.level) + 1);
+                            ch.routeFromRoot = [...parentRoute, this.publicKeyHash];
+                            ch.joinedAtLeastOnce = true;
+                            ch.lastParentDataAt =
+                                currentShadow.liveLastDataAt > 0
+                                    ? currentShadow.liveLastDataAt
+                                    : Date.now();
+                            ch.lastParentUpgradeActivityAt = ch.lastParentDataAt;
+                            ch.receivedAnyParentData = true;
+                            this.resetParentDataLatency(ch);
+                            this.touchPeerHint(ch, candidate.hash);
+                            if (previousParent) {
+                                this.startParentUpgradeGrace(ch, {
+                                    previousParent,
+                                    candidateParent: candidate.hash,
+                                    previousLevel,
+                                    previousRouteFromRoot,
+                                    previousLastParentDataAt,
+                                    previousLastParentUpgradeActivityAt,
+                                    previousReceivedAnyParentData,
+                                    candidateFirstMessages: 0,
+                                    previousFirstMessages: 0,
+                                    minCandidateFirstMessages: shadowDualPathMinMessages,
+                                    minCandidateAdvantageMessages: shadowDualPathMinAdvantageMessages,
+                                    maxPreviousFirstMessages: shadowDualPathMaxParentFirstMessages,
+                                    timeoutMs: shadowDualPathMs,
+                                });
+                            }
+                            ch.metrics.parentShadowPromote += 1;
+                            ch.parentShadow = undefined;
+                            clearShadowInFlight();
+                            clearFailedBackoff();
+                            void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
+                            return true;
+                        }
+                        const remainingMs = deadline - Date.now();
+                        if (remainingMs <= 0)
+                            break;
+                        await delay(Math.min(50, remainingMs), {
+                            signal: options.signal,
+                        });
+                    }
+                    if (ch.parent === previousParent) {
+                        ch.level = previousLevel;
+                        ch.routeFromRoot = previousRouteFromRoot;
+                        ch.lastParentDataAt = previousLastParentDataAt;
+                        ch.lastParentUpgradeActivityAt =
+                            previousLastParentUpgradeActivityAt;
+                        ch.receivedAnyParentData = previousReceivedAnyParentData;
+                    }
+                    void this._sendControl(candidate.hash, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+                    if (ch.parentShadow) {
+                        ch.parentShadow = undefined;
+                        clearShadowInFlight();
+                        ch.metrics.parentShadowReset += 1;
+                    }
+                    // A shadow cutover can only be proven by fresh data. If no
+                    // candidate-first data arrived, wait for enough newer data before
+                    // spending more probes on the same channel. Also cool down this
+                    // candidate; accepting JOIN without proving live data is a weak
+                    // parent signal, not a reason to probe it repeatedly.
+                    rejectProbeCandidate(candidate.hash);
+                    deferParentUpgradeRetryUntilFreshData(2);
+                    applyFailedBackoff();
+                    return false;
+                }
+                const newParent = ch.parent;
+                if (previousParent && newParent && newParent !== previousParent) {
+                    void this._sendControl(previousParent, this.codec.encodeLeave(ch.id.key)).catch(() => { });
+                    if (parentUpgrade.mode === "shadow") {
+                        ch.metrics.parentShadowPromote += 1;
+                        ch.parentShadow = undefined;
+                        clearShadowInFlight();
+                        clearFailedBackoff();
+                    }
+                    return true;
+                }
+                return false;
+            }
+            if (useShadowDualPath) {
+                if (ch.parent === previousParent) {
+                    ch.level = previousLevel;
+                    ch.routeFromRoot = previousRouteFromRoot;
+                    ch.lastParentDataAt = previousLastParentDataAt;
+                    ch.lastParentUpgradeActivityAt =
+                        previousLastParentUpgradeActivityAt;
+                    ch.receivedAnyParentData = previousReceivedAnyParentData;
+                }
+                if (ch.parentShadow?.hash === candidate.hash) {
+                    ch.parentShadow = undefined;
+                    clearShadowInFlight();
+                    ch.metrics.parentShadowReset += 1;
+                }
+                rejectProbeCandidate(candidate.hash);
+                deferParentUpgradeRetryUntilFreshData(2);
+                applyFailedBackoff();
+                return false;
+            }
+        }
+        return false;
+    }
+    async tryJoinOnce(ch, parentHash, reqId, timeoutMs, signal, options) {
+        if (ch.parent && options?.allowReplace !== true)
             return { ok: true };
         if (!this.peers.get(parentHash))
             return { ok: false, timedOut: true };
         const p = new Promise((resolve) => {
-            ch.pendingJoin.set(reqId, { resolve });
+            ch.pendingJoin.set(reqId, {
+                resolve,
+                shadowAttach: options?.shadowAttach === true,
+            });
         });
-        await this._sendControl(parentHash, encodeJoinReq(ch.id.key, reqId, ch.bidPerByte));
+        await this._sendControl(parentHash, this.codec.encodeJoinReq(ch.id.key, reqId, ch.bidPerByte, options?.parentUpgradeReservationToken));
         const res = await Promise.race([
             p,
             delay(Math.max(1, timeoutMs), { signal }).then(() => ({
@@ -4168,13 +5230,41 @@ export class FanoutTree extends DirectStream {
             ch.pendingJoin.delete(reqId);
         return res;
     }
-    async kickChildren(ch) {
-        const children = [...ch.children.keys()];
-        ch.children.clear();
-        ch.dataWriteFailStreakByChild.clear();
-        if (children.length === 0)
+    async kickChildHashes(ch, children, options) {
+        const unique = [...new Set(children)].filter((h) => ch.children.has(h));
+        for (const h of unique) {
+            ch.children.delete(h);
+            ch.dataWriteFailStreakByChild.delete(h);
+        }
+        if (unique.length === 0)
             return;
-        await this._sendControlMany(children, encodeKick(ch.id.key));
+        const resetPeerConnections = options?.resetPeerConnections === true;
+        let kickFailed = false;
+        try {
+            const kickDelivered = await this._sendControlMany(unique, this.codec.encodeKick(ch.id.key));
+            kickFailed = !kickDelivered;
+        }
+        catch (error) {
+            kickFailed = true;
+            throw error;
+        }
+        finally {
+            if (resetPeerConnections && kickFailed) {
+                // If KICK cannot be written on the existing stream, close the peer
+                // connection so the topology change becomes observable.
+                for (const h of unique) {
+                    const stream = this.peers.get(h);
+                    if (!stream)
+                        continue;
+                    void this.components.connectionManager
+                        .closeConnections(stream.peerId)
+                        .catch(() => { });
+                }
+            }
+        }
+    }
+    async kickChildren(ch) {
+        await this.kickChildHashes(ch, [...ch.children.keys()]);
     }
     async onDataMessage(from, peerStream, message, seenBefore) {
         const ignore = this.shouldIgnore(message, seenBefore);
@@ -4203,6 +5293,8 @@ export class FanoutTree extends DirectStream {
             kind === MSG_TRACKER_QUERY ||
             kind === MSG_TRACKER_REPLY ||
             kind === MSG_TRACKER_FEEDBACK ||
+            kind === MSG_PARENT_PROBE_REQ ||
+            kind === MSG_PARENT_PROBE_REPLY ||
             kind === MSG_PROVIDER_ANNOUNCE ||
             kind === MSG_PROVIDER_QUERY ||
             kind === MSG_PROVIDER_REPLY ||
@@ -4224,33 +5316,26 @@ export class FanoutTree extends DirectStream {
                     fromHash === ch.parent)) {
                 return false;
             }
+            if (!ch && kind === MSG_JOIN_REQ && data.length >= 1 + 32 + 4) {
+                // A joiner probed us for a channel we do not host (connected-peer
+                // fallbacks routinely hit bootstraps and non-subscribers). Failing
+                // fast lets the joiner spend its probe budget elsewhere instead of
+                // burning a full join-request timeout and a long cooldown on us.
+                const reqId = readU32BE(data, 33);
+                void this._sendControl(fromHash, this.codec.encodeJoinReject(channelKey, reqId, JOIN_REJECT_NOT_ATTACHED)).catch(() => { });
+                return true;
+            }
             if (kind === MSG_TRACKER_ANNOUNCE) {
-                if (data.length < 1 + 32 + 4 + 2 + 2 + 2 + 4 + 1)
+                const decoded = this.codec.decodeTrackerAnnounce(data);
+                if (!decoded)
                     return false;
-                const ttlMs = readU32BE(data, 33);
-                const level = readU16BE(data, 37);
-                // maxChildren is currently unused, but kept in the wire format.
-                // const maxChildren = readU16BE(data, 39);
-                const freeSlots = readU16BE(data, 41);
-                const bidPerByte = readU32BE(data, 43);
-                const addrCount = data[47];
-                let offset = 48;
-                const addrs = [];
-                const max = Math.min(addrCount, 16);
-                for (let i = 0; i < max; i++) {
-                    if (offset + 2 > data.length)
-                        break;
-                    const len = readU16BE(data, offset);
-                    offset += 2;
-                    if (offset + len > data.length)
-                        break;
-                    addrs.push(data.subarray(offset, offset + len));
-                    offset += len;
-                }
+                const { ttlMs, level, freeSlots, bidPerByte, addrs } = decoded;
                 if (addrs.length === 0) {
                     try {
                         const peer = await this.components.peerStore.get(peerStream.peerId);
-                        const addresses = Array.isArray(peer?.addresses) ? peer.addresses : [];
+                        const addresses = Array.isArray(peer?.addresses)
+                            ? peer.addresses
+                            : [];
                         for (const a of addresses) {
                             const ma = a?.multiaddr ?? a;
                             const bytes = normalizeUint8Array(ma?.bytes);
@@ -4296,10 +5381,10 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_TRACKER_QUERY) {
-                if (data.length < 1 + 32 + 4 + 2)
+                const decoded = this.codec.decodeTrackerQuery(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
-                const want = readU16BE(data, 37);
+                const { reqId, want } = decoded;
                 const now = Date.now();
                 this.touchTrackerNamespace(suffixKey, now);
                 const byPeer = this.trackerBySuffixKey.get(suffixKey);
@@ -4312,8 +5397,9 @@ export class FanoutTree extends DirectStream {
                         }
                         if (hash === fromHash)
                             continue;
-                        if (e.freeSlots <= 0)
+                        if (e.freeSlots <= 0) {
                             continue;
+                        }
                         entries.push(e);
                     }
                     this.pruneTrackerNamespaceIfEmpty(suffixKey);
@@ -4327,21 +5413,28 @@ export class FanoutTree extends DirectStream {
                         return b.bidPerByte - a.bidPerByte;
                     return a.hash < b.hash ? -1 : a.hash > b.hash ? 1 : 0;
                 });
-                const picked = entries.slice(0, clampU16(want));
-                void this._sendControl(fromHash, encodeTrackerReply(channelKey, reqId, picked));
+                // Returning the deterministic head of the directory sends every
+                // concurrent joiner to the same few candidates while deeper capacity
+                // goes unprobed. Sample the reply from a wider best-first pool so
+                // load spreads across all advertised capacity.
+                const wantCount = clampU16(want);
+                const poolSize = Math.min(entries.length, Math.max(wantCount * 4, wantCount));
+                const pool = entries.slice(0, poolSize);
+                for (let i = 0; i < Math.min(wantCount, pool.length); i++) {
+                    const j = i + Math.floor(this.random() * (pool.length - i));
+                    const tmp = pool[i];
+                    pool[i] = pool[j];
+                    pool[j] = tmp;
+                }
+                const picked = pool.slice(0, wantCount);
+                void this._sendControl(fromHash, this.codec.encodeTrackerReply(channelKey, reqId, picked));
                 return true;
             }
             if (kind === MSG_TRACKER_FEEDBACK) {
-                if (data.length < 1 + 32 + 1 + 1 + 1)
-                    return false;
-                const hashLen = data[33];
-                let offset = 34;
-                if (offset + hashLen + 2 > data.length)
+                const decoded = this.codec.decodeTrackerFeedback(data);
+                if (!decoded)
                     return false;
-                const candidateHash = textDecoder.decode(data.subarray(offset, offset + hashLen));
-                offset += hashLen;
-                const event = data[offset++] & 0xff;
-                const reason = data[offset++] & 0xff;
+                const { candidateHash, event, reason } = decoded;
                 const byPeer = this.trackerBySuffixKey.get(suffixKey);
                 if (!byPeer)
                     return true;
@@ -4359,13 +5452,15 @@ export class FanoutTree extends DirectStream {
                     entry.freeSlots = clampU16(Math.max(0, entry.freeSlots - 1));
                     return true;
                 }
-                if (event === TRACKER_FEEDBACK_DIAL_FAILED || event === TRACKER_FEEDBACK_JOIN_TIMEOUT) {
+                if (event === TRACKER_FEEDBACK_DIAL_FAILED ||
+                    event === TRACKER_FEEDBACK_JOIN_TIMEOUT) {
                     byPeer.delete(candidateHash);
                     this.pruneTrackerNamespaceIfEmpty(suffixKey);
                     return true;
                 }
                 if (event === TRACKER_FEEDBACK_JOIN_REJECT) {
-                    if (reason === JOIN_REJECT_NO_CAPACITY || reason === JOIN_REJECT_NOT_ATTACHED) {
+                    if (reason === JOIN_REJECT_NO_CAPACITY ||
+                        reason === JOIN_REJECT_NOT_ATTACHED) {
                         entry.freeSlots = 0;
                         // Expire earlier to reduce time-to-recovery if the entry is stale.
                         entry.expiresAt = Math.min(entry.expiresAt, now + 2_000);
@@ -4375,24 +5470,11 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_PROVIDER_ANNOUNCE) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const decoded = this.codec.decodeProviderAnnounce(data);
+                if (!decoded)
                     return false;
                 const providerId = this.getProviderNamespaceIdFromKey(channelKey, suffixKey);
-                const ttlMs = readU32BE(data, 33);
-                const addrCount = data[37];
-                let offset = 38;
-                const addrs = [];
-                const max = Math.min(addrCount, 16);
-                for (let i = 0; i < max; i++) {
-                    if (offset + 2 > data.length)
-                        break;
-                    const len = readU16BE(data, offset);
-                    offset += 2;
-                    if (offset + len > data.length)
-                        break;
-                    addrs.push(data.subarray(offset, offset + len));
-                    offset += len;
-                }
+                const { ttlMs, addrs } = decoded;
                 if (addrs.length === 0) {
                     try {
                         const peer = await this.components.peerStore.get(peerStream.peerId);
@@ -4446,11 +5528,10 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_PROVIDER_QUERY) {
-                if (data.length < 1 + 32 + 4 + 2 + 4)
+                const decoded = this.codec.decodeProviderQuery(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
-                const want = readU16BE(data, 37);
-                const seed = readU32BE(data, 39);
+                const { reqId, want, seed } = decoded;
                 const now = Date.now();
                 this.touchProviderNamespace(suffixKey, now);
                 const byPeer = this.providerBySuffixKey.get(suffixKey);
@@ -4491,14 +5572,15 @@ export class FanoutTree extends DirectStream {
                     }
                 }
                 const picked = entries.slice(0, clampU16(want));
-                void this._sendControl(fromHash, encodeProviderReply(channelKey, reqId, picked));
+                void this._sendControl(fromHash, this.codec.encodeProviderReply(channelKey, reqId, picked));
                 return true;
             }
             if (kind === MSG_PROVIDER_SUBSCRIBE) {
-                if (data.length < 1 + 32 + 2 + 4)
+                const decoded = this.codec.decodeProviderSubscribe(data);
+                if (!decoded)
                     return false;
-                const want = Math.max(1, readU16BE(data, 33));
-                const ttlMs = Math.min(120_000, Math.max(1_000, readU32BE(data, 35)));
+                const want = Math.max(1, decoded.want);
+                const ttlMs = Math.min(120_000, Math.max(1_000, decoded.ttlMs));
                 const now = Date.now();
                 let watchers = this.providerWatchersBySuffixKey.get(suffixKey);
                 if (!watchers) {
@@ -4520,18 +5602,18 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_PROVIDER_REPLY) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const decoded = this.codec.decodeProviderReply(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
+                const reqId = decoded.reqId;
                 const pendingByReq = this.pendingProviderQueryBySuffixKey.get(suffixKey);
                 const pending = pendingByReq?.get(reqId);
                 if (!pending)
                     return true;
                 pendingByReq.delete(reqId);
-                const count = data[37];
                 const now = Date.now();
                 this.touchProviderNamespace(suffixKey, now);
-                const { providers: candidates } = decodeProviderEntries(data, 38, count);
+                const candidates = this.toProviderCandidates(decoded.entries);
                 this.rememberProviderCandidates(this.getProviderNamespaceIdFromKey(channelKey, suffixKey), candidates, now + 60_000);
                 this.pruneProviderNamespaceIfEmpty(suffixKey);
                 if (candidates.length > 0) {
@@ -4541,11 +5623,11 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_PROVIDER_NOTIFY) {
-                if (data.length < 1 + 32 + 1)
+                const decoded = this.codec.decodeProviderNotify(data);
+                if (!decoded)
                     return false;
-                const count = data[33];
                 const now = Date.now();
-                const { providers } = decodeProviderEntries(data, 34, count);
+                const providers = this.toProviderCandidates(decoded.entries);
                 this.rememberProviderCandidates(this.getProviderNamespaceIdFromKey(channelKey, suffixKey), providers, now + 60_000);
                 if (providers.length > 0) {
                     this.emitProviderUpdate(this.getProviderNamespaceIdFromKey(channelKey, suffixKey), providers);
@@ -4555,45 +5637,18 @@ export class FanoutTree extends DirectStream {
             if (kind === MSG_TRACKER_REPLY) {
                 if (!ch)
                     return true;
-                if (data.length < 1 + 32 + 4 + 1)
+                const decoded = this.codec.decodeTrackerReply(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
+                const reqId = decoded.reqId;
                 const pending = ch.pendingTrackerQuery.get(reqId);
-                if (!pending)
-                    return true;
-                ch.pendingTrackerQuery.delete(reqId);
-                const count = data[37];
-                let offset = 38;
+                if (pending) {
+                    ch.pendingTrackerQuery.delete(reqId);
+                }
                 const candidates = [];
-                const max = Math.min(count, 255);
-                for (let i = 0; i < max; i++) {
-                    if (offset + 1 > data.length)
-                        break;
-                    const hashLen = data[offset++];
-                    if (offset + hashLen > data.length)
-                        break;
-                    const hash = textDecoder.decode(data.subarray(offset, offset + hashLen));
-                    offset += hashLen;
-                    if (offset + 2 + 2 + 4 + 1 > data.length)
-                        break;
-                    const level = readU16BE(data, offset);
-                    offset += 2;
-                    const freeSlots = readU16BE(data, offset);
-                    offset += 2;
-                    const bidPerByte = readU32BE(data, offset);
-                    offset += 4;
-                    const addrCount = data[offset++];
+                for (const entry of decoded.entries) {
                     const addrs = [];
-                    const addrMax = Math.min(addrCount, 16);
-                    for (let j = 0; j < addrMax; j++) {
-                        if (offset + 2 > data.length)
-                            break;
-                        const len = readU16BE(data, offset);
-                        offset += 2;
-                        if (offset + len > data.length)
-                            break;
-                        const bytes = data.subarray(offset, offset + len);
-                        offset += len;
+                    for (const bytes of entry.addrs) {
                         try {
                             addrs.push(multiaddr(bytes));
                         }
@@ -4601,10 +5656,56 @@ export class FanoutTree extends DirectStream {
                             // ignore invalid multiaddrs
                         }
                     }
-                    candidates.push({ hash, level, freeSlots, bidPerByte, addrs });
-                    this.cacheKnownCandidateAddrs(ch, hash, addrs);
+                    candidates.push({
+                        hash: entry.hash,
+                        level: entry.level,
+                        freeSlots: entry.freeSlots,
+                        bidPerByte: entry.bidPerByte,
+                        addrs,
+                    });
+                    this.cacheKnownCandidateAddrs(ch, entry.hash, addrs);
                 }
-                pending.resolve(candidates);
+                if (pending) {
+                    pending.resolve(candidates);
+                }
+                else if (candidates.length > 0) {
+                    // Late reply: the query already timed out, but the candidate
+                    // list is still fresh directory state. Under load the 1s query
+                    // timeout is routinely missed while trackers hold plenty of
+                    // capacity - dropping these replies starves joiners of
+                    // candidates they already paid a round trip for.
+                    const merged = new Map();
+                    for (const c of ch.cachedTrackerCandidates)
+                        merged.set(c.hash, c);
+                    for (const c of candidates)
+                        merged.set(c.hash, c);
+                    ch.cachedTrackerCandidates = [...merged.values()].slice(-256);
+                }
+                return true;
+            }
+            if (kind === MSG_PARENT_PROBE_REQ) {
+                if (!ch || ch.closed)
+                    return true;
+                const decoded = this.codec.decodeParentProbeReq(data);
+                if (!decoded)
+                    return false;
+                this.touchPeerHint(ch, fromHash);
+                void this._sendControl(fromHash, this.encodeParentProbeReplyForChannel(ch, decoded.reqId, fromHash, decoded.minFreeSlots, decoded.reserveRootCapacity)).catch(() => { });
+                return true;
+            }
+            if (kind === MSG_PARENT_PROBE_REPLY) {
+                if (!ch || ch.closed)
+                    return true;
+                const decoded = this.codec.decodeParentProbeReply(data, fromHash);
+                if (!decoded)
+                    return false;
+                const { reqId, ...reply } = decoded;
+                const pending = ch.pendingParentProbe.get(reqId);
+                if (!pending)
+                    return true;
+                ch.pendingParentProbe.delete(reqId);
+                pending.resolve(reply);
+                this.touchPeerHint(ch, fromHash);
                 return true;
             }
             if (!ch)
@@ -4623,20 +5724,20 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_ROUTE_QUERY) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const decoded = this.codec.decodeRouteQuery(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
-                const hashLen = data[37];
-                if (hashLen === 0 || 38 + hashLen > data.length) {
-                    void this._sendControl(fromHash, encodeRouteReply(ch.id.key, reqId)).catch(() => { });
+                const reqId = decoded.reqId;
+                if (decoded.targetHash == null) {
+                    void this._sendControl(fromHash, this.codec.encodeRouteReply(ch.id.key, reqId)).catch(() => { });
                     return true;
                 }
-                const targetHash = textDecoder.decode(data.subarray(38, 38 + hashLen));
+                const targetHash = decoded.targetHash;
                 const localRoute = targetHash === this.publicKeyHash && ch.routeFromRoot
                     ? ch.routeFromRoot
                     : this.getCachedRoute(ch, targetHash);
                 if (this.isRouteValidForChannel(ch, localRoute)) {
-                    void this._sendControl(fromHash, encodeRouteReply(ch.id.key, reqId, localRoute)).catch(() => { });
+                    void this._sendControl(fromHash, this.codec.encodeRouteReply(ch.id.key, reqId, localRoute)).catch(() => { });
                     return true;
                 }
                 if (ch.isRoot) {
@@ -4646,7 +5747,7 @@ export class FanoutTree extends DirectStream {
                     if (rootRoute)
                         this.cacheRoute(ch, rootRoute);
                     if (rootRoute) {
-                        void this._sendControl(fromHash, encodeRouteReply(ch.id.key, reqId, rootRoute)).catch(() => { });
+                        void this._sendControl(fromHash, this.codec.encodeRouteReply(ch.id.key, reqId, rootRoute)).catch(() => { });
                         return true;
                     }
                 }
@@ -4659,16 +5760,19 @@ export class FanoutTree extends DirectStream {
                 }
                 // Cache miss on a parent->child (or root->child) query:
                 // recursively search subtree branches and reply with the first valid route.
-                this.proxyRouteQuery(ch, fromHash, reqId, targetHash, [...ch.children.keys()]);
+                this.proxyRouteQuery(ch, fromHash, reqId, targetHash, [
+                    ...ch.children.keys(),
+                ]);
                 return true;
             }
             if (kind === MSG_ROUTE_REPLY) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const decoded = this.codec.decodeRouteReply(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
-                const routeCount = Math.min(255, data[37]);
-                const { route } = decodeRoute(data, 38, routeCount);
-                const parsedRoute = this.isRouteValidForChannel(ch, route) ? route : undefined;
+                const { reqId, route } = decoded;
+                const parsedRoute = this.isRouteValidForChannel(ch, route)
+                    ? route
+                    : undefined;
                 if (parsedRoute) {
                     this.cacheRoute(ch, parsedRoute);
                 }
@@ -4694,11 +5798,16 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_IHAVE) {
-                if (data.length < 1 + 32 + 4 + 4)
+                const decoded = this.codec.decodeIHave(data);
+                if (!decoded)
                     return false;
-                const haveFrom = readU32BE(data, 33);
-                const haveToExclusive = readU32BE(data, 37);
+                const { haveFrom, haveToExclusive } = decoded;
                 const now = Date.now();
+                if (ch.parent && fromHash === ch.parent) {
+                    ch.lastParentDataAt = now;
+                    ch.receivedAnyParentData = true;
+                    ch.parentRepairUnansweredStreak = 0;
+                }
                 const prev = ch.haveByPeer.get(fromHash);
                 if (prev) {
                     prev.haveFrom = haveFrom;
@@ -4715,6 +5824,16 @@ export class FanoutTree extends DirectStream {
                     });
                 }
                 this.touchPeerHint(ch, fromHash, now);
+                if (ch.parent && fromHash === ch.parent && ch.maxDataAgeMs === 0) {
+                    // A watermark from our parent doubles as gap detection: if data
+                    // writes to us were lost (e.g. burst into a not-yet-writable
+                    // stream) we may have received nothing at all and would
+                    // otherwise never know data exists. Mark the advertised range
+                    // missing so the repair loop pulls it. Deadline-oriented live
+                    // channels (maxDataAgeMs > 0) skip this: catching up on stale
+                    // history would trade deadline latency for completeness.
+                    this.noteEnd(ch, fromHash, haveToExclusive);
+                }
                 // Opportunistic reciprocity: if we still have room in our lazy mesh, add
                 // peers that are actively exchanging IHAVE summaries with us.
                 if (ch.neighborRepair &&
@@ -4728,11 +5847,21 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_JOIN_REQ) {
-                if (data.length < 1 + 32 + 4 + 4)
+                const decoded = this.codec.decodeJoinReq(data);
+                if (!decoded)
                     return false;
-                const reqId = readU32BE(data, 33);
-                const bidPerByte = readU32BE(data, 37);
+                const { reqId, bidPerByte, parentUpgradeReservationToken } = decoded;
                 this.pruneDisconnectedChildren(ch);
+                const hasParentUpgradeReservation = ch.isRoot && parentUpgradeReservationToken > 0;
+                const consumedParentUpgradeReservation = hasParentUpgradeReservation
+                    ? this.consumeParentUpgradeReservation(ch, fromHash, parentUpgradeReservationToken)
+                    : false;
+                if (hasParentUpgradeReservation && !consumedParentUpgradeReservation) {
+                    ch.metrics.parentUpgradeRootReservationRejected += 1;
+                    void this.sendJoinReject(ch, fromHash, reqId, JOIN_REJECT_NO_CAPACITY).catch(() => { });
+                    void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
+                    return true;
+                }
                 // Only accept if we're already attached.
                 if (!ch.isRoot && !ch.parent) {
                     void this.sendJoinReject(ch, fromHash, reqId, JOIN_REJECT_NOT_ATTACHED).catch(() => { });
@@ -4755,8 +5884,16 @@ export class FanoutTree extends DirectStream {
                     void this.sendJoinReject(ch, fromHash, reqId, JOIN_REJECT_NO_CAPACITY).catch(() => { });
                     return true;
                 }
-                if (!ch.children.has(fromHash) && ch.children.size >= ch.effectiveMaxChildren) {
-                    if (!ch.allowKick) {
+                if (!ch.children.has(fromHash) &&
+                    (consumedParentUpgradeReservation
+                        ? ch.children.size >= ch.effectiveMaxChildren
+                        : ch.children.size +
+                            this.parentUpgradeReservationCount(ch, fromHash) >=
+                            ch.effectiveMaxChildren)) {
+                    const blockedByReservedRootCapacity = ch.isRoot &&
+                        !consumedParentUpgradeReservation &&
+                        ch.children.size < ch.effectiveMaxChildren;
+                    if (!ch.allowKick || blockedByReservedRootCapacity) {
                         void this.sendJoinReject(ch, fromHash, reqId, JOIN_REJECT_NO_CAPACITY).catch(() => { });
                         void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                         return true;
@@ -4774,56 +5911,72 @@ export class FanoutTree extends DirectStream {
                         void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                         return true;
                     }
-                    ch.children.delete(worstChild);
-                    ch.dataWriteFailStreakByChild.delete(worstChild);
-                    void this._sendControl(worstChild, encodeKick(ch.id.key));
+                    void this.kickChildHashes(ch, [worstChild]).catch(() => { });
                 }
                 ch.children.set(fromHash, { bidPerByte });
+                if (ch.isRoot && consumedParentUpgradeReservation) {
+                    ch.parentUpgradeTrackerNoCapacityUntil = Math.max(ch.parentUpgradeTrackerNoCapacityUntil, Date.now() + 2_000);
+                }
                 this.touchPeerHint(ch, fromHash);
-                void this._sendControl(fromHash, encodeJoinAccept(ch.id.key, reqId, ch.level, ch.routeFromRoot));
+                const joinAccept = this.codec.encodeJoinAccept(ch.id.key, reqId, ch.level, ch.routeFromRoot, this.getHaveRange(ch));
+                void (async () => {
+                    await this._sendControl(fromHash, joinAccept);
+                    if (ch.endSeqExclusive > 0) {
+                        await this._sendControl(fromHash, this.codec.encodeEnd(ch.id.key, ch.endSeqExclusive));
+                    }
+                })().catch(() => { });
                 void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                 return true;
             }
             if (kind === MSG_JOIN_ACCEPT || kind === MSG_JOIN_REJECT) {
-                if (data.length < 1 + 32 + 4)
+                const reqId = this.codec.decodeJoinResponseReqId(data);
+                if (reqId == null)
                     return false;
-                const reqId = readU32BE(data, 33);
+                // Any explicit join response proves this path is alive end to end.
+                this.noteJoinResponse(fromHash);
                 const pending = ch.pendingJoin.get(reqId);
                 if (!pending)
                     return true;
                 ch.pendingJoin.delete(reqId);
                 if (kind === MSG_JOIN_ACCEPT) {
-                    if (data.length < 1 + 32 + 4 + 2 + 1)
+                    const decoded = this.codec.decodeJoinAccept(data);
+                    if (!decoded)
                         return false;
-                    const parentLevel = readU16BE(data, 37);
-                    const routeCount = Math.min(255, data[39]);
-                    let offset = 40;
-                    const parentRouteFromRoot = [];
-                    const max = Math.min(routeCount, MAX_ROUTE_HOPS);
-                    for (let i = 0; i < max; i++) {
-                        if (offset + 1 > data.length)
-                            break;
-                        const len = data[offset++];
-                        if (len === 0)
-                            break;
-                        if (offset + len > data.length)
-                            break;
-                        parentRouteFromRoot.push(textDecoder.decode(data.subarray(offset, offset + len)));
-                        offset += len;
-                    }
+                    const { parentLevel, parentRouteFromRoot } = decoded;
                     const hasValidParentRoute = parentRouteFromRoot.length > 0 &&
                         parentRouteFromRoot[0] === ch.id.root &&
                         parentRouteFromRoot[parentRouteFromRoot.length - 1] === fromHash;
                     // Defensive: a JOIN_ACCEPT without a rooted route token (unless the parent is the
                     // actual root) can create stable disconnected components. Treat it as a reject.
                     if (fromHash !== ch.id.root && !hasValidParentRoute) {
-                        pending.resolve({ ok: false, rejectReason: JOIN_REJECT_NOT_ATTACHED });
+                        pending.resolve({
+                            ok: false,
+                            rejectReason: JOIN_REJECT_NOT_ATTACHED,
+                        });
+                        return true;
+                    }
+                    const acceptedParentRoute = hasValidParentRoute || fromHash === ch.id.root
+                        ? fromHash === ch.id.root && !hasValidParentRoute
+                            ? [ch.id.root]
+                            : parentRouteFromRoot
+                        : undefined;
+                    if (pending.shadowAttach) {
+                        this.touchPeerHint(ch, fromHash);
+                        pending.resolve({
+                            ok: true,
+                            parentLevel,
+                            parentRouteFromRoot: acceptedParentRoute,
+                        });
                         return true;
                     }
+                    const attachedAt = Date.now();
                     ch.parent = fromHash;
                     ch.level = parentLevel + 1;
                     ch.joinedAtLeastOnce = true;
-                    ch.lastParentDataAt = Date.now();
+                    ch.lastParentDataAt = attachedAt;
+                    ch.lastParentUpgradeActivityAt = attachedAt;
+                    ch.parentRepairUnansweredStreak = 0;
+                    this.resetParentDataLatency(ch);
                     // Treat JOIN_ACCEPT as parent liveness for stale re-parenting:
                     // if callers enable `staleAfterMs`, we should be able to detach even
                     // before the first data message arrives (for example, during churn
@@ -4837,58 +5990,56 @@ export class FanoutTree extends DirectStream {
                         // Minimal fallback: parent is the root.
                         ch.routeFromRoot = [ch.id.root, this.publicKeyHash];
                     }
+                    if (ch.repairEnabled &&
+                        ch.maxDataAgeMs === 0 &&
+                        decoded.haveRange != null) {
+                        // Optional appendix: the parent's current have-range. Lets a
+                        // freshly attached child learn immediately which sequences
+                        // already exist, so lost deliveries surface as missing seqs
+                        // (and repair) instead of silent absence.
+                        const { haveFrom, haveToExclusive } = decoded.haveRange;
+                        if (haveToExclusive > haveFrom) {
+                            // Mark only; the repair loop's own cadence picks the gaps
+                            // up, giving in-flight live deliveries time to land first
+                            // (an immediate pull here races them into duplicates).
+                            this.noteEnd(ch, fromHash, haveToExclusive);
+                        }
+                    }
                     this.touchPeerHint(ch, fromHash);
-                    pending.resolve({ ok: true });
+                    pending.resolve({
+                        ok: true,
+                        parentLevel,
+                        parentRouteFromRoot: acceptedParentRoute,
+                    });
                     this.dispatchEvent(new CustomEvent("fanout:joined", {
-                        detail: { topic: ch.id.topic, root: ch.id.root, parent: fromHash },
+                        detail: {
+                            topic: ch.id.topic,
+                            root: ch.id.root,
+                            parent: fromHash,
+                        },
                     }));
                     void this.announceToTrackers(ch, this.closeController.signal).catch(() => { });
                 }
                 else {
-                    if (data.length < 1 + 32 + 4 + 1)
+                    const decoded = this.codec.decodeJoinReject(data);
+                    if (!decoded)
                         return false;
-                    const reason = data[37] & 0xff;
+                    const reason = decoded.reason;
                     const redirects = [];
-                    if (data.length >= 1 + 32 + 4 + 1 + 1) {
-                        const count = Math.min(255, data[38]);
-                        let offset = 39;
-                        const max = Math.min(count, JOIN_REJECT_REDIRECT_MAX);
-                        for (let i = 0; i < max; i++) {
-                            if (offset + 1 > data.length)
-                                break;
-                            const hashLen = data[offset++];
-                            if (hashLen === 0)
-                                break;
-                            if (offset + hashLen > data.length)
-                                break;
-                            const hash = textDecoder.decode(data.subarray(offset, offset + hashLen));
-                            offset += hashLen;
-                            if (offset + 1 > data.length)
-                                break;
-                            const addrCount = Math.min(255, data[offset++]);
-                            const addrs = [];
-                            const addrMax = Math.min(addrCount, JOIN_REJECT_REDIRECT_ADDR_MAX);
-                            for (let j = 0; j < addrMax; j++) {
-                                if (offset + 2 > data.length)
-                                    break;
-                                const len = readU16BE(data, offset);
-                                offset += 2;
-                                if (offset + len > data.length)
-                                    break;
-                                const bytes = data.subarray(offset, offset + len);
-                                offset += len;
-                                try {
-                                    addrs.push(multiaddr(bytes));
-                                }
-                                catch {
-                                    // ignore invalid multiaddrs
-                                }
+                    for (const redirect of decoded.redirects) {
+                        const addrs = [];
+                        for (const bytes of redirect.addrs) {
+                            try {
+                                addrs.push(multiaddr(bytes));
                             }
-                            if (hash && addrs.length > 0) {
-                                redirects.push({ hash, addrs });
-                                this.cacheKnownCandidateAddrs(ch, hash, addrs);
+                            catch {
+                                // ignore invalid multiaddrs
                             }
                         }
+                        if (redirect.hash && addrs.length > 0) {
+                            redirects.push({ hash: redirect.hash, addrs });
+                            this.cacheKnownCandidateAddrs(ch, redirect.hash, addrs);
+                        }
                     }
                     pending.resolve({ ok: false, rejectReason: reason, redirects });
                 }
@@ -4954,11 +6105,10 @@ export class FanoutTree extends DirectStream {
                 const isFromChild = ch.children.has(fromHash);
                 if (!isFromParent && !isFromChild)
                     return true;
-                if (data.length < 1 + 32 + 8 + 1)
+                const decoded = this.codec.decodeUnicastAck(data);
+                if (!decoded)
                     return false;
-                const ackToken = readU64BE(data, 33);
-                const routeCount = Math.min(255, data[41]);
-                const decoded = decodeRoute(data, 42, routeCount);
+                const ackToken = decoded.ackToken;
                 const route = decoded.route;
                 const target = route.length > 0 ? route[route.length - 1] : "";
                 const origin = message.header.signatures?.publicKeys?.[0]?.hashcode?.() ?? fromHash;
@@ -5038,33 +6188,13 @@ export class FanoutTree extends DirectStream {
                         return true;
                     }
                 }
-                if (data.length < 1 + 32 + 1 + 1)
+                const decoded = this.codec.decodeUnicast(data);
+                if (!decoded)
                     return false;
-                const flags = data[33] & 0xff;
-                let offset = 34;
-                let ackToken;
-                if (flags & UNICAST_FLAG_ACK) {
-                    if (data.length < offset + 8 + 1)
-                        return false;
-                    ackToken = readU64BE(data, offset);
-                    offset += 8;
-                }
-                const routeCount = Math.min(255, data[offset]);
-                offset += 1;
-                const decoded = decodeRoute(data, offset, routeCount);
+                const ackToken = decoded.ackToken;
                 const route = decoded.route;
-                offset = decoded.offset;
-                let replyRoute;
-                if (ackToken != null) {
-                    if (data.length < offset + 1)
-                        return false;
-                    const replyCount = Math.min(255, data[offset]);
-                    offset += 1;
-                    const decodedReply = decodeRoute(data, offset, replyCount);
-                    replyRoute = decodedReply.route;
-                    offset = decodedReply.offset;
-                }
-                const payload = data.subarray(offset);
+                const replyRoute = decoded.replyRoute;
+                const payload = data.subarray(decoded.payloadOffset);
                 const target = route.length > 0 ? route[route.length - 1] : "";
                 const origin = message.header.signatures?.publicKeys?.[0]?.hashcode?.() ?? fromHash;
                 this.touchPeerHint(ch, fromHash);
@@ -5094,7 +6224,7 @@ export class FanoutTree extends DirectStream {
                             if (canAck) {
                                 const nextHop = replyRoute[1];
                                 if (nextHop && ch.children.has(nextHop)) {
-                                    void this._sendControl(nextHop, encodeUnicastAck(ch.id.key, ackToken, replyRoute)).catch(() => { });
+                                    void this._sendControl(nextHop, this.codec.encodeUnicastAck(ch.id.key, ackToken, replyRoute)).catch(() => { });
                                 }
                             }
                         }
@@ -5106,6 +6236,11 @@ export class FanoutTree extends DirectStream {
                     const stream = this.peers.get(nextHop);
                     if (!stream)
                         return true;
+                    // A validated source route is passing through: learn it (and the
+                    // reply route) so subsequent unicasts skip route discovery.
+                    this.cacheRoute(ch, route);
+                    if (replyRoute)
+                        this.cacheRoute(ch, replyRoute);
                     void stream
                         .waitForWrite(message.bytes(), Number(message.header.priority ?? CONTROL_PRIORITY), this.closeController.signal)
                         .catch(() => { });
@@ -5137,7 +6272,7 @@ export class FanoutTree extends DirectStream {
                                 replyRoute[0] === ch.id.root &&
                                 replyRoute[replyRoute.length - 1] === origin;
                             if (canAck) {
-                                void this._sendControl(ch.parent, encodeUnicastAck(ch.id.key, ackToken, replyRoute)).catch(() => { });
+                                void this._sendControl(ch.parent, this.codec.encodeUnicastAck(ch.id.key, ackToken, replyRoute)).catch(() => { });
                             }
                         }
                         return true;
@@ -5148,6 +6283,9 @@ export class FanoutTree extends DirectStream {
                     const stream = this.peers.get(nextHop);
                     if (!stream)
                         return true;
+                    this.cacheRoute(ch, route);
+                    if (replyRoute)
+                        this.cacheRoute(ch, replyRoute);
                     void stream
                         .waitForWrite(message.bytes(), Number(message.header.priority ?? CONTROL_PRIORITY), this.closeController.signal)
                         .catch(() => { });
@@ -5171,14 +6309,18 @@ export class FanoutTree extends DirectStream {
                 ch.routeFromRoot = undefined;
                 ch.routeByPeer.clear();
                 ch.lastParentDataAt = 0;
+                ch.lastParentUpgradeActivityAt = 0;
                 ch.receivedAnyParentData = false;
                 ch.pendingJoin.clear();
+                ch.pendingParentProbe.clear();
+                ch.parentShadow = undefined;
+                void Promise.all(this.clearParentUpgradeGrace(ch, true, true)).catch(() => { });
+                if (this.parentUpgradeShadowInFlightSuffixKey === ch.id.suffixKey) {
+                    this.parentUpgradeShadowInFlightSuffixKey = undefined;
+                }
                 ch.pendingRouteQuery.clear();
                 this.abortPendingUnicastAcks(ch, new AbortError("fanout channel kicked"));
-                for (const pending of ch.pendingRouteProxy.values()) {
-                    clearTimeout(pending.timer);
-                }
-                ch.pendingRouteProxy.clear();
+                this.clearRouteProxies(ch);
                 void this.kickChildren(ch).catch(() => { });
                 this.dispatchEvent(new CustomEvent("fanout:kicked", {
                     detail: { topic: ch.id.topic, root: ch.id.root, from: fromHash },
@@ -5186,27 +6328,30 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_END) {
-                if (data.length < 1 + 32 + 4)
+                const lastSeqExclusive = this.codec.decodeEnd(data);
+                if (lastSeqExclusive == null)
                     return false;
-                const lastSeqExclusive = readU32BE(data, 33);
+                if (ch.parent && fromHash === ch.parent) {
+                    ch.lastParentDataAt = Date.now();
+                    ch.receivedAnyParentData = true;
+                    ch.parentRepairUnansweredStreak = 0;
+                }
                 ch.endSeqExclusive = Math.max(ch.endSeqExclusive, lastSeqExclusive);
                 this.touchPeerHint(ch, fromHash);
                 this.noteEnd(ch, fromHash, lastSeqExclusive);
                 if (ch.children.size > 0) {
-                    void this._sendControlMany([...ch.children.keys()], encodeEnd(ch.id.key, lastSeqExclusive));
+                    void this._sendControlMany([...ch.children.keys()], this.codec.encodeEnd(ch.id.key, lastSeqExclusive));
                 }
                 void this.tickRepair(ch).catch(() => { });
                 return true;
             }
             if (kind === MSG_REPAIR_REQ) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const seqs = this.codec.decodeRepairSeqs(data);
+                if (!seqs)
                     return false;
                 if (!ch.children.has(fromHash))
                     return true;
-                const count = data[37];
-                const max = Math.min(count, Math.floor((data.length - 38) / 4));
-                for (let i = 0; i < max; i++) {
-                    const seq = readU32BE(data, 38 + i * 4);
+                for (const seq of seqs) {
                     const cached = this.getCached(ch, seq);
                     if (!cached) {
                         ch.metrics.cacheMissesServed += 1;
@@ -5218,13 +6363,11 @@ export class FanoutTree extends DirectStream {
                 return true;
             }
             if (kind === MSG_FETCH_REQ) {
-                if (data.length < 1 + 32 + 4 + 1)
+                const seqs = this.codec.decodeRepairSeqs(data);
+                if (!seqs)
                     return false;
                 this.touchPeerHint(ch, fromHash);
-                const count = data[37];
-                const max = Math.min(count, Math.floor((data.length - 38) / 4));
-                for (let i = 0; i < max; i++) {
-                    const seq = readU32BE(data, 38 + i * 4);
+                for (const seq of seqs) {
                     const cached = this.getCached(ch, seq);
                     if (!cached) {
                         ch.metrics.cacheMissesServed += 1;
@@ -5248,10 +6391,100 @@ export class FanoutTree extends DirectStream {
                 return false;
             const seq = readU32BE(id, 4);
             if (ch.parent && fromHash === ch.parent) {
-                ch.lastParentDataAt = Date.now();
+                const receivedAt = Date.now();
+                ch.lastParentDataAt = receivedAt;
+                ch.lastParentUpgradeActivityAt = receivedAt;
                 ch.receivedAnyParentData = true;
+                ch.parentRepairUnansweredStreak = 0;
+            }
+            const hadCachedBeforeData = this.getCached(ch, seq) != null;
+            if (ch.parent && fromHash === ch.parent && !hadCachedBeforeData) {
+                this.noteParentDataLatency(ch, message.header.timestamp);
             }
             ch.maxSeqSeen = Math.max(ch.maxSeqSeen, seq);
+            if (ch.parentUpgradeRetryAfterSeq >= 0 &&
+                seq > ch.parentUpgradeRetryAfterSeq) {
+                ch.parentUpgradeRetryAfterSeq = -1;
+            }
+            const parentShadow = ch.parentShadow;
+            if (parentShadow != null) {
+                const now = Date.now();
+                const pruneShadowSeqMap = (map) => {
+                    while (map.size > 512) {
+                        const oldest = map.keys().next().value;
+                        if (oldest == null)
+                            break;
+                        map.delete(oldest);
+                    }
+                };
+                const pruneShadowSeqSet = (set) => {
+                    while (set.size > 512) {
+                        const oldest = set.keys().next().value;
+                        if (oldest == null)
+                            break;
+                        set.delete(oldest);
+                    }
+                };
+                const rememberShadowArrival = (map) => {
+                    if (map.has(seq))
+                        return map.get(seq);
+                    map.set(seq, now);
+                    pruneShadowSeqMap(map);
+                    return now;
+                };
+                const recordCandidateLead = (candidateAt, parentAt) => {
+                    if (candidateAt == null ||
+                        parentAt == null ||
+                        parentShadow.liveComparedSeqs.has(seq)) {
+                        return;
+                    }
+                    parentShadow.liveComparedSeqs.add(seq);
+                    pruneShadowSeqSet(parentShadow.liveComparedSeqs);
+                    if (candidateAt < parentAt) {
+                        parentShadow.liveCandidateLeadSamples += 1;
+                        parentShadow.liveCandidateLeadMsTotal += parentAt - candidateAt;
+                    }
+                };
+                if (parentShadow.hash === fromHash) {
+                    const candidateAt = rememberShadowArrival(parentShadow.liveCandidateFirstAtBySeq);
+                    recordCandidateLead(candidateAt, parentShadow.liveParentFirstAtBySeq.get(seq));
+                    if (seq > parentShadow.liveMaxSeqSeen) {
+                        parentShadow.liveMaxSeqSeen = seq;
+                        parentShadow.liveDataMessages += 1;
+                    }
+                    if (!hadCachedBeforeData) {
+                        parentShadow.liveFirstDataMessages += 1;
+                    }
+                    parentShadow.liveLastDataAt = now;
+                }
+                else if (ch.parent != null && fromHash === ch.parent) {
+                    const parentAt = rememberShadowArrival(parentShadow.liveParentFirstAtBySeq);
+                    recordCandidateLead(parentShadow.liveCandidateFirstAtBySeq.get(seq), parentAt);
+                    if (!hadCachedBeforeData) {
+                        parentShadow.liveParentFirstDataMessages += 1;
+                    }
+                }
+            }
+            const parentUpgradeGrace = ch.parentUpgradeGrace;
+            if (parentUpgradeGrace != null && !hadCachedBeforeData) {
+                if (fromHash === parentUpgradeGrace.candidateParent) {
+                    parentUpgradeGrace.candidateFirstMessages += 1;
+                }
+                else if (fromHash === parentUpgradeGrace.previousParent) {
+                    parentUpgradeGrace.previousFirstMessages += 1;
+                }
+                if (parentUpgradeGrace.previousFirstMessages >
+                    parentUpgradeGrace.maxPreviousFirstMessages) {
+                    this.rollbackParentUpgradeGrace(ch);
+                }
+                else if (parentUpgradeGrace.candidateFirstMessages >=
+                    parentUpgradeGrace.minCandidateFirstMessages &&
+                    parentUpgradeGrace.candidateFirstMessages >=
+                        parentUpgradeGrace.previousFirstMessages +
+                            parentUpgradeGrace.minCandidateAdvantageMessages) {
+                    this.commitParentUpgradeGrace(ch);
+                }
+            }
             this.noteReceivedSeq(ch, fromHash, seq);
             const payload = data.subarray(1);
             ch.metrics.dataReceives += 1;