@helyx/bot 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.4.1
+
+### Patch Changes
+
+- d25b465: Replace the user-specific shard diagnostic with a reusable, internal-guild-only
+  `/dev` command. Authorize Discord administrators or configured role IDs, expose
+  bounded shard, bot/module-version and process diagnostics, and keep the command
+  available for validating the unsharded compatibility baseline.
+- Updated dependencies [d25b465]
+  - @helyx/config@0.4.1
+  - @helyx/sdk@0.3.2
+  - @helyx/core@0.1.7
+  - @helyx/framework@0.1.7
+  - @helyx/platform@0.2.3
+
+## 0.4.0
+
+### Minor Changes
+
+- 9cdb2ef: Add the opt-in shard supervisor/worker runtime, fenced coordination and routing,
+  durable command state, shard-aware guild ownership, and private operational
+  health while preserving unsharded defaults.
+
+### Patch Changes
+
+- Updated dependencies [9cdb2ef]
+  - @helyx/control-protocol@0.1.2
+  - @helyx/config@0.4.0
+  - @helyx/database@0.4.0
+  - @helyx/sdk@0.3.1
+  - @helyx/platform@0.2.2
+  - @helyx/core@0.1.6
+  - @helyx/framework@0.1.6
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -24,4 +24,72 @@ bot-control endpoint and a separate least-privilege PostgreSQL executor
 credential. The bot refuses Privacy execution when that credential resolves to
 the ordinary runtime database role.
 
+## Shard configuration and operations
+
+`HELYX_SHARD_MODE=off` is the default and compatibility baseline. It runs the
+existing unsharded bot path. Do not set shard-only tuning values in this mode:
+startup rejects shard count, workers, Redis, generation, database budget and
+explicit database-pool settings. The internal `/dev` diagnostics remain
+available in this mode when their guild and role configuration is present.
+
+| Mode    | Required values              | Prohibited values                                                             | Behaviour                                                        |
+| ------- | ---------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `off`   | None                         | Shard count, workers, Redis, namespace, generation, budget and explicit pools | Existing single-process behaviour                                |
+| `auto`  | None for local mode          | Shard count; Redis and namespace unless coordinated                           | Obtains Discord's recommended total                              |
+| `fixed` | `HELYX_SHARD_COUNT` (1-4096) | None beyond the scope rules                                                   | Uses the deliberate total; workers per replica may not exceed it |
+
+`HELYX_SHARD_SCOPE` defaults to `local`; use it for one supervisor host.
+`coordinated` is only valid in a sharded mode and requires all of
+`HELYX_SHARD_REDIS_URL` (`redis:` or `rediss:`),
+`HELYX_SHARD_REDIS_NAMESPACE` (lowercase safe 3-128-character namespace),
+and `HELYX_SHARD_GENERATION` (safe 1-128-character identifier). Redis URL and
+namespace are forbidden in local mode. Generation is optional for local
+sharded mode and forbidden when sharding is off.
+
+`HELYX_SHARD_WORKERS_PER_REPLICA` is a positive integer up to 64 and defaults
+to 1 when off or 2 when sharded. In sharded modes
+`HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX` and
+`HELYX_SHARD_WORKER_DATABASE_POOL_MAX` default to 2 and 4 respectively (each
+may be 1-20).
+`HELYX_SHARD_DATABASE_CONNECTION_BUDGET` is required for any production
+sharded mode, optional elsewhere, and may not exceed 1000. When it is set,
+the following must fit:
+
+```text
+supervisor pool + (workers per replica x worker pool) + (2 when Privacy is enabled) <= database budget
+```
+
+Record the provider's actual connection, memory, CPU and replica limits before
+choosing workers or pools; this repository does not declare a measured
+production budget.
+
+`DISCORD_INTERNAL_GUILD_ID` registers the private `/dev` command only in the
+exact internal guild. `APPROVED_ROLES` is a de-duplicated, comma-separated
+list of at most 100 Discord role IDs. A caller must have Discord's
+Administrator permission or at least one approved role; role names are never
+used for authorization. Every response is ephemeral and read-only:
+
+- `/dev shards` reports bounded shard health, including the unsharded
+  compatibility baseline;
+- `/dev bot` reports the bot build and bounded installed-module versions;
+- `/dev proc` reports safe metrics for the process handling the command.
+
+No `/dev` command exposes tokens, URLs, Redis keys, database details,
+environment variables or process arguments. Future developer subcommands must
+extend this guild-only `/dev` root and reuse the same authorization boundary.
+Hosted operators with `operations.read` can use the Admin Operations shard
+view instead.
+
+For self-hosting, leave the default `off` unless the owner has sized the local
+machine and database. `auto` with the default `local` scope is the supported
+advanced local path and does not require Redis. Coordinated multi-host
+self-hosting is outside the first release.
+
+Changing the total shard count redistributes guild ownership. Treat it as a
+generation change: drain the old generation before admitting the new one and
+never run both as active owners. Shard-capable code does not authorize hosted
+activation. Phase 10 production activation, replica scaling, or any Railway
+variable change requires separate owner authorization; do not provision a new
+Redis or coordinator service for sharding.
+
 For packaged operation use `helyx start`. `helyx migrate` applies core database migrations without Discord, and read-only `helyx doctor` verifies environment, PostgreSQL migration history, and configured package metadata.

