@wopr-network/platform-core 1.69.0 → 1.70.0

package/dist/db/schema/pool-config.d.ts

@@ -0,0 +1,41 @@
+export declare const poolConfig: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "pool_config";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "pool_config";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        poolSize: import("drizzle-orm/pg-core").PgColumn<{
+            name: "pool_size";
+            tableName: "pool_config";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/db/schema/pool-config.js

@@ -0,0 +1,5 @@
+import { integer, pgTable } from "drizzle-orm/pg-core";
+export const poolConfig = pgTable("pool_config", {
+    id: integer("id").primaryKey().default(1),
+    poolSize: integer("pool_size").notNull().default(2),
+});

package/dist/db/schema/pool-instances.d.ts

@@ -0,0 +1,126 @@
+export declare const poolInstances: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "pool_instances";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "pool_instances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        containerId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "container_id";
+            tableName: "pool_instances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "pool_instances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "tenant_id";
+            tableName: "pool_instances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "pool_instances";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "pool_instances";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        claimedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "claimed_at";
+            tableName: "pool_instances";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;

package/dist/db/schema/pool-instances.js

@@ -0,0 +1,10 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+export const poolInstances = pgTable("pool_instances", {
+    id: text("id").primaryKey(),
+    containerId: text("container_id").notNull(),
+    status: text("status").notNull().default("warm"),
+    tenantId: text("tenant_id"),
+    name: text("name"),
+    createdAt: timestamp("created_at").notNull().defaultNow(),
+    claimedAt: timestamp("claimed_at"),
+});

package/dist/server/__tests__/container.test.js

@@ -144,7 +144,10 @@ describe("createTestContainer", () => {
             serviceKeyRepo: {},
         };
         const hotPool = {
-            poolManager: {},
+            start: async () => ({ stop: () => { } }),
+            claim: async () => null,
+            getPoolSize: async () => 2,
+            setPoolSize: async () => { },
         };
         const c = createTestContainer({ fleet, crypto, stripe, gateway, hotPool });
         expect(c.fleet).not.toBeNull();

package/dist/server/container.d.ts

@@ -45,8 +45,24 @@ export interface GatewayServices {
     serviceKeyRepo: IServiceKeyRepository;
 }
 export interface HotPoolServices {
-    /** Will be typed properly when extracted from nemoclaw. */
-    poolManager: unknown;
+    /** Start the pool manager (replenish loop + cleanup). */
+    start: () => Promise<{
+        stop: () => void;
+    }>;
+    /** Claim a warm instance from the pool. Returns null if empty. */
+    claim: (name: string, tenantId: string, adminUser: {
+        id: string;
+        email: string;
+        name: string;
+    }) => Promise<{
+        id: string;
+        name: string;
+        subdomain: string;
+    } | null>;
+    /** Get current pool size from DB. */
+    getPoolSize: () => Promise<number>;
+    /** Set pool size in DB. */
+    setPoolSize: (size: number) => Promise<void>;
 }
 export interface PlatformContainer {
     db: DrizzleDb;

package/dist/server/container.js

@@ -115,9 +115,8 @@ export async function buildContainer(bootConfig) {
         const serviceKeyRepo = new DrizzleServiceKeyRepository(db);
         gateway = { serviceKeyRepo };
     }
-    // hotPool: not yet implemented — needs nemoclaw extraction
-    const hotPool = null;
-    return {
+    // 12. Build the container (hotPool bound after construction)
+    const result = {
         db,
         pool,
         productConfig,
@@ -129,6 +128,21 @@ export async function buildContainer(bootConfig) {
         crypto,
         stripe,
         gateway,
-        hotPool,
+        hotPool: null,
     };
+    // Bind hot pool after container construction (closures need the full container)
+    if (bootConfig.features.hotPool && fleet) {
+        const { startHotPool, setPoolSize: setSize, getPoolSize: getSize } = await import("./services/hot-pool.js");
+        const { claimPoolInstance } = await import("./services/hot-pool-claim.js");
+        const { DrizzlePoolRepository } = await import("./services/pool-repository.js");
+        const poolRepo = new DrizzlePoolRepository(pool);
+        const hotPoolConfig = { provisionSecret: bootConfig.provisionSecret };
+        result.hotPool = {
+            start: () => startHotPool(result, poolRepo, hotPoolConfig),
+            claim: (name, tenantId, adminUser) => claimPoolInstance(result, poolRepo, name, tenantId, adminUser, hotPoolConfig),
+            getPoolSize: () => getSize(poolRepo),
+            setPoolSize: (size) => setSize(poolRepo, size),
+        };
+    }
+    return result;
 }

package/dist/server/lifecycle.js

@@ -26,6 +26,16 @@ export async function startBackgroundServices(container) {
             // Non-fatal — proxy sync will retry on next health tick
         }
     }
+    // Hot pool manager (if enabled)
+    if (container.hotPool) {
+        try {
+            const poolHandles = await container.hotPool.start();
+            handles.unsubscribes.push(poolHandles.stop);
+        }
+        catch {
+            // Non-fatal — pool will be empty but claiming falls back to cold create
+        }
+    }
     return handles;
 }
 // ---------------------------------------------------------------------------

package/dist/server/routes/admin.d.ts

@@ -107,5 +107,23 @@ export declare function createAdminRouter(container: PlatformContainer, config?:
         };
         meta: object;
     }>;
+    getPoolConfig: import("@trpc/server").TRPCQueryProcedure<{
+        input: void;
+        output: {
+            enabled: boolean;
+            poolSize: number;
+            warmCount: number;
+        };
+        meta: object;
+    }>;
+    setPoolSize: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            size: number;
+        };
+        output: {
+            poolSize: number;
+        };
+        meta: object;
+    }>;
 }>>;
 export {};

