p2p-fret 1.0.1 → 1.0.2

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

@@ -253,8 +253,8 @@ export declare class FretService implements IFretService, Startable {
      * Score a direct interaction with `id`.
      *
      * **Scoring never creates.** A peer we hold no entry for is not scored — bookkeeping *about* a
-     * peer must not be able to re-admit it, or removing a peer would not stick: `handleLeave` drops
-     * a departing peer, its connection closes a moment later, and the `peer:disconnect` listener's
+     * peer must not be able to re-admit it, or removing a peer would not stick: `enforceCapacity`
+     * evicts a connected peer, its connection closes later, and the `peer:disconnect` listener's
      * `applyFailure` would resurrect it as an unclassified stranger the classification pass then
      * spends probes on. That is why the helper takes no coordinate: with the entry required to
      * exist, `entry.coord` *is* the value every caller used to compute, so "create this peer at
@@ -320,8 +320,8 @@ export declare class FretService implements IFretService, Startable {
      * Record a failed interaction with `id`.
      *
      * **Scoring never creates** — see {@link applyTouch}. This is the helper the rule exists for:
-     * the `peer:disconnect` listener calls it for a peer `handleLeave` has just removed, and the
-     * old create-on-miss arm brought that peer straight back.
+     * the `peer:disconnect` listener calls it for a peer capacity eviction may already have
+     * removed, and the old create-on-miss arm brought that peer straight back.
      */
     private applyFailure;
     /** This peer's stored ring coordinate, hashing its id when we hold no entry for it yet. */
@@ -766,6 +766,22 @@ export declare class FretService implements IFretService, Startable {
     private computeReplacements;
     private sendLeaveToNeighbors;
     private handleLeave;
+    /**
+     * A peer told us it is leaving: mark it `dead` — the immediate counterpart of a completed run
+     * of failed contacts — rather than removing it.
+     *
+     * Removal did not stick. libp2p keeps the departed peer's peerStore record, negotiated
+     * protocols included, so the next tick's `seedFromPeerStore` (or a `peer:update`) re-created
+     * the entry and labelled it `member` again — a live ring member until three probes failed, and
+     * forever if it had no address to probe. `dead` survives that re-seed because `upsert`
+     * preserves `state` and classification touches only `membership`, and it already carries every
+     * other consequence a departure needs: out of every ring view, unprotected at eviction, skipped
+     * by the maintenance fan-outs, and restored by any proof of life if the peer comes back.
+     *
+     * The contact-failure run is left alone: nothing reads it while the peer is dead, and proof of
+     * life clears it together with the label.
+     */
+    private markDeparted;
     /**
      * Record a leave notice's suggested replacements as untrusted local hints — and nothing more.
      *
@@ -901,12 +917,45 @@ export declare class FretService implements IFretService, Startable {
      */
     private stabilizeOnce;
     /**
-     * The near peers a tick pings and snapshot-fetches: the dialable live members nearest self on
-     * either side, at most 4, in **ring order** (closest first) — deliberately not rotated like the
-     * other candidate lists. These are the peers ring correctness depends on most, so a truncated
-     * tick should skip the 4th-closest and never the immediate successor; it self-corrects next tick.
+     * The S/P window a tick verifies — the live members nearest self, `max(2, m)` per side — split
+     * by whether we can contact them at all.
+     *
+     * `targets` are the dialable ones a tick pings and snapshot-fetches: at most 4, in **ring
+     * order** (closest first, sides interleaved) — deliberately not rotated like the other
+     * candidate lists. These are the peers ring correctness depends on most, so a truncated tick
+     * should skip the outermost and never the immediate successor or predecessor; it
+     * self-corrects next tick. `uncontactable` is the rest of the window, uncapped: the 4 bounds
+     * RPCs, and none is spent on these (see {@link strikeUncontactable}).
+     *
+     * Walked through `ringNeighborsBothSides` rather than the public `getNeighbors`, whose `both`
+     * direction is successor-biased (see the NOTE there): at m = 8 it returned self plus seven
+     * successors on any ring of more than nine live members, so no predecessor was ever verified.
      */
     private nearProbeTargets;
+    /**
+     * Count one failed contact against each live member of the S/P window that no pass could
+     * reach: not connected, and no address libp2p could dial.
+     *
+     * Without this such a peer never reaches `dead`, because a strike is booked only when an
+     * outbound RPC fails and every pass that sends one filters on `isDialable` first. A phone that
+     * dials out and listens nowhere is exactly that peer once its connection drops — so it stayed a
+     * live member, and a cohort member, indefinitely.
+     *
+     * The observation is the tick, not the disconnect, so "an idle `peer:disconnect` is not a
+     * strike" stays true: `applyContactStrike`'s spacing guard makes each passive tick (1.5 s) one
+     * independent strike, the peer is `dead` after `deadAfterFailures` ticks, and one that
+     * reconnects within a tick or two (`peer:connect` is proof of life) is never killed. Once dead
+     * it leaves the live-member window, so the strikes stop by themselves.
+     *
+     * NOTE: only the S/P window is swept, so on a ring of more than 2·max(2, m) + 1 live members an
+     * address-less member outside our window is never struck by us and stays a live member in our
+     * cohorts. If cohorts assembled over such rings start waiting on departed phones, widen this to
+     * every live member — still local work, one store walk.
+     *
+     * Local work with no RPC, so the tick budget does not apply; but our own cancellation is still
+     * not evidence, so nothing is booked once the run signal has fired.
+     */
+    private strikeUncontactable;
     /**
      * Ping `id`, then fetch and merge its neighbor snapshot — one pooled task per near peer.
      *

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

@@ -533,8 +533,8 @@ export class FretService {
      * Score a direct interaction with `id`.
      *
      * **Scoring never creates.** A peer we hold no entry for is not scored — bookkeeping *about* a
-     * peer must not be able to re-admit it, or removing a peer would not stick: `handleLeave` drops
-     * a departing peer, its connection closes a moment later, and the `peer:disconnect` listener's
+     * peer must not be able to re-admit it, or removing a peer would not stick: `enforceCapacity`
+     * evicts a connected peer, its connection closes later, and the `peer:disconnect` listener's
      * `applyFailure` would resurrect it as an unclassified stranger the classification pass then
      * spends probes on. That is why the helper takes no coordinate: with the entry required to
      * exist, `entry.coord` *is* the value every caller used to compute, so "create this peer at
@@ -647,8 +647,8 @@ export class FretService {
      * Record a failed interaction with `id`.
      *
      * **Scoring never creates** — see {@link applyTouch}. This is the helper the rule exists for:
-     * the `peer:disconnect` listener calls it for a peer `handleLeave` has just removed, and the
-     * old create-on-miss arm brought that peer straight back.
+     * the `peer:disconnect` listener calls it for a peer capacity eviction may already have
+     * removed, and the old create-on-miss arm brought that peer straight back.
      */
     async applyFailure(id) {
         const entry = this.store.getById(id);
@@ -1266,9 +1266,9 @@ export class FretService {
                 }, this.protocols.PROTOCOL_MAYBE_ACT, this.maxBytesMaybeAct(), () => { this.diag.rejected.malformed++; }, streamCaps),
                 // NOTE: leave is deliberately the one inbound handler with no `noteInboundRpc`
                 // hook (compare neighbors / maybeAct / ping above and below). That hook applies
-                // the `rpc-inbound` membership signal to the sender, which here is the *departing*
-                // peer — it would re-insert it as a confirmed `member` immediately after
-                // `handleLeave` removed it. The asymmetry is the point; do not "fix" it while
+                // the `rpc-inbound` membership signal and proof of life to the sender, which here
+                // is the *departing* peer — it would restore it as a live `member` immediately after
+                // `handleLeave` marked it dead. The asymmetry is the point; do not "fix" it while
                 // tidying these signatures.
                 registerLeave(this.node, async (notice) => this.handleLeave(notice), this.protocols.PROTOCOL_LEAVE, () => { this.diag.rejected.identityMismatch++; }, () => { this.diag.rejected.malformed++; }, streamCaps),
                 registerPing(this.node, this.protocols.PROTOCOL_PING, () => this.handlePingRequest(), (from) => this.detach(this.noteInboundRpc(from), 'noteInboundRpc(ping)'), streamCaps),
@@ -1899,8 +1899,10 @@ export class FretService {
         try {
             let coord = null;
             const entry = this.store.getById(peerId);
-            if (entry)
+            if (entry) {
                 coord = entry.coord;
+                this.markDeparted(peerId);
+            }
             else {
                 try {
                     coord = await hashPeerId(peerIdFromString(peerId));
@@ -1909,8 +1911,6 @@ export class FretService {
                     log.error('handleLeave: could not hash departing peer id %s - %e', peerId, e);
                 }
             }
-            // remove leaving peer from the store
-            this.store.remove(peerId);
             if (!coord)
                 return;
             await this.recordLeaveReplacements(notice.replacements, peerId);
@@ -1925,6 +1925,28 @@ export class FretService {
             log.error('handleLeave failed for %s - %e', peerId, err);
         }
     }
+    /**
+     * A peer told us it is leaving: mark it `dead` — the immediate counterpart of a completed run
+     * of failed contacts — rather than removing it.
+     *
+     * Removal did not stick. libp2p keeps the departed peer's peerStore record, negotiated
+     * protocols included, so the next tick's `seedFromPeerStore` (or a `peer:update`) re-created
+     * the entry and labelled it `member` again — a live ring member until three probes failed, and
+     * forever if it had no address to probe. `dead` survives that re-seed because `upsert`
+     * preserves `state` and classification touches only `membership`, and it already carries every
+     * other consequence a departure needs: out of every ring view, unprotected at eviction, skipped
+     * by the maintenance fan-outs, and restored by any proof of life if the peer comes back.
+     *
+     * The contact-failure run is left alone: nothing reads it while the peer is dead, and proof of
+     * life clears it together with the label.
+     */
+    markDeparted(id) {
+        // Unreachable for a leave (the transport identity check rejects a notice from self), but a
+        // dead self has no path back short of a restart — the same guard `applyContactStrike` keeps.
+        if (id === this.selfIdStr)
+            return;
+        this.store.update(id, { state: 'dead' });
+    }
     /**
      * Record a leave notice's suggested replacements as untrusted local hints — and nothing more.
      *
@@ -1950,8 +1972,9 @@ export class FretService {
             // Skipping self is a correctness guard, not tidiness: were self ever absent from the
             // store, upserting it here would recreate it as `unknown` and drop self out of every
             // member-only ring view (see *Network-scoped admission* in `docs/fret.md`). Skipping
-            // the departed peer stops us re-adding the one `handleLeave` just removed. Duplicates
-            // inside one list collapse, so 12 copies of an id cost one hash and one upsert.
+            // the departed peer stops a notice naming its own sender from creating an entry for a
+            // peer we held none for. Duplicates inside one list collapse, so 12 copies of an id
+            // cost one hash and one upsert.
             if (id === selfStr || id === departedId || seen.has(id))
                 continue;
             seen.add(id);
@@ -2351,7 +2374,10 @@ export class FretService {
      */
     async stabilizeOnce() {
         this.sweepBoundedMaps();
-        const near = await this.nearProbeTargets();
+        const { targets: near, uncontactable } = await this.nearProbeTargets();
+        // Before phase 1, and awaited: these peers are disjoint from every pooled candidate set
+        // (live members, but undialable), so nothing in the pool races these strikes.
+        await this.strikeUncontactable(uncontactable);
         // `runSignal` is undefined before the first start(); `deadline` accepts that. `cancel()` in
         // the finally is mandatory — see `deadline`.
         const budget = deadline(FretService.STABILIZE_TICK_BUDGET_MS, this.runSignal);
@@ -2383,11 +2409,11 @@ export class FretService {
             // tick still enforces.
             // NOTE: a throw *earlier* in the tick skips this, and the seeds no longer trim for
             // themselves, so that tick's inserts stay untrimmed until the next one. The reachable
-            // candidates are the two calls above the try (`sweepBoundedMaps`, `nearProbeTargets`),
-            // both local and neither able to throw on any input a tick can present; the loop's own
-            // try/catch swallows anything that does, and the overshoot self-heals next tick. If a
-            // deterministic throw is ever found on that path, move the enforcement into this
-            // method's `finally` rather than adding a guard here.
+            // candidates are the three calls above the try (`sweepBoundedMaps`, `nearProbeTargets`,
+            // `strikeUncontactable`), all local and none able to throw on any input a tick can
+            // present; the loop's own try/catch swallows anything that does, and the overshoot
+            // self-heals next tick. If a deterministic throw is ever found on that path, move the
+            // enforcement into this method's `finally` rather than adding a guard here.
             await this.enforceCapacity();
             if (announced.length > 0)
                 this.detach(this.announceToNewPeers(announced), 'announceToNewPeers');
@@ -2408,15 +2434,59 @@ export class FretService {
         }
     }
     /**
-     * The near peers a tick pings and snapshot-fetches: the dialable live members nearest self on
-     * either side, at most 4, in **ring order** (closest first) — deliberately not rotated like the
-     * other candidate lists. These are the peers ring correctness depends on most, so a truncated
-     * tick should skip the 4th-closest and never the immediate successor; it self-corrects next tick.
+     * The S/P window a tick verifies — the live members nearest self, `max(2, m)` per side — split
+     * by whether we can contact them at all.
+     *
+     * `targets` are the dialable ones a tick pings and snapshot-fetches: at most 4, in **ring
+     * order** (closest first, sides interleaved) — deliberately not rotated like the other
+     * candidate lists. These are the peers ring correctness depends on most, so a truncated tick
+     * should skip the outermost and never the immediate successor or predecessor; it
+     * self-corrects next tick. `uncontactable` is the rest of the window, uncapped: the 4 bounds
+     * RPCs, and none is spent on these (see {@link strikeUncontactable}).
+     *
+     * Walked through `ringNeighborsBothSides` rather than the public `getNeighbors`, whose `both`
+     * direction is successor-biased (see the NOTE there): at m = 8 it returned self plus seven
+     * successors on any ring of more than nine live members, so no predecessor was ever verified.
      */
     async nearProbeTargets() {
-        const selfStr = this.selfIdStr;
-        const nearAll = this.getNeighbors(await this.selfCoord(), 'both', Math.max(2, this.cfg.m));
-        return nearAll.filter((id) => id !== selfStr && this.isDialable(id)).slice(0, 4);
+        const window = ringNeighborsBothSides(this.store, await this.selfCoord(), Math.max(2, this.cfg.m), this.selfIdStr, { filter: isLiveMember });
+        const targets = [];
+        const uncontactable = [];
+        for (const id of window)
+            (this.isDialable(id) ? targets : uncontactable).push(id);
+        return { targets: targets.slice(0, 4), uncontactable };
+    }
+    /**
+     * Count one failed contact against each live member of the S/P window that no pass could
+     * reach: not connected, and no address libp2p could dial.
+     *
+     * Without this such a peer never reaches `dead`, because a strike is booked only when an
+     * outbound RPC fails and every pass that sends one filters on `isDialable` first. A phone that
+     * dials out and listens nowhere is exactly that peer once its connection drops — so it stayed a
+     * live member, and a cohort member, indefinitely.
+     *
+     * The observation is the tick, not the disconnect, so "an idle `peer:disconnect` is not a
+     * strike" stays true: `applyContactStrike`'s spacing guard makes each passive tick (1.5 s) one
+     * independent strike, the peer is `dead` after `deadAfterFailures` ticks, and one that
+     * reconnects within a tick or two (`peer:connect` is proof of life) is never killed. Once dead
+     * it leaves the live-member window, so the strikes stop by themselves.
+     *
+     * NOTE: only the S/P window is swept, so on a ring of more than 2·max(2, m) + 1 live members an
+     * address-less member outside our window is never struck by us and stays a live member in our
+     * cohorts. If cohorts assembled over such rings start waiting on departed phones, widen this to
+     * every live member — still local work, one store walk.
+     *
+     * Local work with no RPC, so the tick budget does not apply; but our own cancellation is still
+     * not evidence, so nothing is booked once the run signal has fired.
+     */
+    async strikeUncontactable(ids) {
+        const signal = this.runSignal;
+        for (const id of ids) {
+            if (this.wasCancelled(signal))
+                return;
+            log('near window: %s has no connection and no address - counted as a failed contact', id);
+            await this.applyContactFailure(id);
+        }
     }
     /**
      * Ping `id`, then fetch and merge its neighbor snapshot — one pooled task per near peer.

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

@@ -80,7 +80,22 @@ export declare class Libp2pFretService implements Startable, FretService {
     /** The same instance libp2p reaches via `peerDiscoverySymbol`, for applications that want to listen directly. */
     getPeerDiscovery(): PeerDiscovery;
     start(): Promise<void>;
+    /**
+     * Runs the whole shutdown here, ahead of {@link stop}, because this is the last point at which
+     * the leave notices can still go out. libp2p's `stop()` runs every component's `beforeStop()`
+     * first, then every component's `stop()` under one `Promise.all` — and the connection manager's
+     * `stop()` closes every connection inside that same `Promise.all`. A leave fan-out started from
+     * our `stop()` therefore races the closing connections and loses: a peer that listens nowhere
+     * can reach its neighbours only over connections it already holds, so its notices were sent to
+     * nobody. The registrar is still live here, so unhandling works too.
+     */
+    beforeStop(): Promise<void>;
+    /**
+     * A no-op after {@link beforeStop} under libp2p (both halves are idempotent), and the whole
+     * shutdown for a host that drives this facade by hand without a `beforeStop` call.
+     */
     stop(): Promise<void>;
+    private shutdown;
     routeAct(msg: RouteAndMaybeActV1): Promise<NearAnchorV1 | {
         commitCertificate: string;
     }>;

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

@@ -121,7 +121,26 @@ export class Libp2pFretService {
         // explicit start/stop stay ours.
         await this.discovery.start();
     }
+    /**
+     * Runs the whole shutdown here, ahead of {@link stop}, because this is the last point at which
+     * the leave notices can still go out. libp2p's `stop()` runs every component's `beforeStop()`
+     * first, then every component's `stop()` under one `Promise.all` — and the connection manager's
+     * `stop()` closes every connection inside that same `Promise.all`. A leave fan-out started from
+     * our `stop()` therefore races the closing connections and loses: a peer that listens nowhere
+     * can reach its neighbours only over connections it already holds, so its notices were sent to
+     * nobody. The registrar is still live here, so unhandling works too.
+     */
+    async beforeStop() {
+        await this.shutdown();
+    }
+    /**
+     * A no-op after {@link beforeStop} under libp2p (both halves are idempotent), and the whole
+     * shutdown for a host that drives this facade by hand without a `beforeStop` call.
+     */
     async stop() {
+        await this.shutdown();
+    }
+    async shutdown() {
         await this.discovery.stop();
         await this.inner?.stop();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "p2p-fret",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "type": "module",
   "description": "FRET: Finger Ring Ensemble Topology (libp2p ring overlay with Digitree)",
   "main": "dist/src/index.js",