p2p-fret 0.3.0 → 0.4.0

package/dist/src/index.d.ts

@@ -45,11 +45,40 @@ export interface NearAnchorV1 {
     estimated_cluster_size: number;
     confidence: number;
 }
+export interface BusyResponseV1 {
+    v: 1;
+    busy: true;
+    retry_after_ms: number;
+}
 export interface ReportEvent {
     peerId: string;
     type: 'good' | 'bad';
     reason?: string;
 }
+/** Callback for performing an activity (pend/commit) when in-cluster. */
+export type ActivityHandler = (activity: string, cohort: string[], minSigs: number, correlationId: string) => Promise<{
+    commitCertificate: string;
+}>;
+/** Progressive result events emitted by iterative lookup. */
+export interface RouteProgress {
+    type: 'probing' | 'forwarding' | 'near_anchor' | 'activity_sent' | 'complete' | 'exhausted';
+    hop?: number;
+    peerId?: string;
+    nearAnchor?: NearAnchorV1;
+    result?: {
+        commitCertificate: string;
+    };
+    ttlRemaining?: number;
+}
+/** Options for initiating an iterative lookup. */
+export interface LookupOptions {
+    wantK: number;
+    minSigs: number;
+    activity?: string;
+    digest?: string;
+    ttl?: number;
+    maxAttempts?: number;
+}
 export interface FretService {
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -77,12 +106,18 @@ export interface FretService {
     };
     getNetworkChurn(): number;
     detectPartition(): boolean;
+    setActivityHandler(handler: ActivityHandler): void;
+    iterativeLookup(key: Uint8Array, options: LookupOptions): AsyncGenerator<RouteProgress>;
     exportTable(): SerializedTable;
     importTable(table: SerializedTable): number;
 }
 export type { SerializedPeerEntry, SerializedTable };
 export { FretService as FretServiceImpl } from './service/fret-service.js';
 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 { shouldIncludePayload, computeNearRadius } from './service/payload-heuristic.js';
+export { DedupCache } from './service/dedup-cache.js';
+export { validateTimestamp, readAllBounded } from './rpc/protocols.js';
 export declare function createFret(node: any, cfg?: Partial<FretConfig>): FretService;

package/dist/src/index.js

@@ -1,8 +1,12 @@
 export { FretService as FretServiceImpl } from './service/fret-service.js';
 import { FretService as FretServiceClass } from './service/fret-service.js';
 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 { shouldIncludePayload, computeNearRadius } from './service/payload-heuristic.js';
+export { DedupCache } from './service/dedup-cache.js';
+export { validateTimestamp, readAllBounded } from './rpc/protocols.js';
 export function createFret(node, cfg) {
     return new FretServiceClass(node, cfg);
 }

package/dist/src/rpc/leave.js