package/dist/server/routes/admin.js

@@ -269,5 +269,26 @@ export function createAdminRouter(container, config) {
                 orgCount,
             };
         }),
+        // -----------------------------------------------------------------------
+        // Hot pool config (DB-driven, admin-only)
+        // -----------------------------------------------------------------------
+        getPoolConfig: adminProcedure.query(async () => {
+            if (!container.hotPool) {
+                return { enabled: false, poolSize: 0, warmCount: 0 };
+            }
+            const poolSize = await container.hotPool.getPoolSize();
+            const warmRes = await container.pool.query("SELECT COUNT(*)::int AS count FROM pool_instances WHERE status = 'warm'");
+            const warmCount = Number(warmRes.rows[0]?.count ?? 0);
+            return { enabled: true, poolSize, warmCount };
+        }),
+        setPoolSize: adminProcedure
+            .input(z.object({ size: z.number().int().min(0).max(50) }))
+            .mutation(async ({ input }) => {
+            if (!container.hotPool) {
+                throw new Error("Hot pool not enabled");
+            }
+            await container.hotPool.setPoolSize(input.size);
+            return { poolSize: input.size };
+        }),
     });
 }

package/dist/server/services/hot-pool-claim.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Atomic hot pool claiming.
+ *
+ * Uses IPoolRepository for all DB operations. No raw pool.query().
+ */
+import type { PlatformContainer } from "../container.js";
+import type { IPoolRepository } from "./pool-repository.js";
+export interface ClaimConfig {
+    /** Shared secret for provision auth. */
+    provisionSecret: string;
+    /** Container name prefix. Default: "wopr". */
+    containerPrefix?: string;
+}
+export interface ClaimAdminUser {
+    id: string;
+    email: string;
+    name: string;
+}
+export interface ClaimResult {
+    id: string;
+    name: string;
+    subdomain: string;
+}
+/**
+ * Claim a warm pool instance, rename it, create a fleet profile,
+ * and register the proxy route.
+ *
+ * Returns the claim result on success, or null if the pool is empty.
+ */
+export declare function claimPoolInstance(container: PlatformContainer, repo: IPoolRepository, name: string, tenantId: string, _adminUser: ClaimAdminUser, config?: ClaimConfig): Promise<ClaimResult | null>;

package/dist/server/services/hot-pool-claim.js

@@ -0,0 +1,92 @@
+/**
+ * Atomic hot pool claiming.
+ *
+ * Uses IPoolRepository for all DB operations. No raw pool.query().
+ */
+import { randomBytes } from "node:crypto";
+import { logger } from "../../config/logger.js";
+import { replenishPool } from "./hot-pool.js";
+/**
+ * Claim a warm pool instance, rename it, create a fleet profile,
+ * and register the proxy route.
+ *
+ * Returns the claim result on success, or null if the pool is empty.
+ */
+export async function claimPoolInstance(container, repo, name, tenantId, _adminUser, config) {
+    if (!container.fleet)
+        throw new Error("Fleet services required for pool claim");
+    const pc = container.productConfig;
+    const containerPort = pc.fleet?.containerPort ?? 3100;
+    const containerImage = pc.fleet?.containerImage ?? "ghcr.io/wopr-network/platform:latest";
+    const platformDomain = pc.product?.domain ?? "localhost";
+    const prefix = config?.containerPrefix ?? "wopr";
+    // ---- Step 1: Atomically claim a warm instance ----
+    const claimed = await repo.claimWarm(tenantId, name);
+    if (!claimed)
+        return null;
+    const { id: instanceId, containerId } = claimed;
+    // ---- Step 2: Rename Docker container ----
+    const docker = container.fleet.docker;
+    const containerName = `${prefix}-${name}`;
+    try {
+        const c = docker.getContainer(containerId);
+        await c.rename({ name: containerName });
+        logger.info(`Pool claim: renamed container to ${containerName}`);
+    }
+    catch (err) {
+        logger.error("Pool claim: rename failed", { error: err.message });
+        await repo.markDead(instanceId);
+        return null;
+    }
+    // ---- Step 3: Create fleet profile ----
+    const serviceKeyRepo = container.fleet.serviceKeyRepo;
+    const gatewayKey = serviceKeyRepo ? await serviceKeyRepo.generate(tenantId, instanceId) : crypto.randomUUID();
+    const store = container.fleet.profileStore;
+    const profile = {
+        id: instanceId,
+        name,
+        tenantId,
+        image: containerImage,
+        description: `Managed instance: ${name}`,
+        env: {
+            PORT: String(containerPort),
+            HOST: "0.0.0.0",
+            NODE_ENV: "production",
+            PROVISION_SECRET: config?.provisionSecret ?? "",
+            BETTER_AUTH_SECRET: randomBytes(32).toString("hex"),
+            DATA_HOME: "/data",
+            HOSTED_MODE: "true",
+            DEPLOYMENT_MODE: "hosted_proxy",
+            DEPLOYMENT_EXPOSURE: "private",
+            MIGRATION_AUTO_APPLY: "true",
+            GATEWAY_KEY: gatewayKey,
+        },
+        restartPolicy: "unless-stopped",
+        releaseChannel: "stable",
+        updatePolicy: "manual",
+    };
+    await store.save(profile);
+    logger.info(`Pool claim: saved fleet profile for ${name} (${instanceId})`);
+    // ---- Step 4: Register proxy route ----
+    try {
+        if (container.fleet.proxy.addRoute) {
+            await container.fleet.proxy.addRoute({
+                instanceId,
+                subdomain: name,
+                upstreamHost: containerName,
+                upstreamPort: containerPort,
+                healthy: true,
+            });
+            logger.info(`Pool claim: registered proxy route ${name}.${platformDomain}`);
+        }
+    }
+    catch (err) {
+        logger.error("Pool claim: proxy route registration failed", { error: err.message });
+    }
+    // ---- Step 5: Replenish pool in background ----
+    replenishPool(container, repo, { provisionSecret: config?.provisionSecret ?? "" }).catch((err) => {
+        logger.error("Pool replenish after claim failed", { error: err.message });
+    });
+    const subdomain = `${name}.${platformDomain}`;
+    return { id: instanceId, name, subdomain };
+}

