@wopr-network/platform-core 1.18.0 → 1.20.0

package/dist/billing/crypto/evm/__tests__/watcher.test.js

@@ -17,35 +17,38 @@ function mockTransferLog(to, amount, blockNumber) {
 }
 describe("EvmWatcher", () => {
     it("parses Transfer log into EvmPaymentEvent", async () => {
+        const toAddr = `0x${"cc".repeat(20)}`;
         const events = [];
         const mockRpc = vi
             .fn()
-            .mockResolvedValueOnce(`0x${(102).toString(16)}`) // eth_blockNumber: block 102
-            .mockResolvedValueOnce([mockTransferLog(`0x${"cc".repeat(20)}`, 10000000n, 99)]); // eth_getLogs
+            .mockResolvedValueOnce(`0x${(102).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(toAddr, 10000000n, 99)]);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 99,
+            watchedAddresses: [toAddr],
             onPayment: (evt) => {
                 events.push(evt);
             },
         });
         await watcher.poll();
         expect(events).toHaveLength(1);
-        expect(events[0].amountUsdCents).toBe(1000); // 10 USDC = $10 = 1000 cents
+        expect(events[0].amountUsdCents).toBe(1000);
         expect(events[0].to).toMatch(/^0x/);
     });
     it("advances cursor after processing", async () => {
         const mockRpc = vi
             .fn()
-            .mockResolvedValueOnce(`0x${(200).toString(16)}`) // block 200
-            .mockResolvedValueOnce([]); // no logs
+            .mockResolvedValueOnce(`0x${(200).toString(16)}`)
+            .mockResolvedValueOnce([]);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 100,
+            watchedAddresses: ["0xdeadbeef"],
             onPayment: vi.fn(),
         });
         await watcher.poll();
@@ -53,37 +56,35 @@ describe("EvmWatcher", () => {
     });
     it("skips blocks not yet confirmed", async () => {
         const events = [];
-        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`); // current block: 50
-        // Base needs 1 confirmation, so confirmed = 50 - 1 = 49
-        // cursor starts at 50, so confirmed (49) < cursor (50) → no poll
+        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(50).toString(16)}`);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 50,
+            watchedAddresses: ["0xdeadbeef"],
             onPayment: (evt) => {
                 events.push(evt);
             },
         });
         await watcher.poll();
         expect(events).toHaveLength(0);
-        // eth_getLogs should not even be called
         expect(mockRpc).toHaveBeenCalledTimes(1);
     });
     it("processes multiple logs in one poll", async () => {
+        const addr1 = `0x${"aa".repeat(20)}`;
+        const addr2 = `0x${"bb".repeat(20)}`;
         const events = [];
         const mockRpc = vi
             .fn()
-            .mockResolvedValueOnce(`0x${(110).toString(16)}`) // block 110
-            .mockResolvedValueOnce([
-            mockTransferLog(`0x${"aa".repeat(20)}`, 5000000n, 105), // $5
-            mockTransferLog(`0x${"bb".repeat(20)}`, 20000000n, 107), // $20
-        ]);
+            .mockResolvedValueOnce(`0x${(110).toString(16)}`)
+            .mockResolvedValueOnce([mockTransferLog(addr1, 5000000n, 105), mockTransferLog(addr2, 20000000n, 107)]);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 100,
+            watchedAddresses: [addr1, addr2],
             onPayment: (evt) => {
                 events.push(evt);
             },
@@ -94,16 +95,29 @@ describe("EvmWatcher", () => {
         expect(events[1].amountUsdCents).toBe(2000);
     });
     it("does nothing when no new blocks", async () => {
-        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`); // block 99, confirmed = 98
+        const mockRpc = vi.fn().mockResolvedValueOnce(`0x${(99).toString(16)}`);
         const watcher = new EvmWatcher({
             chain: "base",
             token: "USDC",
             rpcCall: mockRpc,
             fromBlock: 100,
+            watchedAddresses: ["0xdeadbeef"],
             onPayment: vi.fn(),
         });
         await watcher.poll();
-        expect(watcher.cursor).toBe(100); // unchanged
-        expect(mockRpc).toHaveBeenCalledTimes(1); // only eth_blockNumber
+        expect(watcher.cursor).toBe(100);
+        expect(mockRpc).toHaveBeenCalledTimes(1);
+    });
+    it("early-returns when no watched addresses are set", async () => {
+        const mockRpc = vi.fn();
+        const watcher = new EvmWatcher({
+            chain: "base",
+            token: "USDC",
+            rpcCall: mockRpc,
+            fromBlock: 0,
+            onPayment: vi.fn(),
+        });
+        await watcher.poll();
+        expect(mockRpc).not.toHaveBeenCalled(); // no RPC calls at all
     });
 });

