p2p-fret 0.6.0 → 1.0.0-beta.2

package/README.md

@@ -79,7 +79,7 @@ FRET detects potential partitions using multiple signals:
 
 ```typescript
 // FRET automatically includes size estimates in ping responses
-registerPing(node, PROTOCOL_PING, () => {
+await registerPing(node, PROTOCOL_PING, () => {
   return fretService.getNetworkSizeEstimate();
 });
 
@@ -104,7 +104,7 @@ interface FretService {
   exportTable(): SerializedTable;
 
   // Import a previously exported snapshot; returns number of entries loaded
-  importTable(table: SerializedTable): number;
+  importTable(table: SerializedTable): Promise<number>;
 }
 
 interface SerializedTable {
@@ -123,7 +123,7 @@ interface SerializedPeerEntry {
   accessCount: number;
   successCount: number;
   failureCount: number;
-  avgLatencyMs: number;
+  avgLatencyMs: number | null; // null = never measured (absent field reads back as null)
   metadata?: Record<string, any>;
 }
 ```
@@ -144,7 +144,7 @@ await fs.writeFile('fret-table.json', JSON.stringify(table));
 const saved: SerializedTable = JSON.parse(
   await fs.readFile('fret-table.json', 'utf-8')
 );
-const count = fret.importTable(saved);
+const count = await fret.importTable(saved);
 console.log(`Restored ${count} routing entries`);
 
 await fret.start();
@@ -153,7 +153,7 @@ await fret.start();
 ### Behavior
 
 - **State reset**: All imported entries get `state: 'disconnected'` regardless of their exported state — connection liveness must be re-established through pings and stabilization.
-- **Capacity enforcement**: `importTable` enforces the configured capacity after loading. A table exported from a node with a larger capacity won't exceed the importer's limit.
+- **Capacity enforcement**: `importTable` enforces the configured capacity after loading. A table exported from a node with a larger capacity won't exceed the importer's limit. `importTable` is `async` — enforcement needs the self ring coordinate, which is commonly not yet cached when import runs before `start()` — so always `await` it.
 - **Stale data safety**: After import, the normal stabilization loop probes peers to update connection states and relevance scores. Unreachable peers are decayed and eventually evicted.
 - **JSON round-trip safe**: `SerializedTable` survives `JSON.stringify` / `JSON.parse`.
 

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

@@ -3,10 +3,26 @@ export type SizeEstimate = {
     n: number;
     confidence: number;
 };
+export interface SizeEstimateOptions {
+    /** Restrict the estimate to a subset of the store (e.g. same-network members only). */
+    filter?: (e: PeerEntry) => boolean;
+    /**
+     * Ring coordinate of the local node. When supplied, gaps are drawn from the
+     * successor/predecessor window around it — the intended arc-length method. Omitting it
+     * selects the degraded whole-store fallback (see {@link estimateSizeAndConfidence}).
+     */
+    selfCoord?: Uint8Array;
+}
 /**
- * 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.
+ * Online network-size estimate from inter-peer ring gaps: `n = 2^256 / gap`.
+ *
+ * `options.selfCoord` selects the successor/predecessor window as the gap population and is the
+ * intended path; omitting it falls back to whole-store gaps (see {@link collectGaps}).
+ * `options.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` and the derived cluster span /
+ * near-radius. It defaults to counting every entry, leaving the standalone/simulator path
+ * unchanged.
+ *
+ * Confidence blends sample count against 2m with the dispersion factor above.
  */
-export declare function estimateSizeAndConfidence(store: DigitreeStore, m: number, filter?: (e: PeerEntry) => boolean): SizeEstimate;
+export declare function estimateSizeAndConfidence(store: DigitreeStore, m: number, options?: SizeEstimateOptions): SizeEstimate;

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

@@ -1,51 +1,160 @@
+const RING_SIZE = 1n << 256n;
+const HALF_RING = 1n << 255n;
 function bytesToBigInt(u8) {
     let v = 0n;
     for (let i = 0; i < u8.length; i++)
         v = (v << 8n) | BigInt(u8[i]);
     return v;
 }
