@optimystic/db-p2p 0.14.1 → 0.16.3

package/dist/src/storage/ring-selector.js

@@ -1,4 +1,14 @@
 import { hashPeerId } from 'p2p-fret';
+import { peerIdFromString } from '@libp2p/peer-id';
+import { extractPrefix } from './arachnode-partition.js';
+/** EWMA weight for the demand inputs. Higher = more reactive, lower = smoother. */
+const DEFAULT_SMOOTHING_ALPHA = 0.2;
+/** Hysteresis half-width in rings. 0.5 puts a full ring between the move-out and move-in triggers. */
+const DEFAULT_DEADBAND = 0.5;
+/** Minimum time (ms) at a ring after a move is triggered before another may start. */
+const DEFAULT_MIN_DWELL_MS = 10 * 60 * 1000;
+/** Floor for smoothed coverage so `-log2` never sees 0; the [0,16] clamp bounds the result anyway. */
+const DEPTH_EPSILON = 1e-12;
 /**
  * Determines appropriate ring depth based on storage capacity and network demand.
  *
@@ -7,18 +17,36 @@ import { hashPeerId } from 'p2p-fret';
  * - Ring N: 2^N partitions
  *
  * A node selects its ring based on: available_capacity / estimated_neighborhood_demand
+ *
+ * The transition decision ({@link shouldTransition}) is damped so it does not thrash near a ring
+ * boundary: the demand signal is smoothed with an EWMA, a dead-band keeps a hovering ratio from
+ * moving, and a minimum-dwell timer + single-step rule bound how often and how far it moves. See
+ * `docs/arachnode-ring-handoff.md` § Part 1.
  */
 export class RingSelector {
     fretAdapter;
     storageMonitor;
     config;
+    /** EWMA of available capacity (bytes). Undefined until the first sample seeds it. */
+    smoothedAvailable;
+    /** EWMA of estimated total network data (bytes). Undefined until the first sample seeds it. */
+    smoothedTotalData;
+    /** Clock time (ms) a move was last triggered; undefined = no move yet, so dwell does not block. */
+    lastMoveAt;
+    now;
     constructor(fretAdapter, storageMonitor, config) {
         this.fretAdapter = fretAdapter;
         this.storageMonitor = storageMonitor;
         this.config = config;
+        this.now = config.now ?? (() => Date.now());
     }
     /**
-     * Determine appropriate ring depth based on capacity and demand.
+     * Determine appropriate ring depth from an instantaneous capacity + demand snapshot.
+     *
+     * This is the *undamped* reading used for the deterministic first-boot ring and anywhere a
+     * one-shot estimate is wanted. The damped transition logic lives in {@link shouldTransition};
+     * this method intentionally does not touch the EWMA state so its result is a pure function of
+     * the current snapshot.
      */
     async determineRing() {
         const capacity = await this.storageMonitor.getCapacity();
@@ -26,14 +54,31 @@ export class RingSelector {
             // Not enough capacity for any ring
             return -1;
         }
-        // Estimate total network spare capacity by aggregating observed per-ring stats.
-        // See docs/arachnode.md §"Capacity Management and Ring Adjustment": ring selection
-        // should reflect observed network demand, not a hard-coded constant. We treat
-        // Σ (peerCount × avgCapacity) over known rings as a proxy for total network spare
-        // capacity, so `coverage` becomes our share of it. More peers (or richer peers) →
-        // smaller share → higher ring depth (more specialization). On bootstrap, when no
-        // ring stats are observed yet, we fall back to a conservative fixed estimate so
-        // first-boot behavior is deterministic.
+        const estimatedTotalData = this.estimateNetworkData(capacity.available);
+        // Calculate what fraction of keyspace we can cover
+        const coverage = capacity.available / estimatedTotalData;
+        // Ring depth: 0 = full keyspace, N = 2^N partitions
+        // If coverage = 0.01 (1%), we need ~100 partitions ≈ Ring 7
+        // If coverage = 1.0 (100%), we can handle full keyspace = Ring 0
+        const ringDepth = Math.max(0, Math.ceil(-Math.log2(Math.max(0.001, coverage))));
+        return Math.min(ringDepth, 16); // Cap at Ring 16 (65536 partitions)
+    }
+    // NOTE: prefix extraction lives in `arachnode-partition.ts` (single source of truth shared with
+    // the block-side responsibility derivation in RestorationCoordinator / RingShiftCoordinator).
+    /**
+     * Estimate total network spare capacity (bytes) by aggregating observed per-ring stats.
+     *
+     * See docs/arachnode.md §"Capacity Management and Ring Adjustment": ring selection should
+     * reflect observed network demand, not a hard-coded constant. We treat Σ (peerCount ×
+     * avgCapacity) over known rings as a proxy for total network spare capacity, so `coverage`
+     * becomes our share of it. More peers (or richer peers) → smaller share → higher ring depth
+     * (more specialization). On bootstrap, when no ring stats are observed yet, we fall back to a
+     * conservative fixed estimate so first-boot behavior is deterministic.
+     *
+     * @param availableForFallback local available bytes, used only for the pathological
+     * zero-aggregate case (e.g. all peers report 0 available) so coverage collapses to 1.0 (ring 0).
+     */
+    estimateNetworkData(availableForFallback) {
         const ringStats = this.fretAdapter.getRingStats();
         let estimatedTotalData;
         if (ringStats.length > 0) {
@@ -44,18 +89,34 @@ export class RingSelector {
             const estimatedTotalBlocks = 1000; // Conservative estimate
             estimatedTotalData = estimatedTotalBlocks * avgBlockSize;
         }
-        // Guard against pathological zero-aggregate (e.g. all peers report 0 available);
-        // fall back to local capacity so coverage = 1.0 (ring 0).
         if (estimatedTotalData <= 0) {
-            estimatedTotalData = capacity.available;
+            estimatedTotalData = availableForFallback;
         }
-        // Calculate what fraction of keyspace we can cover
-        const coverage = capacity.available / estimatedTotalData;
-        // Ring depth: 0 = full keyspace, N = 2^N partitions
-        // If coverage = 0.01 (1%), we need ~100 partitions ≈ Ring 7
-        // If coverage = 1.0 (100%), we can handle full keyspace = Ring 0
-        const ringDepth = Math.max(0, Math.ceil(-Math.log2(Math.max(0.001, coverage))));
-        return Math.min(ringDepth, 16); // Cap at Ring 16 (65536 partitions)
+        return estimatedTotalData;
+    }
+    /**
+     * Fold one sample into the EWMA of each demand input. Seeds from the first real sample rather
+     * than from 0 — a 0 seed would drag the smoothed depth for many ticks.
+     */
+    updateSmoothing(available, totalData) {
+        const alpha = this.config.smoothingAlpha ?? DEFAULT_SMOOTHING_ALPHA;
+        this.smoothedAvailable = this.smoothedAvailable === undefined
+            ? available
+            : alpha * available + (1 - alpha) * this.smoothedAvailable;
+        this.smoothedTotalData = this.smoothedTotalData === undefined
+            ? totalData
+            : alpha * totalData + (1 - alpha) * this.smoothedTotalData;
+    }
+    /**
+     * Continuous smoothed ring depth `d = clamp(-log2(smoothedCoverage), 0, 16)` from the current
+     * EWMA state. Returns 0 (ring 0) if no sample has been folded in yet.
+     */
+    smoothedDepth() {
+        const available = this.smoothedAvailable ?? 0;
+        const totalData = this.smoothedTotalData ?? 0;
+        const coverage = totalData > 0 ? available / totalData : 1;
+        const depth = -Math.log2(Math.max(DEPTH_EPSILON, coverage));
+        return Math.min(16, Math.max(0, depth));
     }
     /**
      * Calculate partition for a given ring depth and peer ID.
@@ -64,19 +125,27 @@ export class RingSelector {
         if (ringDepth === 0) {
             return undefined; // Full keyspace, no partition
         }
-        // Hash peer ID to get coordinate
-        const coord = await hashPeerId({ toString: () => peerId });
-        // Extract prefix bits from coordinate
+        // Hash peer ID to get coordinate. hashPeerId reads `peerId.toMultihash().bytes`, so it
+        // needs a real PeerId — reconstruct one from the string. Peers must occupy the SAME ring
+        // coordinate FRET uses to place them (hashPeerId(peerId)), or restoration's block-prefix
+        // vs peer-prefix comparison stops meaning "this peer owns this block's slice".
+        const coord = await hashPeerId(peerIdFromString(peerId));
+        // Extract prefix bits from coordinate (shared with block-side responsibility derivation).
         const prefixBits = ringDepth;
-        const prefixValue = this.extractPrefix(coord, prefixBits);
+        const prefixValue = extractPrefix(coord, prefixBits);
         return { prefixBits, prefixValue };
     }
     /**
      * Create Arachnode info for this node.
+     *
+     * @param ringDepthOverride when supplied (e.g. the single-step target from
+     * {@link shouldTransition}), the node advertises exactly this ring instead of a freshly
+     * recomputed {@link determineRing}. The transition site passes it so the advertised ring can
+     * never disagree with the ring the transition decision just chose.
      */
-    async createArachnodeInfo(peerId) {
+    async createArachnodeInfo(peerId, ringDepthOverride) {
         const capacity = await this.storageMonitor.getCapacity();
-        const ringDepth = await this.determineRing();
+        const ringDepth = ringDepthOverride ?? await this.determineRing();
         const partition = ringDepth >= 0
             ? await this.calculatePartition(ringDepth, peerId)
             : undefined;
@@ -92,45 +161,78 @@ export class RingSelector {
         };
     }
     /**
-     * Monitor capacity and determine if ring transition is needed.
+     * Decide whether a damped ring transition should start.
+     *
+     * Damping (see `docs/arachnode-ring-handoff.md` § Part 1):
+     * - **Smoothing** — every call folds the current sample into an EWMA of the demand inputs and
+     *   works off the smoothed continuous depth `d`, so a single noisy sample cannot trigger a move.
+     * - **Hysteresis** — anchored on the node's *currently-advertised* ring `R` (not a freshly
+     *   recomputed one). A move only fires when `d` is past the boundary by the dead-band `h`, so a
+     *   ratio hovering around an integer produces no move.
+     * - **Dwell + single-step** — no new move within `minDwellMs` of the last, no move while a shift
+     *   is already in flight (`status === 'moving'`), and each move steps by exactly ±1 ring even
+     *   when `d` implies a larger jump.
+     *
+     * Return shape (`{ shouldMove, direction, newRingDepth }`) is the *trigger* the handoff protocol
+     * consumes; it is kept stable so that consumer is unaffected.
      */
     async shouldTransition() {
         const capacity = await this.storageMonitor.getCapacity();
-        const usedPercent = capacity.used / capacity.total;
-        if (usedPercent > this.config.thresholds.moveOut) {
-            // Move to outer ring (more granular partition)
-            const currentRingDepth = await this.determineRing();
+        const usedPercent = capacity.total > 0 ? capacity.used / capacity.total : 0;
+        // Smoothing updates every tick, regardless of whether we act, so the EWMA keeps tracking
+        // demand even while a candidate move is dwell-blocked or a shift is already in flight.
+        const rawTotalData = this.estimateNetworkData(capacity.available);
+        this.updateSmoothing(capacity.available, rawTotalData);
+        const d = this.smoothedDepth();
+        const info = this.fretAdapter.getMyArachnodeInfo();
+        // Hysteresis anchor: the node's currently-advertised ring. Fall back to the smoothed depth
+        // only in the pathological case where nothing has been advertised yet (production always
+        // advertises at bootstrap before the first tick).
+        const advertisedRing = info?.ringDepth ?? Math.min(16, Math.max(0, Math.round(d)));
+        // No re-entrant shift: a move already in flight (advertise→confirm→release) owns the ring.
+        if (info?.status === 'moving') {
+            return { shouldMove: false };
+        }
+        // Minimum dwell: rate-limit so signal noise cannot drive rapid flips. `lastMoveAt` undefined
+        // means no prior move, so the first genuine move is never blocked. The stamp here (at *trigger*)
+        // keeps a move from immediately re-triggering before `status` flips to `moving`; the driver then
+        // calls {@link recordShiftSettled} once the advertise→confirm→release handoff SETTLES, so the
+        // effective dwell is measured from the *completed* shift (spec §1.3), not merely the trigger.
+        const minDwellMs = this.config.minDwellMs ?? DEFAULT_MIN_DWELL_MS;
+        if (this.lastMoveAt !== undefined && (this.now() - this.lastMoveAt) < minDwellMs) {
+            return { shouldMove: false };
+        }
+        const h = this.config.deadband ?? DEFAULT_DEADBAND;
+        // Move OUT (R → R+1): smoothed depth solidly past the outer boundary AND storage pressure high.
+        if (d >= advertisedRing + 1 - h && usedPercent > this.config.thresholds.moveOut) {
+            this.lastMoveAt = this.now();
             return {
                 shouldMove: true,
                 direction: 'out',
-                newRingDepth: currentRingDepth + 1
+                newRingDepth: advertisedRing + 1 // single step, even if d implies a larger jump
             };
         }
-        if (usedPercent < this.config.thresholds.moveIn) {
-            // Move to inner ring (broader coverage)
-            const currentRingDepth = await this.determineRing();
-            if (currentRingDepth > 0) {
-                return {
-                    shouldMove: true,
-                    direction: 'in',
-                    newRingDepth: currentRingDepth - 1
-                };
-            }
+        // Move IN (R → R-1): smoothed depth solidly past the inner boundary AND storage slack AND R>0.
+        if (advertisedRing > 0 && d <= advertisedRing - 1 + h && usedPercent < this.config.thresholds.moveIn) {
+            this.lastMoveAt = this.now();
+            return {
+                shouldMove: true,
+                direction: 'in',
+                newRingDepth: advertisedRing - 1 // single step
+            };
         }
         return { shouldMove: false };
     }
     /**
-     * Extract first N bits from byte array as a number.
+     * Re-stamp the dwell timer at the moment a ring shift *settles* — the driver
+     * (`RingShiftCoordinator` via `libp2p-node-base`) calls this once `executeShift` resolves, for a
+     * completed OR a rolled-back move. So the minimum dwell is measured from the settled shift rather
+     * than only from the trigger (`shouldTransition`): a completed shift dwells `minDwellMs` before the
+     * next move (spec §1.3, "after a *completed* shift"), and a shift that keeps failing is rate-limited
+     * rather than retried every tick. No-op-safe to call when no shift ran.
      */
-    extractPrefix(bytes, bits) {
-        let value = 0;
-        for (let i = 0; i < bits; i++) {
-            const byteIndex = Math.floor(i / 8);
-            const bitIndex = 7 - (i % 8);
-            const bit = (bytes[byteIndex] >> bitIndex) & 1;
-            value = (value << 1) | bit;
-        }
-        return value;
+    recordShiftSettled() {
+        this.lastMoveAt = this.now();
     }
 }
 //# sourceMappingURL=ring-selector.js.map

package/dist/src/storage/ring-selector.js.map

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

package/dist/src/storage/ring-shift-coordinator.d.ts

@@ -0,0 +1,128 @@
+import type { FretService } from 'p2p-fret';
+import type { PartitionDetector } from '../cluster/partition-detector.js';
+import type { ArachnodeFretAdapter } from './arachnode-fret-adapter.js';
+import type { RingSelector } from './ring-selector.js';
+/**
+ * The confirm primitive the handoff gates release on. Satisfied by `BlockTransferCoordinator`; kept
+ * as a narrow structural interface so the coordinator is unit-testable with a stub.
+ */
+export interface ReplicationConfirmer {
+    confirmReplicated(blockIds: string[], owners: Map<string, string[]>, floor: number): Promise<{
+        confirmed: string[];
+        unconfirmed: string[];
+    }>;
+}
+export interface RingShiftDeps {
+    fretAdapter: ArachnodeFretAdapter;
+    ringSelector: RingSelector;
+    fret: FretService;
+    partitionDetector: PartitionDetector;
+    /** Confirms a shed block replicated to ≥ N qualifying holders (Phase B). */
+    confirmer: ReplicationConfirmer;
+    /** The blocks this node physically holds — the candidate set the shed range is drawn from. */
+    ownedBlocks: Set<string>;
+    /** This node's own peer id string (excluded from the qualifying-holder count). */
+    selfPeerId: string;
+    /** The replication floor `N` (e.g. `RebalanceMonitor.getCohortSize`), read fresh per shift. */
+    getFloor: () => number;
+    /**
+     * Called with the shed block ids the instant Phase C releases them. The wiring stops serving +
+     * spreading them (untrack) and marks their local bytes GC-eligible — nothing may reclaim a shed
+     * range before this fires.
+     */
+    onRelease: (blockIds: string[]) => void;
+}
+export interface RingShiftConfig {
+    /**
+     * How many extra candidate holders beyond the floor to request from FRET per shed block, giving
+     * headroom to exclude self and same-range movers while still finding `N` qualifying holders.
+     * Default 2.
+     */
+    candidateMargin?: number;
+}
+/** The result of a single `executeShift` — what happened and why, for logging/tests. */
+export type ShiftOutcome = {
+    status: 'moved-out';
+    from: number;
+    to: number;
+    released: string[];
+} | {
+    status: 'moved-in';
+    from: number;
+    to: number;
+} | {
+    status: 'rolled-back';
+    ring: number;
+    reason: string;
+} | {
+    status: 'skipped';
+    reason: string;
+};
+/**
+ * Drives a single damped ring transition through the **advertise → confirm-replication → release**
+ * handoff (`docs/arachnode-ring-handoff.md` § Part 2), so a ring shift never drops a key below its
+ * replication floor `N`.
+ *
+ * - **Move-out** (`R → R+1`, sheds half its keyspace) runs all three phases: advertise the target
+ *   ring while still serving the old range (Phase A), confirm every shed block is replicated to ≥ N
+ *   qualifying post-move holders (Phase B), then release the shed range (Phase C). Any Phase-B
+ *   failure — partition, unreachable holders, floor unmet — rolls back to `active` at the old ring,
+ *   keeping the range. No shed block is released unless EVERY shed block confirmed.
+ * - **Move-in** (`R → R-1`, gains keyspace, sheds nothing) is Phase A only: it advertises the inner
+ *   ring so peers observe the membership change, then pulls the gained half via the restoration /
+ *   rebalance path. The floor is never at risk from a mover that only gains, so there is no
+ *   confirm/release.
+ *
+ * The trigger is the (damped) `RingSelector.shouldTransition()` decision; this class is the state
+ * machine that decision drives.
+ */
+export declare class RingShiftCoordinator {
+    private readonly deps;
+    private readonly candidateMargin;
+    /** Guards against a re-entrant shift if the driving interval overlaps a long confirm. */
+    private inFlight;
+    constructor(deps: RingShiftDeps, config?: RingShiftConfig);
+    /**
+     * Execute one single-step ring transition. No-op (`skipped`) if a shift is already in flight or the
+     * node is already `moving`. `direction`/`newRingDepth` come straight from the damped
+     * `shouldTransition()` trigger.
+     */
+    executeShift(transition: {
+        direction: 'in' | 'out';
+        newRingDepth: number;
+    }): Promise<ShiftOutcome>;
+    /**
+     * Reconcile a stale `status='moving'` advertisement left by a crash between advertise (Phase A) and
+     * release (Phase C). The crashed node never ran Phase C, so it never released the shed range and is
+     * still responsible for its OLD range: restore that range and refresh status to `active`. A node
+     * whose advertised status is not `moving` needs no reconciliation. Called once at startup. See
+     * `docs/arachnode-ring-handoff.md` § Part 3 (crash mid-handoff).
+     */
+    reconcileOnStart(): {
+        reconciled: boolean;
+    };
+    private moveOut;
+    /**
+     * Phase B. Succeeds only when EVERY shed block is confirmed replicated to ≥ `floor` qualifying
+     * holders. Aborts (no partial release) on a detected partition or any unconfirmed block.
+     */
+    private confirmShedRange;
+    /**
+     * The shed range: blocks this node holds that its OLD partition covers but its NEW (target)
+     * partition does not — i.e. the half of its slice it stops covering by moving out.
+     */
+    private computeShedBlocks;
+    /**
+     * For each shed block, the qualifying post-move holders to confirm against: the FRET cohort around
+     * the block minus self and minus any peer that does not still cover the block under its OWN
+     * advertised (target) partition — which excludes same-range movers ({@link qualifiesForFloor}). A
+     * candidate with no advertised Arachnode info is excluded (its coverage cannot be verified).
+     */
+    private buildOwnersMap;
+    private moveIn;
+    /** Restore the pre-move advertisement (old ring/partition, `active`, no `moveFrom`). */
+    private rollback;
+    /** Strip the transient `moveFrom` field so an `active` advertisement never carries move state. */
+    private clearMove;
+}
+//# sourceMappingURL=ring-shift-coordinator.d.ts.map

package/dist/src/storage/ring-shift-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-shift-coordinator.d.ts","sourceRoot":"","sources":["../../../src/storage/ring-shift-coordinator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,6BAA6B,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOvD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACpC,iBAAiB,CAChB,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAC7B,KAAK,EAAE,MAAM,GACX,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,aAAa;IAC7B,WAAW,EAAE,oBAAoB,CAAC;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,iBAAiB,EAAE,iBAAiB,CAAC;IACrC,4EAA4E;IAC5E,SAAS,EAAE,oBAAoB,CAAC;IAChC,8FAA8F;IAC9F,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB;;;;OAIG;IACH,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wFAAwF;AACxF,MAAM,MAAM,YAAY,GACrB;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,oBAAoB;IAM/B,OAAO,CAAC,QAAQ,CAAC,IAAI;IALtB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAS;gBAGP,IAAI,EAAE,aAAa,EACpC,MAAM,GAAE,eAAoB;IAK7B;;;;OAIG;IACG,YAAY,CAAC,UAAU,EAAE;QAAE,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBxG;;;;;;OAMG;IACH,gBAAgB,IAAI;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE;YAiB7B,OAAO;IAgCrB;;;OAGG;YACW,gBAAgB;IAiB9B;;;OAGG;YACW,iBAAiB;IAc/B;;;;;OAKG;YACW,cAAc;YAkBd,MAAM;IAapB,wFAAwF;IACxF,OAAO,CAAC,QAAQ;IAkBhB,kGAAkG;IAClG,OAAO,CAAC,SAAS;CAIjB"}

package/dist/src/storage/ring-shift-coordinator.js

@@ -0,0 +1,196 @@
+import { hashKey } from 'p2p-fret';
+import { partitionCovers, qualifiesForFloor } from './arachnode-partition.js';
+import { createLogger } from '../logger.js';
+const log = createLogger('ring-shift');
+const textEncoder = new TextEncoder();
+/**
+ * Drives a single damped ring transition through the **advertise → confirm-replication → release**
+ * handoff (`docs/arachnode-ring-handoff.md` § Part 2), so a ring shift never drops a key below its
+ * replication floor `N`.
+ *
+ * - **Move-out** (`R → R+1`, sheds half its keyspace) runs all three phases: advertise the target
+ *   ring while still serving the old range (Phase A), confirm every shed block is replicated to ≥ N
+ *   qualifying post-move holders (Phase B), then release the shed range (Phase C). Any Phase-B
+ *   failure — partition, unreachable holders, floor unmet — rolls back to `active` at the old ring,
+ *   keeping the range. No shed block is released unless EVERY shed block confirmed.
+ * - **Move-in** (`R → R-1`, gains keyspace, sheds nothing) is Phase A only: it advertises the inner
+ *   ring so peers observe the membership change, then pulls the gained half via the restoration /
+ *   rebalance path. The floor is never at risk from a mover that only gains, so there is no
+ *   confirm/release.
+ *
+ * The trigger is the (damped) `RingSelector.shouldTransition()` decision; this class is the state
+ * machine that decision drives.
+ */
+export class RingShiftCoordinator {
+    deps;
+    candidateMargin;
+    /** Guards against a re-entrant shift if the driving interval overlaps a long confirm. */
+    inFlight = false;
+    constructor(deps, config = {}) {
+        this.deps = deps;
+        this.candidateMargin = config.candidateMargin ?? 2;
+    }
+    /**
+     * Execute one single-step ring transition. No-op (`skipped`) if a shift is already in flight or the
+     * node is already `moving`. `direction`/`newRingDepth` come straight from the damped
+     * `shouldTransition()` trigger.
+     */
+    async executeShift(transition) {
+        if (this.inFlight) {
+            return { status: 'skipped', reason: 'shift-in-flight' };
+        }
+        const current = this.deps.fretAdapter.getMyArachnodeInfo();
+        if (current?.status === 'moving') {
+            return { status: 'skipped', reason: 'already-moving' };
+        }
+        this.inFlight = true;
+        try {
+            return transition.direction === 'out'
+                ? await this.moveOut(transition.newRingDepth, current)
+                : await this.moveIn(transition.newRingDepth, current);
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+    /**
+     * Reconcile a stale `status='moving'` advertisement left by a crash between advertise (Phase A) and
+     * release (Phase C). The crashed node never ran Phase C, so it never released the shed range and is
+     * still responsible for its OLD range: restore that range and refresh status to `active`. A node
+     * whose advertised status is not `moving` needs no reconciliation. Called once at startup. See
+     * `docs/arachnode-ring-handoff.md` § Part 3 (crash mid-handoff).
+     */
+    reconcileOnStart() {
+        const info = this.deps.fretAdapter.getMyArachnodeInfo();
+        if (!info || info.status !== 'moving') {
+            return { reconciled: false };
+        }
+        // Never released → still responsible for the old range. Resume serving it, active at the old ring.
+        this.deps.fretAdapter.setArachnodeInfo(info.moveFrom
+            ? this.clearMove({ ...info, ringDepth: info.moveFrom.ringDepth, partition: info.moveFrom.partition, status: 'active' })
+            : this.clearMove({ ...info, status: 'active' }));
+        log('reconcile:resumed-old-range ring=%d', info.moveFrom?.ringDepth ?? info.ringDepth);
+        return { reconciled: true };
+    }
+    // --- Move-out: advertise → confirm → release ---
+    async moveOut(newRingDepth, oldInfo) {
+        const oldRing = oldInfo?.ringDepth ?? 0;
+        // Phase A — advertise the target ring; KEEP serving the old range (moveFrom retains it).
+        const target = await this.deps.ringSelector.createArachnodeInfo(this.deps.selfPeerId, newRingDepth);
+        const movingInfo = {
+            ...target,
+            status: 'moving',
+            moveFrom: { ringDepth: oldRing, partition: oldInfo?.partition }
+        };
+        this.deps.fretAdapter.setArachnodeInfo(movingInfo);
+        log('phaseA:advertise from=%d to=%d', oldRing, newRingDepth);
+        // Phase B — confirm the shed range replicated to ≥ N qualifying holders.
+        const shed = await this.computeShedBlocks(oldInfo?.partition, target.partition);
+        const floor = Math.max(1, this.deps.getFloor());
+        const confirm = await this.confirmShedRange(shed, floor);
+        if (!confirm.ok) {
+            this.rollback(oldInfo);
+            log('phaseB:abort reason=%s → rolled-back to ring=%d', confirm.reason, oldRing);
+            return { status: 'rolled-back', ring: oldRing, reason: confirm.reason };
+        }
+        // Phase C — release: active at the new ring (moveFrom cleared), stop serving/spreading + GC-eligible.
+        this.deps.fretAdapter.setArachnodeInfo(this.clearMove({ ...target, status: 'active' }));
+        if (shed.length > 0) {
+            this.deps.onRelease(shed);
+        }
+        log('phaseC:release from=%d to=%d shed=%d', oldRing, newRingDepth, shed.length);
+        return { status: 'moved-out', from: oldRing, to: newRingDepth, released: shed };
+    }
+    /**
+     * Phase B. Succeeds only when EVERY shed block is confirmed replicated to ≥ `floor` qualifying
+     * holders. Aborts (no partial release) on a detected partition or any unconfirmed block.
+     */
+    async confirmShedRange(shed, floor) {
+        if (shed.length === 0) {
+            return { ok: true }; // nothing to shed → trivially safe
+        }
+        if (this.deps.partitionDetector.detectPartition()) {
+            return { ok: false, reason: 'partition' };
+        }
+        const owners = await this.buildOwnersMap(shed, floor);
+        const { confirmed, unconfirmed } = await this.deps.confirmer.confirmReplicated(shed, owners, floor);
+        if (unconfirmed.length > 0) {
+            return { ok: false, reason: `unconfirmed:${unconfirmed.length}` };
+        }
+        // Belt-and-suspenders: every shed block must be in `confirmed` before any is released.
+        return confirmed.length === shed.length ? { ok: true } : { ok: false, reason: 'incomplete' };
+    }
+    /**
+     * The shed range: blocks this node holds that its OLD partition covers but its NEW (target)
+     * partition does not — i.e. the half of its slice it stops covering by moving out.
+     */
+    async computeShedBlocks(oldPartition, newPartition) {
+        const shed = [];
+        for (const blockId of this.deps.ownedBlocks) {
+            const coord = await hashKey(textEncoder.encode(blockId));
+            if (partitionCovers(oldPartition, coord) && !partitionCovers(newPartition, coord)) {
+                shed.push(blockId);
+            }
+        }
+        return shed;
+    }
+    /**
+     * For each shed block, the qualifying post-move holders to confirm against: the FRET cohort around
+     * the block minus self and minus any peer that does not still cover the block under its OWN
+     * advertised (target) partition — which excludes same-range movers ({@link qualifiesForFloor}). A
+     * candidate with no advertised Arachnode info is excluded (its coverage cannot be verified).
+     */
+    async buildOwnersMap(shed, floor) {
+        const owners = new Map();
+        const want = floor + 1 + this.candidateMargin; // headroom for self + excluded movers
+        for (const blockId of shed) {
+            const coord = await hashKey(textEncoder.encode(blockId));
+            const cohort = this.deps.fret.assembleCohort(coord, want);
+            const qualifying = cohort.filter(peerId => {
+                if (peerId === this.deps.selfPeerId)
+                    return false;
+                const info = this.deps.fretAdapter.getArachnodeInfo(peerId);
+                return info !== undefined && qualifiesForFloor(info, coord);
+            });
+            owners.set(blockId, qualifying);
+        }
+        return owners;
+    }
+    // --- Move-in: advertise only (sheds nothing) ---
+    async moveIn(newRingDepth, oldInfo) {
+        const oldRing = oldInfo?.ringDepth ?? 0;
+        // Sheds nothing: advertise the (broader) inner ring directly at `active`. The gained half is
+        // pulled by the restoration / rebalance path; the old holders keep serving until THEY confirm
+        // their own release, so the floor is never at risk from this mover.
+        const target = await this.deps.ringSelector.createArachnodeInfo(this.deps.selfPeerId, newRingDepth);
+        this.deps.fretAdapter.setArachnodeInfo(this.clearMove({ ...target, status: 'active' }));
+        log('moveIn:advertise from=%d to=%d', oldRing, newRingDepth);
+        return { status: 'moved-in', from: oldRing, to: newRingDepth };
+    }
+    // --- Shared helpers ---
+    /** Restore the pre-move advertisement (old ring/partition, `active`, no `moveFrom`). */
+    rollback(oldInfo) {
+        if (oldInfo) {
+            this.deps.fretAdapter.setArachnodeInfo(this.clearMove({ ...oldInfo, status: 'active' }));
+            return;
+        }
+        // No prior advertisement: the node's "old range" is the whole keyspace (ring 0). Phase A has
+        // already replaced self with the `moving` target, so a bare `setStatus('active')` would leave
+        // the aborted NARROWER target ring/partition (and a stray `moveFrom`) advertised as active —
+        // dropping coverage of the shed range with nothing confirmed elsewhere, the exact floor
+        // violation this handoff exists to prevent. Restore a CLEAN active ring-0 advertisement instead.
+        const cur = this.deps.fretAdapter.getMyArachnodeInfo();
+        if (cur) {
+            this.deps.fretAdapter.setArachnodeInfo(this.clearMove({ ...cur, ringDepth: 0, partition: undefined, status: 'active' }));
+        }
+        else {
+            this.deps.fretAdapter.setStatus('active');
+        }
+    }
+    /** Strip the transient `moveFrom` field so an `active` advertisement never carries move state. */
+    clearMove(info) {
+        const { moveFrom: _drop, ...rest } = info;
+        return rest;
+    }
+}
+//# sourceMappingURL=ring-shift-coordinator.js.map