package/dist/billing/crypto/evm/checkout.js

@@ -47,8 +47,10 @@ export async function createStablecoinCheckout(deps, opts) {
         catch (err) {
             // Unique constraint violation = another checkout claimed this index concurrently.
             // Retry with the next available index.
-            const msg = err instanceof Error ? err.message : "";
-            const isConflict = msg.includes("unique") || msg.includes("duplicate") || msg.includes("23505");
+            // PostgreSQL error code 23505 = unique_violation.
+            // Check structured code first, fall back to message for other drivers.
+            const code = err.code;
+            const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
             if (!isConflict || attempt === maxRetries)
                 throw err;
         }

package/dist/billing/crypto/evm/config.js

@@ -6,8 +6,30 @@ const CHAINS = {
         blockTimeMs: 2000,
         chainId: 8453,
     },
+    ethereum: {
+        chain: "ethereum",
+        rpcUrl: process.env.EVM_RPC_ETHEREUM ?? "http://geth:8545",
+        confirmations: 12,
+        blockTimeMs: 12000,
+        chainId: 1,
+    },
+    arbitrum: {
+        chain: "arbitrum",
+        rpcUrl: process.env.EVM_RPC_ARBITRUM ?? "http://nitro:8547",
+        confirmations: 1,
+        blockTimeMs: 250,
+        chainId: 42161,
+    },
+    polygon: {
+        chain: "polygon",
+        rpcUrl: process.env.EVM_RPC_POLYGON ?? "http://bor:8545",
+        confirmations: 32,
+        blockTimeMs: 2000,
+        chainId: 137,
+    },
 };
 const TOKENS = {
+    // --- Base ---
     "USDC:base": {
         token: "USDC",
         chain: "base",
@@ -26,6 +48,57 @@ const TOKENS = {
         contractAddress: "0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb",
         decimals: 18,
     },
+    // --- Ethereum ---
+    "USDC:ethereum": {
+        token: "USDC",
+        chain: "ethereum",
+        contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+        decimals: 6,
+    },
+    "USDT:ethereum": {
+        token: "USDT",
+        chain: "ethereum",
+        contractAddress: "0xdAC17F958D2ee523a2206206994597C13D831ec7",
+        decimals: 6,
+    },
+    "DAI:ethereum": {
+        token: "DAI",
+        chain: "ethereum",
+        contractAddress: "0x6B175474E89094C44Da98b954EedeAC495271d0F",
+        decimals: 18,
+    },
+    // --- Arbitrum ---
+    "USDC:arbitrum": {
+        token: "USDC",
+        chain: "arbitrum",
+        contractAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+        decimals: 6,
+    },
+    "USDT:arbitrum": {
+        token: "USDT",
+        chain: "arbitrum",
+        contractAddress: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
+        decimals: 6,
+    },
+    "DAI:arbitrum": {
+        token: "DAI",
+        chain: "arbitrum",
+        contractAddress: "0xDA10009cBd5D07dd0CeCc66161FC93D7c9000da1",
+        decimals: 18,
+    },
+    // --- Polygon ---
+    "USDC:polygon": {
+        token: "USDC",
+        chain: "polygon",
+        contractAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+        decimals: 6,
+    },
+    "USDT:polygon": {
+        token: "USDT",
+        chain: "polygon",
+        contractAddress: "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
+        decimals: 6,
+    },
 };
 export function getChainConfig(chain) {
     const cfg = CHAINS[chain];

package/dist/billing/crypto/evm/types.d.ts

@@ -1,5 +1,5 @@
 /** Supported EVM chains. */
-export type EvmChain = "base";
+export type EvmChain = "base" | "ethereum" | "arbitrum" | "polygon";
 /** Supported stablecoin tokens. */
 export type StablecoinToken = "USDC" | "USDT" | "DAI";
 /** Chain configuration. */

package/dist/billing/crypto/evm/watcher.js

@@ -32,6 +32,8 @@ export class EvmWatcher {
     }
     /** Poll for new Transfer events. Call on an interval. */
     async poll() {
+        if (this._watchedAddresses.length === 0)
+            return; // nothing to watch
         const latestHex = (await this.rpc("eth_blockNumber", []));
         const latest = Number.parseInt(latestHex, 16);
         const confirmed = latest - this.confirmations;

package/dist/billing/crypto/index.d.ts

@@ -1,4 +1,5 @@
-export type { CryptoChargeRecord, ICryptoChargeRepository, StablecoinChargeInput } from "./charge-store.js";
+export * from "./btc/index.js";
+export type { CryptoChargeRecord, CryptoDepositChargeInput, ICryptoChargeRepository } from "./charge-store.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export type { CryptoConfig } from "./client.js";

package/dist/billing/crypto/index.js

@@ -1,3 +1,4 @@
+export * from "./btc/index.js";
 export { CryptoChargeRepository, DrizzleCryptoChargeRepository } from "./charge-store.js";
 export { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
 export { BTCPayClient, loadCryptoConfig } from "./client.js";

package/dist/db/schema/crypto.js

@@ -27,6 +27,6 @@ export const cryptoCharges = pgTable("crypto_charges", {
     index("idx_crypto_charges_status").on(table.status),
     index("idx_crypto_charges_created").on(table.createdAt),
     index("idx_crypto_charges_deposit_address").on(table.depositAddress),
-    // uniqueIndex would be ideal but drizzle pgTable helper doesn't support it inline.
+    // Unique indexes use WHERE IS NOT NULL partial indexes (declared in migration SQL).
     // Enforced via migration: CREATE UNIQUE INDEX.
 ]);

package/dist/fleet/__tests__/rollout-strategy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fleet/__tests__/rollout-strategy.test.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { createRolloutStrategy, ImmediateStrategy, RollingWaveStrategy, SingleBotStrategy, } from "../rollout-strategy.js";
+function makeBots(count) {
+    return Array.from({ length: count }, (_, i) => ({
+        id: randomUUID(),
+        tenantId: "tenant-1",
+        name: `bot-${i}`,
+        description: "",
+        image: "ghcr.io/wopr-network/test:latest",
+        env: {},
+        restartPolicy: "unless-stopped",
+        releaseChannel: "stable",
+        updatePolicy: "manual",
+    }));
+}
+describe("RollingWaveStrategy", () => {
+    it("returns batchPercent of remaining bots", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 25 });
+        const bots = makeBots(10);
+        const batch = s.nextBatch(bots);
+        // 25% of 10 = 2.5, ceil = 3
+        expect(batch).toHaveLength(3);
+        expect(batch).toEqual(bots.slice(0, 3));
+    });
+    it("returns minimum 1 bot even with low percentage", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 1 });
+        const bots = makeBots(2);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+    });
+    it("returns empty array for empty remaining", () => {
+        const s = new RollingWaveStrategy();
+        expect(s.nextBatch([])).toHaveLength(0);
+    });
+    it("handles 1 bot remaining", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 50 });
+        const bots = makeBots(1);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+    });
+    it("handles batchPercent > 100", () => {
+        const s = new RollingWaveStrategy({ batchPercent: 200 });
+        const bots = makeBots(5);
+        // 200% of 5 = 10, ceil = 10, but slice(0,10) on 5 items = 5
+        expect(s.nextBatch(bots)).toHaveLength(5);
+    });
+    it("returns correct pause duration", () => {
+        expect(new RollingWaveStrategy().pauseDuration()).toBe(60_000);
+        expect(new RollingWaveStrategy({ pauseMs: 30_000 }).pauseDuration()).toBe(30_000);
+    });
+    it("retries on failure until maxRetries", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 2 });
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 1)).toBe("retry");
+    });
+    it("skips after maxRetries when under maxFailures", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 3 });
+        const err = new Error("fail");
+        // attempt >= maxRetries (2), first total failure
+        expect(s.onBotFailure("b1", err, 2)).toBe("skip");
+    });
+    it("aborts when total failures reach maxFailures", () => {
+        const s = new RollingWaveStrategy({ maxFailures: 2 });
+        const err = new Error("fail");
+        // exhaust retries for bot1 → skip (totalFailures=1)
+        expect(s.onBotFailure("b1", err, 2)).toBe("skip");
+        // exhaust retries for bot2 → abort (totalFailures=2 >= maxFailures=2)
+        expect(s.onBotFailure("b2", err, 2)).toBe("abort");
+    });
+    it("has maxRetries of 2", () => {
+        expect(new RollingWaveStrategy().maxRetries()).toBe(2);
+    });
+    it("has healthCheckTimeout of 120_000", () => {
+        expect(new RollingWaveStrategy().healthCheckTimeout()).toBe(120_000);
+    });
+});
+describe("SingleBotStrategy", () => {
+    it("returns exactly 1 bot", () => {
+        const s = new SingleBotStrategy();
+        const bots = makeBots(10);
+        expect(s.nextBatch(bots)).toHaveLength(1);
+        expect(s.nextBatch(bots)[0]).toBe(bots[0]);
+    });
+    it("returns empty for empty remaining", () => {
+        expect(new SingleBotStrategy().nextBatch([])).toHaveLength(0);
+    });
+    it("has pauseDuration of 0", () => {
+        expect(new SingleBotStrategy().pauseDuration()).toBe(0);
+    });
+    it("always retries on failure", () => {
+        const s = new SingleBotStrategy();
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 1)).toBe("retry");
+        expect(s.onBotFailure("b1", err, 2)).toBe("retry");
+        // After maxRetries (3), aborts instead of retrying forever
+        expect(s.onBotFailure("b1", err, 99)).toBe("abort");
+    });
+    it("has maxRetries of 3", () => {
+        expect(new SingleBotStrategy().maxRetries()).toBe(3);
+    });
+    it("has healthCheckTimeout of 120_000", () => {
+        expect(new SingleBotStrategy().healthCheckTimeout()).toBe(120_000);
+    });
+});
+describe("ImmediateStrategy", () => {
+    it("returns all remaining bots", () => {
+        const s = new ImmediateStrategy();
+        const bots = makeBots(10);
+        expect(s.nextBatch(bots)).toHaveLength(10);
+        expect(s.nextBatch(bots)).toEqual(bots);
+    });
+    it("returns empty for empty remaining", () => {
+        expect(new ImmediateStrategy().nextBatch([])).toHaveLength(0);
+    });
+    it("does not mutate the input array", () => {
+        const s = new ImmediateStrategy();
+        const bots = makeBots(3);
+        const result = s.nextBatch(bots);
+        expect(result).not.toBe(bots);
+        expect(result).toEqual(bots);
+    });
+    it("has pauseDuration of 0", () => {
+        expect(new ImmediateStrategy().pauseDuration()).toBe(0);
+    });
+    it("always skips on failure", () => {
+        const s = new ImmediateStrategy();
+        const err = new Error("fail");
+        expect(s.onBotFailure("b1", err, 0)).toBe("skip");
+        expect(s.onBotFailure("b1", err, 5)).toBe("skip");
+    });
+    it("has maxRetries of 1", () => {
+        expect(new ImmediateStrategy().maxRetries()).toBe(1);
+    });
+    it("has healthCheckTimeout of 60_000", () => {
+        expect(new ImmediateStrategy().healthCheckTimeout()).toBe(60_000);
+    });
+});
+describe("createRolloutStrategy", () => {
+    it("creates RollingWaveStrategy", () => {
+        const s = createRolloutStrategy("rolling-wave");
+        expect(s).toBeInstanceOf(RollingWaveStrategy);
+    });
+    it("creates RollingWaveStrategy with options", () => {
+        const s = createRolloutStrategy("rolling-wave", { batchPercent: 50, pauseMs: 10_000 });
+        expect(s).toBeInstanceOf(RollingWaveStrategy);
+        expect(s.pauseDuration()).toBe(10_000);
+    });
+    it("creates SingleBotStrategy", () => {
+        const s = createRolloutStrategy("single-bot");
+        expect(s).toBeInstanceOf(SingleBotStrategy);
+    });
+    it("creates ImmediateStrategy", () => {
+        const s = createRolloutStrategy("immediate");
+        expect(s).toBeInstanceOf(ImmediateStrategy);
+    });
+});

