p2p-fret 1.1.0 → 1.2.0

package/dist/src/index.d.ts

@@ -48,6 +48,22 @@ export interface FretConfig {
      * Must be a positive finite number; the constructor throws otherwise.
      */
     maxPassiveIntervalMs?: number;
+    /**
+     * The longest grace, in milliseconds, a peer this node has watched stay up for a long time is
+     * given to come back before it is marked `dead` (default 300 000 ms — 5 minutes).
+     *
+     * A peer is normally marked dead after `deadAfterFailures` spaced failed contacts — a few
+     * seconds. A peer with long *proven tenure* (how long this node itself has watched it stay up)
+     * is instead marked dead only once its failure run has also lasted `tenure / 12`, capped here:
+     * nothing below 10 minutes of tenure, 50 s at 10 minutes, 2.5 minutes at 30, the full cap from
+     * an hour on. So a long-running server down for a few minutes of maintenance keeps its place in
+     * the ring rather than having the ring re-form around it twice. While in grace the peer is still
+     * a live member — routing steers around it by its probe backoff, and cohorts keep it as a
+     * member that is merely unavailable. `0` disables grace for every peer. Must be a finite number
+     * between 0 and 15 minutes (the tenure gap tolerance — a longer grace could keep a peer "alive"
+     * across a silence long enough to restart its session); the constructor throws otherwise.
+     */
+    maxDeadGraceMs?: number;
     /**
      * This node's libp2p private key — the key `node.peerId` was derived from.
      *
@@ -174,6 +190,13 @@ export interface FretService {
         id: string;
         metadata?: Record<string, unknown>;
     }>;
+    /**
+     * How long, in ms, this node has itself watched `peerId` stay continuously up — measured from
+     * proof of life only, never gossiped (see *Tenure* in docs/fret.md). 0 for a peer the table
+     * holds but has never proven alive; `undefined` for one it does not hold. Cohort order does not
+     * use it — a higher layer may, e.g. to choose which cohort members to ask first.
+     */
+    getPeerTenure(peerId: string): number | undefined;
     reportNetworkSize(estimate: number, confidence: number, source?: string): void;
     getNetworkSizeEstimate(): {
         size_estimate: number;

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

@@ -389,7 +389,7 @@ export declare class FretService implements IFretService, Startable {
      *
      * **Scoring never creates** — a peer we hold no entry for is not scored, and the call returns
      * before the `selfCoord()` await. See {@link applyTouch} for why, and for where creation does
-     * belong. The trailing `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
+     * belong. The `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
      * so stop running for a missing peer, which loses nothing: both already no-op on one.
      *
      * `latencyMs` is optional and must be supplied **only** when the caller timed a round trip
@@ -428,7 +428,16 @@ export declare class FretService implements IFretService, Startable {
      */
     private applyContactFailure;
     /**
-     * Count one failed contact against `id`, marking it `dead` once the run completes.
+     * Count one failed contact against `id`, marking it `dead` once the run completes — and, for a
+     * peer with long proven tenure, has also lasted that peer's grace.
+     *
+     * **The grace** (`deadGraceMs` in `store/tenure.ts`, capped by `maxDeadGraceMs`) is time, not
+     * strikes: strikes arrive at the pass rate, so a larger count would stretch seconds, never the
+     * minutes a server's maintenance takes. A peer under 10 minutes of tenure has none and is judged
+     * exactly as before. Tenure is frozen during the outage (no proof of life arrives), so the grace
+     * is stable across the run without being snapshotted at its start. A peer held in grace is still
+     * a live member: routing steers around it by its probe backoff, and cohorts keep it as a member
+     * that is merely unavailable.
      *
      * **Synchronous by construction.** `applySuccess` / `applyFailure` read an entry, await the
      * self coordinate, then write a value derived before the await — so two concurrent chains
@@ -446,7 +455,7 @@ export declare class FretService implements IFretService, Startable {
     private applyContactStrike;
     /**
      * Record that `id` is demonstrably alive: clear its contact-failure run and, if it was marked
-     * `dead`, restore it to a live state.
+     * `dead`, restore it to a live state — and advance its session tenure (`store/tenure.ts`).
      *
      * Called from every site that proves liveness: the RPC sites through {@link noteRpcEvidence},
      * and a fresh transport connection (`peer:connect`) directly. The counter reset is the
@@ -456,8 +465,15 @@ export declare class FretService implements IFretService, Startable {
      *
      * Relevance is deliberately *not* reset to a baseline. `scoreSuccess` already up-ranks on
      * success, and wiping the health counters would erase the record of a peer that flaps.
+     *
+     * This is the **only** place tenure advances, so it counts proof of life and nothing else:
+     * hearsay (`noteDiscovered`, address hints, the peerStore listeners) never reaches it. The
+     * stamp rides the same write as the liveness patch, and a stamp alone is **not** a change —
+     * otherwise every RPC from a settled neighbour would snap the idle backoff back to its base.
      */
     private noteProofOfLife;
+    /** What proof of life changes about `e`'s liveness bookkeeping — empty when already settled. */
+    private livenessPatch;
     /**
      * The remote *answered on this network's namespaced protocol* — a framed reply came back,
      * whatever it said: `ok: false`, `busy`, or bytes that would not decode.
@@ -1712,6 +1728,7 @@ export declare class FretService implements IFretService, Startable {
         id: string;
         metadata?: Record<string, unknown>;
     }>;
+    getPeerTenure(peerId: string): number | undefined;
     exportTable(): SerializedTable;
     importTable(table: SerializedTable): Promise<number>;
     /**

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

@@ -28,6 +28,7 @@ import { NearExchange, snapshotDigest } from './near-exchange.js';
 import { IdleBackoff } from './idle-backoff.js';
 import { ringNeighborsBothSides } from '../ring/ring-walk.js';
 import { createSparsityModel, normalizedLogDistance, sparsityBonus, touch as scoreTouch, recordSuccess as scoreSuccess, recordFailure as scoreFailure, initialRelevance, } from '../store/relevance.js';
+import { deadGraceMs, noteProven, provenTenureMs, TENURE_GAP_TOLERANCE_MS } from '../store/tenure.js';
 import { createLogger } from '../logger.js';
 const log = createLogger('service:fret');
 function isPlainObject(value) {
@@ -118,6 +119,20 @@ function requirePositiveMs(value, fallback, name) {
     }
     return value;
 }
+/**
+ * The configured dead-verdict grace ceiling (`FretConfig.maxDeadGraceMs`): a finite number of ms
+ * from 0 (the off switch) up to the tenure gap tolerance; absent takes `fallback`. Past the
+ * tolerance a grace could hold a peer "not dead" across a silence long enough that its session
+ * restarts on return — a contradiction, so it fails here rather than being clamped.
+ */
+function requireDeadGraceMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0 || value > TENURE_GAP_TOLERANCE_MS) {
+        throw new Error(`FretService: maxDeadGraceMs must be a finite number of milliseconds from 0 to ${TENURE_GAP_TOLERANCE_MS}, got ${String(value)}`);
+    }
+    return value;
+}
 /**
  * The peer ids named by configured bootstrap entries: a multiaddr's `p2p` component, otherwise
  * the entry itself as a bare peer id. An entry that yields no parseable id is logged and skipped
@@ -485,6 +500,13 @@ export class FretService {
          * sent). A redial cancelled mid-flight by `stop()` counts in neither verdict.
          */
         redials: { started: 0, connected: 0, failed: 0 },
+        /**
+         * Contact strikes that completed a failure run against a live peer but did not mark it
+         * `dead`, because the run had not yet lasted the peer's tenure-earned grace (see
+         * `applyContactStrike`). One per such strike, so a long-tenured peer that stays silent
+         * through its grace counts once per pass until the verdict lands.
+         */
+        deadGraceHeld: 0,
         /**
          * The stabilization loop's idle backoff, as of the last completed pass (see `IdleBackoff`):
          * `delayMs` is the passive delay the loop armed after it — the base while things change,
@@ -564,6 +586,7 @@ export class FretService {
             // Validated like `dialTimeoutMs`: a host that set it meant a number. A value at or
             // below the base interval is the off switch — `IdleBackoff` clamps the cap to the base.
             maxPassiveIntervalMs: requirePositiveMs(cfg?.maxPassiveIntervalMs, 60_000, 'maxPassiveIntervalMs'),
+            maxDeadGraceMs: requireDeadGraceMs(cfg?.maxDeadGraceMs, 300_000),
         };
         this.idle = new IdleBackoff({ baseMs: FretService.PASSIVE_INTERVAL_MS, capMs: this.cfg.maxPassiveIntervalMs });
         // A key that does not derive this node's peer id would seal records no receiver accepts
@@ -771,7 +794,7 @@ export class FretService {
      *
      * **Scoring never creates** — a peer we hold no entry for is not scored, and the call returns
      * before the `selfCoord()` await. See {@link applyTouch} for why, and for where creation does
-     * belong. The trailing `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
+     * belong. The `applyMembershipSignal` / `noteProofOfLife` land inside that guard and
      * so stop running for a missing peer, which loses nothing: both already no-op on one.
      *
      * `latencyMs` is optional and must be supplied **only** when the caller timed a round trip
@@ -789,6 +812,16 @@ export class FretService {
      * inside the store instead of patching a value derived outside it.
      */
     async applySuccess(id, latencyMs) {
+        if (!this.store.getById(id))
+            return;
+        // Every applySuccess call in this service follows a completed RPC over this
+        // network's namespaced protocol (ping or maybeAct), which proves the peer
+        // serves this network → confirm membership for free off normal traffic…
+        this.applyMembershipSignal(id, 'rpc-success');
+        // …and proves it is reachable, which clears any contact-failure run and resurrects it if
+        // a previous run had marked it dead. Before the score, so the score reads the tenure this
+        // very proof extended or restarted — not a session from before a long absence.
+        this.noteRpcEvidence(id);
         const entry = this.store.getById(id);
         if (!entry)
             return;
@@ -806,13 +839,6 @@ export class FretService {
             // has nothing to say about.
             ...(latencyMs === undefined ? {} : { avgLatencyMs: next.avgLatencyMs }),
         });
-        // Every applySuccess call in this service follows a completed RPC over this
-        // network's namespaced protocol (ping or maybeAct), which proves the peer
-        // serves this network → confirm membership for free off normal traffic.
-        this.applyMembershipSignal(id, 'rpc-success');
-        // …and proves it is reachable, which clears any contact-failure run and resurrects it if
-        // a previous run had marked it dead.
-        this.noteRpcEvidence(id);
     }
     /**
      * Record a failed interaction with `id`.
@@ -851,7 +877,16 @@ export class FretService {
         this.applyContactStrike(id);
     }
     /**
-     * Count one failed contact against `id`, marking it `dead` once the run completes.
+     * Count one failed contact against `id`, marking it `dead` once the run completes — and, for a
+     * peer with long proven tenure, has also lasted that peer's grace.
+     *
+     * **The grace** (`deadGraceMs` in `store/tenure.ts`, capped by `maxDeadGraceMs`) is time, not
+     * strikes: strikes arrive at the pass rate, so a larger count would stretch seconds, never the
+     * minutes a server's maintenance takes. A peer under 10 minutes of tenure has none and is judged
+     * exactly as before. Tenure is frozen during the outage (no proof of life arrives), so the grace
+     * is stable across the run without being snapshotted at its start. A peer held in grace is still
+     * a live member: routing steers around it by its probe backoff, and cohorts keep it as a member
+     * that is merely unavailable.
      *
      * **Synchronous by construction.** `applySuccess` / `applyFailure` read an entry, await the
      * self coordinate, then write a value derived before the await — so two concurrent chains
@@ -884,20 +919,30 @@ export class FretService {
         // Clamped at the threshold so the counter stays bounded for a peer we keep re-probing;
         // a peer already dead simply stays dead.
         const failures = Math.min(e.contactFailures + 1, threshold);
-        const patch = { contactFailures: failures, lastContactFailureAt: now };
-        if (failures >= threshold && e.state !== 'dead')
+        // A run carrying no start stamp (counter written outside this method) reads as long over, so
+        // its verdict falls back to the strike count alone — today's rule, never a stuck grace.
+        const runStart = e.contactFailures === 0 ? now : e.contactRunStartedAt;
+        const completed = failures >= threshold && e.state !== 'dead';
+        const toDead = completed && now - runStart >= deadGraceMs(provenTenureMs(e), this.cfg.maxDeadGraceMs);
+        const patch = { contactFailures: failures, lastContactFailureAt: now, contactRunStartedAt: runStart };
+        if (toDead)
             patch.state = 'dead';
         this.store.update(id, patch);
-        // A strike on a peer that was not already dead progressed a run (or completed one). One
-        // on a peer already `dead` — the dead arm re-probing it — moves nothing: the peer is backed
-        // off, there is nothing new to act on, and counting it would reset the delay on every
-        // dead-arm probe forever.
-        if (e.state !== 'dead')
-            this.noteChange(`contact strike ${failures} on ${id}`);
+        if (completed && !toDead)
+            this.diag.deadGraceHeld++;
+        // A change is a strike that progressed the count, or the one that marked the peer dead. A
+        // grace-held strike at the clamped threshold moves nothing — it can repeat every pass for
+        // minutes, and counting it would pin the idle backoff at its base for the whole grace. So
+        // the verdict lands at most one passive interval after the grace expires. A strike on a peer
+        // already `dead` (the dead arm re-probing it) is never a change, or every dead-arm probe
+        // would reset the delay forever.
+        if (e.state !== 'dead' && (failures > e.contactFailures || toDead)) {
+            this.noteChange(toDead ? `contact run completed on ${id}` : `contact strike ${failures} on ${id}`);
+        }
     }
     /**
      * Record that `id` is demonstrably alive: clear its contact-failure run and, if it was marked
-     * `dead`, restore it to a live state.
+     * `dead`, restore it to a live state — and advance its session tenure (`store/tenure.ts`).
      *
      * Called from every site that proves liveness: the RPC sites through {@link noteRpcEvidence},
      * and a fresh transport connection (`peer:connect`) directly. The counter reset is the
@@ -907,28 +952,45 @@ export class FretService {
      *
      * Relevance is deliberately *not* reset to a baseline. `scoreSuccess` already up-ranks on
      * success, and wiping the health counters would erase the record of a peer that flaps.
+     *
+     * This is the **only** place tenure advances, so it counts proof of life and nothing else:
+     * hearsay (`noteDiscovered`, address hints, the peerStore listeners) never reaches it. The
+     * stamp rides the same write as the liveness patch, and a stamp alone is **not** a change —
+     * otherwise every RPC from a settled neighbour would snap the idle backoff back to its base.
      */
     noteProofOfLife(id) {
         const e = this.store.getById(id);
         if (!e)
             return;
+        const patch = this.livenessPatch(e);
+        const settled = Object.keys(patch).length === 0;
+        // Self never reaches here by RPC; the guard keeps a meaningless tenure off its entry anyway.
+        const tenure = id === this.selfIdStr ? undefined : noteProven(e, Date.now());
+        if (settled && tenure === undefined)
+            return;
+        this.store.update(id, { ...patch, ...tenure });
+        // Only when the liveness half wrote — a run cleared or a `dead` peer revived. Proof of life
+        // from a peer already settled (an idle neighbour's ping) at most stamped tenure, which is
+        // not something the next pass could act on.
+        if (settled)
+            return;
+        this.noteChange(patch.state === undefined ? `contact run cleared for ${id}` : `${id} revived`);
+    }
+    /** What proof of life changes about `e`'s liveness bookkeeping — empty when already settled. */
+    livenessPatch(e) {
         const patch = {};
         // The spacing stamp is cleared alongside the count, because it only means anything
         // *within* a run: leaving it behind makes the first failure of the next run land inside
         // the spacing window of a failure from the run just ended, so that strike is discarded
         // and the peer gets a free miss after every recovery.
-        if (e.contactFailures !== 0 || e.lastContactFailureAt !== 0) {
+        if (e.contactFailures !== 0 || e.lastContactFailureAt !== 0 || e.contactRunStartedAt !== 0) {
             patch.contactFailures = 0;
             patch.lastContactFailureAt = 0;
+            patch.contactRunStartedAt = 0;
         }
         if (e.state === 'dead')
-            patch.state = this.isConnected(id) ? 'connected' : 'disconnected';
-        if (Object.keys(patch).length === 0)
-            return; // already settled
-        this.store.update(id, patch);
-        // Only when it wrote — a run cleared or a `dead` peer revived. Proof of life from a peer
-        // already settled (an idle neighbour's ping) returned above and is not a change.
-        this.noteChange(patch.state === undefined ? `contact run cleared for ${id}` : `${id} revived`);
+            patch.state = this.isConnected(e.id) ? 'connected' : 'disconnected';
+        return patch;
     }
     /**
      * The remote *answered on this network's namespaced protocol* — a framed reply came back,
@@ -2305,6 +2367,9 @@ export class FretService {
         // dead self has no path back short of a restart — the same guard `applyContactStrike` keeps.
         if (id === this.selfIdStr)
             return;
+        // NOTE: immediate whatever the sender's tenure — no dead-verdict grace — because the notice is
+        // the peer's own statement that it is going. A "back in N minutes" leave flavour that earns
+        // grace needs leave authentication first (tickets/backlog/22-debt-leave-authentication.md).
         this.store.update(id, { state: 'dead' });
     }
     /**
@@ -4101,6 +4166,9 @@ export class FretService {
             backoffPenalty: (id) => this.backoff.penalty(id),
         };
     }
+    // NOTE: link quality is the success rate alone; session tenure (`store/tenure.ts`) is available
+    // on the entry but deliberately not folded in. If routes are ever measured failing mid-path on
+    // short-lived hops, weight this by `stabilityFactor(provenTenureMs(entry))`.
     linkQuality(id) {
         const entry = this.store.getById(id);
         if (!entry)
@@ -4425,6 +4493,10 @@ export class FretService {
             metadata: entry.metadata
         }));
     }
+    getPeerTenure(peerId) {
+        const entry = this.store.getById(peerId);
+        return entry ? provenTenureMs(entry) : undefined;
+    }
     exportTable() {
         const now = Date.now();
         return {

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

@@ -113,6 +113,7 @@ export declare class Libp2pFretService implements Startable, FretService {
         id: string;
         metadata?: Record<string, unknown>;
     }>;
+    getPeerTenure(peerId: string): number | undefined;
     exportTable(): SerializedTable;
     importTable(table: SerializedTable): Promise<number>;
     reportNetworkSize(estimate: number, confidence: number, source?: string): void;

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

@@ -168,7 +168,7 @@ export class Libp2pFretService {
     // dropping the `return` changes nothing a caller can observe. What it does change is
     // `test/libp2p-facade-forwarding.spec.ts`, which injects a mock core returning a distinct
     // sentinel from *every* method and asserts each facade method hands that exact object back —
-    // one uniform exact-forwarding rule over all 20 members rather than a per-method judgement
+    // one uniform exact-forwarding rule over all 21 members rather than a per-method judgement
     // about which returns are worth checking. Deleting a `return` here fails that spec with
     // "<method> return identity"; keep them.
     async ready() {
@@ -190,6 +190,9 @@ export class Libp2pFretService {
     listPeers() {
         return this.ensure().listPeers();
     }
+    getPeerTenure(peerId) {
+        return this.ensure().getPeerTenure(peerId);
+    }
     exportTable() {
         return this.ensure().exportTable();
     }

package/dist/src/store/digitree-store.d.ts

@@ -59,6 +59,15 @@ export interface PeerEntry {
      * serialized — it describes a live attempt and says nothing after a restart. 0 = never counted.
      */
     lastContactFailureAt: number;
+    /**
+     * Unix ms of the first strike counted in the current contact-failure run; 0 = no run.
+     *
+     * The dead-verdict grace (`deadGraceMs` in `store/tenure.ts`) is measured from here: a peer we
+     * have watched stay up for a long time is marked `dead` only once its run has both reached the
+     * strike threshold *and* lasted that long. Same lifecycle as `lastContactFailureAt` — not
+     * serialized, 0 on insert and import, cleared together with the run by proof of life.
+     */
+    contactRunStartedAt: number;
     accessCount: number;
     successCount: number;
     failureCount: number;
@@ -74,6 +83,20 @@ export interface PeerEntry {
      * measurements away. Neither mistake is expressible now.
      */
     avgLatencyMs: number | null;
+    /**
+     * Local-clock unix ms at which this peer's current *session* began — the first proof of life
+     * of a run in which no two consecutive proofs were further apart than the tenure gap tolerance.
+     * 0 = never proven. Paired with {@link lastProvenAliveAt}; proven tenure is the span between
+     * them (see `store/tenure.ts`). Like the counters, the store stores and exposes it and never
+     * branches on it.
+     */
+    sessionStartedAt: number;
+    /**
+     * Local-clock unix ms of the latest proof of life counted toward the current session (stamped
+     * at a granularity of about a second, so a burst of RPCs is one write). 0 = never proven.
+     * Written only by `FretService.noteProofOfLife`; hearsay never touches it.
+     */
+    lastProvenAliveAt: number;
     metadata?: Record<string, unknown>;
     /**
      * This peer's most recent **verified** signed address record — the marshaled libp2p
@@ -137,6 +160,8 @@ export interface SerializedPeerEntry {
     successCount: number;
     failureCount: number;
     avgLatencyMs: number | null;
+    sessionStartedAt?: number;
+    lastProvenAliveAt?: number;
     metadata?: Record<string, unknown>;
     addressRecord?: SerializedAddressRecord;
 }

package/dist/src/store/digitree-store.js

@@ -209,10 +209,13 @@ export class DigitreeStore {
             lastNegotiateFailureAt: 0,
             contactFailures: 0,
             lastContactFailureAt: 0,
+            contactRunStartedAt: 0,
             accessCount: 0,
             successCount: 0,
             failureCount: 0,
-            avgLatencyMs: null
+            avgLatencyMs: null,
+            sessionStartedAt: 0,
+            lastProvenAliveAt: 0
         });
     }
     update(id, patch) {
@@ -442,6 +445,8 @@ export class DigitreeStore {
             successCount: e.successCount,
             failureCount: e.failureCount,
             avgLatencyMs: e.avgLatencyMs,
+            sessionStartedAt: e.sessionStartedAt,
+            lastProvenAliveAt: e.lastProvenAliveAt,
             ...(e.metadata ? { metadata: e.metadata } : {}),
             ...(e.addressRecord ? { addressRecord: serializeAddressRecord(e.addressRecord) } : {}),
         }));
@@ -486,6 +491,7 @@ export class DigitreeStore {
                 // on its very next failure.
                 contactFailures: 0,
                 lastContactFailureAt: 0,
+                contactRunStartedAt: 0,
                 // NOTE: a snapshot taken before frequency credit was narrowed to proven contact
                 // carries an accessCount that also counted mentions, so a restored entry can be
                 // over-credited. Self-correcting — the next scoring call rewrites relevance from
@@ -499,6 +505,12 @@ export class DigitreeStore {
                 // reads back as a genuine 0 ms — accepted, since the next ping overwrites it and
                 // a coercion would instead discard real 0 ms measurements.
                 avgLatencyMs: s.avgLatencyMs ?? null,
+                // Restored rather than reset: tenure is history, and a proof after a restart longer
+                // than the gap tolerance starts a fresh session anyway. NOTE: a tampered file can
+                // inflate it, exactly as it can inflate the imported relevance and counters — table
+                // signing (tickets/backlog/23-debt-routing-table-export-signing.md) closes that class.
+                sessionStartedAt: s.sessionStartedAt ?? 0,
+                lastProvenAliveAt: s.lastProvenAliveAt ?? 0,
                 ...(s.metadata ? { metadata: s.metadata } : {}),
                 ...(addressRecord ? { addressRecord } : {}),
             };

package/dist/src/store/relevance.js

@@ -1,4 +1,5 @@
 import { minDistance, normalizedLogMagnitude } from '../ring/distance.js';
+import { provenTenureMs, stabilityFactor } from './tenure.js';
 export function createSparsityModel(m = 12, sigma = 0.08, alpha = 0.03, beta = 0.6, sMin = 0.7, sMax = 1.8, eps = 1e-6) {
     const centers = [];
     for (let i = 0; i < m; i++)
@@ -86,11 +87,20 @@ function baseRelevance(entry, now) {
         wFreq * frequencyScore(entry) +
         wHealth * healthScore(entry));
 }
+/**
+ * `base · S(x) · stability`: every scoring function's final step. Stability comes from the
+ * entry's *proven* tenure (`store/tenure.ts`), which is 0 — factor 1 — for a brand-new or hearsay
+ * entry, so only a peer this node has itself watched stay up earns the multiplier. A failing peer
+ * is scored with its tenure frozen at the last proof, which is what lets a long-lived server under
+ * maintenance keep its edge at eviction over a fresh peer with similar counters.
+ */
+function weighted(base, entry, x, model) {
+    return base * sparsityBonus(model, x) * stabilityFactor(provenTenureMs(entry));
+}
 export function touch(entry, x, model, now = Date.now()) {
     observeDistance(model, x);
     const base = baseRelevance({ ...entry, accessCount: entry.accessCount + 1 }, now);
-    const bonus = sparsityBonus(model, x);
-    const relevance = base * bonus;
+    const relevance = weighted(base, entry, x, model);
     return {
         ...entry,
         lastAccess: now,
@@ -104,9 +114,7 @@ export function touch(entry, x, model, now = Date.now()) {
  * a distance we accessed.
  */
 export function initialRelevance(entry, x, model, now = Date.now()) {
-    const base = baseRelevance(entry, now);
-    const bonus = sparsityBonus(model, x);
-    return base * bonus;
+    return weighted(baseRelevance(entry, now), entry, x, model);
 }
 /**
  * Blend a new latency sample into a peer's running average.
@@ -142,8 +150,7 @@ export function recordSuccess(entry, latencyMs, x, model, now = Date.now()) {
     observeDistance(model, x);
     const avgLatencyMs = blendLatency(entry.avgLatencyMs, latencyMs);
     const base = baseRelevance({ ...entry, avgLatencyMs, successCount: entry.successCount + 1, accessCount: entry.accessCount + 1 }, now);
-    const bonus = sparsityBonus(model, x);
-    const relevance = base * bonus;
+    const relevance = weighted(base, entry, x, model);
     return {
         ...entry,
         lastAccess: now,
@@ -157,8 +164,7 @@ export function recordFailure(entry, x, model, now = Date.now()) {
     observeDistance(model, x);
     // degrade relevance softly
     const base = baseRelevance({ ...entry, failureCount: entry.failureCount + 1 }, now) * 0.7;
-    const bonus = sparsityBonus(model, x);
-    const relevance = base * bonus;
+    const relevance = weighted(base, entry, x, model);
     return {
         ...entry,
         lastAccess: now,

package/dist/src/store/tenure.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Session tenure: how long this node has *itself* watched a peer stay up, measured from proof of
+ * life only — a pure module with no clock of its own (callers pass `now`) and no service
+ * dependencies, so the rules are unit-testable without sleeps.
+ *
+ * A **session** is a run of proofs of life in which no two consecutive proofs are more than
+ * {@link TENURE_GAP_TOLERANCE_MS} apart. **Proven tenure** is `lastProvenAliveAt −
+ * sessionStartedAt`: the span actually observed, frozen while the peer is silent — it never grows
+ * on the clock alone, so a peer that went quiet gets no credit for the time it was away. The gap
+ * is measured on our clock, so our own downtime past the tolerance restarts every session too: we
+ * cannot vouch for time we did not observe.
+ *
+ * Nothing here is gossiped. Tenure is what *this* node saw, so no other peer can inflate it — the
+ * same rule as frequency credit (`FretService.noteDiscovered`).
+ */
+/**
+ * The longest silence a session survives. Covers "a few minutes of maintenance" with room to
+ * spare, and must stay comfortably above the longest regular contact interval for a peer we
+ * actively watch — the near pass at the idle-backoff cap (60 s) and the dead re-probe window
+ * (at most 32 s) — or a healthy neighbour's session would break on its own. Not longer: a longer
+ * tolerance lets an intermittent peer accumulate tenure across its absences.
+ */
+export declare const TENURE_GAP_TOLERANCE_MS: number;
+/** Below this many ms between stamps, a proof refreshes nothing (write coalescing). */
+export declare const TENURE_STAMP_GRANULARITY_MS = 1000;
+/** Tenure at which the stability factor reaches half its maximum bonus. */
+export declare const STABILITY_HALF_TENURE_MS: number;
+/** Maximum relevance multiplier bonus: factor ∈ [1, 1 + STABILITY_MAX_BONUS). */
+export declare const STABILITY_MAX_BONUS = 0.5;
+/** The two tenure stamps a routing-table entry carries — local-clock unix ms, 0 = never proven. */
+export interface TenureFields {
+    sessionStartedAt: number;
+    lastProvenAliveAt: number;
+}
+/**
+ * The patch a proof of life at `now` implies, or `undefined` when nothing needs writing.
+ *
+ * Continues the current session when the gap since the last proof is within the tolerance
+ * (inclusive); otherwise — never proven, too long a silence, or `now` before the last stamp (the
+ * clock went backwards, or the table came from a skewed clock) — starts a new one at `now`, so
+ * tenure is never negative. A continuing proof less than {@link TENURE_STAMP_GRANULARITY_MS}
+ * after the last stamp writes nothing, so a burst of RPCs costs one store write, not one per
+ * message.
+ */
+export declare function noteProven(cur: TenureFields, now: number): TenureFields | undefined;
+/** Proven tenure in ms: 0 when never proven, and never negative or non-finite. */
+export declare function provenTenureMs(cur: TenureFields): number;
+/**
+ * The relevance multiplier tenure earns: `1 + MAX · t / (t + HALF)` — 1 at zero tenure, about
+ * 1.038 at 5 minutes, 1.25 at an hour, 1.48 at a day. Monotone and bounded below
+ * `1 + STABILITY_MAX_BONUS`, so tenure can tip a close eviction but never dominate the other
+ * relevance terms.
+ */
+export declare function stabilityFactor(tenureMs: number): number;
+/** Below this proven tenure a peer gets no dead-verdict grace: newcomers keep the fast verdict. */
+export declare const DEAD_GRACE_MIN_TENURE_MS: number;
+/**
+ * Grace earned per unit of proven tenure: a peer we have watched stay up for T is given T/12 to
+ * come back before it is declared dead. A judgement call, not a measurement — Lindy-shaped: the
+ * longer a peer has been up, the longer an absence is still plausibly "brief".
+ */
+export declare const DEAD_GRACE_TENURE_RATIO: number;
+/**
+ * How long a contact-failure run against a peer with `tenureMs` of proven tenure must last before
+ * the peer may be marked `dead`, capped at `capMs` (`FretConfig.maxDeadGraceMs`; 0 disables grace).
+ *
+ * 0 below {@link DEAD_GRACE_MIN_TENURE_MS}, so a phone that appeared five minutes ago is judged
+ * exactly as before; at the default 5-minute cap, 50 s at 10 minutes of tenure, 2.5 minutes at
+ * 30, and the full cap from an hour on. Strike count alone cannot do this — strikes arrive at the
+ * stabilization pass rate, so a larger count stretches seconds, not minutes.
+ */
+export declare function deadGraceMs(tenureMs: number, capMs: number): number;