@antseed/cli 0.1.143 → 0.1.145

package/dist/proxy/peer-attribution.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Deciding whether a failed request is the *peer's* fault.
+ *
+ * The dispatch path funnels nearly every error into a single catch, where a
+ * dead seller is indistinguishable from a dropped wifi connection, a suspended
+ * laptop, an unreachable chain RPC, or one of our own state-machine bugs. If we
+ * cooled a peer down on every failure, closing the laptop lid would exile the
+ * entire peer set — and the cooldown is persisted, so it would survive the
+ * restart too.
+ *
+ * So attribution is evidence-based and fails safe: a failure escalates a peer's
+ * cooldown only when we have positive evidence that the buyer itself is
+ * healthy. Three independent gates provide that evidence, and each one alone is
+ * enough to stop a buyer-side outage from mass-penalizing innocent peers.
+ */
+/** A success on another peer older than this no longer vouches for the buyer. */
+export declare const CORROBORATION_WINDOW_MS: number;
+/** Distinct peers that must fail together before we blame ourselves instead. */
+export declare const CORRELATED_DISTINCT_PEERS = 3;
+/** How close together those failures must land to count as one outage. */
+export declare const CORRELATION_WINDOW_MS = 60000;
+/** How long we keep suppressing after concluding the buyer is the problem. */
+export declare const CORRELATION_SUPPRESSION_MS = 60000;
+/** Heartbeat cadence used to notice the wall clock jumping forward. */
+export declare const HEARTBEAT_MS = 10000;
+/** Extra slack past the heartbeat before a gap reads as suspend, not lag. */
+export declare const SUSPEND_JUMP_MS = 30000;
+/** Quarantine after a detected suspend, covering the wake-up failure storm. */
+export declare const SUSPEND_QUARANTINE_MS = 60000;
+/**
+ * Slack applied before the last good heartbeat when rolling back a suspend. The
+ * failures that matter are the ones recorded during the untrusted gap, plus any
+ * that landed just as the machine was going down.
+ */
+export declare const ROLLBACK_LOOKBACK_MS = 15000;
+export type AttributionSuppressionReason = 'no-corroborating-success' | 'correlated-failure' | 'suspend-detected' | 'buyer-fault' | 'non-escalating-reason';
+export type AttributionVerdict = {
+    escalate: true;
+} | {
+    escalate: false;
+    suppressedBy: AttributionSuppressionReason;
+};
+export type AttributionInput = {
+    peerId: string;
+    /** False for reasons that are informational only, e.g. 429 or a buyer fault. */
+    reasonEscalates: boolean;
+    /** Fault attribution derived from the thrown error, when it is known. */
+    fault?: 'buyer' | 'peer' | 'unknown';
+    now: number;
+};
+export type AttributionSnapshot = {
+    lastAnySuccessAt: number;
+    /** 0 when not currently suppressing. */
+    suppressedUntil: number;
+    lastSuppressedBy: AttributionSuppressionReason | null;
+};
+/**
+ * Tracks the buyer-health evidence needed to attribute failures. Deliberately
+ * holds no peer-health state of its own: it answers "may this failure count
+ * against the peer?" and hands back the set of peers whose recent failures the
+ * caller should roll back when it turns out the buyer was the problem.
+ */
+export declare class PeerAttributionTracker {
+    private _lastAnySuccessAt;
+    private readonly _lastSuccessByPeer;
+    private _recentFailures;
+    private _suppressedUntil;
+    private _lastSuppressedBy;
+    private _lastHeartbeatAt;
+    /**
+     * Record proof of life. Any HTTP response from a peer counts, including error
+     * statuses — the peer answered, so our network, DHT, RPC and wallet are fine.
+     */
+    recordSuccess(peerId: string, now: number): void;
+    /**
+     * Decide whether a failure may escalate, and register it toward correlation
+     * detection. Returns the peers to roll back when this failure is the one that
+     * reveals a buyer-side outage.
+     */
+    classify(input: AttributionInput): {
+        verdict: AttributionVerdict;
+        rollbackPeerIds: string[];
+    };
+    /**
+     * Heartbeat tick. A wall-clock gap far larger than the cadence means the
+     * process was suspended; every pending timeout and keepalive fires at once on
+     * wake, so quarantine and roll back the resulting storm.
+     *
+     * Returns the peers to roll back, or null when nothing unusual happened.
+     */
+    onHeartbeat(now: number): {
+        rollbackPeerIds: string[];
+    } | null;
+    snapshot(now: number): AttributionSnapshot;
+    /** Whether the buyer currently has evidence it is healthy at all. */
+    isBuyerHealthy(now: number): boolean;
+    private _hasCorroboratingSuccess;
+    private _pruneFailures;
+}
+//# sourceMappingURL=peer-attribution.d.ts.map

