@wopr-network/platform-core 1.24.0 → 1.26.0

package/dist/fleet/init-fleet-updater.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Wires the fleet auto-update pipeline: ImagePoller → RolloutOrchestrator → ContainerUpdater.
+ *
+ * Consumers call initFleetUpdater() with a Docker instance, FleetManager, and config.
+ * The pipeline detects new image digests, batches updates via a rollout strategy,
+ * snapshots volumes before updating, and restores on failure (nuclear rollback).
+ *
+ * When a new image digest is detected for ANY bot, the orchestrator triggers a
+ * fleet-wide rollout across all non-manual bots. This is intentional: the managed
+ * Paperclip image is shared across all tenants, so a single digest change means
+ * all bots need updating.
+ */
+import type Docker from "dockerode";
+import type { IBotProfileRepository } from "./bot-profile-repository.js";
+import type { FleetManager } from "./fleet-manager.js";
+import { ImagePoller } from "./image-poller.js";
+import type { IProfileStore } from "./profile-store.js";
+import { RolloutOrchestrator, type RolloutResult } from "./rollout-orchestrator.js";
+import { type RollingWaveOptions } from "./rollout-strategy.js";
+import { ContainerUpdater } from "./updater.js";
+import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
+export interface FleetUpdaterConfig {
+    /** Rollout strategy type. Default: "rolling-wave" */
+    strategy?: "rolling-wave" | "single-bot" | "immediate";
+    /** Options for RollingWaveStrategy (ignored for other strategies) */
+    strategyOptions?: RollingWaveOptions;
+    /** Directory for volume snapshots. Default: "/data/fleet/snapshots" */
+    snapshotDir?: string;
+    /** Called after each bot update */
+    onBotUpdated?: (result: {
+        botId: string;
+        success: boolean;
+        volumeRestored: boolean;
+    }) => void;
+    /** Called when a rollout completes */
+    onRolloutComplete?: (result: RolloutResult) => void;
+}
+export interface FleetUpdaterHandle {
+    poller: ImagePoller;
+    updater: ContainerUpdater;
+    orchestrator: RolloutOrchestrator;
+    snapshotManager: VolumeSnapshotManager;
+    /** Stop the poller and wait for any active rollout to finish */
+    stop: () => Promise<void>;
+}
+/**
+ * Initialize the fleet auto-update pipeline.
+ *
+ * Creates and wires: ImagePoller → RolloutOrchestrator → ContainerUpdater
+ * with VolumeSnapshotManager for nuclear rollback.
+ *
+ * @param docker - Dockerode instance for container operations
+ * @param fleet - FleetManager for container lifecycle
+ * @param profileStore - Legacy IProfileStore (used by ImagePoller/ContainerUpdater)
+ * @param profileRepo - PostgreSQL-backed IBotProfileRepository (used for updatable profile queries)
+ * @param config - Optional pipeline configuration
+ */
+export declare function initFleetUpdater(docker: Docker, fleet: FleetManager, profileStore: IProfileStore, profileRepo: IBotProfileRepository, config?: FleetUpdaterConfig): FleetUpdaterHandle;

package/dist/fleet/init-fleet-updater.js