package/dist/server/services/hot-pool.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hot pool manager — pre-provisions warm containers for instant claiming.
+ *
+ * Reads desired pool size from DB (`pool_config` table) via IPoolRepository.
+ * Periodically replenishes the pool and cleans up dead containers.
+ *
+ * All config is DB-driven — no env vars for pool size, container image,
+ * or port. Admin API updates pool_config, this reads it.
+ */
+import type { PlatformContainer } from "../container.js";
+import type { IPoolRepository } from "./pool-repository.js";
+export interface HotPoolConfig {
+    /** Shared secret for provision auth between platform and managed instances. */
+    provisionSecret: string;
+    /** Replenish interval in ms. Default: 60_000. */
+    replenishIntervalMs?: number;
+}
+export interface HotPoolHandles {
+    replenishTimer: ReturnType<typeof setInterval>;
+    stop: () => void;
+}
+export declare function getPoolSize(repo: IPoolRepository): Promise<number>;
+export declare function setPoolSize(repo: IPoolRepository, size: number): Promise<void>;
+export declare function replenishPool(container: PlatformContainer, repo: IPoolRepository, config: HotPoolConfig): Promise<void>;
+export declare function startHotPool(container: PlatformContainer, repo: IPoolRepository, config: HotPoolConfig): Promise<HotPoolHandles>;

package/dist/server/services/hot-pool.js

@@ -0,0 +1,129 @@
+/**
+ * Hot pool manager — pre-provisions warm containers for instant claiming.
+ *
+ * Reads desired pool size from DB (`pool_config` table) via IPoolRepository.
+ * Periodically replenishes the pool and cleans up dead containers.
+ *
+ * All config is DB-driven — no env vars for pool size, container image,
+ * or port. Admin API updates pool_config, this reads it.
+ */
+import { logger } from "../../config/logger.js";
+// ---------------------------------------------------------------------------
+// Pool size — delegates to repository
+// ---------------------------------------------------------------------------
+export async function getPoolSize(repo) {
+    return repo.getPoolSize();
+}
+export async function setPoolSize(repo, size) {
+    return repo.setPoolSize(size);
+}
+// ---------------------------------------------------------------------------
+// Warm container management
+// ---------------------------------------------------------------------------
+async function createWarmContainer(container, repo, config) {
+    if (!container.fleet)
+        throw new Error("Fleet services required for hot pool");
+    const pc = container.productConfig;
+    const containerImage = pc.fleet?.containerImage ?? "ghcr.io/wopr-network/platform:latest";
+    const containerPort = pc.fleet?.containerPort ?? 3100;
+    const provisionSecret = config.provisionSecret;
+    const dockerNetwork = pc.fleet?.dockerNetwork ?? "";
+    const docker = container.fleet.docker;
+    const id = crypto.randomUUID();
+    const containerName = `pool-${id.slice(0, 8)}`;
+    const volumeName = `pool-${id.slice(0, 8)}`;
+    try {
+        // Init volume permissions
+        const init = await docker.createContainer({
+            Image: containerImage,
+            Entrypoint: ["/bin/sh", "-c"],
+            Cmd: ["chown -R 999:999 /data"],
+            User: "root",
+            HostConfig: { Binds: [`${volumeName}:/data`] },
+        });
+        await init.start();
+        await init.wait();
+        await init.remove();
+        const warmContainer = await docker.createContainer({
+            Image: containerImage,
+            name: containerName,
+            Env: [`PORT=${containerPort}`, `PROVISION_SECRET=${provisionSecret}`, "HOME=/data"],
+            HostConfig: {
+                Binds: [`${volumeName}:/data`],
+                RestartPolicy: { Name: "unless-stopped" },
+            },
+        });
+        await warmContainer.start();
+        if (dockerNetwork) {
+            const network = docker.getNetwork(dockerNetwork);
+            await network.connect({ Container: warmContainer.id });
+        }
+        await repo.insertWarm(id, warmContainer.id);
+        logger.info(`Hot pool: created warm container ${containerName} (${id})`);
+    }
+    catch (err) {
+        logger.error("Hot pool: failed to create warm container", {
+            error: err.message,
+        });
+    }
+}
+export async function replenishPool(container, repo, config) {
+    const desired = await repo.getPoolSize();
+    const current = await repo.warmCount();
+    const deficit = desired - current;
+    if (deficit <= 0)
+        return;
+    logger.info(`Hot pool: replenishing ${deficit} container(s) (have ${current}, want ${desired})`);
+    for (let i = 0; i < deficit; i++) {
+        await createWarmContainer(container, repo, config);
+    }
+}
+async function cleanupDead(container, repo) {
+    if (!container.fleet)
+        return;
+    const docker = container.fleet.docker;
+    const warmInstances = await repo.listWarm();
+    for (const instance of warmInstances) {
+        try {
+            const c = docker.getContainer(instance.containerId);
+            const info = await c.inspect();
+            if (!info.State.Running) {
+                await repo.markDead(instance.id);
+                try {
+                    await c.remove({ force: true });
+                }
+                catch {
+                    /* already gone */
+                }
+                logger.warn(`Hot pool: marked dead container ${instance.id}`);
+            }
+        }
+        catch {
+            await repo.markDead(instance.id);
+            logger.warn(`Hot pool: marked missing container ${instance.id} as dead`);
+        }
+    }
+    await repo.deleteDead();
+}
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+export async function startHotPool(container, repo, config) {
+    await cleanupDead(container, repo);
+    await replenishPool(container, repo, config);
+    const intervalMs = config.replenishIntervalMs ?? 60_000;
+    const replenishTimer = setInterval(async () => {
+        try {
+            await cleanupDead(container, repo);
+            await replenishPool(container, repo, config);
+        }
+        catch (err) {
+            logger.error("Hot pool tick failed", { error: err.message });
+        }
+    }, intervalMs);
+    logger.info("Hot pool manager started");
+    return {
+        replenishTimer,
+        stop: () => clearInterval(replenishTimer),
+    };
+}