package/dist/proxy/peer-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-attribution.d.ts","sourceRoot":"","sources":["../../src/proxy/peer-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,QAAc,CAAA;AAClD,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,IAAI,CAAA;AAC1C,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,QAAS,CAAA;AAC3C,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,QAAS,CAAA;AAChD,uEAAuE;AACvE,eAAO,MAAM,YAAY,QAAS,CAAA;AAClC,6EAA6E;AAC7E,eAAO,MAAM,eAAe,QAAS,CAAA;AACrC,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAAS,CAAA;AAC3C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAS,CAAA;AAE1C,MAAM,MAAM,4BAA4B,GACpC,0BAA0B,GAC1B,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,uBAAuB,CAAA;AAE3B,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAClB;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,4BAA4B,CAAA;CAAE,CAAA;AAEnE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,eAAe,EAAE,OAAO,CAAA;IACxB,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAID,MAAM,MAAM,mBAAmB,GAAG;IAChC,gBAAgB,EAAE,MAAM,CAAA;IACxB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,4BAA4B,GAAG,IAAI,CAAA;CACtD,CAAA;AAKD;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,iBAAiB,CAAI;IAC7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4B;IAC/D,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,gBAAgB,CAAI;IAC5B,OAAO,CAAC,iBAAiB,CAA4C;IACrE,OAAO,CAAC,gBAAgB,CAAsB;IAE9C;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAYhD;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG;QAAE,OAAO,EAAE,kBAAkB,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE;IAsD7F;;;;;;OAMG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI;IAyB9D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB;IAQ1C,qEAAqE;IACrE,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAMpC,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,cAAc;CAMvB"}

package/dist/proxy/peer-attribution.js