package/dist/fleet/__tests__/volume-snapshot-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fleet/__tests__/volume-snapshot-manager.test.js

@@ -0,0 +1,171 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { VolumeSnapshotManager } from "../volume-snapshot-manager.js";
+// Mock fs/promises
+vi.mock("node:fs/promises", () => ({
+    mkdir: vi.fn().mockResolvedValue(undefined),
+    stat: vi.fn().mockResolvedValue({ size: 1024, mtime: new Date("2026-03-14T10:00:00Z") }),
+    readdir: vi.fn().mockResolvedValue([]),
+    rm: vi.fn().mockResolvedValue(undefined),
+}));
+// Mock logger
+vi.mock("../../config/logger.js", () => ({
+    logger: {
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+        debug: vi.fn(),
+    },
+}));
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
+function mockContainer() {
+    return {
+        start: vi.fn().mockResolvedValue(undefined),
+        wait: vi.fn().mockResolvedValue({ StatusCode: 0 }),
+        remove: vi.fn().mockResolvedValue(undefined),
+    };
+}
+function mockDocker() {
+    return {
+        createContainer: vi.fn().mockResolvedValue(mockContainer()),
+    };
+}
+describe("VolumeSnapshotManager", () => {
+    let docker;
+    let manager;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        docker = mockDocker();
+        manager = new VolumeSnapshotManager(docker, "/data/fleet/snapshots");
+    });
+    describe("snapshot()", () => {
+        it("creates container with correct binds and runs tar", async () => {
+            await manager.snapshot("my-volume");
+            expect(docker.createContainer).toHaveBeenCalledWith(expect.objectContaining({
+                Image: "alpine:latest",
+                Cmd: expect.arrayContaining(["tar", "cf"]),
+                HostConfig: expect.objectContaining({
+                    Binds: expect.arrayContaining(["my-volume:/source:ro", "/data/fleet/snapshots:/backup"]),
+                    AutoRemove: true,
+                }),
+            }));
+            const container = await docker.createContainer.mock.results[0].value;
+            expect(container.start).toHaveBeenCalled();
+            expect(container.wait).toHaveBeenCalled();
+        });
+        it("returns a VolumeSnapshot with correct fields", async () => {
+            const result = await manager.snapshot("my-volume");
+            expect(result.volumeName).toBe("my-volume");
+            expect(result.id).toMatch(/^my-volume-\d{4}-\d{2}-\d{2}T/);
+            expect(result.archivePath).toMatch(/^\/data\/fleet\/snapshots\/my-volume-.*\.tar$/);
+            expect(result.sizeBytes).toBe(1024);
+            expect(result.createdAt).toBeInstanceOf(Date);
+        });
+        it("ensures backup directory exists", async () => {
+            await manager.snapshot("my-volume");
+            expect(mkdir).toHaveBeenCalledWith("/data/fleet/snapshots", { recursive: true });
+        });
+        it("cleans up container on start failure", async () => {
+            const container = mockContainer();
+            container.start.mockRejectedValue(new Error("start failed"));
+            docker.createContainer.mockResolvedValue(container);
+            await expect(manager.snapshot("my-volume")).rejects.toThrow("start failed");
+            expect(container.remove).toHaveBeenCalledWith({ force: true });
+        });
+    });
+    describe("restore()", () => {
+        it("creates container with correct binds and runs tar xf", async () => {
+            const snapshotId = "my-volume-2026-03-14T10-00-00-000Z";
+            await manager.restore(snapshotId);
+            expect(docker.createContainer).toHaveBeenCalledWith(expect.objectContaining({
+                Image: "alpine:latest",
+                Cmd: ["sh", "-c", `cd /target && rm -rf ./* ./.??* && tar xf /backup/${snapshotId}.tar -C /target`],
+                HostConfig: expect.objectContaining({
+                    Binds: expect.arrayContaining(["my-volume:/target", "/data/fleet/snapshots:/backup:ro"]),
+                    AutoRemove: true,
+                }),
+            }));
+        });
+        it("starts and waits for container", async () => {
+            const container = mockContainer();
+            docker.createContainer.mockResolvedValue(container);
+            await manager.restore("my-volume-2026-03-14T10-00-00-000Z");
+            expect(container.start).toHaveBeenCalled();
+            expect(container.wait).toHaveBeenCalled();
+        });
+        it("throws if archive does not exist", async () => {
+            stat.mockRejectedValueOnce(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            await expect(manager.restore("nonexistent-2026-03-14T10-00-00-000Z")).rejects.toThrow("ENOENT");
+        });
+    });
+    describe("list()", () => {
+        it("returns snapshots sorted by date, newest first", async () => {
+            readdir.mockResolvedValue([
+                "my-volume-2026-03-12T08-00-00-000Z.tar",
+                "my-volume-2026-03-14T10-00-00-000Z.tar",
+                "my-volume-2026-03-13T09-00-00-000Z.tar",
+            ]);
+            const oldDate = new Date("2026-03-12T08:00:00Z");
+            const midDate = new Date("2026-03-13T09:00:00Z");
+            const newDate = new Date("2026-03-14T10:00:00Z");
+            stat
+                .mockResolvedValueOnce({ size: 100, mtime: oldDate })
+                .mockResolvedValueOnce({ size: 300, mtime: newDate })
+                .mockResolvedValueOnce({ size: 200, mtime: midDate });
+            const result = await manager.list("my-volume");
+            expect(result).toHaveLength(3);
+            expect(result[0].createdAt).toEqual(newDate);
+            expect(result[1].createdAt).toEqual(midDate);
+            expect(result[2].createdAt).toEqual(oldDate);
+        });
+        it("filters to only matching volume name", async () => {
+            readdir.mockResolvedValue([
+                "my-volume-2026-03-14T10-00-00-000Z.tar",
+                "other-volume-2026-03-14T10-00-00-000Z.tar",
+            ]);
+            const result = await manager.list("my-volume");
+            expect(result).toHaveLength(1);
+            expect(result[0].volumeName).toBe("my-volume");
+        });
+        it("returns empty array when backup dir does not exist", async () => {
+            readdir.mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            const result = await manager.list("my-volume");
+            expect(result).toEqual([]);
+        });
+    });
+    describe("delete()", () => {
+        it("removes the archive file", async () => {
+            await manager.delete("my-volume-2026-03-14T10-00-00-000Z");
+            expect(rm).toHaveBeenCalledWith("/data/fleet/snapshots/my-volume-2026-03-14T10-00-00-000Z.tar", { force: true });
+        });
+    });
+    describe("cleanup()", () => {
+        it("removes old snapshots and keeps recent ones", async () => {
+            const now = Date.now();
+            const oldTime = new Date(now - 2 * 60 * 60 * 1000); // 2 hours ago
+            const recentTime = new Date(now - 10 * 60 * 1000); // 10 minutes ago
+            readdir.mockResolvedValue([
+                "vol-2026-03-14T08-00-00-000Z.tar",
+                "vol-2026-03-14T09-50-00-000Z.tar",
+            ]);
+            stat
+                .mockResolvedValueOnce({ size: 100, mtime: oldTime })
+                .mockResolvedValueOnce({ size: 200, mtime: recentTime });
+            const maxAge = 60 * 60 * 1000; // 1 hour
+            const deleted = await manager.cleanup(maxAge);
+            expect(deleted).toBe(1);
+            expect(rm).toHaveBeenCalledTimes(1);
+            expect(rm).toHaveBeenCalledWith("/data/fleet/snapshots/vol-2026-03-14T08-00-00-000Z.tar", { force: true });
+        });
+        it("returns 0 when backup dir does not exist", async () => {
+            readdir.mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }));
+            const result = await manager.cleanup(60_000);
+            expect(result).toBe(0);
+        });
+        it("skips non-tar files", async () => {
+            readdir.mockResolvedValue(["readme.txt", ".gitkeep"]);
+            const result = await manager.cleanup(60_000);
+            expect(result).toBe(0);
+            expect(stat).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/fleet/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./repository-types.js";
+export * from "./rollout-strategy.js";
 export * from "./services.js";
 export * from "./types.js";
+export * from "./volume-snapshot-manager.js";

package/dist/fleet/index.js

@@ -1,3 +1,5 @@
 export * from "./repository-types.js";
+export * from "./rollout-strategy.js";
 export * from "./services.js";
 export * from "./types.js";
+export * from "./volume-snapshot-manager.js";

package/dist/fleet/rollout-strategy.d.ts

@@ -0,0 +1,52 @@
+import type { BotProfile } from "./types.js";
+export interface IRolloutStrategy {
+    /** Select next batch from remaining bots */
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    /** Milliseconds to wait between waves */
+    pauseDuration(): number;
+    /** What to do when a single bot update fails */
+    onBotFailure(botId: string, error: Error, attempt: number): "abort" | "skip" | "retry";
+    /** Max retries per bot before skip/abort */
+    maxRetries(): number;
+    /** Health check timeout per bot (ms) */
+    healthCheckTimeout(): number;
+}
+export interface RollingWaveOptions {
+    batchPercent?: number;
+    pauseMs?: number;
+    maxFailures?: number;
+}
+/**
+ * Rolling wave strategy — processes bots in configurable percentage batches.
+ * Create a new instance per rollout; totalFailures accumulates across waves
+ * within a single rollout. Call reset() if reusing across rollouts.
+ */
+export declare class RollingWaveStrategy implements IRolloutStrategy {
+    private readonly batchPercent;
+    private readonly pauseMs;
+    private readonly maxFailures;
+    private totalFailures;
+    constructor(opts?: RollingWaveOptions);
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+    /** Reset failure counters for reuse across rollouts. */
+    reset(): void;
+}
+export declare class SingleBotStrategy implements IRolloutStrategy {
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+}
+export declare class ImmediateStrategy implements IRolloutStrategy {
+    nextBatch(remaining: BotProfile[]): BotProfile[];
+    pauseDuration(): number;
+    onBotFailure(_botId: string, _error: Error, _attempt: number): "abort" | "skip" | "retry";
+    maxRetries(): number;
+    healthCheckTimeout(): number;
+}
+export declare function createRolloutStrategy(type: "rolling-wave" | "single-bot" | "immediate", options?: RollingWaveOptions): IRolloutStrategy;