@optimystic/db-p2p 0.14.1 → 0.16.3

package/dist/src/index.js

@@ -12,12 +12,15 @@ export * from "./repo/cluster-coordinator.js";
 export * from "./repo/coordinator-repo.js";
 export * from "./repo/service.js";
 export * from "./storage/block-storage.js";
+export * from "./storage/raw-store-driver.js";
+export * from "./storage/kv-raw-storage.js";
+export * from "./storage/memory-store-driver.js";
 export * from "./storage/memory-storage.js";
 export * from "./storage/i-block-storage.js";
 export * from "./storage/i-raw-storage.js";
 export * from "./storage/struct.js";
 export * from "./storage/storage-repo.js";
-export * from "./storage/restoration-coordinator-v2.js";
+export * from "./storage/restoration-coordinator.js";
 export * from "./storage/ring-selector.js";
 export * from "./storage/storage-monitor.js";
 export * from "./storage/arachnode-fret-adapter.js";

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AACxD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wCAAwC,CAAC;AACvD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iDAAiD,CAAC;AAChE,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qCAAqC,CAAC;AACpD,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qCAAqC,CAAC;AACpD,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sCAAsC,CAAC;AACrD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wCAAwC,CAAC;AACvD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iDAAiD,CAAC;AAChE,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC"}

package/dist/src/it-utility.d.ts

@@ -1,4 +1,4 @@
-export declare function first<T>(createIterable: (signal: AbortSignal) => AsyncIterable<T>, onEmpty?: () => T, timeoutMs?: number): Promise<T>;
+export declare function first<T>(createIterable: () => AsyncIterable<T>, onEmpty?: () => T): Promise<T>;
 export declare function asyncIteratorToArray<T>(iterator: AsyncIterable<T>): Promise<T[]>;
 export declare function reduce<TP, TC>(iter: IterableIterator<TC>, each: (prior: TP, current: TC, index: number) => TP, start: TP): TP;
 //# sourceMappingURL=it-utility.d.ts.map

package/dist/src/it-utility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"it-utility.d.ts","sourceRoot":"","sources":["../../src/it-utility.ts"],"names":[],"mappings":"AAAA,wBAAsB,KAAK,CAAC,CAAC,EAC5B,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,aAAa,CAAC,CAAC,CAAC,EACzD,OAAO,GAAE,MAAM,CAA+C,EAC9D,SAAS,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,CAAC,CAAC,CAYZ;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAMtF;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,MAQxH"}
+{"version":3,"file":"it-utility.d.ts","sourceRoot":"","sources":["../../src/it-utility.ts"],"names":[],"mappings":"AAAA,wBAAsB,KAAK,CAAC,CAAC,EAC5B,cAAc,EAAE,MAAM,aAAa,CAAC,CAAC,CAAC,EACtC,OAAO,GAAE,MAAM,CAA+C,GAC5D,OAAO,CAAC,CAAC,CAAC,CAKZ;AAED,wBAAsB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAMtF;AAED,wBAAgB,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,MAQxH"}

package/dist/src/it-utility.js