@@ -0,0 +1,175 @@
+/**
+ * Deciding whether a failed request is the *peer's* fault.
+ *
+ * The dispatch path funnels nearly every error into a single catch, where a
+ * dead seller is indistinguishable from a dropped wifi connection, a suspended
+ * laptop, an unreachable chain RPC, or one of our own state-machine bugs. If we
+ * cooled a peer down on every failure, closing the laptop lid would exile the
+ * entire peer set — and the cooldown is persisted, so it would survive the
+ * restart too.
+ *
+ * So attribution is evidence-based and fails safe: a failure escalates a peer's
+ * cooldown only when we have positive evidence that the buyer itself is
+ * healthy. Three independent gates provide that evidence, and each one alone is
+ * enough to stop a buyer-side outage from mass-penalizing innocent peers.
+ */
+/** A success on another peer older than this no longer vouches for the buyer. */
+export const CORROBORATION_WINDOW_MS = 10 * 60_000;
+/** Distinct peers that must fail together before we blame ourselves instead. */
+export const CORRELATED_DISTINCT_PEERS = 3;
+/** How close together those failures must land to count as one outage. */
+export const CORRELATION_WINDOW_MS = 60_000;
+/** How long we keep suppressing after concluding the buyer is the problem. */
+export const CORRELATION_SUPPRESSION_MS = 60_000;
+/** Heartbeat cadence used to notice the wall clock jumping forward. */
+export const HEARTBEAT_MS = 10_000;
+/** Extra slack past the heartbeat before a gap reads as suspend, not lag. */
+export const SUSPEND_JUMP_MS = 30_000;
+/** Quarantine after a detected suspend, covering the wake-up failure storm. */
+export const SUSPEND_QUARANTINE_MS = 60_000;
+/**
+ * Slack applied before the last good heartbeat when rolling back a suspend. The
+ * failures that matter are the ones recorded during the untrusted gap, plus any
+ * that landed just as the machine was going down.
+ */
+export const ROLLBACK_LOOKBACK_MS = 15_000;
+/** Bound on remembered per-peer successes; only the freshest ones matter. */
+const MAX_TRACKED_SUCCESS_PEERS = 512;
+/**
+ * Tracks the buyer-health evidence needed to attribute failures. Deliberately
+ * holds no peer-health state of its own: it answers "may this failure count
+ * against the peer?" and hands back the set of peers whose recent failures the
+ * caller should roll back when it turns out the buyer was the problem.
+ */
+export class PeerAttributionTracker {
+    _lastAnySuccessAt = 0;
+    _lastSuccessByPeer = new Map();
+    _recentFailures = [];
+    _suppressedUntil = 0;
+    _lastSuppressedBy = null;
+    _lastHeartbeatAt = null;
+    /**
+     * Record proof of life. Any HTTP response from a peer counts, including error
+     * statuses — the peer answered, so our network, DHT, RPC and wallet are fine.
+     */
+    recordSuccess(peerId, now) {
+        // Re-insert so map order stays least-recently-successful first.
+        this._lastSuccessByPeer.delete(peerId);
+        this._lastSuccessByPeer.set(peerId, now);
+        while (this._lastSuccessByPeer.size > MAX_TRACKED_SUCCESS_PEERS) {
+            const oldest = this._lastSuccessByPeer.keys().next();
+            if (oldest.done)
+                break;
+            this._lastSuccessByPeer.delete(oldest.value);
+        }
+        if (now > this._lastAnySuccessAt)
+            this._lastAnySuccessAt = now;
+    }
+    /**
+     * Decide whether a failure may escalate, and register it toward correlation
+     * detection. Returns the peers to roll back when this failure is the one that
+     * reveals a buyer-side outage.
+     */
+    classify(input) {
+        const { peerId, reasonEscalates, fault, now } = input;
+        if (fault === 'buyer') {
+            return { verdict: { escalate: false, suppressedBy: 'buyer-fault' }, rollbackPeerIds: [] };
+        }
+        if (!reasonEscalates) {
+            return { verdict: { escalate: false, suppressedBy: 'non-escalating-reason' }, rollbackPeerIds: [] };
+        }
+        this._pruneFailures(now);
+        this._recentFailures.push({ peerId, at: now });
+        // Gate 1c: the machine slept. Nothing recorded around the wake-up is
+        // trustworthy, including failures that landed just before we noticed.
+        if (now < this._suppressedUntil && this._lastSuppressedBy === 'suspend-detected') {
+            return {
+                verdict: { escalate: false, suppressedBy: 'suspend-detected' },
+                rollbackPeerIds: [],
+            };
+        }
+        // Gate 1b: several distinct peers failing at once means the common factor
+        // is us. Trip suppression and undo what this outage already recorded.
+        const distinctPeers = new Set(this._recentFailures.map((f) => f.peerId));
+        if (distinctPeers.size >= CORRELATED_DISTINCT_PEERS) {
+            this._suppressedUntil = now + CORRELATION_SUPPRESSION_MS;
+            this._lastSuppressedBy = 'correlated-failure';
+            return {
+                verdict: { escalate: false, suppressedBy: 'correlated-failure' },
+                rollbackPeerIds: [...distinctPeers],
+            };
+        }
+        if (now < this._suppressedUntil) {
+            return {
+                verdict: { escalate: false, suppressedBy: this._lastSuppressedBy ?? 'correlated-failure' },
+                rollbackPeerIds: [],
+            };
+        }
+        // Gate 1a: without a recent success on some *other* peer we have no proof
+        // the buyer is healthy, so we cannot fairly blame this one. A buyer that
+        // only ever talks to one peer never escalates it — correct, since there is
+        // nothing to fail over to anyway.
+        if (!this._hasCorroboratingSuccess(peerId, now)) {
+            return {
+                verdict: { escalate: false, suppressedBy: 'no-corroborating-success' },
+                rollbackPeerIds: [],
+            };
+        }
+        return { verdict: { escalate: true }, rollbackPeerIds: [] };
+    }
+    /**
+     * Heartbeat tick. A wall-clock gap far larger than the cadence means the
+     * process was suspended; every pending timeout and keepalive fires at once on
+     * wake, so quarantine and roll back the resulting storm.
+     *
+     * Returns the peers to roll back, or null when nothing unusual happened.
+     */
+    onHeartbeat(now) {
+        const previous = this._lastHeartbeatAt;
+        this._lastHeartbeatAt = now;
+        if (previous === null)
+            return null;
+        const elapsed = now - previous;
+        if (elapsed <= HEARTBEAT_MS + SUSPEND_JUMP_MS)
+            return null;
+        this._suppressedUntil = now + SUSPEND_QUARANTINE_MS;
+        this._lastSuppressedBy = 'suspend-detected';
+        // Everything recorded since the last trustworthy tick is suspect: the
+        // suspend itself is what killed those requests, not the peers.
+        const untrustedFrom = previous - ROLLBACK_LOOKBACK_MS;
+        const rollbackPeerIds = [
+            ...new Set(this._recentFailures
+                .filter((f) => f.at >= untrustedFrom)
+                .map((f) => f.peerId)),
+        ];
+        this._recentFailures = [];
+        return { rollbackPeerIds };
+    }
+    snapshot(now) {
+        return {
+            lastAnySuccessAt: this._lastAnySuccessAt,
+            suppressedUntil: now < this._suppressedUntil ? this._suppressedUntil : 0,
+            lastSuppressedBy: this._lastSuppressedBy,
+        };
+    }
+    /** Whether the buyer currently has evidence it is healthy at all. */
+    isBuyerHealthy(now) {
+        return now >= this._suppressedUntil
+            && this._lastAnySuccessAt > 0
+            && now - this._lastAnySuccessAt <= CORROBORATION_WINDOW_MS;
+    }
+    _hasCorroboratingSuccess(failedPeerId, now) {
+        for (const [peerId, at] of this._lastSuccessByPeer) {
+            if (peerId === failedPeerId)
+                continue;
+            if (now - at <= CORROBORATION_WINDOW_MS && at <= now)
+                return true;
+        }
+        return false;
+    }
+    _pruneFailures(now) {
+        // A backwards clock jump would otherwise strand marks in the buffer.
+        this._recentFailures = this._recentFailures.filter((f) => f.at <= now && now - f.at <= CORRELATION_WINDOW_MS);
+    }
+}
+//# sourceMappingURL=peer-attribution.js.map

