p2p-fret 0.5.0 → 0.6.0

package/dist/src/estimate/size-estimator.d.ts

@@ -1,6 +1,12 @@
-import type { DigitreeStore } from '../store/digitree-store.js';
+import type { DigitreeStore, PeerEntry } from '../store/digitree-store.js';
 export type SizeEstimate = {
     n: number;
     confidence: number;
 };
-export declare function estimateSizeAndConfidence(store: DigitreeStore, m: number): SizeEstimate;
+/**
+ * Online network-size estimate from inter-peer ring gaps. An optional `filter` scopes the
+ * estimate to a subset of the store (e.g. same-network members only) so foreign peers from
+ * a co-resident network can't inflate `n_est` and the derived cluster span / near-radius.
+ * Defaults to counting every entry, leaving the standalone/simulator path unchanged.
+ */
+export declare function estimateSizeAndConfidence(store: DigitreeStore, m: number, filter?: (e: PeerEntry) => boolean): SizeEstimate;

package/dist/src/estimate/size-estimator.js

@@ -11,8 +11,14 @@ function medianBigInt(values) {
     const mid = Math.floor(arr.length / 2);
     return arr.length % 2 === 0 ? (arr[mid - 1] + arr[mid]) / 2n : arr[mid];
 }
-export function estimateSizeAndConfidence(store, m) {
-    const peers = store.list();
+/**
+ * Online network-size estimate from inter-peer ring gaps. An optional `filter` scopes the
+ * estimate to a subset of the store (e.g. same-network members only) so foreign peers from
+ * a co-resident network can't inflate `n_est` and the derived cluster span / near-radius.
+ * Defaults to counting every entry, leaving the standalone/simulator path unchanged.
+ */
+export function estimateSizeAndConfidence(store, m, filter) {
+    const peers = filter ? store.list().filter(filter) : store.list();
     const count = peers.length;
     if (count === 0)
         return { n: 0, confidence: 0 };

package/dist/src/index.d.ts

@@ -120,7 +120,7 @@ export { hashKey, hashPeerId } from './ring/hash.js';
 export type { RingCoord } from './ring/hash.js';
 export { xorDistance, clockwiseDistance, minDistance, lexLess } from './ring/distance.js';
 export { DigitreeStore } from './store/digitree-store.js';
-export type { PeerEntry, PeerState } from './store/digitree-store.js';
+export type { PeerEntry, PeerState, MembershipState } from './store/digitree-store.js';
 export { estimateSizeAndConfidence } from './estimate/size-estimator.js';
 export type { SizeEstimate } from './estimate/size-estimator.js';
 export { assembleCohort } from './service/cohort.js';

package/dist/src/rpc/leave.js

@@ -1,5 +1,5 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_LEAVE, encodeJson, decodeJson, readAllBounded } from './protocols.js';
+import { PROTOCOL_LEAVE, encodeJson, decodeJson, readAllBounded, openRpcStream } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:leave');
 const MAX_REPLACEMENTS = 12;
@@ -33,15 +33,9 @@ export function registerLeave(node, onLeave, protocol = PROTOCOL_LEAVE) {
 }
 export async function sendLeave(node, peerIdStr, notice, protocol = PROTOCOL_LEAVE) {
     const pid = peerIdFromString(peerIdStr);
-    const conns = node.getConnections(pid);
     let stream;
     try {
-        if (conns.length > 0) {
-            stream = await conns[0].newStream([protocol]);
-        }
-        else {
-            stream = await node.dialProtocol(pid, [protocol]);
-        }
+        stream = await openRpcStream(node, pid, [protocol]);
         stream.send(await encodeJson(notice));
         await stream.close();
     }

package/dist/src/rpc/maybe-act.js

@@ -1,5 +1,5 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_MAYBE_ACT, encodeJson, decodeJson, readAllBounded } from './protocols.js';
+import { PROTOCOL_MAYBE_ACT, encodeJson, decodeJson, readAllBounded, openRpcStream } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:maybeAct');
 export function registerMaybeAct(node, handle, protocol = PROTOCOL_MAYBE_ACT, maxBytes = 512 * 1024) {
@@ -18,15 +18,9 @@ export function registerMaybeAct(node, handle, protocol = PROTOCOL_MAYBE_ACT, ma
 }
 export async function sendMaybeAct(node, peerIdStr, msg, protocol = PROTOCOL_MAYBE_ACT) {
     const pid = peerIdFromString(peerIdStr);
-    const conns = node.getConnections(pid);
     let stream;
     try {
-        if (conns.length > 0) {
-            stream = await conns[0].newStream([protocol]);
-        }
-        else {
-            stream = await node.dialProtocol(pid, [protocol]);
-        }
+        stream = await openRpcStream(node, pid, [protocol]);
         stream.send(await encodeJson(msg));
         await stream.close();
         const bytes = await readAllBounded(stream, 512 * 1024);

package/dist/src/rpc/neighbors.js

@@ -1,5 +1,5 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE, encodeJson, decodeJson, readAllBounded, } from './protocols.js';
+import { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE, encodeJson, decodeJson, readAllBounded, openRpcStream, } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:neighbors');
 export function registerNeighbors(node, getSnapshot, onAnnounce, protocols = { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE }, maxBytes = 128 * 1024) {
@@ -30,14 +30,13 @@ export function registerNeighbors(node, getSnapshot, onAnnounce, protocols = { P
 }
 export async function fetchNeighbors(node, peerIdOrStr, protocol = PROTOCOL_NEIGHBORS) {
     const pid = peerIdFromString(peerIdOrStr);
-    const conns = node.getConnections(pid);
-    if (conns.length === 0) {
-        // No existing connection - skip to reduce churn
-        return { v: 1, from: peerIdOrStr, timestamp: Date.now(), successors: [], predecessors: [], sig: '' };
-    }
     let stream;
     try {
-        stream = await conns[0].newStream([protocol]);
+        stream = await openRpcStream(node, pid, [protocol], { requireExisting: true });
+        if (stream == null) {
+            // No existing connection - skip to reduce churn
+            return { v: 1, from: peerIdOrStr, timestamp: Date.now(), successors: [], predecessors: [], sig: '' };
+        }
         const bytes = await readAllBounded(stream, 128 * 1024);
         const res = await decodeJson(bytes);
         if ('busy' in res && res.busy) {
@@ -60,13 +59,12 @@ export async function fetchNeighbors(node, peerIdOrStr, protocol = PROTOCOL_NEIG
 }
 export async function announceNeighbors(node, peerIdOrStr, snapshot, protocol = PROTOCOL_NEIGHBORS_ANNOUNCE) {
     const pid = peerIdFromString(peerIdOrStr);
-    const conns = node.getConnections(pid);
-    if (conns.length === 0) {
-        return; // skip if not connected
-    }
     let stream;
     try {
-        stream = await conns[0].newStream([protocol]);
+        stream = await openRpcStream(node, pid, [protocol], { requireExisting: true });
+        if (stream == null) {
+            return; // skip if not connected
+        }
         stream.send(await encodeJson(snapshot));
         await stream.close();
     }

package/dist/src/rpc/ping.js

@@ -1,5 +1,5 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_PING, encodeJson, decodeJson, readAllBounded } from './protocols.js';
+import { PROTOCOL_PING, encodeJson, decodeJson, readAllBounded, openRpcStream } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:ping');
 function isBusy(res) {
@@ -37,13 +37,7 @@ export async function sendPing(node, peer, protocol = PROTOCOL_PING) {
     const pid = peerIdFromString(peer);
     let stream;
     try {
-        const conns = node.getConnections(pid);
-        if (conns.length > 0) {
-            stream = await conns[0].newStream([protocol]);
-        }
-        else {
-            stream = await node.dialProtocol(pid, [protocol]);
-        }
+        stream = await openRpcStream(node, pid, [protocol]);
         const bytes = await readAllBounded(stream, 1024);
         const rttMs = Math.max(0, Date.now() - start);
         if (bytes.length === 0)

package/dist/src/rpc/protocols.d.ts

@@ -1,3 +1,5 @@
+import type { Libp2p } from 'libp2p';
+import type { PeerId, Stream } from '@libp2p/interface';
 export declare function makeProtocols(networkName?: string): {
     PROTOCOL_NEIGHBORS: string;
     PROTOCOL_NEIGHBORS_ANNOUNCE: string;
@@ -10,6 +12,17 @@ export declare const PROTOCOL_NEIGHBORS_ANNOUNCE = "/optimystic/default/fret/1.0
 export declare const PROTOCOL_MAYBE_ACT = "/optimystic/default/fret/1.0.0/maybeAct";
 export declare const PROTOCOL_LEAVE = "/optimystic/default/fret/1.0.0/leave";
 export declare const PROTOCOL_PING = "/optimystic/default/fret/1.0.0/ping";
+/**
+ * True when `err` is libp2p's protocol-negotiation failure — i.e. the remote does
+ * not support the dialed protocol. Thrown by `dialProtocol`/`newStream` (via
+ * multistream-select) as `UnsupportedProtocolError`.
+ *
+ * This is the definitive "foreign network" signal for namespaced FRET RPCs: it must
+ * be distinguished from a generic timeout / transient failure (which leaves a peer
+ * unclassified). Matches by `name` (modern libp2p) and `code` (legacy
+ * `ERR_UNSUPPORTED_PROTOCOL`), with a message-substring fallback.
+ */
+export declare function isUnsupportedProtocolError(err: unknown): boolean;
 export declare function encodeJson(obj: unknown): Promise<Uint8Array>;
 export declare function decodeJson<T = unknown>(bytes: Uint8Array): Promise<T>;
 export declare function toBytes(chunk: Uint8Array | {
@@ -19,3 +32,20 @@ export declare function readAllBounded(stream: AsyncIterable<Uint8Array | {
     subarray(): Uint8Array;
 }>, maxBytes: number, timeoutMs?: number): Promise<Uint8Array>;
 export declare function validateTimestamp(ts: number, maxDriftMs?: number): boolean;
+/**
+ * Open an RPC stream to `pid`, preferring a DIRECT open connection and falling
+ * back to a limited (circuit-relay) one.
+ *
+ * `runOnLimitedConnection: true` is REQUIRED for the relayed path — libp2p
+ * rejects a stream over a limited connection without it — and is a harmless
+ * no-op on a direct connection. Preferring a direct connection avoids riding a
+ * circuit that the relay can reset once a per-circuit cap or reservation lapses
+ * (and which briefly coexists with the upgraded direct link after DCUtR).
+ *
+ * When `requireExisting` is set the caller skips dialing if no connection
+ * exists (neighbors fetch/announce reduce churn this way) and `undefined` is
+ * returned; otherwise we `dialProtocol`.
+ */
+export declare function openRpcStream(node: Libp2p, pid: PeerId, protocols: string[], opts?: {
+    requireExisting?: boolean;
+}): Promise<Stream | undefined>;

package/dist/src/rpc/protocols.js

@@ -14,6 +14,31 @@ export const PROTOCOL_NEIGHBORS_ANNOUNCE = '/optimystic/default/fret/1.0.0/neigh
 export const PROTOCOL_MAYBE_ACT = '/optimystic/default/fret/1.0.0/maybeAct';
 export const PROTOCOL_LEAVE = '/optimystic/default/fret/1.0.0/leave';
 export const PROTOCOL_PING = '/optimystic/default/fret/1.0.0/ping';
+/**
+ * True when `err` is libp2p's protocol-negotiation failure — i.e. the remote does
+ * not support the dialed protocol. Thrown by `dialProtocol`/`newStream` (via
+ * multistream-select) as `UnsupportedProtocolError`.
+ *
+ * This is the definitive "foreign network" signal for namespaced FRET RPCs: it must
+ * be distinguished from a generic timeout / transient failure (which leaves a peer
+ * unclassified). Matches by `name` (modern libp2p) and `code` (legacy
+ * `ERR_UNSUPPORTED_PROTOCOL`), with a message-substring fallback.
+ */
+export function isUnsupportedProtocolError(err) {
+    if (err == null || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.name === 'UnsupportedProtocolError')
+        return true;
+    if (e.code === 'ERR_UNSUPPORTED_PROTOCOL')
+        return true;
+    if (typeof e.message === 'string') {
+        const m = e.message.toLowerCase();
+        if (m.includes('could not negotiate') || m.includes('protocol selection failed'))
+            return true;
+    }
+    return false;
+}
 export async function encodeJson(obj) {
     const text = JSON.stringify(obj);
     return new TextEncoder().encode(text);
@@ -79,3 +104,42 @@ export async function readAllBounded(stream, maxBytes, timeoutMs = 5000) {
 export function validateTimestamp(ts, maxDriftMs = 300_000) {
     return Math.abs(Date.now() - ts) <= maxDriftMs;
 }
+/**
+ * True for a circuit-relay ("limited") connection. libp2p stamps a relayed
+ * connection with `limits` (per-circuit data/duration caps); we additionally
+ * sniff the multiaddr for `/p2p-circuit` as a fallback for transports/versions
+ * that don't populate `limits`.
+ */
+function isLimitedConnection(c) {
+    if (c.limits != null)
+        return true;
+    const addr = c.remoteAddr?.toString?.();
+    return addr != null && addr.includes('/p2p-circuit');
+}
+/**
+ * Open an RPC stream to `pid`, preferring a DIRECT open connection and falling
+ * back to a limited (circuit-relay) one.
+ *
+ * `runOnLimitedConnection: true` is REQUIRED for the relayed path — libp2p
+ * rejects a stream over a limited connection without it — and is a harmless
+ * no-op on a direct connection. Preferring a direct connection avoids riding a
+ * circuit that the relay can reset once a per-circuit cap or reservation lapses
+ * (and which briefly coexists with the upgraded direct link after DCUtR).
+ *
+ * When `requireExisting` is set the caller skips dialing if no connection
+ * exists (neighbors fetch/announce reduce churn this way) and `undefined` is
+ * returned; otherwise we `dialProtocol`.
+ */
+export async function openRpcStream(node, pid, protocols, opts = {}) {
+    const open = node.getConnections(pid)
+        .filter(c => c?.status === 'open' && typeof c?.newStream === 'function');
+    // Prefer a direct connection; fall back to the limited one only when it is
+    // the only open path (the steady state for browsers and NATed peers).
+    const chosen = open.find(c => !isLimitedConnection(c)) ?? open[0];
+    const streamOpts = { runOnLimitedConnection: true, negotiateFully: false };
+    if (chosen)
+        return chosen.newStream(protocols, streamOpts);
+    if (opts.requireExisting)
+        return undefined;
+    return node.dialProtocol(pid, protocols, streamOpts);
+}

package/dist/src/service/cohort.d.ts

@@ -1,4 +1,4 @@
-import type { DigitreeStore } from '../store/digitree-store.js';
+import type { DigitreeStore, PeerEntry } from '../store/digitree-store.js';
 /**
  * Two-sided cohort assembly: an alternating successor/predecessor walk outward from
  * `hashedCoord`, returning up to `wants` distinct peer ids. Auto-adapts when fewer than
@@ -7,5 +7,10 @@ import type { DigitreeStore } from '../store/digitree-store.js';
  * Pure over the store — no libp2p/node state — so the same selection logic is shared by
  * `FretService.assembleCohort` and out-of-band consumers (e.g. the Optimystic design
  * simulator) with zero divergence.
+ *
+ * `filter` is forwarded to the underlying ring walks: with it, the walk skips non-matching
+ * entries and keeps advancing (so a cluster of foreign peers near the key can't starve the
+ * cohort — the over-fetch of `wants * 2` plus skip-and-continue still reaches `wants`
+ * matching members). Defaults to no filter, leaving the standalone/simulator path unchanged.
  */
-export declare function assembleCohort(store: DigitreeStore, hashedCoord: Uint8Array, wants: number, exclude?: Set<string>): string[];
+export declare function assembleCohort(store: DigitreeStore, hashedCoord: Uint8Array, wants: number, exclude?: Set<string>, filter?: (e: PeerEntry) => boolean): string[];

package/dist/src/service/cohort.js

@@ -6,12 +6,17 @@
  * Pure over the store — no libp2p/node state — so the same selection logic is shared by
  * `FretService.assembleCohort` and out-of-band consumers (e.g. the Optimystic design
  * simulator) with zero divergence.
+ *
+ * `filter` is forwarded to the underlying ring walks: with it, the walk skips non-matching
+ * entries and keeps advancing (so a cluster of foreign peers near the key can't starve the
+ * cohort — the over-fetch of `wants * 2` plus skip-and-continue still reaches `wants`
+ * matching members). Defaults to no filter, leaving the standalone/simulator path unchanged.
  */
-export function assembleCohort(store, hashedCoord, wants, exclude) {
+export function assembleCohort(store, hashedCoord, wants, exclude, filter) {
     const out = [];
     const ex = exclude ?? new Set();
-    const succIds = store.neighborsRight(hashedCoord, wants * 2);
-    const predIds = store.neighborsLeft(hashedCoord, wants * 2);
+    const succIds = store.neighborsRight(hashedCoord, wants * 2, filter);
+    const predIds = store.neighborsLeft(hashedCoord, wants * 2, filter);
     let si = 0, pi = 0;
     while (out.length < wants && (si < succIds.length || pi < predIds.length)) {
         if (out.length % 2 === 0 && si < succIds.length) {

package/dist/src/service/fret-service.d.ts

@@ -1,13 +1,17 @@
 import type { Startable } from '@libp2p/interface';
 import type { FretService as IFretService, FretMode, FretConfig, ReportEvent, RouteAndMaybeActV1, NearAnchorV1, SerializedTable, ActivityHandler, RouteProgress, LookupOptions } from '../index.js';
-import { DigitreeStore } from '../store/digitree-store.js';
+import { DigitreeStore, type PeerEntry } from '../store/digitree-store.js';
 import type { Libp2p } from 'libp2p';
 import { type SparsityModel } from '../store/relevance.js';
 /**
  * Select sample entries spread across diverse ring positions using sparsity-biased scoring.
  * Excludes self and entries already in successors/predecessors (they're redundant).
+ *
+ * `filter` scopes the candidate set (FretService passes the member predicate so an outgoing
+ * snapshot never advertises a foreign peer to same-network neighbors). Defaults to no filter,
+ * leaving the exported standalone unchanged.
  */
-export declare function selectDiverseSample(store: DigitreeStore, selfCoord: Uint8Array, sparsity: SparsityModel, excludeIds: Set<string>, cap: number): Array<{
+export declare function selectDiverseSample(store: DigitreeStore, selfCoord: Uint8Array, sparsity: SparsityModel, excludeIds: Set<string>, cap: number, filter?: (e: PeerEntry) => boolean): Array<{
     id: string;
     coord: string;
     relevance: number;
@@ -18,6 +22,8 @@ export declare class FretService implements IFretService, Startable {
     private readonly cfg;
     private readonly node;
     private stabilizing;
+    private stopped;
+    private readonly nodeListeners;
     private inflightAct;
     private readonly bucketNeighbors;
     private readonly bucketMaybeAct;
@@ -51,8 +57,27 @@ export declare class FretService implements IFretService, Startable {
     private applyTouch;
     private applySuccess;
     private applyFailure;
+    /** Confirm `id` serves this network (idempotent; no-op if absent or already member). */
+    private markMember;
+    /**
+     * Confirm `id` does NOT serve this network (idempotent). Foreign is reversible —
+     * a later successful namespaced RPC or re-identify promotes it back to member.
+     * We tag and retain rather than evict: an evicted foreign peer is just re-added by
+     * the next peer:connect/peerStore seed and re-probed in a loop.
+     */
+    private markForeign;
+    /**
+     * Classify `id` from a libp2p-reported protocol list (available once identify has
+     * run). Member if any of our namespaced protocols appears; foreign if the list is
+     * non-empty but contains none of them; left unknown if empty (identify pending).
+     */
+    private classifyByProtocols;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /** Register a node event listener and track it so stop() can detach it. */
+    private addNodeListener;
+    /** Detach all node event listeners registered via addNodeListener. */
+    private removeNodeListeners;
     setMode(mode: FretMode): void;
     ready(): Promise<void>;
     private maxBytesNeighbors;
@@ -75,12 +100,50 @@ export declare class FretService implements IFretService, Startable {
     private announceOnDeparture;
     private isNearNeighbor;
     private announceToNewPeers;
+    /**
+     * Feed a received snapshot's network-size estimate into the local estimator.
+     * No-op unless both estimate and confidence are present and positive.
+     */
+    private calibrateSizeFromSnapshot;
     private mergeAnnounceSnapshot;
     private seedFromPeerStore;
     private startStabilizationLoop;
     private seedFromBootstraps;
     private stabilizeOnce;
     private probeNeighborsLatency;
+    /**
+     * Bounded classification probe pass over `unknown` peers.
+     *
+     * Normal traffic only touches peers the ring already selects, but the follow-on
+     * gating work will exclude `unknown` peers from the ring — so without a dedicated
+     * pass an unknown same-network peer would never be selected, never probed, and be
+     * permanently starved. This iterates unknowns directly from the store (not through
+     * ring views), prefers connected / has-addresses ones, and sends a namespaced ping
+     * to at most N per tick. It runs only while unknowns exist; in single-network
+     * steady state every peer becomes member and this is a no-op (no extra traffic).
+     */
+    private classifyUnknownPeers;
+    /**
+     * Occasionally re-probe a few `foreign` peers so a same-network peer that was *mislabeled*
+     * foreign (e.g. identify completed before the peer registered our protocol handlers) is
+     * re-admitted via a successful namespaced ping. Before ring-membership gating this self-
+     * healed for free — `probeNeighborsLatency` pinged near ring peers regardless of label —
+     * but gating excludes foreign peers from the ring, closing that path. The `peer:update`
+     * identify path also re-admits, but it is not guaranteed (it depends on the remote pushing
+     * an identify update), so this RPC path is the backstop the gating work owes (per the
+     * `ring-membership-classification` review tripwire).
+     *
+     * Bounded and self-limiting: only a couple of off-backoff foreign peers per tick, and a
+     * confirmed-foreign probe records a growing backoff (see `probeMembership`), so a genuinely
+     * foreign peer is re-probed at most ~once per backoff window rather than every tick.
+     */
+    private reprobeForeignPeers;
+    /**
+     * Probe a single peer's membership with a namespaced ping. Success → member;
+     * unsupported-protocol → foreign; timeout / transient → stay unknown but back off
+     * so we don't hammer an unreachable-but-connected peer every tick.
+     */
+    private probeMembership;
     private mergeNeighborSnapshots;
     private snapshot;
     neighborDistance(selfId: string, hashedCoord: Uint8Array, k: number): number;
@@ -101,6 +164,7 @@ export declare class FretService implements IFretService, Startable {
     private recordBackoff;
     private clearBackoff;
     private getBackoffPenalty;
+    private pruneBackoffMap;
     report(_evt: ReportEvent): void;
     /**
      * Add an external network size observation (e.g., from cluster messages, peer queries)