@@ -0,0 +1,88 @@
+/**
+ * Wires the fleet auto-update pipeline: ImagePoller → RolloutOrchestrator → ContainerUpdater.
+ *
+ * Consumers call initFleetUpdater() with a Docker instance, FleetManager, and config.
+ * The pipeline detects new image digests, batches updates via a rollout strategy,
+ * snapshots volumes before updating, and restores on failure (nuclear rollback).
+ *
+ * When a new image digest is detected for ANY bot, the orchestrator triggers a
+ * fleet-wide rollout across all non-manual bots. This is intentional: the managed
+ * Paperclip image is shared across all tenants, so a single digest change means
+ * all bots need updating.
+ */
+import { logger } from "../config/logger.js";
+import { ImagePoller } from "./image-poller.js";
+import { RolloutOrchestrator } from "./rollout-orchestrator.js";
+import { createRolloutStrategy } from "./rollout-strategy.js";
+import { ContainerUpdater } from "./updater.js";
+import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
+/**
+ * Initialize the fleet auto-update pipeline.
+ *
+ * Creates and wires: ImagePoller → RolloutOrchestrator → ContainerUpdater
+ * with VolumeSnapshotManager for nuclear rollback.
+ *
+ * @param docker - Dockerode instance for container operations
+ * @param fleet - FleetManager for container lifecycle
+ * @param profileStore - Legacy IProfileStore (used by ImagePoller/ContainerUpdater)
+ * @param profileRepo - PostgreSQL-backed IBotProfileRepository (used for updatable profile queries)
+ * @param config - Optional pipeline configuration
+ */
+export function initFleetUpdater(docker, fleet, profileStore, profileRepo, config = {}) {
+    const { strategy: strategyType = "rolling-wave", strategyOptions, snapshotDir = "/data/fleet/snapshots", onBotUpdated, onRolloutComplete, } = config;
+    const poller = new ImagePoller(docker, profileStore);
+    const updater = new ContainerUpdater(docker, profileStore, fleet, poller);
+    const snapshotManager = new VolumeSnapshotManager(docker, snapshotDir);
+    const strategy = createRolloutStrategy(strategyType, strategyOptions);
+    const orchestrator = new RolloutOrchestrator({
+        updater,
+        snapshotManager,
+        strategy,
+        getUpdatableProfiles: async () => {
+            const profiles = await profileRepo.list();
+            return profiles.filter((p) => p.updatePolicy !== "manual");
+        },
+        onBotUpdated,
+        onRolloutComplete,
+    });
+    // Wire the detection → orchestration pipeline.
+    // Any digest change triggers a fleet-wide rollout because the managed image
+    // is shared across all tenants — one new digest means all bots need updating.
+    poller.onUpdateAvailable = async (_botId, _newDigest) => {
+        if (orchestrator.isRolling) {
+            logger.debug("Skipping update trigger — rollout already in progress");
+            return;
+        }
+        logger.info("New image digest detected — starting fleet-wide rollout");
+        await orchestrator.rollout().catch((err) => {
+            logger.error("Rollout failed", { err });
+        });
+    };
+    // Start polling
+    poller.start().catch((err) => {
+        logger.error("ImagePoller failed to start", { err });
+    });
+    logger.info("Fleet auto-update pipeline initialized", {
+        strategy: strategyType,
+        snapshotDir,
+    });
+    return {
+        poller,
+        updater,
+        orchestrator,
+        snapshotManager,
+        stop: async () => {
+            poller.stop();
+            // Wait for any in-flight rollout to complete before returning
+            if (orchestrator.isRolling) {
+                logger.info("Waiting for active rollout to finish before shutdown...");
+                // Poll until rollout finishes (max 5 minutes)
+                const deadline = Date.now() + 5 * 60 * 1000;
+                while (orchestrator.isRolling && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+            }
+            logger.info("Fleet auto-update pipeline stopped");
+        },
+    };
+}

package/drizzle/migrations/0008_payment_methods.sql

@@ -0,0 +1,22 @@
+CREATE TABLE IF NOT EXISTS "payment_methods" (
+  "id" text PRIMARY KEY NOT NULL,
+  "type" text NOT NULL,
+  "token" text NOT NULL,
+  "chain" text NOT NULL,
+  "contract_address" text,
+  "decimals" integer NOT NULL,
+  "display_name" text NOT NULL,
+  "enabled" boolean NOT NULL DEFAULT true,
+  "display_order" integer NOT NULL DEFAULT 0,
+  "rpc_url" text,
+  "confirmations" integer NOT NULL DEFAULT 1,
+  "created_at" text DEFAULT (now()) NOT NULL
+);
+--> statement-breakpoint
+INSERT INTO "payment_methods" ("id", "type", "token", "chain", "contract_address", "decimals", "display_name", "display_order", "confirmations") VALUES
+  ('USDC:base', 'erc20', 'USDC', 'base', '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', 6, 'USDC on Base', 0, 1),
+  ('USDT:base', 'erc20', 'USDT', 'base', '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2', 6, 'USDT on Base', 1, 1),
+  ('DAI:base', 'erc20', 'DAI', 'base', '0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb', 18, 'DAI on Base', 2, 1),
+  ('ETH:base', 'native', 'ETH', 'base', NULL, 18, 'ETH on Base', 3, 1),
+  ('BTC:mainnet', 'native', 'BTC', 'bitcoin', NULL, 8, 'Bitcoin', 10, 3)
+ON CONFLICT ("id") DO NOTHING;

package/drizzle/migrations/meta/_journal.json

@@ -57,6 +57,13 @@
       "when": 1742227200000,
       "tag": "0007_watcher_cursors",
       "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "7",
+      "when": 1742313600000,
+      "tag": "0008_payment_methods",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/billing/crypto/index.ts

@@ -8,6 +8,8 @@ export type { IWatcherCursorStore } from "./cursor-store.js";
 export { DrizzleWatcherCursorStore } from "./cursor-store.js";
 export * from "./evm/index.js";
 export * from "./oracle/index.js";
+export type { IPaymentMethodStore, PaymentMethodRecord } from "./payment-method-store.js";
+export { DrizzlePaymentMethodStore } from "./payment-method-store.js";
 export type {
   CryptoBillingConfig,
   CryptoCheckoutOpts,
@@ -16,5 +18,7 @@ export type {
   CryptoWebhookResult,
 } from "./types.js";
 export { mapBtcPayEventToStatus } from "./types.js";
+export type { UnifiedCheckoutDeps, UnifiedCheckoutResult } from "./unified-checkout.js";
+export { createUnifiedCheckout, MIN_CHECKOUT_USD } from "./unified-checkout.js";
 export type { CryptoWebhookDeps } from "./webhook.js";
 export { handleCryptoWebhook, verifyCryptoWebhookSignature } from "./webhook.js";

package/src/billing/crypto/payment-method-store.ts

@@ -0,0 +1,117 @@
+import { and, eq } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { paymentMethods } from "../../db/schema/crypto.js";
+
+export interface PaymentMethodRecord {
+  id: string;
+  type: string;
+  token: string;
+  chain: string;
+  contractAddress: string | null;
+  decimals: number;
+  displayName: string;
+  enabled: boolean;
+  displayOrder: number;
+  rpcUrl: string | null;
+  confirmations: number;
+}
+
+export interface IPaymentMethodStore {
+  /** List all enabled payment methods, ordered by displayOrder. */
+  listEnabled(): Promise<PaymentMethodRecord[]>;
+  /** List all payment methods (including disabled). */
+  listAll(): Promise<PaymentMethodRecord[]>;
+  /** Get a specific payment method by id. */
+  getById(id: string): Promise<PaymentMethodRecord | null>;
+  /** Get enabled methods by type (stablecoin, eth, btc). */
+  listByType(type: string): Promise<PaymentMethodRecord[]>;
+  /** Upsert a payment method (admin). */
+  upsert(method: PaymentMethodRecord): Promise<void>;
+  /** Enable or disable a payment method (admin). */
+  setEnabled(id: string, enabled: boolean): Promise<void>;
+}
+
+export class DrizzlePaymentMethodStore implements IPaymentMethodStore {
+  constructor(private readonly db: PlatformDb) {}
+
+  async listEnabled(): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db
+      .select()
+      .from(paymentMethods)
+      .where(eq(paymentMethods.enabled, true))
+      .orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async listAll(): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db.select().from(paymentMethods).orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async getById(id: string): Promise<PaymentMethodRecord | null> {
+    const row = (await this.db.select().from(paymentMethods).where(eq(paymentMethods.id, id)))[0];
+    return row ? toRecord(row) : null;
+  }
+
+  async listByType(type: string): Promise<PaymentMethodRecord[]> {
+    const rows = await this.db
+      .select()
+      .from(paymentMethods)
+      .where(and(eq(paymentMethods.type, type), eq(paymentMethods.enabled, true)))
+      .orderBy(paymentMethods.displayOrder);
+    return rows.map(toRecord);
+  }
+
+  async upsert(method: PaymentMethodRecord): Promise<void> {
+    await this.db
+      .insert(paymentMethods)
+      .values({
+        id: method.id,
+        type: method.type,
+        token: method.token,
+        chain: method.chain,
+        contractAddress: method.contractAddress,
+        decimals: method.decimals,
+        displayName: method.displayName,
+        enabled: method.enabled,
+        displayOrder: method.displayOrder,
+        rpcUrl: method.rpcUrl,
+        confirmations: method.confirmations,
+      })
+      .onConflictDoUpdate({
+        target: paymentMethods.id,
+        set: {
+          type: method.type,
+          token: method.token,
+          chain: method.chain,
+          contractAddress: method.contractAddress,
+          decimals: method.decimals,
+          displayName: method.displayName,
+          enabled: method.enabled,
+          displayOrder: method.displayOrder,
+          rpcUrl: method.rpcUrl,
+          confirmations: method.confirmations,
+        },
+      });
+  }
+
+  async setEnabled(id: string, enabled: boolean): Promise<void> {
+    await this.db.update(paymentMethods).set({ enabled }).where(eq(paymentMethods.id, id));
+  }
+}
+
+function toRecord(row: typeof paymentMethods.$inferSelect): PaymentMethodRecord {
+  return {
+    id: row.id,
+    type: row.type,
+    token: row.token,
+    chain: row.chain,
+    contractAddress: row.contractAddress,
+    decimals: row.decimals,
+    displayName: row.displayName,
+    enabled: row.enabled,
+    displayOrder: row.displayOrder,
+    rpcUrl: row.rpcUrl,
+    confirmations: row.confirmations,
+  };
+}

package/src/billing/crypto/unified-checkout.ts

@@ -0,0 +1,190 @@
+import { Credit } from "../../credits/credit.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import { deriveDepositAddress } from "./evm/address-gen.js";
+import { centsToNative } from "./oracle/convert.js";
+import type { IPriceOracle } from "./oracle/types.js";
+import type { PaymentMethodRecord } from "./payment-method-store.js";
+
+export const MIN_CHECKOUT_USD = 10;
+
+export interface UnifiedCheckoutDeps {
+  chargeStore: Pick<ICryptoChargeRepository, "getNextDerivationIndex" | "createStablecoinCharge">;
+  oracle: IPriceOracle;
+  evmXpub: string;
+  btcXpub?: string;
+}
+
+export interface UnifiedCheckoutResult {
+  depositAddress: string;
+  /** Human-readable amount to send (e.g. "50 USDC", "0.014285 ETH"). */
+  displayAmount: string;
+  amountUsd: number;
+  token: string;
+  chain: string;
+  referenceId: string;
+  /** For volatile assets: price at checkout time (USD cents per unit). */
+  priceCents?: number;
+}
+
+/**
+ * Unified checkout — one entry point for all payment methods.
+ *
+ * Looks up the method record, routes by type:
+ *   - erc20: derives EVM address, computes token amount (1:1 USD for stablecoins)
+ *   - native (ETH): derives EVM address, oracle-priced
+ *   - native (BTC): derives BTC address, oracle-priced
+ *
+ * CRITICAL: amountUsd → integer cents via Credit.fromDollars().toCentsRounded().
+ */
+export async function createUnifiedCheckout(
+  deps: UnifiedCheckoutDeps,
+  method: PaymentMethodRecord,
+  opts: { tenant: string; amountUsd: number },
+): Promise<UnifiedCheckoutResult> {
+  if (!Number.isFinite(opts.amountUsd) || opts.amountUsd < MIN_CHECKOUT_USD) {
+    throw new Error(`Minimum payment amount is $${MIN_CHECKOUT_USD}`);
+  }
+
+  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+
+  if (method.type === "erc20") {
+    return handleErc20(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
+  }
+  if (method.token === "ETH") {
+    return handleNativeEth(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
+  }
+  if (method.token === "BTC") {
+    return handleNativeBtc(deps, method, opts.tenant, amountUsdCents, opts.amountUsd);
+  }
+
+  throw new Error(`Unsupported payment method type: ${method.type}/${method.token}`);
+}
+
+async function handleErc20(
+  deps: UnifiedCheckoutDeps,
+  method: PaymentMethodRecord,
+  tenant: string,
+  amountUsdCents: number,
+  amountUsd: number,
+): Promise<UnifiedCheckoutResult> {
+  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
+
+  return {
+    depositAddress,
+    displayAmount: `${amountUsd} ${method.token}`,
+    amountUsd,
+    token: method.token,
+    chain: method.chain,
+    referenceId: `erc20:${method.chain}:${depositAddress}`,
+  };
+}
+
+async function handleNativeEth(
+  deps: UnifiedCheckoutDeps,
+  method: PaymentMethodRecord,
+  tenant: string,
+  amountUsdCents: number,
+  amountUsd: number,
+): Promise<UnifiedCheckoutResult> {
+  const { priceCents } = await deps.oracle.getPrice("ETH");
+  const expectedWei = centsToNative(amountUsdCents, priceCents, 18);
+  const depositAddress = await deriveAndStore(deps, method, tenant, amountUsdCents);
+
+  const divisor = BigInt("1000000000000000000");
+  const whole = expectedWei / divisor;
+  const frac = (expectedWei % divisor).toString().padStart(18, "0").slice(0, 6);
+
+  return {
+    depositAddress,
+    displayAmount: `${whole}.${frac} ETH`,
+    amountUsd,
+    token: "ETH",
+    chain: method.chain,
+    referenceId: `eth:${method.chain}:${depositAddress}`,
+    priceCents,
+  };
+}
+
+async function handleNativeBtc(
+  deps: UnifiedCheckoutDeps,
+  _method: PaymentMethodRecord,
+  tenant: string,
+  amountUsdCents: number,
+  amountUsd: number,
+): Promise<UnifiedCheckoutResult> {
+  const { priceCents } = await deps.oracle.getPrice("BTC");
+  const expectedSats = centsToNative(amountUsdCents, priceCents, 8);
+
+  // BTC address derivation uses btcXpub — import from btc module
+  const { deriveBtcAddress } = await import("./btc/address-gen.js");
+  if (!deps.btcXpub) throw new Error("BTC payments not configured (no BTC_XPUB)");
+
+  const maxRetries = 3;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveBtcAddress(deps.btcXpub, derivationIndex, "mainnet");
+    const referenceId = `btc:${depositAddress}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: tenant,
+        amountUsdCents,
+        chain: "bitcoin",
+        token: "BTC",
+        depositAddress,
+        derivationIndex,
+      });
+
+      const btcAmount = Number(expectedSats) / 100_000_000;
+      return {
+        depositAddress,
+        displayAmount: `${btcAmount.toFixed(8)} BTC`,
+        amountUsd,
+        token: "BTC",
+        chain: "bitcoin",
+        referenceId,
+        priceCents,
+      };
+    } catch (err: unknown) {
+      const code = (err as { code?: string }).code;
+      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
+      if (!isConflict || attempt === maxRetries) throw err;
+    }
+  }
+
+  throw new Error("Failed to claim derivation index after retries");
+}
+
+/** Derive an EVM deposit address and store the charge. Retries on unique conflict. */
+async function deriveAndStore(
+  deps: UnifiedCheckoutDeps,
+  method: PaymentMethodRecord,
+  tenant: string,
+  amountUsdCents: number,
+): Promise<string> {
+  const maxRetries = 3;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    const derivationIndex = await deps.chargeStore.getNextDerivationIndex();
+    const depositAddress = deriveDepositAddress(deps.evmXpub, derivationIndex);
+    const referenceId = `${method.type}:${method.chain}:${depositAddress}`;
+
+    try {
+      await deps.chargeStore.createStablecoinCharge({
+        referenceId,
+        tenantId: tenant,
+        amountUsdCents,
+        chain: method.chain,
+        token: method.token,
+        depositAddress,
+        derivationIndex,
+      });
+      return depositAddress;
+    } catch (err: unknown) {
+      const code = (err as { code?: string }).code;
+      const isConflict = code === "23505" || (err instanceof Error && err.message.includes("unique_violation"));
+      if (!isConflict || attempt === maxRetries) throw err;
+    }
+  }
+  throw new Error("Failed to claim derivation index after retries");
+}

package/src/db/schema/crypto.ts

@@ -1,5 +1,5 @@
 import { sql } from "drizzle-orm";
-import { index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
+import { boolean, index, integer, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
 
 /**
  * Crypto payment charges — tracks the lifecycle of each BTCPay invoice.
@@ -46,6 +46,26 @@ export const watcherCursors = pgTable("watcher_cursors", {
   updatedAt: text("updated_at").notNull().default(sql`(now())`),
 });
 
+/**
+ * Payment method registry — runtime-configurable tokens/chains.
+ * Admin inserts a row to enable a new payment method. No deploy needed.
+ * Contract addresses are immutable on-chain but configurable here.
+ */
+export const paymentMethods = pgTable("payment_methods", {
+  id: text("id").primaryKey(), // "USDC:base", "ETH:base", "BTC:mainnet"
+  type: text("type").notNull(), // "stablecoin", "eth", "btc"
+  token: text("token").notNull(), // "USDC", "ETH", "BTC"
+  chain: text("chain").notNull(), // "base", "ethereum", "bitcoin"
+  contractAddress: text("contract_address"), // null for native (ETH, BTC)
+  decimals: integer("decimals").notNull(),
+  displayName: text("display_name").notNull(),
+  enabled: boolean("enabled").notNull().default(true),
+  displayOrder: integer("display_order").notNull().default(0),
+  rpcUrl: text("rpc_url"), // override per-chain RPC (null = use default)
+  confirmations: integer("confirmations").notNull().default(1),
+  createdAt: text("created_at").notNull().default(sql`(now())`),
+});
+
 /** Processed transaction IDs for watchers without block cursors (e.g. BTC). */
 export const watcherProcessed = pgTable(
   "watcher_processed",

package/src/fleet/__tests__/init-fleet-updater.test.ts

@@ -0,0 +1,129 @@
+import type Docker from "dockerode";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { IBotProfileRepository } from "../bot-profile-repository.js";
+import type { FleetManager } from "../fleet-manager.js";
+import { initFleetUpdater } from "../init-fleet-updater.js";
+import type { IProfileStore } from "../profile-store.js";
+
+function mockDocker(): Docker {
+  return {} as Docker;
+}
+
+function mockFleet(): FleetManager {
+  return {} as FleetManager;
+}
+
+function mockStore(): IProfileStore {
+  return {
+    list: vi.fn(async () => []),
+    get: vi.fn(async () => undefined),
+    save: vi.fn(async () => {}),
+    delete: vi.fn(async () => {}),
+  } as unknown as IProfileStore;
+}
+
+function mockRepo(profiles: unknown[] = []): IBotProfileRepository {
+  return {
+    list: vi.fn(async () => profiles),
+    get: vi.fn(async () => null),
+    save: vi.fn(async (p: unknown) => p),
+    delete: vi.fn(async () => true),
+  } as unknown as IBotProfileRepository;
+}
+
+describe("initFleetUpdater", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns a handle with all components", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    expect(handle.poller).toBeDefined();
+    expect(handle.updater).toBeDefined();
+    expect(handle.orchestrator).toBeDefined();
+    expect(handle.snapshotManager).toBeDefined();
+    expect(handle.stop).toBeTypeOf("function");
+
+    await handle.stop();
+  });
+
+  it("wires poller.onUpdateAvailable to orchestrator", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    expect(handle.poller.onUpdateAvailable).toBeTypeOf("function");
+
+    await handle.stop();
+  });
+
+  it("accepts custom strategy config", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+      strategy: "immediate",
+      snapshotDir: "/tmp/snapshots",
+    });
+
+    expect(handle.orchestrator).toBeDefined();
+
+    await handle.stop();
+  });
+
+  it("accepts callbacks", async () => {
+    const onBotUpdated = vi.fn();
+    const onRolloutComplete = vi.fn();
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+      onBotUpdated,
+      onRolloutComplete,
+    });
+
+    expect(handle.orchestrator).toBeDefined();
+
+    await handle.stop();
+  });
+
+  it("stop() stops the poller", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    const stopSpy = vi.spyOn(handle.poller, "stop");
+
+    await handle.stop();
+
+    expect(stopSpy).toHaveBeenCalled();
+  });
+
+  it("filters manual-policy bots from updatable profiles", async () => {
+    const repo = mockRepo([
+      { id: "b1", updatePolicy: "nightly" },
+      { id: "b2", updatePolicy: "manual" },
+      { id: "b3", updatePolicy: "on-push" },
+    ]);
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), repo, {
+      strategy: "immediate",
+    });
+
+    const rolloutResult = await handle.orchestrator.rollout();
+
+    // b2 (manual) should be filtered out, b1 and b3 included
+    expect(rolloutResult.totalBots).toBe(2);
+
+    await handle.stop();
+  });
+
+  it("uses profileRepo for updatable profiles, not profileStore", async () => {
+    const store = mockStore();
+    const repo = mockRepo([{ id: "b1", updatePolicy: "nightly" }]);
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), store, repo, {
+      strategy: "immediate",
+    });
+
+    await handle.orchestrator.rollout();
+
+    // profileRepo.list() was called for updatable profiles
+    expect(repo.list).toHaveBeenCalled();
+    // profileStore.list() may also be called by ImagePoller — that's expected
+
+    await handle.stop();
+  });
+});

package/src/fleet/index.ts

@@ -1,3 +1,4 @@
+export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";
 export * from "./rollout-strategy.js";