@@ -1,17 +1,8 @@
-export async function first(createIterable, onEmpty = () => { throw new Error('No items found'); }, timeoutMs) {
-    const controller = new AbortController();
-    const timer = typeof timeoutMs === 'number' ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
-    try {
-        for await (const item of createIterable(controller.signal)) {
-            return item;
-        }
-        return onEmpty();
-    }
-    finally {
-        if (timer !== undefined)
-            clearTimeout(timer);
-        controller.abort();
+export async function first(createIterable, onEmpty = () => { throw new Error('No items found'); }) {
+    for await (const item of createIterable()) {
+        return item;
     }
+    return onEmpty();
 }
 export async function asyncIteratorToArray(iterator) {
     const result = [];

package/dist/src/it-utility.js.map

@@ -1 +1 @@
-{"version":3,"file":"it-utility.js","sourceRoot":"","sources":["../../src/it-utility.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,KAAK,CAC1B,cAAyD,EACzD,UAAmB,GAAG,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAA,CAAC,CAAC,EAC9D,SAAkB;IAElB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1G,IAAI,CAAC;QACJ,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,OAAO,EAAE,CAAC;IAClB,CAAC;YAAS,CAAC;QACV,IAAI,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7C,UAAU,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;AACF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,QAA0B;IACvE,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED,MAAM,UAAU,MAAM,CAAS,IAA0B,EAAE,IAAmD,EAAE,KAAS;IACxH,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QAC1B,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAChC,EAAE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC"}
+{"version":3,"file":"it-utility.js","sourceRoot":"","sources":["../../src/it-utility.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,KAAK,UAAU,KAAK,CAC1B,cAAsC,EACtC,UAAmB,GAAG,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAA,CAAC,CAAC;IAE9D,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,cAAc,EAAE,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,QAA0B;IACvE,MAAM,MAAM,GAAQ,EAAE,CAAC;IACvB,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED,MAAM,UAAU,MAAM,CAAS,IAA0B,EAAE,IAAmD,EAAE,KAAS;IACxH,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QAC1B,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAChC,EAAE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/src/libp2p-key-network.d.ts

@@ -23,8 +23,28 @@ export declare const FIND_COORDINATOR_ERROR_CODES: {
     readonly SELF_COORDINATION_EXHAUSTED: "SELF_COORDINATION_EXHAUSTED";
     /** No peer (including self) is an eligible coordinator. */
     readonly NO_COORDINATOR_AVAILABLE: "NO_COORDINATOR_AVAILABLE";
+    /**
+     * The candidate set was non-empty but every non-self candidate serves a
+     * DIFFERENT network's protocol (or none of this network's). Distinct from
+     * NO_COORDINATOR_AVAILABLE so a Sereus-style trace points at the real cause —
+     * "peer(s) do not serve this network's protocol" — instead of a generic
+     * "all candidates excluded" / super-majority failure.
+     */
+    readonly NO_NETWORK_COORDINATOR: "NO_NETWORK_COORDINATOR";
 };
 export type FindCoordinatorErrorCode = typeof FIND_COORDINATOR_ERROR_CODES[keyof typeof FIND_COORDINATOR_ERROR_CODES];
+/**
+ * Network-membership classification of a peer relative to THIS node's network,
+ * derived from the peer's libp2p peerStore protocol list:
+ * - `serves`   — advertises this network's namespaced `cluster`/`repo` protocol.
+ * - `foreign`  — has a non-empty protocol list but none for this network → another network.
+ * - `unknown`  — protocol list empty / peer absent → identify not yet completed. This is
+ *                both a fresh same-network peer (will flip to `serves`) AND a cross-network
+ *                peer (whose network-namespaced identify can NEVER complete, so it stays
+ *                `unknown` forever) — indistinguishable at a single instant, separated over
+ *                the retry/stabilization window.
+ */
+export type NetworkMembership = 'serves' | 'foreign' | 'unknown';
 export declare class FindCoordinatorError extends Error {
     readonly code: FindCoordinatorErrorCode;
     constructor(code: FindCoordinatorErrorCode, message: string);
@@ -63,13 +83,31 @@ export declare class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
     private readonly libp2p;
     private readonly clusterSize;
     private readonly reputation?;
+    /**
+     * Network-namespaced protocol prefix (`/optimystic/<networkName>`). When
+     * provided, coordinator/cohort selection is scoped to peers that serve THIS
+     * network's `cluster`/`repo` protocol, so a peer that only belongs to another
+     * network sharing the same physical nodes/bootstraps is never chosen. When
+     * ABSENT, the membership filter is disabled (today's exact behavior) — required
+     * for backward compatibility because most call sites don't know the network name.
+     */
+    private readonly protocolPrefix?;
     private readonly selfCoordinationConfig;
     private networkHighWaterMark;
     private lastConnectedTime;
     private consecutiveIsolatedSessions;
     private readonly networkMode;
     private readonly persistence?;
-    constructor(libp2p: Libp2p, clusterSize?: number, selfCoordinationConfig?: SelfCoordinationConfig, networkMode?: NetworkMode, persistence?: NetworkStatePersistence, reputation?: IPeerReputation | undefined);
+    constructor(libp2p: Libp2p, clusterSize?: number, selfCoordinationConfig?: SelfCoordinationConfig, networkMode?: NetworkMode, persistence?: NetworkStatePersistence, reputation?: IPeerReputation | undefined, 
+    /**
+     * Network-namespaced protocol prefix (`/optimystic/<networkName>`). When
+     * provided, coordinator/cohort selection is scoped to peers that serve THIS
+     * network's `cluster`/`repo` protocol, so a peer that only belongs to another
+     * network sharing the same physical nodes/bootstraps is never chosen. When
+     * ABSENT, the membership filter is disabled (today's exact behavior) — required
+     * for backward compatibility because most call sites don't know the network name.
+     */
+    protocolPrefix?: string | undefined);
     private readonly coordinatorCache;
     private static readonly MAX_CACHE_ENTRIES;
     private readonly log;
@@ -95,6 +133,13 @@ export declare class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
     shouldAllowSelfCoordination(): SelfCoordinationDecision;
     recordCoordinator(key: Uint8Array, peerId: PeerId, ttlMs?: number): void;
     private getCachedCoordinator;
+    /**
+     * 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`.
+     */
+    private isLimitedConnection;
     connect(peerId: PeerId, protocol: string, options?: AbortOptions): Promise<Stream>;
     private getFret;
     private getNeighborIdsForKey;
@@ -109,5 +154,57 @@ export declare class Libp2pKeyPeerNetwork implements IKeyNetwork, IPeerNetwork {
      * back to the defense-in-depth drop than throw out of findCluster.
      */
     private getPeerStoreAddrsByPeer;
+    /**
+     * Single-pass peerStore read returning BOTH protocols and addresses per peer from one
+     * `store.get` call. Used on the membership-scoped `findCluster` hot path, where the
+     * cohort needs protocols (to classify membership) AND addresses (to backfill dial
+     * targets) for the same peers — reading them together avoids a second `store.get` per
+     * finally-selected member. Same error handling as {@link getPeerStoreProtocolsByPeer}
+     * and {@link getPeerStoreAddrsByPeer}: a missing peer or peerStore failure is left
+     * absent from the map (caller treats absent protocols as 'unknown', absent addrs as none).
+     */
+    private getPeerStoreRecordsByPeer;
+    /**
+     * Prefetch each peer's advertised protocol list from the libp2p peerStore.
+     * Returns a map from peer-id string to its protocols (empty array when the peer
+     * is absent or has not yet been identified). Mirrors {@link getPeerStoreAddrsByPeer};
+     * errors are swallowed so a peerStore hiccup degrades to "unknown" rather than throwing.
+     */
+    private getPeerStoreProtocolsByPeer;
+    /**
+     * Over-fetch width for network-membership scoping. A cross-network peer can sit
+     * NEARER the key than a legitimate same-network peer and displace it from the
+     * nearest-`clusterSize` window, so when scoping is active we ask FRET for a wider
+     * proximity band and then keep the nearest peers that actually serve this network.
+     * (A ring polluted by more cross-network peers than this band is the domain of the
+     * separate FRET-side eviction follow-up; this band covers realistic co-location.)
+     */
+    private membershipOverfetch;
+    /**
+     * Classify a peer's network membership from its advertised protocols. Self always
+     * `serves` (it trivially serves its own network). When no `protocolPrefix` is
+     * configured the filter is disabled and EVERY peer is reported `serves`, so all
+     * callers behave exactly as before this scoping was added.
+     */
+    private membershipOf;
+    /**
+     * Scope a reputation-ordered candidate id list to this network for COORDINATOR
+     * selection: keep ONLY peers confirmed to serve this network (`serves`, which always
+     * includes self), dropping both `foreign` peers (serving another network) and
+     * `unknown` peers (peerStore protocol list empty — not yet confirmed). Incoming
+     * (reputation) order is preserved among the surviving `serves` peers. A no-op
+     * (returns the input unchanged, no drops) when `protocolPrefix` is unset or the list
+     * is empty — the membership-disabled path is therefore untouched.
+     *
+     * `droppedUnconfirmed` reports whether any candidate was excluded because it was not
+     * confirmed to serve this network — `foreign` OR `unknown` under scoping — so the
+     * caller can surface a distinct "no network coordinator" failure rather than a generic
+     * one. An `unknown` peer is not gambled on as coordinator: a permanent cross-network
+     * contaminant and a fresh same-network peer mid-identify are indistinguishable at an
+     * instant, but the filter re-reads the peerStore on every retry attempt, so a genuine
+     * same-network peer that completes `identify` within the retry window flips to `serves`
+     * and is selected normally on that attempt.
+     */
+    private filterByMembership;
 }
 //# sourceMappingURL=libp2p-key-network.d.ts.map

package/dist/src/libp2p-key-network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"libp2p-key-network.d.ts","sourceRoot":"","sources":["../../src/libp2p-key-network.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"libp2p-key-network.d.ts","sourceRoot":"","sources":["../../src/libp2p-key-network.ts"],"names":[],"mappings":"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"}

package/dist/src/libp2p-key-network.js

@@ -22,7 +22,15 @@ export const FIND_COORDINATOR_ERROR_CODES = {
      */
     SELF_COORDINATION_EXHAUSTED: 'SELF_COORDINATION_EXHAUSTED',
     /** No peer (including self) is an eligible coordinator. */
-    NO_COORDINATOR_AVAILABLE: 'NO_COORDINATOR_AVAILABLE'
+    NO_COORDINATOR_AVAILABLE: 'NO_COORDINATOR_AVAILABLE',
+    /**
+     * The candidate set was non-empty but every non-self candidate serves a
+     * DIFFERENT network's protocol (or none of this network's). Distinct from
+     * NO_COORDINATOR_AVAILABLE so a Sereus-style trace points at the real cause —
+     * "peer(s) do not serve this network's protocol" — instead of a generic
+     * "all candidates excluded" / super-majority failure.
+     */
+    NO_NETWORK_COORDINATOR: 'NO_NETWORK_COORDINATOR'
 };
 export class FindCoordinatorError extends Error {
     code;
@@ -36,16 +44,27 @@ export class Libp2pKeyPeerNetwork {
     libp2p;
     clusterSize;
     reputation;
+    protocolPrefix;
     selfCoordinationConfig;
     networkHighWaterMark = 1;
     lastConnectedTime = Date.now();
     consecutiveIsolatedSessions = 0;
     networkMode;
     persistence;
-    constructor(libp2p, clusterSize = 16, selfCoordinationConfig, networkMode, persistence, reputation) {
+    constructor(libp2p, clusterSize = 16, selfCoordinationConfig, networkMode, persistence, reputation, 
+    /**
+     * Network-namespaced protocol prefix (`/optimystic/<networkName>`). When
+     * provided, coordinator/cohort selection is scoped to peers that serve THIS
+     * network's `cluster`/`repo` protocol, so a peer that only belongs to another
+     * network sharing the same physical nodes/bootstraps is never chosen. When
+     * ABSENT, the membership filter is disabled (today's exact behavior) — required
+     * for backward compatibility because most call sites don't know the network name.
+     */
+    protocolPrefix) {
         this.libp2p = libp2p;
         this.clusterSize = clusterSize;
         this.reputation = reputation;
+        this.protocolPrefix = protocolPrefix;
         this.selfCoordinationConfig = {
             gracePeriodMs: selfCoordinationConfig?.gracePeriodMs ?? 30_000,
             shrinkageThreshold: selfCoordinationConfig?.shrinkageThreshold ?? 0.5,
@@ -233,17 +252,39 @@ export class Libp2pKeyPeerNetwork {
             this.coordinatorCache.delete(k);
         return undefined;
     }
+    /**
+     * 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`.
+     */
+    isLimitedConnection(c) {
+        if (c.limits != null)
+            return true;
+        const addr = c.remoteAddr?.toString?.();
+        return addr != null && addr.includes('/p2p-circuit');
+    }
     connect(peerId, protocol, options) {
         const conns = this.libp2p.getConnections?.(peerId) ?? [];
         // Filter to only-open connections so a closing/closed entry that libp2p
         // hasn't yet evicted from its index doesn't get picked up here.
-        const open = conns.find(c => c?.status === 'open' && typeof c?.newStream === 'function');
-        if (open) {
+        const open = conns.filter(c => c?.status === 'open' && typeof c?.newStream === 'function');
+        // Prefer a DIRECT connection over a limited (circuit-relay) one for the RPC.
+        // A relayed/limited connection can be reset by the relay once a per-circuit
+        // cap or reservation lapses (@libp2p/circuit-relay-v2), surfacing to the
+        // coordinator as a StreamResetError that fails consensus. After DCUtR upgrades
+        // a relayed link to direct, both connections briefly coexist — picking the
+        // direct one avoids riding the soon-to-be-reset circuit. We only fall back to
+        // the limited connection (with runOnLimitedConnection) when it is the only open
+        // path — the steady state for browsers and NATed peers before any upgrade.
+        const chosen = open.find(c => !this.isLimitedConnection(c)) ?? open[0];
+        if (chosen) {
             // runOnLimitedConnection: true is required to open a stream over a
             // circuit-relay (limited) connection — the steady-state path for
             // browsers and NATed peers. Without it, the warm relay connection
-            // from a prior dialProtocol cannot be reused on subsequent RPCs.
-            return open.newStream([protocol], {
+            // from a prior dialProtocol cannot be reused on subsequent RPCs. It is
+            // a harmless no-op on the preferred direct connection.
+            return chosen.newStream([protocol], {
                 signal: options?.signal,
                 runOnLimitedConnection: true,
                 negotiateFully: false
@@ -272,6 +313,12 @@ export class Libp2pKeyPeerNetwork {
         const t0 = Date.now();
         const excludedSet = new Set((_options?.excludedPeers ?? []).map(p => p.toString()));
         const keyStr = this.toCacheKey(key).substring(0, 12);
+        // Tracks whether the network-membership filter excluded an UNCONFIRMED candidate
+        // — `foreign` (another network) OR `unknown` (not yet confirmed to serve this
+        // network) — during any attempt. If selection ultimately fails with self
+        // unavailable, this lets us surface NO_NETWORK_COORDINATOR (the real cause)
+        // instead of the generic NO_COORDINATOR_AVAILABLE.
+        let droppedUnconfirmedAnyAttempt = false;
         this.log('findCoordinator:start key=%s excluded=%o', keyStr, Array.from(excludedSet).map(s => s.substring(0, 12)));
         // honor cache if not excluded
         const cached = this.getCachedCoordinator(key);
@@ -301,7 +348,18 @@ export class Libp2pKeyPeerNetwork {
                     && !(this.reputation?.isBanned(id)))
                     .sort((a, b) => (this.reputation?.getScore(a) ?? 0) - (this.reputation?.getScore(b) ?? 0));
                 this.log('findCoordinator:fret-connected key=%s count=%d peers=%o', keyStr, connectedFretIds.length, connectedFretIds.map(s => s.substring(0, 12)));
-                const pick = connectedFretIds[0];
+                // Network-membership scoping (no-op when protocolPrefix is unset): only a peer
+                // CONFIRMED to serve this network ('serves') is eligible — both `foreign`
+                // (another network) and `unknown` (not yet identified) peers are excluded
+                // from selection. A cross-network peer is permanently 'unknown' (its
+                // namespaced identify never completes), so it is never gambled on; over the
+                // 3×500ms retry window a genuine same-network peer flips to 'serves' on a
+                // re-read of the peerStore and is selected normally on that attempt. Self
+                // always classifies as 'serves' and stays eligible.
+                const { ranked, droppedUnconfirmed } = await this.filterByMembership(connectedFretIds);
+                if (droppedUnconfirmed)
+                    droppedUnconfirmedAnyAttempt = true;
+                const pick = ranked[0];
                 if (pick) {
                     const pid = peerIdFromString(pick);
                     this.recordCoordinator(key, pid);
@@ -312,14 +370,24 @@ export class Libp2pKeyPeerNetwork {
             catch (err) {
                 this.log('findCoordinator getNeighborIdsForKey failed - %o', err);
             }
-            // fallback: prefer any existing connected peer that's not excluded or banned
-            const connectedPick = connected
+            // fallback: prefer any existing connected peer that's not excluded or banned,
+            // scoped to this network's serving peers (a `foreign` or not-yet-confirmed
+            // `unknown` peer is never picked). Note this candidate set is built from
+            // connected REMOTE peers and never includes self, so when no serving peer is
+            // present selection falls through to the last-resort self-coordination block.
+            const connectedCandidates = connected
                 .filter(p => !excludedSet.has(p.toString()) && !(this.reputation?.isBanned(p.toString())))
-                .sort((a, b) => (this.reputation?.getScore(a.toString()) ?? 0) - (this.reputation?.getScore(b.toString()) ?? 0))[0];
+                .sort((a, b) => (this.reputation?.getScore(a.toString()) ?? 0) - (this.reputation?.getScore(b.toString()) ?? 0))
+                .map(p => p.toString());
+            const { ranked: connRanked, droppedUnconfirmed: connDroppedUnconfirmed } = await this.filterByMembership(connectedCandidates);
+            if (connDroppedUnconfirmed)
+                droppedUnconfirmedAnyAttempt = true;
+            const connectedPick = connRanked[0];
             if (connectedPick) {
-                this.recordCoordinator(key, connectedPick);
+                const pid = peerIdFromString(connectedPick);
+                this.recordCoordinator(key, pid);
                 this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'connected-fallback');
-                return connectedPick;
+                return pid;
             }
             // If no connections and not the last attempt, wait and retry
             if (connected.length === 0 && attempt < maxRetries - 1) {
@@ -349,6 +417,15 @@ export class Libp2pKeyPeerNetwork {
             this.log('findCoordinator:done key=%s ms=%d source=%s', keyStr, Date.now() - t0, 'self');
             return self;
         }
+        // Self is excluded and selection found no eligible peer. If the membership filter is
+        // the reason the candidate set emptied (the only other peers are `foreign` — serving
+        // a DIFFERENT network — or `unknown` — not yet confirmed to serve this network),
+        // surface a distinct, accurate cause instead of the generic codes below.
+        if (droppedUnconfirmedAnyAttempt) {
+            this.log('findCoordinator:no-network-coordinator key=%s prefix=%s self=%s', keyStr, this.protocolPrefix ?? '?', self.toString().substring(0, 12));
+            throw new FindCoordinatorError(FIND_COORDINATOR_ERROR_CODES.NO_NETWORK_COORDINATOR, `No coordinator available for key on network ${this.protocolPrefix ?? '?'}: ` +
+                `the remaining candidate peer(s) are foreign or not-yet-confirmed to serve this network's cluster/repo protocol.`);
+        }
         // Self is excluded. On a solo/bootstrap node (HWM<=1 and no other connected/FRET peers),
         // this means the caller already tried self and the retry has nowhere to go — surface a
         // distinct error so retry logic stops and the original first-attempt cause is preserved.
@@ -380,7 +457,7 @@ export class Libp2pKeyPeerNetwork {
                 out.push(a);
             }
             catch (err) {
-                console.warn('invalid multiaddr from connection', a, err);
+                this.log('WARN: invalid multiaddr from connection %s %o', a, err);
             }
         }
         return out;
@@ -389,19 +466,84 @@ export class Libp2pKeyPeerNetwork {
         const t0 = Date.now();
         const fret = this.getFret();
         const coord = await hashKey(key);
-        const cohort = fret.assembleCohort(coord, this.clusterSize);
+        // When membership scoping is active, over-fetch a wider proximity band so the
+        // nearest peers that SERVE this network are in the candidate pool even if cross-
+        // network peers sit nearer the key (see membershipOverfetch).
+        const wants = this.protocolPrefix != null ? this.membershipOverfetch() : this.clusterSize;
+        const cohort = fret.assembleCohort(coord, wants);
         const keyStr = this.toCacheKey(key).substring(0, 12);
         this.log('findCluster:start key=%s', keyStr);
         // Include self in the cohort
         const selfId = this.libp2p.peerId.toString();
-        const ids = Array.from(new Set([...cohort, selfId]));
+        let ids = Array.from(new Set([...cohort, selfId]));
+        // Network-membership scoping (no-op when protocolPrefix is unset): a cohort
+        // member that serves a DIFFERENT network's protocol can never negotiate THIS
+        // network's cluster/repo dial, so it guarantees a super-majority failure rather
+        // than contributing a promise. Drop such 'foreign' members; build the cohort from
+        // positively-'serves' members only and NEVER admit a not-yet-identified ('unknown')
+        // member. A permanently cross-network peer and a freshly-discovered same-network
+        // peer mid-identify are indistinguishable while 'unknown' (both have an empty
+        // peerStore protocol list), so admitting an 'unknown' on the strength of a viability
+        // floor risks pulling a cross-network contaminant into the cohort — its repo dial
+        // then negotiates a different network's protocol and the whole write fails. A fresh
+        // same-network peer is not starved: it flips to 'serves' once identify completes and
+        // is re-included on the caller's retry, and in the meantime a self-only cohort still
+        // completes the write under allowClusterDownsize (the default).
+        // Scoped path only: one peerStore read per cohort member yields both protocols
+        // (for membership classification here) and addresses (reused at backfill below),
+        // so a finally-selected member isn't fetched from the peerStore twice. Left
+        // undefined on the unscoped path, which never classifies membership.
+        let peerStoreRecords;
+        if (this.protocolPrefix != null) {
+            // `cohort` is the over-fetched nearest-first band. Classify each non-self
+            // member, preserving proximity order within each tier.
+            const nonSelf = cohort.filter(id => id !== selfId);
+            peerStoreRecords = await this.getPeerStoreRecordsByPeer(nonSelf);
+            const serves = [];
+            const unknown = [];
+            let foreignDropped = 0;
+            for (const id of nonSelf) {
+                const m = this.membershipOf(id, peerStoreRecords[id]?.protocols);
+                if (m === 'serves')
+                    serves.push(id);
+                else if (m === 'unknown')
+                    unknown.push(id);
+                else
+                    foreignDropped++;
+            }
+            // Take the nearest `clusterSize - 1` SERVING peers. Self is ALWAYS added below and
+            // counts toward `clusterSize` (matching the unscoped path, where `assembleCohort`
+            // returns the nearest `clusterSize` peers INCLUDING self when self is near the key —
+            // the coordinator case), so reserving a slot for self keeps a healthy same-network
+            // cohort at exactly `clusterSize` members rather than `clusterSize + 1`. Over-sizing
+            // would inflate the super-majority promise count (ceil(peerCount * threshold)) above
+            // what the configured `clusterSize` intends and hurt write availability. 'unknown'
+            // members are never backfilled: an 'unknown' peer may be a permanently cross-network
+            // contaminant whose repo dial cannot negotiate this network's protocol, and a fresh
+            // same-network peer mid-identify is indistinguishable from it. We therefore admit
+            // only positively-'serves' peers; when self is the sole serving member the cohort is
+            // self-only, which completes the write under allowClusterDownsize (the default) and
+            // re-includes any legitimate peer as 'serves' on the caller's retry once identify
+            // completes. `unknown.length` is still computed above for the diagnostic log line.
+            const nonSelfTarget = Math.max(0, this.clusterSize - 1);
+            const others = serves.slice(0, nonSelfTarget);
+            ids = Array.from(new Set([selfId, ...others]));
+            this.log('findCluster:membership key=%s serves=%d unknown=%d foreignDropped=%d kept=%d', keyStr, serves.length, unknown.length, foreignDropped, ids.length);
+        }
         const connectedByPeer = this.getConnectedAddrsByPeer();
         const connectedPeerIds = Object.keys(connectedByPeer);
         // Backfill addresses from the peerStore for cohort members we don't have
         // a live connection to. The cohort is keyspace-determined and can include
         // peers we know-of but haven't dialed yet; without this backfill those
-        // would be silently dropped.
-        const peerStoreAddrs = await this.getPeerStoreAddrsByPeer(ids.filter(id => id !== selfId));
+        // would be silently dropped. On the scoped path reuse the addresses already
+        // read into `peerStoreRecords` above (no second store.get per member); on the
+        // unscoped path (no record map) do the single peerStore read as before.
+        const backfillIds = ids.filter(id => id !== selfId);
+        const peerStoreAddrs = peerStoreRecords
+            ? Object.fromEntries(backfillIds
+                .map(id => [id, peerStoreRecords[id]?.addrs ?? []])
+                .filter(([, addrs]) => addrs.length > 0))
+            : await this.getPeerStoreAddrsByPeer(backfillIds);
         this.log('findCluster key=%s fretCohort=%d connected=%d', keyStr, cohort.length, connectedPeerIds.length);
         if (verbose)
             this.log('findCluster:detail key=%s cohortPeers=%o connectedPeers=%o', keyStr, ids, connectedPeerIds);
@@ -458,5 +600,118 @@ export class Libp2pKeyPeerNetwork {
         }));
         return out;
     }
+    /**
+     * Single-pass peerStore read returning BOTH protocols and addresses per peer from one
+     * `store.get` call. Used on the membership-scoped `findCluster` hot path, where the
+     * cohort needs protocols (to classify membership) AND addresses (to backfill dial
+     * targets) for the same peers — reading them together avoids a second `store.get` per
+     * finally-selected member. Same error handling as {@link getPeerStoreProtocolsByPeer}
+     * and {@link getPeerStoreAddrsByPeer}: a missing peer or peerStore failure is left
+     * absent from the map (caller treats absent protocols as 'unknown', absent addrs as none).
+     */
+    async getPeerStoreRecordsByPeer(ids) {
+        const out = {};
+        const store = this.libp2p.peerStore;
+        if (!store?.get)
+            return out;
+        await Promise.all(ids.map(async (idStr) => {
+            try {
+                const pid = peerIdFromString(idStr);
+                const peer = await store.get(pid);
+                const addrs = (peer?.addresses ?? []).map(a => a.multiaddr.toString());
+                out[idStr] = { protocols: peer?.protocols ?? [], addrs };
+            }
+            catch {
+                // Unknown peer or peerStore failure — leave out of the map.
+            }
+        }));
+        return out;
+    }
+    /**
+     * Prefetch each peer's advertised protocol list from the libp2p peerStore.
+     * Returns a map from peer-id string to its protocols (empty array when the peer
+     * is absent or has not yet been identified). Mirrors {@link getPeerStoreAddrsByPeer};
+     * errors are swallowed so a peerStore hiccup degrades to "unknown" rather than throwing.
+     */
+    async getPeerStoreProtocolsByPeer(ids) {
+        const out = {};
+        const store = this.libp2p.peerStore;
+        if (!store?.get)
+            return out;
+        await Promise.all(ids.map(async (idStr) => {
+            try {
+                const pid = peerIdFromString(idStr);
+                const peer = await store.get(pid);
+                out[idStr] = peer?.protocols ?? [];
+            }
+            catch {
+                // Unknown peer or peerStore failure — leave out (treated as 'unknown').
+            }
+        }));
+        return out;
+    }
+    /**
+     * Over-fetch width for network-membership scoping. A cross-network peer can sit
+     * NEARER the key than a legitimate same-network peer and displace it from the
+     * nearest-`clusterSize` window, so when scoping is active we ask FRET for a wider
+     * proximity band and then keep the nearest peers that actually serve this network.
+     * (A ring polluted by more cross-network peers than this band is the domain of the
+     * separate FRET-side eviction follow-up; this band covers realistic co-location.)
+     */
+    membershipOverfetch() {
+        return Math.max(this.clusterSize * 4, this.clusterSize + 16);
+    }
+    /**
+     * Classify a peer's network membership from its advertised protocols. Self always
+     * `serves` (it trivially serves its own network). When no `protocolPrefix` is
+     * configured the filter is disabled and EVERY peer is reported `serves`, so all
+     * callers behave exactly as before this scoping was added.
+     */
+    membershipOf(idStr, protocols) {
+        if (this.protocolPrefix == null)
+            return 'serves';
+        if (idStr === this.libp2p.peerId.toString())
+            return 'serves';
+        if (protocols == null || protocols.length === 0)
+            return 'unknown';
+        if (protocols.includes(`${this.protocolPrefix}/cluster/1.0.0`)
+            || protocols.includes(`${this.protocolPrefix}/repo/1.0.0`))
+            return 'serves';
+        return 'foreign';
+    }
+    /**
+     * Scope a reputation-ordered candidate id list to this network for COORDINATOR
+     * selection: keep ONLY peers confirmed to serve this network (`serves`, which always
+     * includes self), dropping both `foreign` peers (serving another network) and
+     * `unknown` peers (peerStore protocol list empty — not yet confirmed). Incoming
+     * (reputation) order is preserved among the surviving `serves` peers. A no-op
+     * (returns the input unchanged, no drops) when `protocolPrefix` is unset or the list
+     * is empty — the membership-disabled path is therefore untouched.
+     *
+     * `droppedUnconfirmed` reports whether any candidate was excluded because it was not
+     * confirmed to serve this network — `foreign` OR `unknown` under scoping — so the
+     * caller can surface a distinct "no network coordinator" failure rather than a generic
+     * one. An `unknown` peer is not gambled on as coordinator: a permanent cross-network
+     * contaminant and a fresh same-network peer mid-identify are indistinguishable at an
+     * instant, but the filter re-reads the peerStore on every retry attempt, so a genuine
+     * same-network peer that completes `identify` within the retry window flips to `serves`
+     * and is selected normally on that attempt.
+     */
+    async filterByMembership(ids) {
+        if (this.protocolPrefix == null || ids.length === 0)
+            return { ranked: ids, droppedUnconfirmed: false };
+        const selfStr = this.libp2p.peerId.toString();
+        const protocolsByPeer = await this.getPeerStoreProtocolsByPeer(ids.filter(id => id !== selfStr));
+        const serves = [];
+        let droppedUnconfirmed = false;
+        for (const id of ids) {
+            const m = this.membershipOf(id, protocolsByPeer[id]);
+            if (m === 'serves')
+                serves.push(id);
+            else
+                droppedUnconfirmed = true;
+        }
+        return { ranked: serves, droppedUnconfirmed };
+    }
 }
 //# sourceMappingURL=libp2p-key-network.js.map