p2p-fret 0.4.0 → 0.5.0

package/dist/src/index.d.ts

@@ -117,6 +117,13 @@ export { seedDiscovery } from './service/discovery.js';
 export { FretPeerDiscovery, type FretPeerDiscoveryConfig } from './service/peer-discovery.js';
 export { Libp2pFretService, fretService } from './service/libp2p-fret-service.js';
 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 { estimateSizeAndConfidence } from './estimate/size-estimator.js';
+export type { SizeEstimate } from './estimate/size-estimator.js';
+export { assembleCohort } from './service/cohort.js';
 export { shouldIncludePayload, computeNearRadius } from './service/payload-heuristic.js';
 export { DedupCache } from './service/dedup-cache.js';
 export { validateTimestamp, readAllBounded } from './rpc/protocols.js';

package/dist/src/index.js

@@ -4,6 +4,10 @@ export { seedDiscovery } from './service/discovery.js';
 export { FretPeerDiscovery } from './service/peer-discovery.js';
 export { Libp2pFretService, fretService } from './service/libp2p-fret-service.js';
 export { hashKey, hashPeerId } from './ring/hash.js';
+export { xorDistance, clockwiseDistance, minDistance, lexLess } from './ring/distance.js';
+export { DigitreeStore } from './store/digitree-store.js';
+export { estimateSizeAndConfidence } from './estimate/size-estimator.js';
+export { assembleCohort } from './service/cohort.js';
 export { shouldIncludePayload, computeNearRadius } from './service/payload-heuristic.js';
 export { DedupCache } from './service/dedup-cache.js';
 export { validateTimestamp, readAllBounded } from './rpc/protocols.js';

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

@@ -0,0 +1,11 @@
+import type { DigitreeStore } 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
+ * `wants` peers exist (`n < k`) by returning whatever the ring holds.
+ *
+ * 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.
+ */
+export declare function assembleCohort(store: DigitreeStore, hashedCoord: Uint8Array, wants: number, exclude?: Set<string>): string[];

package/dist/src/service/cohort.js

@@ -0,0 +1,34 @@
+/**
+ * Two-sided cohort assembly: an alternating successor/predecessor walk outward from
+ * `hashedCoord`, returning up to `wants` distinct peer ids. Auto-adapts when fewer than
+ * `wants` peers exist (`n < k`) by returning whatever the ring holds.
+ *
+ * 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.
+ */
+export function assembleCohort(store, hashedCoord, wants, exclude) {
+    const out = [];
+    const ex = exclude ?? new Set();
+    const succIds = store.neighborsRight(hashedCoord, wants * 2);
+    const predIds = store.neighborsLeft(hashedCoord, wants * 2);
+    let si = 0, pi = 0;
+    while (out.length < wants && (si < succIds.length || pi < predIds.length)) {
+        if (out.length % 2 === 0 && si < succIds.length) {
+            const id = succIds[si++];
+            if (id && !ex.has(id))
+                out.push(id);
+        }
+        else if (pi < predIds.length) {
+            const id = predIds[pi++];
+            if (id && !ex.has(id))
+                out.push(id);
+        }
+        else if (si < succIds.length) {
+            const id = succIds[si++];
+            if (id && !ex.has(id))
+                out.push(id);
+        }
+    }
+    return Array.from(new Set(out)).slice(0, wants);
+}

package/dist/src/service/fret-service.js

@@ -14,6 +14,7 @@ import { chooseNextHop } from '../selector/next-hop.js';
 import { DedupCache } from './dedup-cache.js';
 import { shouldIncludePayload, computeNearRadius } from './payload-heuristic.js';
 import { xorDistance } from '../ring/distance.js';
+import { assembleCohort as assembleCohortOverStore } from './cohort.js';
 import { createSparsityModel, normalizedLogDistance, sparsityBonus, touch as scoreTouch, recordSuccess as scoreSuccess, recordFailure as scoreFailure, } from '../store/relevance.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('service:fret');