+function ascending(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
 function medianBigInt(values) {
     if (values.length === 0)
         return 0n;
-    const arr = [...values].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const arr = [...values].sort(ascending);
     const mid = Math.floor(arr.length / 2);
     return arr.length % 2 === 0 ? (arr[mid - 1] + arr[mid]) / 2n : arr[mid];
 }
+function meanBigInt(values) {
+    if (values.length === 0)
+        return 0n;
+    let sum = 0n;
+    for (const v of values)
+        sum += v;
+    return sum / BigInt(values.length);
+}
+/**
+ * Differences between adjacent entries of an ascending list.
+ *
+ * The wrap-around gap (last back round to first) is deliberately **not** included. A node's
+ * knowledge of the ring is never complete, so that gap spans the arc it has not sampled — it is
+ * the single largest outlier in the population and says nothing about inter-peer spacing.
+ */
+function consecutiveGaps(ascendingValues) {
+    const gaps = [];
+    for (let i = 1; i < ascendingValues.length; i++)
+        gaps.push(ascendingValues[i] - ascendingValues[i - 1]);
+    return gaps;
+}
+/**
+ * Gaps between adjacent members of the successor/predecessor window around `selfCoord`.
+ *
+ * Coordinates are re-centred on self as *signed* offsets in (−2^255, 2^255] rather than compared
+ * raw, so a window straddling coordinate 0 stays one contiguous run. Sorting raw coordinates
+ * would split such a window in two and manufacture an interior gap the size of the rest of the
+ * ring — precisely the outlier this method exists to avoid.
+ *
+ * Self is normally present in the store, and a walk anchored exactly at `selfCoord` returns it
+ * as its own first result on *both* sides — so each side is asked for `m + 1` to still yield the
+ * m successors and m predecessors the S/P window is defined as, and offsets are collected in a
+ * `Set` so self (and any coincident coordinate) contributes once. Asking for plain `m` instead
+ * costs two of the 2m gaps. When self is absent from the store the extra slot simply widens the
+ * window by one peer per side, which is harmless.
+ */
+function windowGaps(store, m, selfCoord, filter) {
+    const selfBig = bytesToBigInt(selfCoord);
+    const offsets = new Set([0n]);
+    const addById = (id) => {
+        const entry = store.getById(id);
+        if (!entry)
+            return;
+        let d = (bytesToBigInt(entry.coord) - selfBig) % RING_SIZE;
+        if (d < 0n)
+            d += RING_SIZE;
+        offsets.add(d > HALF_RING ? d - RING_SIZE : d);
+    };
+    const reach = m + 1;
+    for (const id of store.neighborsRight(selfCoord, reach, filter))
+        addById(id);
+    for (const id of store.neighborsLeft(selfCoord, reach, filter))
+        addById(id);
+    return consecutiveGaps([...offsets].sort(ascending));
+}
 /**
- * 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.
+ * Relative standard error of the mean gap, as a [0,1] sample-quality factor.
+ *
+ * Gaps on a uniform-random ring are exponentially distributed, so a coefficient of variation
+ * near 1 is the *healthy* value rather than a defect. Flooring cv at 1 encodes that prior: a
+ * synthetically perfect (evenly spaced) sample cannot claim zero sampling error from a handful
+ * of gaps. The factor is then monotone in window size, capping confidence at 0.5 + 0.5·(1 −
+ * 1/√G) — 0.875 at G = 16 (a full S/P window at the default m = 8), ~0.65 at G = 2.
+ *
+ * NOTE: this measures *local* spacing regularity only. A node whose neighbors are all packed
+ * into a tiny, evenly-spaced arc — an eclipse, or a very young ring — scores high here while
+ * `n` is wildly wrong, because no statistic over the sampled arc can see the arc that was never
+ * sampled. The defense is corroboration from peer-reported estimates (`reportNetworkSize` /
+ * `calibrateSizeFromSnapshot`), not a better local formula.
  */
-export function estimateSizeAndConfidence(store, m, filter) {
-    const peers = filter ? store.list().filter(filter) : store.list();
+function dispersionFactor(gaps) {
+    const count = gaps.length;
+    if (count === 0)
+        return 0;
+    const values = gaps.map(Number);
+    let sum = 0;
+    for (const v of values)
+        sum += v;
+    const mean = sum / count;
+    // Degenerate: every sampled peer sits at one coordinate, so there is no spacing to judge.
+    if (mean <= 0)
+        return 0;
+    let squared = 0;
+    for (const v of values)
+        squared += (v - mean) ** 2;
+    const cv = Math.sqrt(squared / count) / mean;
+    const rse = Math.max(cv, 1) / Math.sqrt(count);
+    return Math.max(0, Math.min(1, 1 - rse));
+}
+/**
+ * The gap population the estimate rests on, plus the representative gap derived from it.
+ *
+ * With `selfCoord` this is the successor/predecessor window and its arithmetic **mean** — the
+ * arc-length method from docs/fret.md. Without it, the degraded fallback: every known
+ * coordinate, and the **median** to blunt the outliers a whole-store population carries.
+ *
+ * The fallback is degraded because a node's knowledge is deliberately non-uniform — it knows
+ * every peer near itself but only a sparsity-weighted scattering of far ones — so whole-store
+ * gaps mix ~2m near-true spacings with a long tail of huge far-peer gaps. Once far peers
+ * outnumber near ones (the normal steady state) even the median lands in that tail and `n`
+ * collapses by an order of magnitude.
+ */
+function collectGaps(store, m, peers, filter, selfCoord) {
+    if (selfCoord) {
+        const gaps = windowGaps(store, m, selfCoord, filter);
+        if (gaps.length > 0)
+            return { gaps, representativeGap: meanBigInt(gaps) };
+    }
+    const gaps = consecutiveGaps(peers.map((p) => bytesToBigInt(p.coord)).sort(ascending));
+    return { gaps, representativeGap: medianBigInt(gaps) };
+}
+/**
+ * Online network-size estimate from inter-peer ring gaps: `n = 2^256 / gap`.
+ *
+ * `options.selfCoord` selects the successor/predecessor window as the gap population and is the
+ * intended path; omitting it falls back to whole-store gaps (see {@link collectGaps}).
+ * `options.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` and the derived cluster span /
+ * near-radius. It defaults to counting every entry, leaving the standalone/simulator path
+ * unchanged.
+ *
+ * Confidence blends sample count against 2m with the dispersion factor above.
+ */
+export function estimateSizeAndConfidence(store, m, options) {
+    // NOTE: `list()` walks and materializes every entry, but on the `selfCoord` path only its
+    // length is used (for `sizeFactor`) — the gap population comes from the S/P window instead.
+    // That is an O(store) allocation per call, and the estimator is called once per inbound
+    // maybeAct. Fine at today's capacity (2048) and message rates; if either grows, give the
+    // store a `countWhere(filter)` and build the list only for the whole-store fallback.
+    const peers = options?.filter ? store.list().filter(options.filter) : store.list();
     const count = peers.length;
     if (count === 0)
         return { n: 0, confidence: 0 };
     if (count === 1)
         return { n: 1, confidence: 0.2 };
-    const ringSize = 1n << 256n;
-    const coords = peers.map((p) => bytesToBigInt(p.coord)).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-    const gaps = [];
-    for (let i = 1; i < coords.length; i++)
-        gaps.push(coords[i] - coords[i - 1]);
-    gaps.push((coords[0] + ringSize) - coords[coords.length - 1]);
-    // Use median gap to reduce skew from sparse knowledge
-    const medGap = medianBigInt(gaps);
-    const safeGap = medGap > 0n ? medGap : ringSize / BigInt(Math.max(1, count));
-    const nEstBig = ringSize / safeGap;
-    const nEst = Math.max(1, Math.min(Number(nEstBig), 1_000_000_000));
-    // Confidence from sample size and gap variance
-    let minGap = gaps[0];
-    let maxGap = gaps[0];
-    for (const g of gaps) {
-        if (g < minGap)
-            minGap = g;
-        if (g > maxGap)
-            maxGap = g;
-    }
+    const { gaps, representativeGap } = collectGaps(store, m, peers, options?.filter, options?.selfCoord);
+    const safeGap = representativeGap > 0n ? representativeGap : RING_SIZE / BigInt(count);
+    const nEst = Math.max(1, Math.min(Number(RING_SIZE / safeGap), 1_000_000_000));
     const sizeFactor = Math.min(1, count / Math.max(1, m * 2));
-    const varianceFactor = maxGap === 0n ? 0 : Number(minGap) / Number(maxGap);
-    const confidence = Math.max(0.05, Math.min(1, 0.5 * sizeFactor + 0.5 * varianceFactor));
+    const confidence = Math.max(0.05, Math.min(1, 0.5 * sizeFactor + 0.5 * dispersionFactor(gaps)));
     return { n: nEst, confidence };
 }

package/dist/src/index.d.ts

@@ -1,4 +1,6 @@
+import type { Libp2p } from 'libp2p';
 import type { SerializedPeerEntry, SerializedTable } from './store/digitree-store.js';
+import { FretService as FretServiceClass } from './service/fret-service.js';
 export type FretMode = 'active' | 'passive';
 export interface FretConfig {
     k: number;
@@ -7,6 +9,14 @@ export interface FretConfig {
     profile: 'edge' | 'core';
     bootstraps?: string[];
     networkName?: string;
+    /**
+     * Consecutive failed contact attempts before a peer is marked `dead` (default 3).
+     *
+     * A "failed contact" is failure to reach the peer at all — not a peer that answered and
+     * refused, which is membership evidence instead. Failures closer together than the service's
+     * spacing window count once, so the run is genuinely spread over time.
+     */
+    deadAfterFailures?: number;
 }
 export interface NeighborSnapshotV1 {
     v: 1;
@@ -22,7 +32,7 @@ export interface NeighborSnapshotV1 {
     size_estimate?: number;
     confidence?: number;
     sig: string;
-    metadata?: Record<string, any>;
+    metadata?: Record<string, unknown>;
 }
 export interface RouteAndMaybeActV1 {
     v: 1;
@@ -92,11 +102,11 @@ export interface FretService {
         commitCertificate: string;
     }>;
     report(evt: ReportEvent): void;
-    setMetadata(metadata: Record<string, any>): void;
-    getMetadata(peerId: string): Record<string, any> | undefined;
+    setMetadata(metadata: Record<string, unknown>): void;
+    getMetadata(peerId: string): Record<string, unknown> | undefined;
     listPeers(): Array<{
         id: string;
-        metadata?: Record<string, any>;
+        metadata?: Record<string, unknown>;
     }>;
     reportNetworkSize(estimate: number, confidence: number, source?: string): void;
     getNetworkSizeEstimate(): {
@@ -109,22 +119,29 @@ export interface FretService {
     setActivityHandler(handler: ActivityHandler): void;
     iterativeLookup(key: Uint8Array, options: LookupOptions): AsyncGenerator<RouteProgress>;
     exportTable(): SerializedTable;
-    importTable(table: SerializedTable): number;
+    importTable(table: SerializedTable): Promise<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 { FretServiceClass as FretServiceImpl };
+export { FretPeerDiscovery, type DiscoverySnapshotSource, type FretPeerDiscoveryInput, 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 { clockwiseDistance, minDistance, lexLess } from './ring/distance.js';
 export { DigitreeStore } from './store/digitree-store.js';
-export type { PeerEntry, PeerState, MembershipState } from './store/digitree-store.js';
+export type { PeerEntry, PeerPatch, PeerState, MembershipState, RingCursor, RingWalkPage } from './store/digitree-store.js';
 export { estimateSizeAndConfidence } from './estimate/size-estimator.js';
-export type { SizeEstimate } from './estimate/size-estimator.js';
+export type { SizeEstimate, SizeEstimateOptions } 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';
-export declare function createFret(node: any, cfg?: Partial<FretConfig>): FretService;
+export { DedupCache, DEDUP_TTL_MS } from './service/dedup-cache.js';
+export { validateTimestamp, sendFramed, readFramed, openRpcStream, releaseRpcStream } from './rpc/protocols.js';
+export { rpcRequest } from './rpc/request.js';
+export type { RpcRequestOptions } from './rpc/request.js';
+export type { RpcOutcome } from './rpc/outcome.js';
+export type { Stream } from '@libp2p/interface';
+export { registerRpcHandler, registerJsonHandler } from './rpc/protocols.js';
+export type { JsonRequestHandlerOpts, JsonReplyOnlyHandlerOpts } from './rpc/protocols.js';
+export { parseRouteAndMaybeAct, parseLeaveNotice, makeSnapshotParser, parsePingResponse, parseNearAnchor, parseMaybeActReply, sanitizeReplacements, parseOrThrow, ReplyRejectedError, isReplyRejectedError, } from './rpc/validate.js';
+export type { Parser, SnapshotCaps } from './rpc/validate.js';
+export declare function createFret(node: Libp2p, cfg?: Partial<FretConfig>): FretService;

package/dist/src/index.js

@@ -1,16 +1,48 @@
-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 { FretServiceClass as FretServiceImpl };
 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 { 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';
+export { DedupCache, DEDUP_TTL_MS } from './service/dedup-cache.js';
+// `openRpcStream` and `releaseRpcStream` are one seam: an opened stream must be released, and the
+// release rule (abort once the caller's signal has fired, close otherwise) is the half a consumer
+// gets wrong — a bare `close()` is unbounded against a stalled remote. Exporting only the opener
+// invites a hand-rolled releaser, which is the class of bug this export exists to retire.
+// `sendFramed` and `readFramed` ship together for the same reason: a consumer given only the
+// reader hand-rolls the writer, and the framing has to match.
+export { validateTimestamp, sendFramed, readFramed, openRpcStream, releaseRpcStream } from './rpc/protocols.js';
+// `rpcRequest` is the one owner of the open/write/read/close sequence those four primitives
+// compose, so a consumer sending a request never re-derives the order or the release rule. It
+// never throws for a network outcome — an unreachable peer, a foreign protocol, a truncated
+// reply, a busy answer and a timeout are all variants of the `RpcOutcome` it returns, and only a
+// caller bug (a malformed peer id, an unsatisfiable dial policy) throws. Callers that read the
+// outcome therefore branch on evidence about the peer rather than on error identity.
+export { rpcRequest } from './rpc/request.js';
+// The receive-side mirror of `rpcRequest`: a consumer wrapping its own protocol over the same
+// libp2p node has exactly the drop-vs-abort and stream-release problem these two solve, and the
+// hand-rolled copy is what leaks streams (a handler that throws mid-message leaves the inbound
+// stream open forever, and streams are counted per protocol per connection). `registerRpcHandler`
+// owns the budgeted success close and the synchronous error `abort()`; `registerJsonHandler`
+// stacks the framed-JSON decode + parse on top of it. Their option interfaces ship with them —
+// without those a consumer cannot name what it is passing.
+export { registerRpcHandler, registerJsonHandler } from './rpc/protocols.js';
+// The wire-shape parsers are exported for the same reason `registerRpcHandler` / `rpcRequest` /
+// `openRpcStream` are: a consumer registering its own handler over this node otherwise re-derives
+// the shape rules by hand, and a hand-rolled copy is what drifts. They are pure functions with no
+// service state behind them. The primitives they are spelled with (peer-id parsing, bounded string
+// arrays) stay module-scoped — implementation detail, not surface.
+export { parseRouteAndMaybeAct, parseLeaveNotice, makeSnapshotParser, parsePingResponse, parseNearAnchor, parseMaybeActReply, sanitizeReplacements, 
+// The adapter that wires a `Parser` into `rpcRequest`'s `decode`. It ships with the parsers
+// because passing one in raw is a silent bug rather than a compile error: `rpcRequest` has no
+// `undefined` check, so a returned rejection becomes `{ kind: 'ok', value: undefined }` and
+// `T` infers as `Reply | undefined`. Its error type is exported alongside so a consumer can
+// recognise the rejection by identity, not by message text.
+parseOrThrow, ReplyRejectedError, isReplyRejectedError, } from './rpc/validate.js';
 export function createFret(node, cfg) {
     return new FretServiceClass(node, cfg);
 }

package/dist/src/ring/distance.d.ts

@@ -1,4 +1,31 @@
-export declare function xorDistance(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Magnitude compare of two big-endian unsigned integers: `a < b`.
+ *
+ * Operands are right-aligned — a shorter array is read as zero-padded on the
+ * *left*, which is what it is numerically, and matches the arithmetic in
+ * `clockwiseDistance`.  Comparing from index 0 would instead read a 16-byte
+ * value as a 32-byte one scaled by 2^128.  Equal-length inputs (every caller
+ * today) compare byte-for-byte from the top, unchanged.
+ */
 export declare function lexLess(a: Uint8Array, b: Uint8Array): boolean;
 export declare function clockwiseDistance(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * True ring distance: the shorter of the two arcs between a and b, on a ring of
+ * 2^(8·len).  This is the single distance metric FRET uses — routing, payload
+ * inclusion, and the relevance sparsity model all measure with it, so the
+ * wrap-around point behaves like every other point on the ring.  Maximum value
+ * is 2^(8·len − 1) (half the ring), not 2^(8·len) − 1.
+ */
 export declare function minDistance(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Position of a distance magnitude on a log scale, normalized to [0,1]: 0 for a
+ * zero distance, rising toward 1 as the leading-zero-bit count falls.  Shared by
+ * the next-hop cost function and the relevance sparsity model so both read the
+ * ring at the same resolution.
+ *
+ * A `minDistance` result reaches exactly 1 only at the antipode (2^255, whose
+ * top bit is set); every other pair lands at 1 − 1/256 or below.  The value is
+ * consumed as a relative position, so that near-unreachable top step needs no
+ * rescaling.
+ */
+export declare function normalizedLogMagnitude(dist: Uint8Array): number;

package/dist/src/ring/distance.js

@@ -1,18 +1,17 @@
-export function xorDistance(a, b) {
-    const len = Math.max(a.length, b.length);
-    const out = new Uint8Array(len);
-    for (let i = 0; i < len; i++) {
-        const ai = a[a.length - 1 - i] ?? 0;
-        const bi = b[b.length - 1 - i] ?? 0;
-        out[len - 1 - i] = ai ^ bi;
-    }
-    return out;
-}
+/**
+ * Magnitude compare of two big-endian unsigned integers: `a < b`.
+ *
+ * Operands are right-aligned — a shorter array is read as zero-padded on the
+ * *left*, which is what it is numerically, and matches the arithmetic in
+ * `clockwiseDistance`.  Comparing from index 0 would instead read a 16-byte
+ * value as a 32-byte one scaled by 2^128.  Equal-length inputs (every caller
+ * today) compare byte-for-byte from the top, unchanged.
+ */
 export function lexLess(a, b) {
     const len = Math.max(a.length, b.length);
-    for (let i = 0; i < len; i++) {
-        const av = a[i] ?? 0;
-        const bv = b[i] ?? 0;
+    for (let i = len - 1; i >= 0; i--) {
+        const av = a[a.length - 1 - i] ?? 0;
+        const bv = b[b.length - 1 - i] ?? 0;
         if (av < bv)
             return true;
         if (av > bv)
@@ -41,7 +40,45 @@ export function clockwiseDistance(a, b) {
     }
     return out;
 }
+/**
+ * True ring distance: the shorter of the two arcs between a and b, on a ring of
+ * 2^(8·len).  This is the single distance metric FRET uses — routing, payload
+ * inclusion, and the relevance sparsity model all measure with it, so the
+ * wrap-around point behaves like every other point on the ring.  Maximum value
+ * is 2^(8·len − 1) (half the ring), not 2^(8·len) − 1.
+ */
 export function minDistance(a, b) {
-    // For routing we use absolute ring distance via XOR by default
-    return xorDistance(a, b);
+    // NOTE: allocates both arcs (2 × 32 bytes) to discard one, on a path walked
+    // per routing candidate and per relevance update.  Measured cost has not been
+    // an issue; if distance ever shows up in a profile, compare the arcs in place
+    // (cw < half-ring ⇒ cw is the shorter one) and build only the winner.
+    const cw = clockwiseDistance(a, b);
+    const ccw = clockwiseDistance(b, a);
+    return lexLess(ccw, cw) ? ccw : cw;
+}
+/**
+ * Position of a distance magnitude on a log scale, normalized to [0,1]: 0 for a
+ * zero distance, rising toward 1 as the leading-zero-bit count falls.  Shared by
+ * the next-hop cost function and the relevance sparsity model so both read the
+ * ring at the same resolution.
+ *
+ * A `minDistance` result reaches exactly 1 only at the antipode (2^255, whose
+ * top bit is set); every other pair lands at 1 − 1/256 or below.  The value is
+ * consumed as a relative position, so that near-unreachable top step needs no
+ * rescaling.
+ */
+export function normalizedLogMagnitude(dist) {
+    const totalBits = dist.length * 8;
+    if (totalBits === 0)
+        return 0;
+    let lzBits = 0;
+    for (const byte of dist) {
+        if (byte === 0) {
+            lzBits += 8;
+            continue;
+        }
+        lzBits += Math.clz32(byte) - 24; // clz32 counts over 32 bits; drop the 24 above the byte
+        break;
+    }
+    return 1 - lzBits / totalBits;
 }

package/dist/src/ring/hash.d.ts

@@ -4,6 +4,18 @@ export declare const COORD_BYTES = 32;
 export type RingCoord = Uint8Array;
 export declare function hashPeerId(peerId: PeerId): Promise<RingCoord>;
 export declare function hashKey(key: Uint8Array): Promise<RingCoord>;
+/**
+ * Fixed-length 64 hex chars — the encoding the routing store's tree key is built from.
+ *
+ * This is the hottest pure function in FRET: `DigitreeStore` embeds the hex coordinate in
+ * every tree key, so it runs once per store write *and* once per ring walk (each walk seeks
+ * by `hex(coord)`), which puts it under neighbor exchange, cohort assembly, next-hop
+ * selection and size estimation alike. Formatting each byte with
+ * `toString(16).padStart(2, '0')` allocates two throwaway strings per byte — 64 per
+ * coordinate — and measured **38% of total CPU** in the N=100 simulation spec. The lookup
+ * table is therefore load-bearing rather than a micro-optimization: the output is identical,
+ * but the per-byte allocations are gone.
+ */
 export declare function coordToHex(coord: RingCoord): string;
 export declare function hexToCoord(hex: string): RingCoord;
 export declare function coordToBase64url(coord: RingCoord): string;

package/dist/src/ring/hash.js

@@ -13,16 +13,31 @@ export async function hashKey(key) {
     const digest = await sha256.encode(key);
     return digest;
 }
+/** Byte value → its fixed-width hex pair. Built once; see {@link coordToHex}. */
+const HEX_PAIR = Array.from({ length: 256 }, (_, b) => b.toString(16).padStart(2, '0'));
+/**
+ * Fixed-length 64 hex chars — the encoding the routing store's tree key is built from.
+ *
+ * This is the hottest pure function in FRET: `DigitreeStore` embeds the hex coordinate in
+ * every tree key, so it runs once per store write *and* once per ring walk (each walk seeks
+ * by `hex(coord)`), which puts it under neighbor exchange, cohort assembly, next-hop
+ * selection and size estimation alike. Formatting each byte with
+ * `toString(16).padStart(2, '0')` allocates two throwaway strings per byte — 64 per
+ * coordinate — and measured **38% of total CPU** in the N=100 simulation spec. The lookup
+ * table is therefore load-bearing rather than a micro-optimization: the output is identical,
+ * but the per-byte allocations are gone.
+ */
 export function coordToHex(coord) {
-    // Fixed-length 64 hex chars
     let s = '';
-    for (let i = 0; i < coord.length; i++) {
-        const b = coord[i].toString(16).padStart(2, '0');
-        s += b;
-    }
+    for (let i = 0; i < coord.length; i++)
+        s += HEX_PAIR[coord[i]];
     return s;
 }
+const HEX_COORD_RE = new RegExp(`^[0-9a-fA-F]{${COORD_BYTES * 2}}$`);
 export function hexToCoord(hex) {
+    if (!HEX_COORD_RE.test(hex)) {
+        throw new Error(`hexToCoord: expected ${COORD_BYTES * 2} hex chars, got ${JSON.stringify(hex)}`);
+    }
     const out = new Uint8Array(COORD_BYTES);
     for (let i = 0; i < COORD_BYTES; i++) {
         out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
@@ -33,5 +48,9 @@ export function coordToBase64url(coord) {
     return u8ToString(coord, 'base64url');
 }
 export function base64urlToCoord(s) {
-    return u8FromString(s, 'base64url');
+    const coord = u8FromString(s, 'base64url');
+    if (coord.length !== COORD_BYTES) {
+        throw new Error(`base64urlToCoord: expected ${COORD_BYTES} bytes, got ${coord.length}`);
+    }
+    return coord;
 }

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

@@ -1,9 +1,13 @@
 import type { Libp2p } from 'libp2p';
+import type { RpcOutcome } from './outcome.js';
 export interface LeaveNoticeV1 {
     v: 1;
     from: string;
     replacements?: string[];
     timestamp: number;
 }
-export declare function registerLeave(node: Libp2p, onLeave: (notice: LeaveNoticeV1) => Promise<void> | void, protocol?: string): void;
-export declare function sendLeave(node: Libp2p, peerIdStr: string, notice: LeaveNoticeV1, protocol?: string): Promise<void>;
+export declare function registerLeave(node: Libp2p, onLeave: (notice: LeaveNoticeV1) => Promise<void> | void, protocol?: string, onIdentityMismatch?: (claimed: string, actual: string) => void, onMalformed?: (reason: 'decode' | 'parse') => void): Promise<void>;
+export declare function sendLeave(node: Libp2p, peerIdStr: string, notice: LeaveNoticeV1, protocol?: string, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<RpcOutcome<undefined>>;