package/dist/server/services/pool-repository.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Repository for hot pool database operations.
+ *
+ * Encapsulates all pool_config and pool_instances queries behind
+ * a testable interface. No raw pool.query() outside this file.
+ */
+import type { Pool } from "pg";
+export interface PoolInstance {
+    id: string;
+    containerId: string;
+    status: string;
+    tenantId: string | null;
+    name: string | null;
+}
+export interface IPoolRepository {
+    getPoolSize(): Promise<number>;
+    setPoolSize(size: number): Promise<void>;
+    warmCount(): Promise<number>;
+    insertWarm(id: string, containerId: string): Promise<void>;
+    listWarm(): Promise<PoolInstance[]>;
+    markDead(id: string): Promise<void>;
+    deleteDead(): Promise<void>;
+    claimWarm(tenantId: string, name: string): Promise<{
+        id: string;
+        containerId: string;
+    } | null>;
+    updateInstanceStatus(id: string, status: string): Promise<void>;
+}
+export declare class DrizzlePoolRepository implements IPoolRepository {
+    private pool;
+    constructor(pool: Pool);
+    getPoolSize(): Promise<number>;
+    setPoolSize(size: number): Promise<void>;
+    warmCount(): Promise<number>;
+    insertWarm(id: string, containerId: string): Promise<void>;
+    listWarm(): Promise<PoolInstance[]>;
+    markDead(id: string): Promise<void>;
+    deleteDead(): Promise<void>;
+    claimWarm(tenantId: string, name: string): Promise<{
+        id: string;
+        containerId: string;
+    } | null>;
+    updateInstanceStatus(id: string, status: string): Promise<void>;
+}

package/dist/server/services/pool-repository.js

@@ -0,0 +1,72 @@
+/**
+ * Repository for hot pool database operations.
+ *
+ * Encapsulates all pool_config and pool_instances queries behind
+ * a testable interface. No raw pool.query() outside this file.
+ */
+export class DrizzlePoolRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async getPoolSize() {
+        try {
+            const res = await this.pool.query("SELECT pool_size FROM pool_config WHERE id = 1");
+            return res.rows[0]?.pool_size ?? 2;
+        }
+        catch {
+            return 2;
+        }
+    }
+    async setPoolSize(size) {
+        await this.pool.query("INSERT INTO pool_config (id, pool_size) VALUES (1, $1) ON CONFLICT (id) DO UPDATE SET pool_size = $1", [size]);
+    }
+    async warmCount() {
+        const res = await this.pool.query("SELECT COUNT(*)::int AS count FROM pool_instances WHERE status = 'warm'");
+        return res.rows[0].count;
+    }
+    async insertWarm(id, containerId) {
+        await this.pool.query("INSERT INTO pool_instances (id, container_id, status) VALUES ($1, $2, 'warm')", [
+            id,
+            containerId,
+        ]);
+    }
+    async listWarm() {
+        const res = await this.pool.query("SELECT id, container_id, status, tenant_id, name FROM pool_instances WHERE status = 'warm'");
+        return res.rows.map((r) => ({
+            id: r.id,
+            containerId: r.container_id,
+            status: r.status,
+            tenantId: r.tenant_id ?? null,
+            name: r.name ?? null,
+        }));
+    }
+    async markDead(id) {
+        await this.pool.query("UPDATE pool_instances SET status = 'dead' WHERE id = $1", [id]);
+    }
+    async deleteDead() {
+        await this.pool.query("DELETE FROM pool_instances WHERE status = 'dead'");
+    }
+    async claimWarm(tenantId, name) {
+        const res = await this.pool.query(`UPDATE pool_instances
+          SET status = 'claimed',
+              claimed_at = NOW(),
+              tenant_id = $1,
+              name = $2
+        WHERE id = (
+          SELECT id FROM pool_instances
+           WHERE status = 'warm'
+           ORDER BY created_at ASC
+           LIMIT 1
+             FOR UPDATE SKIP LOCKED
+        )
+        RETURNING id, container_id`, [tenantId, name]);
+        if (res.rowCount === 0)
+            return null;
+        const row = res.rows[0];
+        return { id: row.id, containerId: row.container_id };
+    }
+    async updateInstanceStatus(id, status) {
+        await this.pool.query("UPDATE pool_instances SET status = $1 WHERE id = $2", [status, id]);
+    }
+}