package/dist/proxy/peer-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-attribution.js","sourceRoot":"","sources":["../../src/proxy/peer-attribution.ts"],"names":[],"mappings":"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"}

package/dist/proxy/peer-attribution.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=peer-attribution.test.d.ts.map

package/dist/proxy/peer-attribution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-attribution.test.d.ts","sourceRoot":"","sources":["../../src/proxy/peer-attribution.test.ts"],"names":[],"mappings":""}

package/dist/proxy/peer-attribution.test.js

@@ -0,0 +1,140 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { PeerAttributionTracker, CORROBORATION_WINDOW_MS, CORRELATION_WINDOW_MS, HEARTBEAT_MS, SUSPEND_JUMP_MS, } from './peer-attribution.js';
+const A = 'a'.repeat(40);
+const B = 'b'.repeat(40);
+const C = 'c'.repeat(40);
+const D = 'd'.repeat(40);
+function fail(tracker, peerId, now) {
+    return tracker.classify({ peerId, reasonEscalates: true, fault: 'unknown', now });
+}
+test('a failure never escalates without a prior success anywhere', () => {
+    const tracker = new PeerAttributionTracker();
+    const { verdict } = fail(tracker, A, 1_000_000);
+    assert.deepEqual(verdict, { escalate: false, suppressedBy: 'no-corroborating-success' });
+});
+test('a recent success on another peer lets the failure escalate', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(B, 1_000_000);
+    const { verdict } = fail(tracker, A, 1_001_000);
+    assert.deepEqual(verdict, { escalate: true });
+});
+test('a success on the failing peer itself does not vouch for the buyer', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(A, 1_000_000);
+    const { verdict } = fail(tracker, A, 1_001_000);
+    assert.deepEqual(verdict, { escalate: false, suppressedBy: 'no-corroborating-success' });
+});
+test('a success older than the corroboration window stops vouching', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(B, 1_000_000);
+    const { verdict } = fail(tracker, A, 1_000_000 + CORROBORATION_WINDOW_MS + 1);
+    assert.deepEqual(verdict, { escalate: false, suppressedBy: 'no-corroborating-success' });
+});
+test('three distinct peers failing together blames the buyer and rolls them back', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    assert.deepEqual(fail(tracker, A, 1_000_100).verdict, { escalate: true });
+    assert.deepEqual(fail(tracker, B, 1_000_200).verdict, { escalate: true });
+    const third = fail(tracker, C, 1_000_300);
+    assert.deepEqual(third.verdict, { escalate: false, suppressedBy: 'correlated-failure' });
+    assert.deepEqual([...third.rollbackPeerIds].sort(), [A, B, C].sort());
+});
+test('repeated failures on a single peer do not trip correlation suppression', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    for (let i = 1; i <= 5; i += 1) {
+        const { verdict } = fail(tracker, A, 1_000_000 + i * 1_000);
+        assert.deepEqual(verdict, { escalate: true }, `failure ${i} should still escalate`);
+    }
+});
+test('failures spread beyond the correlation window are not correlated', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    // Three distinct peers, but far enough apart that they are three separate
+    // incidents rather than one buyer-side outage. Each is judged on its own.
+    const spacing = CORRELATION_WINDOW_MS + 1_000;
+    assert.deepEqual(fail(tracker, A, 1_000_100).verdict, { escalate: true });
+    assert.deepEqual(fail(tracker, B, 1_000_100 + spacing).verdict, { escalate: true });
+    assert.deepEqual(fail(tracker, C, 1_000_100 + spacing * 2).verdict, { escalate: true });
+});
+test('suppression persists for the window after a correlation trip', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    fail(tracker, A, 1_000_100);
+    fail(tracker, B, 1_000_200);
+    fail(tracker, C, 1_000_300);
+    const later = fail(tracker, A, 1_000_400);
+    assert.deepEqual(later.verdict, { escalate: false, suppressedBy: 'correlated-failure' });
+});
+test('a buyer-attributed fault never escalates, even with corroboration', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(B, 1_000_000);
+    const { verdict } = tracker.classify({
+        peerId: A, reasonEscalates: true, fault: 'buyer', now: 1_001_000,
+    });
+    assert.deepEqual(verdict, { escalate: false, suppressedBy: 'buyer-fault' });
+});
+test('a non-escalating reason is recorded but never cools a peer down', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(B, 1_000_000);
+    const { verdict } = tracker.classify({
+        peerId: A, reasonEscalates: false, fault: 'peer', now: 1_001_000,
+    });
+    assert.deepEqual(verdict, { escalate: false, suppressedBy: 'non-escalating-reason' });
+});
+test('a wall-clock jump reads as suspend, quarantines, and rolls back the storm', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    assert.equal(tracker.onHeartbeat(1_000_000), null);
+    // Two peers fail as the machine goes down; the jump is noticed on the next tick.
+    fail(tracker, A, 1_000_100);
+    fail(tracker, B, 1_000_200);
+    const wake = 1_000_200 + HEARTBEAT_MS + SUSPEND_JUMP_MS + 1_000;
+    const result = tracker.onHeartbeat(wake);
+    assert.ok(result, 'expected the clock jump to be detected');
+    assert.deepEqual([...result.rollbackPeerIds].sort(), [A, B].sort());
+    const afterWake = fail(tracker, C, wake + 100);
+    assert.deepEqual(afterWake.verdict, { escalate: false, suppressedBy: 'suspend-detected' });
+});
+test('a normal heartbeat cadence is not mistaken for suspend', () => {
+    const tracker = new PeerAttributionTracker();
+    assert.equal(tracker.onHeartbeat(1_000_000), null);
+    assert.equal(tracker.onHeartbeat(1_000_000 + HEARTBEAT_MS), null);
+    assert.equal(tracker.onHeartbeat(1_000_000 + HEARTBEAT_MS * 2 + 500), null);
+});
+test('isBuyerHealthy tracks corroboration and suppression', () => {
+    const tracker = new PeerAttributionTracker();
+    assert.equal(tracker.isBuyerHealthy(1_000_000), false);
+    tracker.recordSuccess(B, 1_000_000);
+    assert.equal(tracker.isBuyerHealthy(1_000_100), true);
+    assert.equal(tracker.isBuyerHealthy(1_000_000 + CORROBORATION_WINDOW_MS + 1), false);
+    fail(tracker, A, 1_000_100);
+    fail(tracker, B, 1_000_200);
+    fail(tracker, C, 1_000_300);
+    assert.equal(tracker.isBuyerHealthy(1_000_400), false);
+});
+test('snapshot reports the active suppression window and clears once it lapses', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 1_000_000);
+    fail(tracker, A, 1_000_100);
+    fail(tracker, B, 1_000_200);
+    fail(tracker, C, 1_000_300);
+    const during = tracker.snapshot(1_000_400);
+    assert.ok(during.suppressedUntil > 1_000_400);
+    assert.equal(during.lastSuppressedBy, 'correlated-failure');
+    assert.equal(during.lastAnySuccessAt, 1_000_000);
+    const after = tracker.snapshot(1_000_300 + 120_000);
+    assert.equal(after.suppressedUntil, 0);
+});
+test('a backwards clock jump does not strand failures in the correlation buffer', () => {
+    const tracker = new PeerAttributionTracker();
+    tracker.recordSuccess(D, 2_000_000);
+    fail(tracker, A, 2_000_100);
+    fail(tracker, B, 2_000_200);
+    // Clock steps backwards past the earlier marks; they must be discarded, so
+    // this third distinct peer does not trip correlation on stale data.
+    const { verdict } = fail(tracker, C, 1_000_000);
+    assert.notEqual(verdict.escalate === false ? verdict.suppressedBy : null, 'correlated-failure');
+});
+//# sourceMappingURL=peer-attribution.test.js.map