package/dist/cloud-connector.d.ts

@@ -11,13 +11,47 @@ export interface CloudConnectorStatus {
     lastConnectedAt?: Date;
     lastErrorCode?: string;
 }
-export declare class CloudConnectorController {
+export interface CloudDiscordSnapshot {
+    applicationId: string;
+    botUserId: string;
+    botUsername: string;
+    ownerUserIds: string[];
+    guilds: Array<{
+        guildId: string;
+        name: string;
+        ownerUserId: string | null;
+    }>;
+}
+export interface CloudDiscordDirectory {
+    snapshot(): Promise<CloudDiscordSnapshot>;
+}
+export interface CloudConnector {
+    setControlHandler(handler: BotControlHandler): void;
+    start(): Promise<void>;
+    status(): CloudConnectorStatus;
+    getSupportConsent(): Promise<CloudConnectorConsentRecord>;
+    updateSupportConsent(input: {
+        supportInspectionEnabled: boolean;
+        supportDataClasses: string[];
+        diagnosticsEnabled: boolean;
+    }): Promise<CloudConnectorConsentRecord>;
+    enrol(rawToken: string, source: "startup" | "discord" | "file"): Promise<CloudConnectorStatus>;
+    disconnect(): Promise<void>;
+    rotate(): Promise<CloudConnectorStatus>;
+    stop(): Promise<void>;
+}
+export declare class ClientCloudDiscordDirectory implements CloudDiscordDirectory {
+    private readonly client;
+    constructor(client: Client);
+    snapshot(): Promise<CloudDiscordSnapshot>;
+}
+export declare class CloudConnectorController implements CloudConnector {
     #private;
     private readonly input;
     constructor(input: {
         environment: BotEnvironment;
         database: DatabasePool;
-        client: Client;
+        discord: CloudDiscordDirectory;
         modules: readonly ConfiguredModulePackage[];
         coreVersion: string;
         logger: Logger;

package/dist/cloud-connector.js

@@ -1,4 +1,4 @@
-import { CLOUD_DEFAULT_REQUEST_TIMEOUT_MS, CLOUD_PROTOCOL_VERSION, ConnectionSequenceGuard, assertCloudMessageSize, cloudControlResponsePayloadSchema, connectedCloudMessageSchema, connectorAcceptedSchema, connectorChallengeSchema, connectorCredentialActionSchema, connectorHelloSchema, connectorRejectedSchema, generateConnectorKeyPair, signConnectorCredentialAction, signConnectorChallenge, } from "@helyx/control-protocol";
+import { CLOUD_DEFAULT_REQUEST_TIMEOUT_MS, CLOUD_PROTOCOL_VERSION, ConnectionSequenceGuard, assertCloudHandshakeSize, assertCloudMessageSize, cloudControlResponsePayloadSchema, connectedCloudMessageSchema, connectorAcceptedSchema, connectorChallengeSchema, connectorCredentialActionSchema, connectorHelloSchema, connectorRejectedSchema, generateConnectorKeyPair, signConnectorCredentialAction, signConnectorChallenge, } from "@helyx/control-protocol";
 import { CloudConnectorRepository, } from "@helyx/database";
 import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
@@ -42,6 +42,34 @@ const supportConsentInputSchema = z
     diagnosticsEnabled: z.boolean(),
 })
     .strict();
+export class ClientCloudDiscordDirectory {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async snapshot() {
+        const application = await this.client.application?.fetch();
+        const botUser = this.client.user;
+        if (!application || !botUser)
+            throw new Error("discord_not_ready");
+        const owner = application.owner;
+        return {
+            applicationId: application.id,
+            botUserId: botUser.id,
+            botUsername: botUser.username,
+            ownerUserIds: !owner
+                ? []
+                : "members" in owner
+                    ? [...owner.members.keys()]
+                    : [owner.id],
+            guilds: this.client.guilds.cache.map((guild) => ({
+                guildId: guild.id,
+                name: guild.name,
+                ownerUserId: guild.ownerId || null,
+            })),
+        };
+    }
+}
 export class CloudConnectorController {
     input;
     #repository;
@@ -143,9 +171,8 @@ export class CloudConnectorController {
             throw new CloudConnectorUserError("HELYX_DATA_ENCRYPTION_KEY is not configured");
         const token = normalizeEnrolmentToken(rawToken);
         const keyPair = generateConnectorKeyPair();
-        const application = await this.input.client.application?.fetch();
-        const botUser = this.input.client.user;
-        if (!application || !botUser)
+        const discord = await this.input.discord.snapshot().catch(() => undefined);
+        if (!discord)
             throw new CloudConnectorUserError("Discord must be connected before Cloud Connect enrolment");
         let response;
         try {
@@ -161,9 +188,9 @@ export class CloudConnectorController {
                     publicKeyFingerprint: keyPair.fingerprint,
                     protocolVersion: CLOUD_PROTOCOL_VERSION,
                     coreVersion: this.input.coreVersion,
-                    botApplicationId: application.id,
-                    botUserId: botUser.id,
-                    displayName: botUser.username,
+                    botApplicationId: discord.applicationId,
+                    botUserId: discord.botUserId,
+                    displayName: discord.botUsername,
                 }),
                 signal: AbortSignal.timeout(CLOUD_DEFAULT_REQUEST_TIMEOUT_MS),
             });
@@ -456,15 +483,7 @@ export class CloudConnectorController {
     async #sendHello(socket, identity, privateKey, challenge) {
         if (challenge.installationId !== identity.installationId)
             throw new Error("challenge_installation_mismatch");
-        const application = await this.input.client.application?.fetch();
-        const botUser = this.input.client.user;
-        if (!application || !botUser)
-            throw new Error("discord_not_ready");
-        const guilds = this.input.client.guilds.cache.map((guild) => ({
-            guildId: guild.id,
-            name: guild.name,
-            ownerUserId: guild.ownerId || null,
-        }));
+        const discord = await this.input.discord.snapshot();
         const capabilities = connectorCapabilities();
         const hello = connectorHelloSchema.parse({
             protocolVersion: CLOUD_PROTOCOL_VERSION,
@@ -476,8 +495,8 @@ export class CloudConnectorController {
             challengeId: challenge.challengeId,
             signature: signConnectorChallenge(privateKey, challenge),
             coreVersion: this.input.coreVersion,
-            botApplicationId: application.id,
-            botUserId: botUser.id,
+            botApplicationId: discord.applicationId,
+            botUserId: discord.botUserId,
             capabilities,
             modules: this.input.modules.map(({ specifier, definition }) => ({
                 id: definition.manifest.id,
@@ -486,9 +505,11 @@ export class CloudConnectorController {
                 manifestSchemaVersion: 1,
                 configurationSchemaVersion: definition.configuration?.schemaVersion ?? 1,
             })),
-            guilds,
+            guilds: discord.guilds,
         });
-        socket.send(JSON.stringify(hello));
+        const encodedHello = JSON.stringify(hello);
+        assertCloudHandshakeSize(encodedHello);
+        socket.send(encodedHello);
     }
     async #dispatch(request, correlationId) {
         try {

package/dist/cloud-management-module.d.ts

@@ -1,15 +1,17 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import type { Client } from "discord.js";
-import type { CloudConnectorController } from "./cloud-connector.js";
+import { type CloudConnector, type CloudDiscordDirectory } from "./cloud-connector.js";
 export declare class DeploymentOwnerAuthorizer {
     #private;
-    constructor(client: Client, configuredOwnerUserIds: readonly string[]);
+    constructor(directory: CloudDiscordDirectory | Client, configuredOwnerUserIds: readonly string[]);
     isOwner(userId: string): boolean;
     refresh(): Promise<void>;
 }
 export declare function createCloudManagementModule(input: {
-    connector: CloudConnectorController;
+    connector: CloudConnector;
+    discord?: CloudDiscordDirectory;
     client: Client;
     configuredOwnerUserIds: readonly string[];
+    periodicOwnerRefresh?: boolean;
 }): ModuleDefinition;
 //# sourceMappingURL=cloud-management-module.d.ts.map

package/dist/cloud-management-module.js

@@ -1,6 +1,6 @@
 import { defineModule, } from "@helyx/sdk";
 import { Events } from "discord.js";
-import { CloudConnectorUserError, } from "./cloud-connector.js";
+import { ClientCloudDiscordDirectory, CloudConnectorUserError, } from "./cloud-connector.js";
 const CONNECT_MODAL_ID = "helyx.cloud.connect";
 const CONNECT_CODE_FIELD_ID = "helyx.cloud.connect.code";
 const DISCONNECT_MODAL_ID = "helyx.cloud.disconnect";
@@ -16,11 +16,17 @@ const SUCCESS = 0x16a34a;
 const DANGER = 0xdc2626;
 const OWNER_REFRESH_INTERVAL_MS = 15 * 60 * 1_000;
 export class DeploymentOwnerAuthorizer {
+    #directory;
     #client;
     #configuredOwnerUserIds;
     #applicationOwnerUserIds = new Set();
-    constructor(client, configuredOwnerUserIds) {
-        this.#client = client;
+    constructor(directory, configuredOwnerUserIds) {
+        if ("snapshot" in directory)
+            this.#directory = directory;
+        else {
+            this.#client = directory;
+            this.#applicationOwnerUserIds = discordOwnerIds(directory.application?.owner);
+        }
         this.#configuredOwnerUserIds = new Set(configuredOwnerUserIds);
     }
     isOwner(userId) {
@@ -28,23 +34,24 @@ export class DeploymentOwnerAuthorizer {
             this.#applicationOwnerUserIds.has(userId));
     }
     async refresh() {
-        const application = this.#client.application;
-        if (!application)
+        if (this.#directory) {
+            const snapshot = await this.#directory.snapshot();
+            this.#applicationOwnerUserIds = new Set(snapshot.ownerUserIds);
             return;
-        this.#replaceApplicationOwners(application.owner);
-        const refreshed = await application.fetch();
-        this.#replaceApplicationOwners(refreshed.owner);
-    }
-    #replaceApplicationOwners(owner) {
-        this.#applicationOwnerUserIds = !owner
-            ? new Set()
-            : "members" in owner
-                ? new Set(owner.members.keys())
-                : new Set([owner.id]);
+        }
+        const application = await this.#client?.application?.fetch();
+        this.#applicationOwnerUserIds = discordOwnerIds(application?.owner);
     }
 }
+function discordOwnerIds(owner) {
+    if (!owner)
+        return new Set();
+    if ("id" in owner)
+        return new Set([owner.id]);
+    return new Set([...owner.members.values()].map((member) => member.id));
+}
 export function createCloudManagementModule(input) {
-    const ownerAuthorizer = new DeploymentOwnerAuthorizer(input.client, input.configuredOwnerUserIds);
+    const ownerAuthorizer = new DeploymentOwnerAuthorizer(input.discord ?? new ClientCloudDiscordDirectory(input.client), input.configuredOwnerUserIds);
     let ownerRefreshInterval;
     let onClientReady;
     const requireOwner = async (context) => {
@@ -455,8 +462,10 @@ export function createCloudManagementModule(input) {
             };
             onClientReady = () => {
                 refreshOwners();
-                ownerRefreshInterval ??= setInterval(refreshOwners, OWNER_REFRESH_INTERVAL_MS);
-                ownerRefreshInterval.unref();
+                if (input.periodicOwnerRefresh !== false) {
+                    ownerRefreshInterval ??= setInterval(refreshOwners, OWNER_REFRESH_INTERVAL_MS);
+                    ownerRefreshInterval.unref();
+                }
             };
             if (input.client.isReady())
                 onClientReady();

package/dist/command-sync.d.ts

@@ -0,0 +1,32 @@
+import type { ModuleDefinition } from "@helyx/sdk";
+export interface CommandHashState {
+    value: unknown;
+    version: bigint;
+}
+export interface CommandHashStore {
+    get(key: string): Promise<CommandHashState | null>;
+    set(key: string, value: unknown, expectedVersion?: bigint | null): Promise<CommandHashState>;
+}
+export interface DiscordCommandRest {
+    put(route: `/${string}`, options: {
+        body: unknown;
+    }): Promise<unknown>;
+}
+export interface CommandSyncResult {
+    global: "updated" | "unchanged";
+    guild: "updated" | "unchanged" | "not_configured";
+    globalCount: number;
+    guildCount: number;
+    globalHash: string;
+    guildHash?: string;
+}
+export declare function synchroniseApplicationCommands(input: {
+    applicationId: string;
+    token: string;
+    modules: readonly ModuleDefinition[];
+    internalGuildId?: string;
+    state: CommandHashStore;
+    rest?: DiscordCommandRest;
+}): Promise<CommandSyncResult>;
+export declare function commandDefinitionsHash(definitions: readonly unknown[]): string;
+//# sourceMappingURL=command-sync.d.ts.map

package/dist/command-sync.js

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { REST, Routes } from "discord.js";
+import { buildApplicationCommandDefinitions } from "./interactions.js";
+export async function synchroniseApplicationCommands(input) {
+    const definitions = buildApplicationCommandDefinitions(input.modules, input.internalGuildId);
+    definitions.global.sort((left, right) => left.name.localeCompare(right.name));
+    definitions.guild.sort((left, right) => left.name.localeCompare(right.name));
+    const rest = input.rest ?? new REST({ version: "10" }).setToken(input.token);
+    const globalKey = `commands:${input.applicationId}:global`;
+    const globalHash = commandDefinitionsHash(definitions.global);
+    const global = await synchroniseCollection({
+        key: globalKey,
+        hash: globalHash,
+        definitions: definitions.global,
+        state: input.state,
+        update: () => rest.put(Routes.applicationCommands(input.applicationId), {
+            body: definitions.global,
+        }),
+    });
+    if (!input.internalGuildId)
+        return {
+            global,
+            guild: "not_configured",
+            globalCount: definitions.global.length,
+            guildCount: 0,
+            globalHash,
+        };
+    const guildKey = `commands:${input.applicationId}:guild:${input.internalGuildId}`;
+    const guildHash = commandDefinitionsHash(definitions.guild);
+    const guild = await synchroniseCollection({
+        key: guildKey,
+        hash: guildHash,
+        definitions: definitions.guild,
+        state: input.state,
+        update: () => rest.put(Routes.applicationGuildCommands(input.applicationId, input.internalGuildId), { body: definitions.guild }),
+    });
+    return {
+        global,
+        guild,
+        globalCount: definitions.global.length,
+        guildCount: definitions.guild.length,
+        globalHash,
+        guildHash,
+    };
+}
+export function commandDefinitionsHash(definitions) {
+    return createHash("sha256").update(JSON.stringify(definitions)).digest("hex");
+}
+async function synchroniseCollection(input) {
+    const current = await input.state.get(input.key);
+    if (isCommandHashState(current?.value, input.hash))
+        return "unchanged";
+    await input.update();
+    await input.state.set(input.key, {
+        hash: input.hash,
+        commandCount: input.definitions.length,
+        synchronisedAt: new Date().toISOString(),
+    }, current?.version ?? null);
+    return "updated";
+}
+function isCommandHashState(value, expectedHash) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "hash" in value &&
+        value.hash === expectedHash);
+}
+//# sourceMappingURL=command-sync.js.map

package/dist/control-server.d.ts

@@ -2,6 +2,7 @@ import { type DatabasePool } from "@helyx/database";
 import { type DashboardActionResult, type MessageResponse, type ModuleDefinition, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type ServiceAccess } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import { type FastifyInstance } from "fastify";
+import { type ShardHealthSnapshot } from "./shard-contracts.js";
 interface DashboardPermissionPolicy {
     preset: "everyone" | "moderators" | "administrators" | "custom";
     allowedRoleIds: string[];
@@ -161,6 +162,10 @@ export interface BotControlHandler {
         cursor?: string;
     }): Promise<PrivacyErasePage>;
 }
+export declare class BotControlTransportError extends Error {
+    readonly status: 400 | 404 | 409 | 502 | 503 | 504;
+    constructor(status: 400 | 404 | 409 | 502 | 503 | 504, message: string);
+}
 export declare class BotControlService implements BotControlHandler {
     #private;
     private readonly database;
@@ -236,6 +241,11 @@ export declare function createBotControlServer(input: {
     logger?: boolean | {
         level: string;
     };
+    shardHealth?: () => Promise<ShardHealthSnapshot>;
 }): Promise<FastifyInstance>;
+export declare function mapBotControlError(error: unknown): {
+    status: 400 | 404 | 409;
+    message: string;
+} | undefined;
 export {};
 //# sourceMappingURL=control-server.d.ts.map

package/dist/control-server.js

@@ -5,6 +5,7 @@ import Fastify, {} from "fastify";
 import { createHash, timingSafeEqual } from "node:crypto";
 import { z, ZodError } from "zod";
 import { deleteChannelMessage as deleteDiscordChannelMessage, sendToChannel as sendDiscordMessageToChannel, } from "./interactions.js";
+import { SHARD_HEALTH_STALE_MS, } from "./shard-contracts.js";
 const snowflake = z.string().regex(/^\d{17,20}$/u);
 const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
 const configurationValue = z.record(z.string(), z.union([
@@ -87,6 +88,14 @@ export class DiscordGuildResourceDirectory {
         return deleteDiscordChannelMessage(this.client, channelId, messageId);
     }
 }
+export class BotControlTransportError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "BotControlTransportError";
+    }
+}
 export class BotControlService {
     database;
     resources;
@@ -504,8 +513,62 @@ export async function createBotControlServer(input) {
         if (!timingSafeEqual(expectedSecret, digest(supplied)))
             return reply.code(401).send({ message: "Control authentication failed" });
     });
-    server.get("/health", () => ({ status: "ok" }));
-    server.get("/v1/health", () => ({ status: "ok" }));
+    async function readiness(reply) {
+        if (!input.shardHealth)
+            return { status: "ok" };
+        try {
+            const health = await input.shardHealth();
+            if (health.status === "healthy")
+                return { status: "ok" };
+        }
+        catch {
+            // The public readiness route deliberately returns no internal detail.
+        }
+        return reply.code(503).send({ status: "unavailable" });
+    }
+    server.get("/health", (_request, reply) => readiness(reply));
+    server.get("/v1/health", (_request, reply) => readiness(reply));
+    server.get("/v1/shards/health", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!input.shardHealth)
+            return reply.code(503).send({
+                message: "Shard health is unavailable while sharding is off",
+            });
+        const { cursor, limit } = z
+            .object({
+            cursor: z.coerce.number().int().min(0).max(4_095).default(0),
+            limit: z.coerce.number().int().min(1).max(100).default(50),
+        })
+            .strict()
+            .parse(request.query);
+        const health = await input.shardHealth();
+        const now = Date.now();
+        const shards = health.shards.slice(cursor, cursor + limit);
+        const nextCursor = cursor + shards.length < health.shards.length
+            ? String(cursor + shards.length)
+            : null;
+        return {
+            mode: health.mode,
+            configuredShardCount: health.configuredShardCount,
+            readyShardCount: health.readyShardCount,
+            observedAt: health.observedAt,
+            nextCursor,
+            shards: shards.map((shard) => ({
+                id: shard.shardId,
+                status: now - new Date(shard.observedAt).getTime() > SHARD_HEALTH_STALE_MS
+                    ? "stale"
+                    : shard.status === "ready"
+                        ? "healthy"
+                        : shard.status === "starting" || shard.status === "reconnecting"
+                            ? "starting"
+                            : "degraded",
+                guildCount: shard.guildCount,
+                gatewayPingMs: shard.gatewayPingMs < 0 ? null : Math.round(shard.gatewayPingMs),
+                uptimeSeconds: Math.floor(shard.uptimeSeconds),
+                restartCount: shard.restartCount,
+            })),
+        };
+    });
     server.get("/v1/privacy/providers", () => input.service.listPrivacyProviders());
     server.post("/v1/privacy/capture", async (request) => {
         const body = z
@@ -605,22 +668,11 @@ export async function createBotControlServer(input) {
         return input.service.updateLoggingPolicy({ ...params, ...body });
     });
     server.setErrorHandler(async (error, request, reply) => {
-        if (error instanceof ZodError)
-            return reply
-                .code(400)
-                .send({ message: "The control request was invalid" });
-        if (error instanceof BotControlValidationError)
-            return reply.code(400).send({ message: error.message });
-        if (error instanceof DashboardActionValidationError)
-            return reply.code(400).send({ message: error.message });
-        if (error instanceof ModuleStateValidationError)
-            return reply.code(400).send({ message: error.message });
-        if (error instanceof BotControlNotFoundError)
-            return reply.code(404).send({ message: error.message });
-        if (error instanceof OptimisticConcurrencyError)
-            return reply.code(409).send({
-                message: "Configuration changed in another session. Reload and try again.",
-            });
+        const mapped = mapBotControlError(error);
+        if (mapped)
+            return reply.code(mapped.status).send({ message: mapped.message });
+        if (error instanceof BotControlTransportError)
+            return reply.code(error.status).send({ message: error.message });
         const safeError = error instanceof Error
             ? { name: error.name, message: error.message }
             : { name: "Error", message: "Unknown control failure" };
@@ -629,6 +681,22 @@ export async function createBotControlServer(input) {
     });
     return server;
 }
+export function mapBotControlError(error) {
+    if (error instanceof ZodError)
+        return { status: 400, message: "The control request was invalid" };
+    if (error instanceof BotControlValidationError ||
+        error instanceof DashboardActionValidationError ||
+        error instanceof ModuleStateValidationError)
+        return { status: 400, message: error.message };
+    if (error instanceof BotControlNotFoundError)
+        return { status: 404, message: error.message };
+    if (error instanceof OptimisticConcurrencyError)
+        return {
+            status: 409,
+            message: "Configuration changed in another session. Reload and try again.",
+        };
+    return undefined;
+}
 class BotControlValidationError extends Error {
 }
 class BotControlNotFoundError extends Error {

package/dist/developer-operations-module.d.ts

@@ -0,0 +1,28 @@
+import { type ModuleDefinition } from "@helyx/sdk";
+import { type ShardHealthSnapshot } from "./shard-contracts.js";
+export interface ShardHealthProvider {
+    getHealth(): Promise<ShardHealthSnapshot>;
+}
+export interface DeveloperModuleSummary {
+    id: string;
+    name: string;
+    version: string;
+}
+export interface DeveloperOperationsInput {
+    internalGuildId: string;
+    approvedRoleIds: readonly string[];
+    botVersion: string;
+    deploymentReference?: string;
+    coreFunctions: readonly DeveloperModuleSummary[];
+    modules: readonly DeveloperModuleSummary[];
+    processLabel: string;
+    health: ShardHealthProvider;
+}
+export declare function createDeveloperOperationsModule(input: DeveloperOperationsInput): ModuleDefinition;
+export declare class WorkerShardHealthProvider implements ShardHealthProvider {
+    #private;
+    getHealth(): Promise<ShardHealthSnapshot>;
+    accept(raw: unknown): void;
+    stop(): void;
+}
+//# sourceMappingURL=developer-operations-module.d.ts.map