package/drizzle/migrations/0025_hot_pool_tables.sql

@@ -0,0 +1,29 @@
+-- Hot pool: pre-provisioned warm containers for instant claiming
+CREATE TABLE IF NOT EXISTS "pool_config" (
+  "id" integer PRIMARY KEY DEFAULT 1,
+  "pool_size" integer NOT NULL DEFAULT 2
+);
+--> statement-breakpoint
+
+CREATE TABLE IF NOT EXISTS "pool_instances" (
+  "id" text PRIMARY KEY,
+  "container_id" text NOT NULL,
+  "status" text NOT NULL DEFAULT 'warm',
+  "tenant_id" text,
+  "name" text,
+  "created_at" timestamp NOT NULL DEFAULT now(),
+  "claimed_at" timestamp
+);
+--> statement-breakpoint
+
+-- Claim query: WHERE status = 'warm' ORDER BY created_at ASC FOR UPDATE SKIP LOCKED
+CREATE INDEX IF NOT EXISTS "pool_instances_status_created" ON "pool_instances" ("status", "created_at");
+--> statement-breakpoint
+
+-- Tenant lookup for admin queries
+CREATE INDEX IF NOT EXISTS "pool_instances_tenant" ON "pool_instances" ("tenant_id") WHERE "tenant_id" IS NOT NULL;
+--> statement-breakpoint
+
+-- Seed default pool config
+INSERT INTO "pool_config" ("id", "pool_size") VALUES (1, 2)
+  ON CONFLICT ("id") DO NOTHING;

package/package.json

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

package/src/db/schema/pool-config.ts

@@ -0,0 +1,6 @@
+import { integer, pgTable } from "drizzle-orm/pg-core";
+
+export const poolConfig = pgTable("pool_config", {
+  id: integer("id").primaryKey().default(1),
+  poolSize: integer("pool_size").notNull().default(2),
+});

package/src/db/schema/pool-instances.ts

@@ -0,0 +1,11 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const poolInstances = pgTable("pool_instances", {
+  id: text("id").primaryKey(),
+  containerId: text("container_id").notNull(),
+  status: text("status").notNull().default("warm"),
+  tenantId: text("tenant_id"),
+  name: text("name"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  claimedAt: timestamp("claimed_at"),
+});

package/src/server/__tests__/container.test.ts

@@ -172,7 +172,10 @@ describe("createTestContainer", () => {
     };
 
     const hotPool: HotPoolServices = {
-      poolManager: {},
+      start: async () => ({ stop: () => {} }),
+      claim: async () => null,
+      getPoolSize: async () => 2,
+      setPoolSize: async () => {},
     };
 
     const c = createTestContainer({ fleet, crypto, stripe, gateway, hotPool });

package/src/server/container.ts

@@ -53,8 +53,18 @@ export interface GatewayServices {
 }
 
 export interface HotPoolServices {
-  /** Will be typed properly when extracted from nemoclaw. */
-  poolManager: unknown;
+  /** Start the pool manager (replenish loop + cleanup). */
+  start: () => Promise<{ stop: () => void }>;
+  /** Claim a warm instance from the pool. Returns null if empty. */
+  claim: (
+    name: string,
+    tenantId: string,
+    adminUser: { id: string; email: string; name: string },
+  ) => Promise<{ id: string; name: string; subdomain: string } | null>;
+  /** Get current pool size from DB. */
+  getPoolSize: () => Promise<number>;
+  /** Set pool size in DB. */
+  setPoolSize: (size: number) => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -217,10 +227,8 @@ export async function buildContainer(bootConfig: BootConfig): Promise<PlatformCo
     gateway = { serviceKeyRepo };
   }
 
-  // hotPool: not yet implemented — needs nemoclaw extraction
-  const hotPool: HotPoolServices | null = null;
-
-  return {
+  // 12. Build the container (hotPool bound after construction)
+  const result: PlatformContainer = {
     db,
     pool,
     productConfig,
@@ -232,6 +240,25 @@ export async function buildContainer(bootConfig: BootConfig): Promise<PlatformCo
     crypto,
     stripe,
     gateway,
-    hotPool,
+    hotPool: null,
   };
+
+  // Bind hot pool after container construction (closures need the full container)
+  if (bootConfig.features.hotPool && fleet) {
+    const { startHotPool, setPoolSize: setSize, getPoolSize: getSize } = await import("./services/hot-pool.js");
+    const { claimPoolInstance } = await import("./services/hot-pool-claim.js");
+    const { DrizzlePoolRepository } = await import("./services/pool-repository.js");
+    const poolRepo = new DrizzlePoolRepository(pool);
+
+    const hotPoolConfig = { provisionSecret: bootConfig.provisionSecret };
+    result.hotPool = {
+      start: () => startHotPool(result, poolRepo, hotPoolConfig),
+      claim: (name, tenantId, adminUser) =>
+        claimPoolInstance(result, poolRepo, name, tenantId, adminUser, hotPoolConfig),
+      getPoolSize: () => getSize(poolRepo),
+      setPoolSize: (size) => setSize(poolRepo, size),
+    };
+  }
+
+  return result;
 }

package/src/server/lifecycle.ts

@@ -40,6 +40,16 @@ export async function startBackgroundServices(container: PlatformContainer): Pro
     }
   }
 