package/dist/proxy/peer-attribution.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-attribution.test.js","sourceRoot":"","sources":["../../src/proxy/peer-attribution.test.ts"],"names":[],"mappings":"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"}

package/dist/proxy/peer-health.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Per-peer failure bookkeeping and cooldown state for the buyer proxy.
+ *
+ * A peer that stops responding should stop being picked, but only temporarily:
+ * peers go offline for legitimate reasons, so there is no permanent auto-ban.
+ * Whether a failure is even allowed to escalate is decided separately, by
+ * `peer-attribution.ts` — this module owns the state machine, not the blame.
+ *
+ * Cooldown is always advisory. The proxy still dispatches to a cooling-down
+ * peer when a request names it, so a pinned conversation keeps working and no
+ * amount of cooldown can deadlock routing.
+ */
+/** Failures older than this start a fresh streak rather than compounding. */
+export declare const PEER_HEALTH_WINDOW_MS: number;
+/** Concurrent requests failing together count as one episode, not several. */
+export declare const PEER_HEALTH_COALESCE_MS = 1000;
+/** Ceiling on any single cooldown, and the sanity bound for persisted values. */
+export declare const PEER_HEALTH_MAX_COOLDOWN_MS: number;
+/** How long an idle entry is kept before it is forgotten entirely. */
+export declare const PEER_HEALTH_RETENTION_MS: number;
+/** Upper bound on tracked peers, newest failures retained. */
+export declare const PEER_HEALTH_MAX_ENTRIES = 512;
+export type PeerFailureReason = 
+/** Transport threw, timed out, or the connection died mid-request. */
+'request-failed'
+/** Seller answered 500/502/503/504. */
+ | 'seller-5xx'
+/** Seller answered 408. */
+ | 'seller-timeout'
+/** Seller answered 429 — capacity pressure, not death. Never escalates. */
+ | 'seller-busy'
+/** Our own wallet, deposits, config or state machine. Never escalates. */
+ | 'buyer-local';
+/** Whether a reason is even a candidate for cooling a peer down. */
+export declare function reasonEscalates(reason: PeerFailureReason): boolean;
+export type PeerHealthEntry = {
+    failureStreak: number;
+    windowStartedAt: number;
+    /** Start of the current coalesced failure episode. */
+    episodeStartedAt: number;
+    lastFailureAt: number;
+    lastReason: PeerFailureReason;
+    /** 0 when the peer is not cooling down. */
+    cooldownUntil: number;
+    /** 0 when the peer has never answered us. */
+    lastSuccessAt: number;
+};
+export declare function computeCooldownMs(failureStreak: number): number;
+/**
+ * Fold a failure into a peer's health.
+ *
+ * `escalate` comes from the attribution gates: when false the failure is still
+ * recorded for diagnostics and UI, but the streak and cooldown stay put.
+ */
+export declare function recordPeerFailureEntry(previous: PeerHealthEntry | undefined, reason: PeerFailureReason, now: number, escalate: boolean): PeerHealthEntry;
+/**
+ * Any response from a peer is proof of life, so a success wipes the streak and
+ * releases the cooldown. `lastSuccessAt` is kept for diagnostics.
+ */
+export declare function clearPeerHealthEntry(previous: PeerHealthEntry | undefined, now: number): PeerHealthEntry;
+export declare function isCoolingDown(entry: PeerHealthEntry | undefined, now: number): boolean;
+/** Drop stale entries and cap the map, keeping the most recently active peers. */
+export declare function prunePeerHealth(entries: Map<string, PeerHealthEntry>, now: number): Map<string, PeerHealthEntry>;
+/**
+ * Parse the `peerHealth` map out of a buyer.state.json blob.
+ *
+ * Cooldown survives a restart — a peer that died ten seconds before we exited is
+ * still dead — but is never extended or resurrected by one: anything expired,
+ * impossibly far in the future, or stamped after `now` is discarded.
+ */
+export declare function parsePersistedPeerHealth(parsed: unknown, now?: number): Map<string, PeerHealthEntry>;
+export declare function serializePeerHealth(entries: Map<string, PeerHealthEntry>): Record<string, PeerHealthEntry>;
+//# sourceMappingURL=peer-health.d.ts.map