@@ -1,12 +1,27 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_LEAVE, encodeJson, decodeJson } from './protocols.js';
+import { PROTOCOL_LEAVE, encodeJson, decodeJson, readAllBounded } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:leave');
+const MAX_REPLACEMENTS = 12;
+function sanitizeReplacements(ids) {
+    if (!ids || ids.length === 0)
+        return undefined;
+    const valid = [];
+    for (const id of ids.slice(0, MAX_REPLACEMENTS)) {
+        try {
+            peerIdFromString(id);
+            valid.push(id);
+        }
+        catch { /* drop unparseable */ }
+    }
+    return valid.length > 0 ? valid : undefined;
+}
 export function registerLeave(node, onLeave, protocol = PROTOCOL_LEAVE) {
     void node.handle(protocol, async (stream) => {
         try {
-            const bytes = await readAll(stream);
+            const bytes = await readAllBounded(stream, 4096);
             const msg = await decodeJson(bytes);
+            msg.replacements = sanitizeReplacements(msg.replacements);
             await onLeave(msg);
             stream.send(await encodeJson({ ok: true }));
             await stream.close();
@@ -39,23 +54,3 @@ export async function sendLeave(node, peerIdStr, notice, protocol = PROTOCOL_LEA
         }
     }
 }
-function toBytes(chunk) {
-    if (chunk instanceof Uint8Array)
-        return chunk;
-    return chunk.subarray();
-}
-async function readAll(stream) {
-    const parts = [];
-    for await (const chunk of stream)
-        parts.push(toBytes(chunk));
-    let len = 0;
-    for (const p of parts)
-        len += p.length;
-    const out = new Uint8Array(len);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}

package/dist/src/rpc/maybe-act.d.ts

@@ -1,8 +1,8 @@
 import type { Libp2p } from 'libp2p';
-import type { RouteAndMaybeActV1, NearAnchorV1 } from '../index.js';
-export declare function registerMaybeAct(node: Libp2p, handle: (msg: RouteAndMaybeActV1) => Promise<NearAnchorV1 | {
+import type { RouteAndMaybeActV1, NearAnchorV1, BusyResponseV1 } from '../index.js';
+export declare function registerMaybeAct(node: Libp2p, handle: (msg: RouteAndMaybeActV1) => Promise<NearAnchorV1 | BusyResponseV1 | {
     commitCertificate: string;
-}>, protocol?: string): void;
-export declare function sendMaybeAct(node: Libp2p, peerIdStr: string, msg: RouteAndMaybeActV1, protocol?: string): Promise<NearAnchorV1 | {
+}>, protocol?: string, maxBytes?: number): void;
+export declare function sendMaybeAct(node: Libp2p, peerIdStr: string, msg: RouteAndMaybeActV1, protocol?: string): Promise<NearAnchorV1 | BusyResponseV1 | {
     commitCertificate: string;
 }>;

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

@@ -1,11 +1,11 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_MAYBE_ACT, encodeJson, decodeJson } from './protocols.js';
+import { PROTOCOL_MAYBE_ACT, encodeJson, decodeJson, readAllBounded } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:maybeAct');
-export function registerMaybeAct(node, handle, protocol = PROTOCOL_MAYBE_ACT) {
+export function registerMaybeAct(node, handle, protocol = PROTOCOL_MAYBE_ACT, maxBytes = 512 * 1024) {
     void node.handle(protocol, async (stream) => {
         try {
-            const bytes = await readAll(stream);
+            const bytes = await readAllBounded(stream, maxBytes);
             const msg = await decodeJson(bytes);
             const res = await handle(msg);
             stream.send(await encodeJson(res));
@@ -29,7 +29,7 @@ export async function sendMaybeAct(node, peerIdStr, msg, protocol = PROTOCOL_MAY
         }
         stream.send(await encodeJson(msg));
         await stream.close();
-        const bytes = await readAll(stream);
+        const bytes = await readAllBounded(stream, 512 * 1024);
         return await decodeJson(bytes);
     }
     finally {
@@ -41,23 +41,3 @@ export async function sendMaybeAct(node, peerIdStr, msg, protocol = PROTOCOL_MAY
         }
     }
 }
-function toBytes(chunk) {
-    if (chunk instanceof Uint8Array)
-        return chunk;
-    return chunk.subarray();
-}
-async function readAll(stream) {
-    const parts = [];
-    for await (const chunk of stream)
-        parts.push(toBytes(chunk));
-    let len = 0;
-    for (const p of parts)
-        len += p.length;
-    const out = new Uint8Array(len);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}

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

@@ -1,8 +1,8 @@
 import type { Libp2p } from 'libp2p';
-import type { NeighborSnapshotV1 } from '../index.js';
-export declare function registerNeighbors(node: Libp2p, getSnapshot: () => NeighborSnapshotV1 | Promise<NeighborSnapshotV1>, onAnnounce?: (from: string, snapshot: NeighborSnapshotV1) => void, protocols?: {
+import type { NeighborSnapshotV1, BusyResponseV1 } from '../index.js';
+export declare function registerNeighbors(node: Libp2p, getSnapshot: () => NeighborSnapshotV1 | BusyResponseV1 | Promise<NeighborSnapshotV1 | BusyResponseV1>, onAnnounce?: (from: string, snapshot: NeighborSnapshotV1) => void, protocols?: {
     PROTOCOL_NEIGHBORS: string;
     PROTOCOL_NEIGHBORS_ANNOUNCE: string;
-}): void;
+}, maxBytes?: number): void;
 export declare function fetchNeighbors(node: Libp2p, peerIdOrStr: string, protocol?: string): Promise<NeighborSnapshotV1>;
 export declare function announceNeighbors(node: Libp2p, peerIdOrStr: string, snapshot: NeighborSnapshotV1, protocol?: string): Promise<void>;

package/dist/src/rpc/neighbors.js

@@ -1,8 +1,8 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE, encodeJson, decodeJson, } from './protocols.js';
+import { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE, encodeJson, decodeJson, readAllBounded, } 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 }) {
+export function registerNeighbors(node, getSnapshot, onAnnounce, protocols = { PROTOCOL_NEIGHBORS, PROTOCOL_NEIGHBORS_ANNOUNCE }, maxBytes = 128 * 1024) {
     void node.handle(protocols.PROTOCOL_NEIGHBORS, async (stream) => {
         try {
             const snap = await getSnapshot();
@@ -13,11 +13,10 @@ export function registerNeighbors(node, getSnapshot, onAnnounce, protocols = { P
             log.error('neighbors handler error - %e', err);
         }
     });
-    // Optional: accept pushed announcements of neighbor snapshots
     if (onAnnounce) {
         void node.handle(protocols.PROTOCOL_NEIGHBORS_ANNOUNCE, async (stream) => {
             try {
-                const bytes = await readAll(stream);
+                const bytes = await readAllBounded(stream, maxBytes);
                 const snap = await decodeJson(bytes);
                 onAnnounce(snap.from, snap);
                 stream.send(await encodeJson({ ok: true }));
@@ -39,8 +38,12 @@ export async function fetchNeighbors(node, peerIdOrStr, protocol = PROTOCOL_NEIG
     let stream;
     try {
         stream = await conns[0].newStream([protocol]);
-        const bytes = await readAll(stream);
-        return await decodeJson(bytes);
+        const bytes = await readAllBounded(stream, 128 * 1024);
+        const res = await decodeJson(bytes);
+        if ('busy' in res && res.busy) {
+            return { v: 1, from: peerIdOrStr, timestamp: Date.now(), successors: [], predecessors: [], sig: '' };
+        }
+        return res;
     }
     catch (err) {
         log.error('fetchNeighbors decode failed for %s - %e', peerIdOrStr, err);
@@ -79,23 +82,3 @@ export async function announceNeighbors(node, peerIdOrStr, snapshot, protocol =
         }
     }
 }
-function toBytes(chunk) {
-    if (chunk instanceof Uint8Array)
-        return chunk;
-    return chunk.subarray();
-}
-async function readAll(stream) {
-    const parts = [];
-    for await (const chunk of stream)
-        parts.push(toBytes(chunk));
-    let len = 0;
-    for (const p of parts)
-        len += p.length;
-    const out = new Uint8Array(len);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}

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

@@ -1,4 +1,5 @@
 import type { Libp2p } from 'libp2p';
+import type { BusyResponseV1 } from '../index.js';
 export interface PingResponseV1 {
     ok: boolean;
     ts: number;
@@ -8,10 +9,10 @@ export interface PingResponseV1 {
 export type SizeEstimateProvider = () => {
     size_estimate?: number;
     confidence?: number;
-} | Promise<{
+} | BusyResponseV1 | Promise<{
     size_estimate?: number;
     confidence?: number;
-}>;
+} | BusyResponseV1>;
 export declare function registerPing(node: Libp2p, protocol?: string, getSizeEstimate?: SizeEstimateProvider): void;
 export declare function sendPing(node: Libp2p, peer: string, protocol?: string): Promise<{
     ok: boolean;

package/dist/src/rpc/ping.js

@@ -1,24 +1,34 @@
 import { peerIdFromString } from '@libp2p/peer-id';
-import { PROTOCOL_PING, encodeJson, decodeJson } from './protocols.js';
+import { PROTOCOL_PING, encodeJson, decodeJson, readAllBounded } from './protocols.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('rpc:ping');
+function isBusy(res) {
+    return typeof res === 'object' && res !== null && 'busy' in res && res.busy === true;
+}
 export function registerPing(node, protocol = PROTOCOL_PING, getSizeEstimate) {
     void node.handle(protocol, async (stream) => {
-        const response = { ok: true, ts: Date.now() };
-        // Add network size hint if provider available
         if (getSizeEstimate) {
             try {
                 const sizeInfo = await getSizeEstimate();
+                if (isBusy(sizeInfo)) {
+                    stream.send(await encodeJson(sizeInfo));
+                    await stream.close();
+                    return;
+                }
+                const response = { ok: true, ts: Date.now() };
                 if (sizeInfo.size_estimate !== undefined) {
                     response.size_estimate = sizeInfo.size_estimate;
                     response.confidence = sizeInfo.confidence;
                 }
+                stream.send(await encodeJson(response));
+                await stream.close();
+                return;
             }
             catch (err) {
                 log.error('getSizeEstimate failed - %e', err);
             }
         }
-        stream.send(await encodeJson(response));
+        stream.send(await encodeJson({ ok: true, ts: Date.now() }));
         await stream.close();
     });
 }
@@ -34,12 +44,14 @@ export async function sendPing(node, peer, protocol = PROTOCOL_PING) {
         else {
             stream = await node.dialProtocol(pid, [protocol]);
         }
-        const bytes = await readAll(stream);
+        const bytes = await readAllBounded(stream, 1024);
         const rttMs = Math.max(0, Date.now() - start);
         if (bytes.length === 0)
             return { ok: false, rttMs };
         try {
             const res = await decodeJson(bytes);
+            if (isBusy(res))
+                return { ok: false, rttMs };
             return {
                 ok: Boolean(res.ok),
                 rttMs,
@@ -61,23 +73,3 @@ export async function sendPing(node, peer, protocol = PROTOCOL_PING) {
         }
     }
 }
-function toBytes(chunk) {
-    if (chunk instanceof Uint8Array)
-        return chunk;
-    return chunk.subarray();
-}
-async function readAll(stream) {
-    const parts = [];
-    for await (const chunk of stream)
-        parts.push(toBytes(chunk));
-    let len = 0;
-    for (const p of parts)
-        len += p.length;
-    const out = new Uint8Array(len);
-    let o = 0;
-    for (const p of parts) {
-        out.set(p, o);
-        o += p.length;
-    }
-    return out;
-}

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

@@ -12,3 +12,10 @@ export declare const PROTOCOL_LEAVE = "/optimystic/default/fret/1.0.0/leave";
 export declare const PROTOCOL_PING = "/optimystic/default/fret/1.0.0/ping";
 export declare function encodeJson(obj: unknown): Promise<Uint8Array>;
 export declare function decodeJson<T = unknown>(bytes: Uint8Array): Promise<T>;
+export declare function toBytes(chunk: Uint8Array | {
+    subarray(): Uint8Array;
+}): Uint8Array;
+export declare function readAllBounded(stream: AsyncIterable<Uint8Array | {
+    subarray(): Uint8Array;
+}>, maxBytes: number, timeoutMs?: number): Promise<Uint8Array>;
+export declare function validateTimestamp(ts: number, maxDriftMs?: number): boolean;

package/dist/src/rpc/protocols.js

@@ -34,3 +34,48 @@ export async function decodeJson(bytes) {
     const text = new TextDecoder().decode(bytes.subarray(start, end));
     return JSON.parse(text);
 }
+export function toBytes(chunk) {
+    if (chunk instanceof Uint8Array)
+        return chunk;
+    return chunk.subarray();
+}
+export async function readAllBounded(stream, maxBytes, timeoutMs = 5000) {
+    const parts = [];
+    let len = 0;
+    const iter = stream[Symbol.asyncIterator]();
+    const deadline = Date.now() + timeoutMs;
+    // Short idle timeout after first data arrives — works around muxer
+    // implementations that fail to propagate remote-close EOF.
+    const idleMs = 100;
+    while (true) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            break;
+        const chunkTimeout = len > 0 ? Math.min(remaining, idleMs) : remaining;
+        let timer;
+        const timeout = new Promise(r => {
+            timer = setTimeout(() => r({ done: true, value: undefined }), chunkTimeout);
+        });
+        const next = iter.next();
+        next.catch(() => { }); // Prevent unhandled rejection if timeout wins
+        const result = await Promise.race([next, timeout]);
+        clearTimeout(timer);
+        if (result.done)
+            break;
+        const bytes = toBytes(result.value);
+        len += bytes.length;
+        if (len > maxBytes)
+            throw new Error(`payload too large: ${len} exceeds ${maxBytes} byte limit`);
+        parts.push(bytes);
+    }
+    const out = new Uint8Array(len);
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+}
+export function validateTimestamp(ts, maxDriftMs = 300_000) {
+    return Math.abs(Date.now() - ts) <= maxDriftMs;
+}

package/dist/src/selector/next-hop.d.ts

@@ -1,4 +1,24 @@
 import type { DigitreeStore } from '../store/digitree-store.js';
 export type LinkQuality = (id: string) => number;
 export type IsConnected = (id: string) => boolean;
-export declare function chooseNextHop(store: DigitreeStore, targetCoord: Uint8Array, candidates: string[], isConnected: IsConnected, linkQ: LinkQuality, connectedToleranceBytes?: number): string | undefined;
+export type BackoffPenalty = (id: string) => number;
+export interface NextHopOptions {
+    /** Near-radius threshold; distances ≤ this trigger strict mode. */
+    nearRadius?: Uint8Array;
+    /** Confidence in network size estimate [0,1]; adjusts weight balance. */
+    confidence?: number;
+    /** Per-peer backoff penalty [0,1]; penalizes recently-failed peers. */
+    backoffPenalty?: BackoffPenalty;
+    /**
+     * Legacy tolerance: connected peers within this many leading-zero-byte
+     * difference are preferred (default 1).  Ignored when nearRadius is set.
+     */
+    connectedToleranceBytes?: number;
+}
+/**
+ * Select the best next hop from candidates.
+ *
+ * Backwards compatible: when called without options (or with just
+ * connectedToleranceBytes), falls back to the original leading-byte heuristic.
+ */
+export declare function chooseNextHop(store: DigitreeStore, targetCoord: Uint8Array, candidates: string[], isConnected: IsConnected, linkQ: LinkQuality, optionsOrTolerance?: NextHopOptions | number): string | undefined;

package/dist/src/selector/next-hop.js

@@ -18,11 +18,115 @@ function betterByDist(idA, distA, idB, distB) {
         return true;
     if (lexLess(distB, distA))
         return false;
-    // equal distance: tie-break by peer id lex order
     return idA < idB;
 }
-export function chooseNextHop(store, targetCoord, candidates, isConnected, linkQ, connectedToleranceBytes = 1 // connected peers within this many leading bytes are preferred
-) {
+function isNear(dist, nearRadius) {
+    return !lexLess(nearRadius, dist); // dist <= nearRadius
+}
+function weightsForContext(near, confidence) {
+    // Base weights (far)
+    let wD = 0.4;
+    let wConn = 0.4;
+    const wQ = 0.1;
+    const wB = 0.1;
+    if (near) {
+        // Strict distance when close to target
+        wD = 0.7;
+        wConn = 0.1;
+    }
+    // Confidence adjustment: low confidence → rely on connections, not distance
+    const cAdj = (confidence - 0.5) * 0.2; // range [-0.1, 0.1]
+    wD = Math.max(0.1, wD + cAdj);
+    wConn = Math.max(0.05, wConn - cAdj);
+    return { wD, wConn, wQ, wB };
+}
+function normalizeDistance(dist) {
+    // Count leading zero bits for fine-grained log-distance [0,1]
+    // 0 = identical (distance zero), 1 = maximally far
+    let lzBits = 0;
+    for (let i = 0; i < dist.length; i++) {
+        const v = dist[i];
+        if (v === 0) {
+            lzBits += 8;
+            continue;
+        }
+        lzBits += Math.clz32(v) - 24; // clz32 counts for 32-bit; subtract 24 for byte
+        break;
+    }
+    const totalBits = dist.length * 8;
+    if (lzBits >= totalBits)
+        return 0;
+    return Math.max(0, Math.min(1, 1 - lzBits / totalBits));
+}
+function cost(normDist, connected, linkQ, backoff, w) {
+    return (w.wD * normDist
+        - w.wConn * (connected ? 1 : 0)
+        - w.wQ * linkQ
+        + w.wB * backoff);
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Select the best next hop from candidates.
+ *
+ * Backwards compatible: when called without options (or with just
+ * connectedToleranceBytes), falls back to the original leading-byte heuristic.
+ */
+export function chooseNextHop(store, targetCoord, candidates, isConnected, linkQ, optionsOrTolerance) {
+    const opts = typeof optionsOrTolerance === 'number'
+        ? { connectedToleranceBytes: optionsOrTolerance }
+        : optionsOrTolerance ?? {};
+    // If nearRadius is provided, use cost-function path
+    if (opts.nearRadius) {
+        return chooseNextHopCost(store, targetCoord, candidates, isConnected, linkQ, opts);
+    }
+    // Legacy connected-first heuristic (tolerance-bytes based)
+    return chooseNextHopLegacy(store, targetCoord, candidates, isConnected, linkQ, opts.connectedToleranceBytes ?? 1);
+}
+function chooseNextHopCost(store, targetCoord, candidates, isConnected, linkQ, opts) {
+    const confidence = opts.confidence ?? 0.5;
+    const backoff = opts.backoffPenalty ?? (() => 0);
+    const nearRadius = opts.nearRadius;
+    const scored = [];
+    for (const id of candidates) {
+        const entry = store.getById(id);
+        if (!entry)
+            continue;
+        const dist = xorDistance(entry.coord, targetCoord);
+        const near = isNear(dist, nearRadius);
+        const connected = isConnected(id);
+        const w = weightsForContext(near, confidence);
+        const costVal = cost(normalizeDistance(dist), connected, linkQ(id), backoff(id), w);
+        scored.push({ id, dist, near, connected, costVal });
+    }
+    if (scored.length === 0)
+        return undefined;
+    // Partition: near-mode candidates use strict distance ordering;
+    // far-mode candidates use cost function.
+    const nearCandidates = scored.filter(s => s.near);
+    const farCandidates = scored.filter(s => !s.near);
+    // Near mode: strict distance improvement (ε ≈ 0); connection only breaks ties
+    if (nearCandidates.length > 0) {
+        nearCandidates.sort((a, b) => {
+            if (betterByDist(a.id, a.dist, b.id, b.dist))
+                return -1;
+            if (betterByDist(b.id, b.dist, a.id, a.dist))
+                return 1;
+            // Equal distance: prefer connected, then lower cost
+            if (a.connected !== b.connected)
+                return a.connected ? -1 : 1;
+            return a.costVal - b.costVal;
+        });
+        return nearCandidates[0].id;
+    }
+    // Far mode: use cost function
+    farCandidates.sort((a, b) => {
+        if (a.costVal !== b.costVal)
+            return a.costVal - b.costVal;
+        return betterByDist(a.id, a.dist, b.id, b.dist) ? -1 : 1;
+    });
+    return farCandidates[0].id;
+}
+function chooseNextHopLegacy(store, targetCoord, candidates, isConnected, linkQ, connectedToleranceBytes) {
     let bestByDist;
     const scored = [];
     for (const id of candidates) {
@@ -49,7 +153,6 @@ export function chooseNextHop(store, targetCoord, candidates, isConnected, linkQ
                 bestConnected = { id: s.id, dist: s.dist, score: s.score };
                 continue;
             }
-            // Prefer strictly better distance; tie-break by higher score; then by id
             if (betterByDist(s.id, s.dist, bestConnected.id, bestConnected.dist)) {
                 bestConnected = { id: s.id, dist: s.dist, score: s.score };
             }

package/dist/src/service/dedup-cache.d.ts

@@ -0,0 +1,12 @@
+/** Bounded TTL cache for correlation-ID deduplication. */
+export declare class DedupCache<T> {
+    private readonly entries;
+    private readonly ttlMs;
+    private readonly maxSize;
+    constructor(ttlMs?: number, maxSize?: number);
+    get(key: string): T | undefined;
+    has(key: string): boolean;
+    set(key: string, result: T): void;
+    private evictExpired;
+    private evictOldest;
+}

package/dist/src/service/dedup-cache.js

@@ -0,0 +1,43 @@
+/** Bounded TTL cache for correlation-ID deduplication. */
+export class DedupCache {
+    entries = new Map();
+    ttlMs;
+    maxSize;
+    constructor(ttlMs = 30_000, maxSize = 1024) {
+        this.ttlMs = ttlMs;
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const e = this.entries.get(key);
+        if (!e)
+            return undefined;
+        if (e.expires < Date.now()) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        return e.result;
+    }
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    set(key, result) {
+        if (this.entries.size >= this.maxSize)
+            this.evictExpired();
+        if (this.entries.size >= this.maxSize)
+            this.evictOldest();
+        this.entries.set(key, { result, expires: Date.now() + this.ttlMs });
+    }
+    evictExpired() {
+        const now = Date.now();
+        for (const [k, v] of this.entries) {
+            if (v.expires < now)
+                this.entries.delete(k);
+        }
+    }
+    evictOldest() {
+        // Delete the first (oldest-inserted) entry
+        const first = this.entries.keys().next();
+        if (!first.done)
+            this.entries.delete(first.value);
+    }
+}