+  // Hot pool manager (if enabled)
+  if (container.hotPool) {
+    try {
+      const poolHandles = await container.hotPool.start();
+      handles.unsubscribes.push(poolHandles.stop);
+    } catch {
+      // Non-fatal — pool will be empty but claiming falls back to cold create
+    }
+  }
+
   return handles;
 }
 

package/src/server/routes/admin.ts

@@ -330,5 +330,31 @@ export function createAdminRouter(container: PlatformContainer, config?: AdminRo
         orgCount,
       };
     }),
+
+    // -----------------------------------------------------------------------
+    // Hot pool config (DB-driven, admin-only)
+    // -----------------------------------------------------------------------
+
+    getPoolConfig: adminProcedure.query(async () => {
+      if (!container.hotPool) {
+        return { enabled: false, poolSize: 0, warmCount: 0 };
+      }
+      const poolSize = await container.hotPool.getPoolSize();
+      const warmRes = await container.pool.query<{ count: string }>(
+        "SELECT COUNT(*)::int AS count FROM pool_instances WHERE status = 'warm'",
+      );
+      const warmCount = Number(warmRes.rows[0]?.count ?? 0);
+      return { enabled: true, poolSize, warmCount };
+    }),
+
+    setPoolSize: adminProcedure
+      .input(z.object({ size: z.number().int().min(0).max(50) }))
+      .mutation(async ({ input }) => {
+        if (!container.hotPool) {
+          throw new Error("Hot pool not enabled");
+        }
+        await container.hotPool.setPoolSize(input.size);
+        return { poolSize: input.size };
+      }),
   });
 }

package/src/server/services/hot-pool-claim.ts

@@ -0,0 +1,130 @@
+/**
+ * Atomic hot pool claiming.
+ *
+ * Uses IPoolRepository for all DB operations. No raw pool.query().
+ */
+
+import { randomBytes } from "node:crypto";
+
+import { logger } from "../../config/logger.js";
+import type { PlatformContainer } from "../container.js";
+import { replenishPool } from "./hot-pool.js";
+import type { IPoolRepository } from "./pool-repository.js";
+
+export interface ClaimConfig {
+  /** Shared secret for provision auth. */
+  provisionSecret: string;
+  /** Container name prefix. Default: "wopr". */
+  containerPrefix?: string;
+}
+
+export interface ClaimAdminUser {
+  id: string;
+  email: string;
+  name: string;
+}
+
+export interface ClaimResult {
+  id: string;
+  name: string;
+  subdomain: string;
+}
+
+/**
+ * Claim a warm pool instance, rename it, create a fleet profile,
+ * and register the proxy route.
+ *
+ * Returns the claim result on success, or null if the pool is empty.
+ */
+export async function claimPoolInstance(
+  container: PlatformContainer,
+  repo: IPoolRepository,
+  name: string,
+  tenantId: string,
+  _adminUser: ClaimAdminUser,
+  config?: ClaimConfig,
+): Promise<ClaimResult | null> {
+  if (!container.fleet) throw new Error("Fleet services required for pool claim");
+
+  const pc = container.productConfig;
+  const containerPort = pc.fleet?.containerPort ?? 3100;
+  const containerImage = pc.fleet?.containerImage ?? "ghcr.io/wopr-network/platform:latest";
+  const platformDomain = pc.product?.domain ?? "localhost";
+  const prefix = config?.containerPrefix ?? "wopr";
+
+  // ---- Step 1: Atomically claim a warm instance ----
+  const claimed = await repo.claimWarm(tenantId, name);
+  if (!claimed) return null;
+
+  const { id: instanceId, containerId } = claimed;
+
+  // ---- Step 2: Rename Docker container ----
+  const docker = container.fleet.docker;
+  const containerName = `${prefix}-${name}`;
+
+  try {
+    const c = docker.getContainer(containerId);
+    await c.rename({ name: containerName });
+    logger.info(`Pool claim: renamed container to ${containerName}`);
+  } catch (err) {
+    logger.error("Pool claim: rename failed", { error: (err as Error).message });
+    await repo.markDead(instanceId);
+    return null;
+  }
+
+  // ---- Step 3: Create fleet profile ----
+  const serviceKeyRepo = container.fleet.serviceKeyRepo;
+  const gatewayKey = serviceKeyRepo ? await serviceKeyRepo.generate(tenantId, instanceId) : crypto.randomUUID();
+
+  const store = container.fleet.profileStore;
+  const profile = {
+    id: instanceId,
+    name,
+    tenantId,
+    image: containerImage,
+    description: `Managed instance: ${name}`,
+    env: {
+      PORT: String(containerPort),
+      HOST: "0.0.0.0",
+      NODE_ENV: "production",
+      PROVISION_SECRET: config?.provisionSecret ?? "",
+      BETTER_AUTH_SECRET: randomBytes(32).toString("hex"),
+      DATA_HOME: "/data",
+      HOSTED_MODE: "true",
+      DEPLOYMENT_MODE: "hosted_proxy",
+      DEPLOYMENT_EXPOSURE: "private",
+      MIGRATION_AUTO_APPLY: "true",
+      GATEWAY_KEY: gatewayKey,
+    },
+    restartPolicy: "unless-stopped" as const,
+    releaseChannel: "stable" as const,
+    updatePolicy: "manual" as const,
+  };
+
+  await store.save(profile);
+  logger.info(`Pool claim: saved fleet profile for ${name} (${instanceId})`);
+
+  // ---- Step 4: Register proxy route ----
+  try {
+    if (container.fleet.proxy.addRoute) {
+      await container.fleet.proxy.addRoute({
+        instanceId,
+        subdomain: name,
+        upstreamHost: containerName,
+        upstreamPort: containerPort,
+        healthy: true,
+      });
+      logger.info(`Pool claim: registered proxy route ${name}.${platformDomain}`);
+    }
+  } catch (err) {
+    logger.error("Pool claim: proxy route registration failed", { error: (err as Error).message });
+  }
+
+  // ---- Step 5: Replenish pool in background ----
+  replenishPool(container, repo, { provisionSecret: config?.provisionSecret ?? "" }).catch((err) => {
+    logger.error("Pool replenish after claim failed", { error: (err as Error).message });
+  });
+
+  const subdomain = `${name}.${platformDomain}`;
+  return { id: instanceId, name, subdomain };
+}