package/dist/proxy/peer-health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-health.d.ts","sourceRoot":"","sources":["../../src/proxy/peer-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAUH,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAC/C,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,OAAQ,CAAA;AAC5C,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,QAAa,CAAA;AACrD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAAmB,CAAA;AACxD,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAE1C,MAAM,MAAM,iBAAiB;AAC3B,sEAAsE;AACpE,gBAAgB;AAClB,uCAAuC;GACrC,YAAY;AACd,2BAA2B;GACzB,gBAAgB;AAClB,2EAA2E;GACzE,aAAa;AACf,0EAA0E;GACxE,aAAa,CAAA;AAMjB,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAElE;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,iBAAiB,CAAA;IAC7B,2CAA2C;IAC3C,aAAa,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAA;CACtB,CAAA;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAI/D;AAcD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,MAAM,EAAE,iBAAiB,EACzB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,GAChB,eAAe,CA+BjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,eAAe,GAAG,SAAS,EACrC,GAAG,EAAE,MAAM,GACV,eAAe,CASjB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAItF;AAUD,kFAAkF;AAClF,wBAAgB,eAAe,CAC7B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACrC,GAAG,EAAE,MAAM,GACV,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAS9B;AAMD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,EACf,GAAG,GAAE,MAAmB,GACvB,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CA+C9B;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAEjC"}