@@ -908,29 +909,7 @@ export class FretService {
         return arr[(idx - 1 + arr.length) % arr.length];
     }
     assembleCohort(hashedCoord, wants, exclude) {
-        const out = [];
-        const ex = exclude ?? new Set();
-        const succIds = this.store.neighborsRight(hashedCoord, wants * 2);
-        const predIds = this.store.neighborsLeft(hashedCoord, wants * 2);
-        let si = 0, pi = 0;
-        while (out.length < wants && (si < succIds.length || pi < predIds.length)) {
-            if (out.length % 2 === 0 && si < succIds.length) {
-                const id = succIds[si++];
-                if (id && !ex.has(id))
-                    out.push(id);
-            }
-            else if (pi < predIds.length) {
-                const id = predIds[pi++];
-                if (id && !ex.has(id))
-                    out.push(id);
-            }
-            else if (si < succIds.length) {
-                const id = succIds[si++];
-                if (id && !ex.has(id))
-                    out.push(id);
-            }
-        }
-        return Array.from(new Set(out)).slice(0, wants);
+        return assembleCohortOverStore(this.store, hashedCoord, wants, exclude);
     }
     expandCohort(current, hashedCoord, step, exclude) {
         const base = new Set(current);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "p2p-fret",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "FRET: Finger Ring Ensemble Topology (libp2p ring overlay with Digitree)",
   "main": "dist/src/index.js",
@@ -20,7 +20,7 @@
   "scripts": {
     "clean": "rimraf dist",
     "build": "tsc",
-    "test": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors"
+    "test": "node --import ./register.mjs node_modules/mocha/bin/mocha.js \"test/**/*.spec.ts\" --colors --exit"
   },
   "peerDependencies": {
     "@libp2p/interface": "^3.1.0",

package/src/index.ts

@@ -126,6 +126,13 @@ export { seedDiscovery } from './service/discovery.js';
 export { FretPeerDiscovery, type FretPeerDiscoveryConfig } from './service/peer-discovery.js';
 export { Libp2pFretService, fretService } from './service/libp2p-fret-service.js';
 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 { estimateSizeAndConfidence } from './estimate/size-estimator.js';
+export type { SizeEstimate } from './estimate/size-estimator.js';
+export { assembleCohort } from './service/cohort.js';
 export { shouldIncludePayload, computeNearRadius } from './service/payload-heuristic.js';
 export { DedupCache } from './service/dedup-cache.js';
 export { validateTimestamp, readAllBounded } from './rpc/protocols.js';

package/src/service/cohort.ts

@@ -0,0 +1,37 @@
+import type { DigitreeStore } 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
+ * `wants` peers exist (`n < k`) by returning whatever the ring holds.
+ *
+ * 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.
+ */
+export function assembleCohort(
+	store: DigitreeStore,
+	hashedCoord: Uint8Array,
+	wants: number,
+	exclude?: Set<string>
+): string[] {
+	const out: string[] = [];
+	const ex = exclude ?? new Set<string>();
+	const succIds = store.neighborsRight(hashedCoord, wants * 2);
+	const predIds = store.neighborsLeft(hashedCoord, wants * 2);
+	let si = 0,
+		pi = 0;
+	while (out.length < wants && (si < succIds.length || pi < predIds.length)) {
+		if (out.length % 2 === 0 && si < succIds.length) {
+			const id = succIds[si++];
+			if (id && !ex.has(id)) out.push(id);
+		} else if (pi < predIds.length) {
+			const id = predIds[pi++];
+			if (id && !ex.has(id)) out.push(id);
+		} else if (si < succIds.length) {
+			const id = succIds[si++];
+			if (id && !ex.has(id)) out.push(id);
+		}
+	}
+	return Array.from(new Set(out)).slice(0, wants);
+}

package/src/service/fret-service.ts

@@ -30,6 +30,7 @@ import { chooseNextHop, type NextHopOptions } from '../selector/next-hop.js';
 import { DedupCache } from './dedup-cache.js';
 import { shouldIncludePayload, computeNearRadius } from './payload-heuristic.js';
 import { xorDistance } from '../ring/distance.js';
+import { assembleCohort as assembleCohortOverStore } from './cohort.js';
 import {
     createSparsityModel,
     normalizedLogDistance,
@@ -881,25 +882,7 @@ export class FretService implements IFretService, Startable {
 	}
 
 	assembleCohort(hashedCoord: Uint8Array, wants: number, exclude?: Set<string>): string[] {
-		const out: string[] = [];
-		const ex = exclude ?? new Set<string>();
-		const succIds = this.store.neighborsRight(hashedCoord, wants * 2);
-		const predIds = this.store.neighborsLeft(hashedCoord, wants * 2);
-		let si = 0,
-			pi = 0;
-		while (out.length < wants && (si < succIds.length || pi < predIds.length)) {
-			if (out.length % 2 === 0 && si < succIds.length) {
-				const id = succIds[si++];
-				if (id && !ex.has(id)) out.push(id);
-			} else if (pi < predIds.length) {
-				const id = predIds[pi++];
-				if (id && !ex.has(id)) out.push(id);
-			} else if (si < succIds.length) {
-				const id = succIds[si++];
-				if (id && !ex.has(id)) out.push(id);
-			}
-		}
-		return Array.from(new Set(out)).slice(0, wants);
+		return assembleCohortOverStore(this.store, hashedCoord, wants, exclude);
 	}
 
 	expandCohort(