package/src/server/services/hot-pool.ts

@@ -0,0 +1,174 @@
+/**
+ * Hot pool manager — pre-provisions warm containers for instant claiming.
+ *
+ * Reads desired pool size from DB (`pool_config` table) via IPoolRepository.
+ * Periodically replenishes the pool and cleans up dead containers.
+ *
+ * All config is DB-driven — no env vars for pool size, container image,
+ * or port. Admin API updates pool_config, this reads it.
+ */
+
+import { logger } from "../../config/logger.js";
+import type { PlatformContainer } from "../container.js";
+import type { IPoolRepository } from "./pool-repository.js";
+
+export interface HotPoolConfig {
+  /** Shared secret for provision auth between platform and managed instances. */
+  provisionSecret: string;
+  /** Replenish interval in ms. Default: 60_000. */
+  replenishIntervalMs?: number;
+}
+
+export interface HotPoolHandles {
+  replenishTimer: ReturnType<typeof setInterval>;
+  stop: () => void;
+}
+
+// ---------------------------------------------------------------------------
+// Pool size — delegates to repository
+// ---------------------------------------------------------------------------
+
+export async function getPoolSize(repo: IPoolRepository): Promise<number> {
+  return repo.getPoolSize();
+}
+
+export async function setPoolSize(repo: IPoolRepository, size: number): Promise<void> {
+  return repo.setPoolSize(size);
+}
+
+// ---------------------------------------------------------------------------
+// Warm container management
+// ---------------------------------------------------------------------------
+
+async function createWarmContainer(
+  container: PlatformContainer,
+  repo: IPoolRepository,
+  config: HotPoolConfig,
+): Promise<void> {
+  if (!container.fleet) throw new Error("Fleet services required for hot pool");
+
+  const pc = container.productConfig;
+  const containerImage = pc.fleet?.containerImage ?? "ghcr.io/wopr-network/platform:latest";
+  const containerPort = pc.fleet?.containerPort ?? 3100;
+  const provisionSecret = config.provisionSecret;
+  const dockerNetwork = pc.fleet?.dockerNetwork ?? "";
+  const docker = container.fleet.docker;
+  const id = crypto.randomUUID();
+  const containerName = `pool-${id.slice(0, 8)}`;
+  const volumeName = `pool-${id.slice(0, 8)}`;
+
+  try {
+    // Init volume permissions
+    const init = await docker.createContainer({
+      Image: containerImage,
+      Entrypoint: ["/bin/sh", "-c"],
+      Cmd: ["chown -R 999:999 /data"],
+      User: "root",
+      HostConfig: { Binds: [`${volumeName}:/data`] },
+    });
+    await init.start();
+    await init.wait();
+    await init.remove();
+
+    const warmContainer = await docker.createContainer({
+      Image: containerImage,
+      name: containerName,
+      Env: [`PORT=${containerPort}`, `PROVISION_SECRET=${provisionSecret}`, "HOME=/data"],
+      HostConfig: {
+        Binds: [`${volumeName}:/data`],
+        RestartPolicy: { Name: "unless-stopped" },
+      },
+    });
+
+    await warmContainer.start();
+
+    if (dockerNetwork) {
+      const network = docker.getNetwork(dockerNetwork);
+      await network.connect({ Container: warmContainer.id });
+    }
+
+    await repo.insertWarm(id, warmContainer.id);
+
+    logger.info(`Hot pool: created warm container ${containerName} (${id})`);
+  } catch (err) {
+    logger.error("Hot pool: failed to create warm container", {
+      error: (err as Error).message,
+    });
+  }
+}
+
+export async function replenishPool(
+  container: PlatformContainer,
+  repo: IPoolRepository,
+  config: HotPoolConfig,
+): Promise<void> {
+  const desired = await repo.getPoolSize();
+  const current = await repo.warmCount();
+  const deficit = desired - current;
+
+  if (deficit <= 0) return;
+
+  logger.info(`Hot pool: replenishing ${deficit} container(s) (have ${current}, want ${desired})`);
+
+  for (let i = 0; i < deficit; i++) {
+    await createWarmContainer(container, repo, config);
+  }
+}
+
+async function cleanupDead(container: PlatformContainer, repo: IPoolRepository): Promise<void> {
+  if (!container.fleet) return;
+
+  const docker = container.fleet.docker;
+  const warmInstances = await repo.listWarm();
+
+  for (const instance of warmInstances) {
+    try {
+      const c = docker.getContainer(instance.containerId);
+      const info = await c.inspect();
+      if (!info.State.Running) {
+        await repo.markDead(instance.id);
+        try {
+          await c.remove({ force: true });
+        } catch {
+          /* already gone */
+        }
+        logger.warn(`Hot pool: marked dead container ${instance.id}`);
+      }
+    } catch {
+      await repo.markDead(instance.id);
+      logger.warn(`Hot pool: marked missing container ${instance.id} as dead`);
+    }
+  }
+
+  await repo.deleteDead();
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+export async function startHotPool(
+  container: PlatformContainer,
+  repo: IPoolRepository,
+  config: HotPoolConfig,
+): Promise<HotPoolHandles> {
+  await cleanupDead(container, repo);
+  await replenishPool(container, repo, config);
+
+  const intervalMs = config.replenishIntervalMs ?? 60_000;
+  const replenishTimer = setInterval(async () => {
+    try {
+      await cleanupDead(container, repo);
+      await replenishPool(container, repo, config);
+    } catch (err) {
+      logger.error("Hot pool tick failed", { error: (err as Error).message });
+    }
+  }, intervalMs);
+
+  logger.info("Hot pool manager started");
+
+  return {
+    replenishTimer,
+    stop: () => clearInterval(replenishTimer),
+  };
+}

package/src/server/services/pool-repository.ts

@@ -0,0 +1,107 @@
+/**
+ * Repository for hot pool database operations.
+ *
+ * Encapsulates all pool_config and pool_instances queries behind
+ * a testable interface. No raw pool.query() outside this file.
+ */
+
+import type { Pool } from "pg";
+
+export interface PoolInstance {
+  id: string;
+  containerId: string;
+  status: string;
+  tenantId: string | null;
+  name: string | null;
+}
+
+export interface IPoolRepository {
+  getPoolSize(): Promise<number>;
+  setPoolSize(size: number): Promise<void>;
+  warmCount(): Promise<number>;
+  insertWarm(id: string, containerId: string): Promise<void>;
+  listWarm(): Promise<PoolInstance[]>;
+  markDead(id: string): Promise<void>;
+  deleteDead(): Promise<void>;
+  claimWarm(tenantId: string, name: string): Promise<{ id: string; containerId: string } | null>;
+  updateInstanceStatus(id: string, status: string): Promise<void>;
+}
+
+export class DrizzlePoolRepository implements IPoolRepository {
+  constructor(private pool: Pool) {}
+
+  async getPoolSize(): Promise<number> {
+    try {
+      const res = await this.pool.query("SELECT pool_size FROM pool_config WHERE id = 1");
+      return res.rows[0]?.pool_size ?? 2;
+    } catch {
+      return 2;
+    }
+  }
+
+  async setPoolSize(size: number): Promise<void> {
+    await this.pool.query(
+      "INSERT INTO pool_config (id, pool_size) VALUES (1, $1) ON CONFLICT (id) DO UPDATE SET pool_size = $1",
+      [size],
+    );
+  }
+
+  async warmCount(): Promise<number> {
+    const res = await this.pool.query("SELECT COUNT(*)::int AS count FROM pool_instances WHERE status = 'warm'");
+    return res.rows[0].count;
+  }
+
+  async insertWarm(id: string, containerId: string): Promise<void> {
+    await this.pool.query("INSERT INTO pool_instances (id, container_id, status) VALUES ($1, $2, 'warm')", [
+      id,
+      containerId,
+    ]);
+  }
+
+  async listWarm(): Promise<PoolInstance[]> {
+    const res = await this.pool.query(
+      "SELECT id, container_id, status, tenant_id, name FROM pool_instances WHERE status = 'warm'",
+    );
+    return res.rows.map((r: Record<string, unknown>) => ({
+      id: r.id as string,
+      containerId: r.container_id as string,
+      status: r.status as string,
+      tenantId: (r.tenant_id as string) ?? null,
+      name: (r.name as string) ?? null,
+    }));
+  }
+
+  async markDead(id: string): Promise<void> {
+    await this.pool.query("UPDATE pool_instances SET status = 'dead' WHERE id = $1", [id]);
+  }
+
+  async deleteDead(): Promise<void> {
+    await this.pool.query("DELETE FROM pool_instances WHERE status = 'dead'");
+  }
+
+  async claimWarm(tenantId: string, name: string): Promise<{ id: string; containerId: string } | null> {
+    const res = await this.pool.query(
+      `UPDATE pool_instances
+          SET status = 'claimed',
+              claimed_at = NOW(),
+              tenant_id = $1,
+              name = $2
+        WHERE id = (
+          SELECT id FROM pool_instances
+           WHERE status = 'warm'
+           ORDER BY created_at ASC
+           LIMIT 1
+             FOR UPDATE SKIP LOCKED
+        )
+        RETURNING id, container_id`,
+      [tenantId, name],
+    );
+    if (res.rowCount === 0) return null;
+    const row = res.rows[0] as { id: string; container_id: string };
+    return { id: row.id, containerId: row.container_id };
+  }
+
+  async updateInstanceStatus(id: string, status: string): Promise<void> {
+    await this.pool.query("UPDATE pool_instances SET status = $1 WHERE id = $2", [status, id]);
+  }
+}