@helyx/bot 0.3.1 → 0.4.1

package/dist/developer-operations-module.js

@@ -0,0 +1,249 @@
+import { defineModule, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { SHARD_CONTROL_TIMEOUT_MS, assertShardMessageSize, shardOperationsHealthResponseSchema, } from "./shard-contracts.js";
+const DEVELOPER_MODULE_ID = "helyx.developer-operations";
+const DEVELOPER_MODULE_NAME = "Helyx Developer Operations";
+const DEVELOPER_MODULE_VERSION = "0.2.0";
+const MAX_MODULE_LINES = 8;
+export function createDeveloperOperationsModule(input) {
+    const approvedRoles = new Set(input.approvedRoleIds);
+    return defineModule({
+        manifest: {
+            manifestVersion: "0.1",
+            releaseStatus: "live",
+            id: DEVELOPER_MODULE_ID,
+            name: DEVELOPER_MODULE_NAME,
+            version: DEVELOPER_MODULE_VERSION,
+            description: "Private read-only development operations for Helyx support.",
+            entry: "./dist/developer-operations-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["dev"], events: [] },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "dev",
+                    description: "Inspect private Helyx development operations",
+                    registration: "guild",
+                    contexts: ["guild"],
+                    integrationTypes: ["guild_install"],
+                    subcommands: [
+                        {
+                            name: "shards",
+                            description: "Show bounded read-only shard health",
+                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await authorizeDeveloperCommand(context)))
+                                    return;
+                                const health = await input.health.getHealth();
+                                const shardLines = health.shards.slice(0, 25).map((shard) => {
+                                    const ping = shard.gatewayPingMs < 0
+                                        ? "n/a"
+                                        : `${Math.round(shard.gatewayPingMs)}ms`;
+                                    return `\`${shard.shardId}\` ${shard.status} · ${shard.guildCount} guilds · ${ping} · restarts ${shard.restartCount}`;
+                                });
+                                await context.reply({
+                                    ephemeral: true,
+                                    componentsV2: {
+                                        accentColor: health.status === "healthy" ? 0x16a34a : 0xdc2626,
+                                        text: [
+                                            {
+                                                content: [
+                                                    "## Shard health",
+                                                    `**${health.status}** · ${health.readyShardCount}/${health.configuredShardCount} ready`,
+                                                    `Mode: ${health.mode}/${health.scope}`,
+                                                    `Generation: \`${health.generation}\``,
+                                                    `Observed: ${health.observedAt}`,
+                                                    "",
+                                                    ...shardLines,
+                                                    ...(health.shards.length < health.configuredShardCount
+                                                        ? [
+                                                            `… showing ${health.shards.length} of ${health.configuredShardCount} shards`,
+                                                        ]
+                                                        : []),
+                                                ].join("\n"),
+                                            },
+                                        ],
+                                    },
+                                });
+                            },
+                        },
+                        {
+                            name: "bot",
+                            description: "Show the bot build and installed module versions",
+                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await authorizeDeveloperCommand(context)))
+                                    return;
+                                const coreFunctions = [
+                                    {
+                                        id: DEVELOPER_MODULE_ID,
+                                        name: DEVELOPER_MODULE_NAME,
+                                        version: DEVELOPER_MODULE_VERSION,
+                                    },
+                                    ...input.coreFunctions,
+                                ].sort((left, right) => left.id.localeCompare(right.id));
+                                const modules = [...input.modules].sort((left, right) => left.id.localeCompare(right.id));
+                                const visibleCoreFunctions = coreFunctions.slice(0, MAX_MODULE_LINES);
+                                const visibleModules = modules.slice(0, Math.max(0, MAX_MODULE_LINES - visibleCoreFunctions.length));
+                                const coreFunctionLines = visibleCoreFunctions.map((coreFunction) => `- ${safeInlineCode(coreFunction.name)} · ${safeInlineCode(coreFunction.id)} · ${safeInlineCode(coreFunction.version)}`);
+                                const moduleLines = visibleModules.map((module) => `- ${safeInlineCode(module.name)} · ${safeInlineCode(module.id)} · ${safeInlineCode(module.version)}`);
+                                const componentCount = coreFunctions.length + modules.length;
+                                const visibleComponentCount = visibleCoreFunctions.length + visibleModules.length;
+                                await context.reply({
+                                    ephemeral: true,
+                                    componentsV2: {
+                                        accentColor: 0x2563eb,
+                                        text: [
+                                            {
+                                                content: [
+                                                    "## Bot information",
+                                                    `Version: ${safeInlineCode(input.botVersion)}`,
+                                                    `Build: ${safeInlineCode(input.deploymentReference ?? "not supplied")}`,
+                                                    `Runtime: ${input.processLabel}`,
+                                                    `Core functions: ${coreFunctions.length}`,
+                                                    `Installed modules: ${modules.length}`,
+                                                    "",
+                                                    "### Core functions",
+                                                    ...coreFunctionLines,
+                                                    "",
+                                                    "### Modules",
+                                                    ...moduleLines,
+                                                    ...(componentCount > visibleComponentCount
+                                                        ? [
+                                                            `… showing ${visibleComponentCount} of ${componentCount} components`,
+                                                        ]
+                                                        : []),
+                                                ].join("\n"),
+                                            },
+                                        ],
+                                    },
+                                });
+                            },
+                        },
+                        {
+                            name: "proc",
+                            description: "Show safe process resource and uptime information",
+                            rateLimit: { scope: "user", limit: 10, windowSeconds: 60 },
+                            async execute(context) {
+                                if (!(await authorizeDeveloperCommand(context)))
+                                    return;
+                                const memory = process.memoryUsage();
+                                const cpu = process.cpuUsage();
+                                await context.reply({
+                                    ephemeral: true,
+                                    componentsV2: {
+                                        accentColor: 0x2563eb,
+                                        text: [
+                                            {
+                                                content: [
+                                                    "## Process information",
+                                                    `Runtime: ${input.processLabel}`,
+                                                    `Uptime: ${formatDuration(process.uptime())}`,
+                                                    `RSS memory: ${formatBytes(memory.rss)}`,
+                                                    `Heap: ${formatBytes(memory.heapUsed)} used / ${formatBytes(memory.heapTotal)} allocated`,
+                                                    `External memory: ${formatBytes(memory.external)}`,
+                                                    `CPU time: ${formatCpu(cpu.user)} user / ${formatCpu(cpu.system)} system`,
+                                                    `Node: ${safeInlineCode(process.version)}`,
+                                                    `Platform: ${safeInlineCode(`${process.platform}/${process.arch}`)}`,
+                                                    `PID: ${process.pid}`,
+                                                ].join("\n"),
+                                            },
+                                        ],
+                                    },
+                                });
+                            },
+                        },
+                    ],
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    });
+    async function authorizeDeveloperCommand(context) {
+        const approved = context.serverId === input.internalGuildId &&
+            (context.isAdministrator ||
+                context.userRoleIds.some((roleId) => approvedRoles.has(roleId)));
+        if (approved)
+            return true;
+        await context.reply({
+            ephemeral: true,
+            componentsV2: {
+                accentColor: 0xdc2626,
+                text: [
+                    {
+                        content: "This private development command is unavailable.",
+                    },
+                ],
+            },
+        });
+        return false;
+    }
+}
+function safeInlineCode(value) {
+    return `\`${value.replaceAll("`", "'").slice(0, 120)}\``;
+}
+function formatBytes(value) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
+}
+function formatCpu(microseconds) {
+    return `${(microseconds / 1_000_000).toFixed(2)}s`;
+}
+function formatDuration(seconds) {
+    const total = Math.max(0, Math.floor(seconds));
+    const days = Math.floor(total / 86_400);
+    const hours = Math.floor((total % 86_400) / 3_600);
+    const minutes = Math.floor((total % 3_600) / 60);
+    const remainder = total % 60;
+    return [
+        ...(days > 0 ? [`${days}d`] : []),
+        ...(days > 0 || hours > 0 ? [`${hours}h`] : []),
+        `${minutes}m`,
+        `${remainder}s`,
+    ].join(" ");
+}
+export class WorkerShardHealthProvider {
+    #pending = new Map();
+    getHealth() {
+        if (!process.send)
+            return Promise.reject(new Error("Shard supervisor IPC is unavailable"));
+        const requestId = randomUUID();
+        const message = {
+            version: 1,
+            type: "helyx.operations.health.request",
+            requestId,
+            deadlineAt: new Date(Date.now() + SHARD_CONTROL_TIMEOUT_MS).toISOString(),
+        };
+        assertShardMessageSize(message);
+        const response = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(requestId);
+                reject(new Error("Shard health request timed out"));
+            }, SHARD_CONTROL_TIMEOUT_MS);
+            timer.unref();
+            this.#pending.set(requestId, { resolve, reject, timer });
+        });
+        process.send(message);
+        return response;
+    }
+    accept(raw) {
+        const response = shardOperationsHealthResponseSchema.parse(raw);
+        const pending = this.#pending.get(response.requestId);
+        if (!pending)
+            return;
+        this.#pending.delete(response.requestId);
+        clearTimeout(pending.timer);
+        pending.resolve(response.health);
+    }
+    stop() {
+        for (const pending of this.#pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error("Shard worker is stopping"));
+        }
+        this.#pending.clear();
+    }
+}
+//# sourceMappingURL=developer-operations-module.js.map

package/dist/events.d.ts

@@ -1,7 +1,11 @@
 import type { ModuleDefinition, ServiceAccess } from "@helyx/sdk";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
-export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): void;
+export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): ModuleEventHandle;
+export interface ModuleEventHandle {
+    stop(): Promise<void>;
+    queueDepth(): number;
+}
 export declare function reactionEmojiKey(reaction: MessageReaction | PartialMessageReaction): string;
 export declare function reactionCacheKey(emojiIdentifier: string): string;
 //# sourceMappingURL=events.d.ts.map

package/dist/events.js

@@ -11,15 +11,18 @@ export function installModuleEvents(client, modules, logger, services) {
         contribution,
     })));
     if (reactionContributions.length === 0 && memberAddContributions.length === 0)
-        return;
+        return { stop: () => Promise.resolve(), queueDepth: () => 0 };
+    const queue = new BoundedGuildEventQueue(logger);
     if (reactionContributions.length > 0) {
         client.on(Events.MessageReactionAdd, (reaction, user) => {
-            void handleReaction(reaction, user);
+            const guildId = reaction.message.guildId;
+            if (guildId)
+                queue.enqueue(guildId, () => handleReaction(reaction, user));
         });
     }
     if (memberAddContributions.length > 0) {
         client.on(Events.GuildMemberAdd, (member) => {
-            void handleMemberAdd(member);
+            queue.enqueue(member.guild.id, () => handleMemberAdd(member));
         });
     }
     async function handleReaction(receivedReaction, receivedUser) {
@@ -109,6 +112,69 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    return { stop: () => queue.stop(), queueDepth: () => queue.queueDepth() };
+}
+class BoundedGuildEventQueue {
+    logger;
+    #pending = [];
+    #activeGuilds = new Set();
+    #drainWaiters = new Set();
+    #active = 0;
+    #accepting = true;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    enqueue(guildId, run) {
+        if (!this.#accepting || this.#pending.length >= 1_000) {
+            this.logger.warn({ event: "module.event_dropped", reason: "queue_capacity" }, "Module gateway event queue rejected work");
+            return;
+        }
+        this.#pending.push({ guildId, run });
+        this.#pump();
+    }
+    queueDepth() {
+        return this.#pending.length;
+    }
+    async stop() {
+        this.#accepting = false;
+        if (this.#active === 0 && this.#pending.length === 0)
+            return;
+        await Promise.race([
+            new Promise((resolve) => this.#drainWaiters.add(resolve)),
+            new Promise((resolve) => {
+                const timer = setTimeout(resolve, 5_000);
+                timer.unref();
+            }),
+        ]);
+        this.#pending.length = 0;
+    }
+    #pump() {
+        while (this.#active < 16) {
+            const index = this.#pending.findIndex(({ guildId }) => !this.#activeGuilds.has(guildId));
+            if (index < 0)
+                break;
+            const [task] = this.#pending.splice(index, 1);
+            if (!task)
+                break;
+            this.#active += 1;
+            this.#activeGuilds.add(task.guildId);
+            void task
+                .run()
+                .catch((error) => {
+                this.logger.warn({ event: "module.event_failed", error: safeError(error) }, "Queued module gateway event failed");
+            })
+                .finally(() => {
+                this.#active -= 1;
+                this.#activeGuilds.delete(task.guildId);
+                this.#pump();
+                if (this.#active === 0 && this.#pending.length === 0) {
+                    for (const resolve of this.#drainWaiters)
+                        resolve();
+                    this.#drainWaiters.clear();
+                }
+            });
+        }
+    }
 }
 async function assignMemberRole(member, roleId) {
     const role = await member.guild.roles.fetch(roleId);

package/dist/guilds.d.ts

@@ -1,6 +1,6 @@
-import { type DatabasePool } from "@helyx/database";
+import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
 import type { ModuleDefinition } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import type { InteractionLogger } from "./interactions.js";
-export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>): (readyClient: Client<true>) => Promise<void>;
+export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership): (readyClient: Client<true>) => Promise<void>;
 //# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -1,13 +1,21 @@
-import { InstallationRepository } from "@helyx/database";
+import { InstallationRepository, } from "@helyx/database";
 import { Events } from "discord.js";
-export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set()) {
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership) {
     const repository = new InstallationRepository(database);
     async function syncGuild(guild) {
-        await repository.syncGuild({
+        const record = await repository.syncGuild({
             guildId: guild.id,
             ownerUserId: guild.ownerId,
             name: guild.name,
+            ...(ownership ? { ownership } : {}),
         });
+        if (ownership &&
+            (record.shardGeneration !== ownership.generation ||
+                record.shardDeploymentOrder !== (ownership.deploymentOrder ?? 1n) ||
+                record.shardSupervisorId !== ownership.supervisorId ||
+                record.shardId !== ownership.shardId ||
+                record.shardFencingToken !== ownership.fencingToken))
+            throw new Error("Guild observation was rejected by a newer shard owner");
         for (const module of modules) {
             await repository.ensureModule({
                 guildId: guild.id,
@@ -29,7 +37,9 @@ export function installGuildTracking(client, database, modules, logger, enabledB
         });
     });
     client.on(Events.GuildDelete, (guild) => {
-        void repository.markGuildRemoved(guild.id).catch((error) => {
+        void repository
+            .markGuildRemoved(guild.id, ownership)
+            .catch((error) => {
             logger.error({
                 event: "guild.remove_failed",
                 guildId: guild.id,
@@ -37,6 +47,9 @@ export function installGuildTracking(client, database, modules, logger, enabledB
             }, "Guild removal tracking failed");
         });
     });
+    client.on(Events.GuildUnavailable, (guild) => {
+        logger.warn({ event: "guild.unavailable", guildId: guild.id }, "Discord guild is temporarily unavailable; installation remains active");
+    });
     return async (readyClient) => {
         for (const guild of readyClient.guilds.cache.values())
             await syncGuild(guild);

package/dist/index.d.ts

@@ -7,5 +7,7 @@ export interface BotHandle {
     shutdown(reason?: string): Promise<void>;
 }
 export declare function startBot(processEnvironment?: NodeJS.ProcessEnv): Promise<BotHandle>;
+export declare function resolveBotWorkerEntryPoint(entryUrl?: string): string;
+export declare function readBotVersion(): string;
 export declare function gatewayIntentsForModules(modules: readonly ModuleDefinition[]): GatewayIntentBits[];
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,10 +6,11 @@ import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
+import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { CloudConnectorController } from "./cloud-connector.js";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { ClientCloudDiscordDirectory, CloudConnectorController, } from "./cloud-connector.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { installInteractions } from "./interactions.js";
 import { installGuildTracking } from "./guilds.js";
@@ -20,14 +21,29 @@ import { createManagementModule } from "./management-module.js";
 import { installModuleEvents } from "./events.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
 import { BotControlService, createBotControlServer, DiscordGuildResourceDirectory, } from "./control-server.js";
+import { startShardSupervisor } from "./shard-supervisor.js";
+import { parseShardWorkerLaunchContract, startShardWorker, } from "./shard-worker.js";
+import { createDeveloperOperationsModule } from "./developer-operations-module.js";
+import { shardHealthSnapshotSchema } from "./shard-contracts.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
 const bootstrapLogger = pino({ base: { component: "bot" } });
 const RETENTION_CLEANUP_INTERVAL_MS = 60 * 60 * 1_000;
 export async function startBot(processEnvironment = process.env) {
+    if (processEnvironment.HELYX_SHARD_WORKER_CONTRACT !== undefined)
+        return startShardWorker(processEnvironment, parseShardWorkerLaunchContract(processEnvironment.HELYX_SHARD_WORKER_CONTRACT));
     const environment = parseBotEnvironment(processEnvironment);
     bootstrapLogger.level = environment.LOG_LEVEL;
+    if (environment.HELYX_SHARD_MODE !== "off")
+        return startShardSupervisor(environment, processEnvironment, resolveBotWorkerEntryPoint());
+    return startUnshardedBot(processEnvironment);
+}
+export function resolveBotWorkerEntryPoint(entryUrl = import.meta.url) {
+    return fileURLToPath(entryUrl);
+}
+async function startUnshardedBot(processEnvironment) {
+    const environment = parseBotEnvironment(processEnvironment);
     const database = createDatabasePool({
         connectionString: environment.DATABASE_URL,
         sslMode: environment.DATABASE_SSL,
@@ -113,7 +129,7 @@ export async function startBot(processEnvironment = process.env) {
         const cloudConnector = new CloudConnectorController({
             environment,
             database,
-            client,
+            discord: new ClientCloudDiscordDirectory(client),
             modules: modulePackages,
             coreVersion: readBotVersion(),
             logger: bootstrapLogger,
@@ -127,15 +143,85 @@ export async function startBot(processEnvironment = process.env) {
                 configuredOwnerUserIds: environment.HELYX_OWNER_USER_IDS,
             })
             : undefined;
-        const modules = [
+        const publicModules = [
             managementModule,
             permissionsModule,
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
         ];
-        const platformServices = new Map(createPlatformServices(database, modules));
+        const unshardedSupervisorId = randomUUID();
+        const deployedCommit = deploymentReference(processEnvironment);
+        const operationsModule = environment.DISCORD_INTERNAL_GUILD_ID
+            ? createDeveloperOperationsModule({
+                internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
+                approvedRoleIds: environment.APPROVED_ROLES,
+                botVersion: readBotVersion(),
+                ...(deployedCommit ? { deploymentReference: deployedCommit } : {}),
+                coreFunctions: [
+                    managementModule,
+                    permissionsModule,
+                    ...(cloudManagementModule ? [cloudManagementModule] : []),
+                ].map(({ manifest }) => manifest),
+                modules: featureModules.map(({ manifest }) => manifest),
+                processLabel: "unsharded bot process",
+                health: {
+                    getHealth: async () => {
+                        let databaseHealthy = true;
+                        try {
+                            await checkDatabaseConnection(database);
+                        }
+                        catch {
+                            databaseHealthy = false;
+                        }
+                        const ready = client.isReady();
+                        const observedAt = new Date().toISOString();
+                        const gatewayPingMs = Number.isFinite(client.ws.ping)
+                            ? client.ws.ping
+                            : -1;
+                        return shardHealthSnapshotSchema.parse({
+                            version: 1,
+                            mode: "off",
+                            scope: "local",
+                            status: ready && databaseHealthy
+                                ? "healthy"
+                                : ready
+                                    ? "degraded"
+                                    : "starting",
+                            observedAt,
+                            generation: "unsharded",
+                            supervisorId: unshardedSupervisorId,
+                            configuredShardCount: 1,
+                            readyShardCount: ready ? 1 : 0,
+                            coordination: {
+                                redis: "not_required",
+                                database: databaseHealthy ? "healthy" : "unavailable",
+                            },
+                            shards: [
+                                {
+                                    shardId: 0,
+                                    status: ready ? "ready" : "starting",
+                                    guildCount: client.guilds.cache.size,
+                                    gatewayPingMs,
+                                    uptimeSeconds: process.uptime(),
+                                    restartCount: 0,
+                                    eventLoopDelayMs: 0,
+                                    memoryRssBytes: process.memoryUsage().rss,
+                                    queueDepth: 0,
+                                    observedAt,
+                                },
+                            ],
+                        });
+                    },
+                },
+            })
+            : undefined;
+        const modules = [
+            ...publicModules,
+            ...(operationsModule ? [operationsModule] : []),
+        ];
+        const platformServices = new Map(createPlatformServices(database, publicModules));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging")) {
-            platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, modules, bootstrapLogger));
+            platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, publicModules, bootstrapLogger));
         }
         const serviceAccess = new ServiceRegistry(platformServices);
         const runtime = createRuntime({
@@ -147,16 +233,24 @@ export async function startBot(processEnvironment = process.env) {
             managementModule.manifest.id,
             permissionsModule.manifest.id,
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
+            ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
-        const prepareGuilds = installGuildTracking(client, database, modules, bootstrapLogger, enabledCoreModuleIds);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds);
         const commandsReady = installInteractions(client, modules, {
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
                 : {}),
             prepare: prepareGuilds,
+            ...(operationsModule
+                ? {
+                    selfAuthorizingGuildModuleIds: new Set([
+                        operationsModule.manifest.id,
+                    ]),
+                }
+                : {}),
         }, bootstrapLogger, serviceAccess);
-        installModuleEvents(client, modules, bootstrapLogger, serviceAccess);
-        const controlService = new BotControlService(database, modules, guildResources, serviceAccess, privacyDatabase
+        const moduleEvents = installModuleEvents(client, publicModules, bootstrapLogger, serviceAccess);
+        const controlService = new BotControlService(database, publicModules, guildResources, serviceAccess, privacyDatabase
             ? new PostgresPrivacyProviderExecutor({
                 readPool: database,
                 executorPool: privacyDatabase,
@@ -185,6 +279,7 @@ export async function startBot(processEnvironment = process.env) {
                     bootstrapLogger.error({ event: "control.stop_failed", error: safeError(error) }, "Private bot control shutdown failed");
                 });
             try {
+                await moduleEvents.stop();
                 await runtime.stop();
             }
             catch (error) {
@@ -230,6 +325,7 @@ export async function startBot(processEnvironment = process.env) {
             if (controlServer)
                 await controlServer.close().catch(() => undefined);
             try {
+                await moduleEvents.stop();
                 await runtime.stop();
             }
             catch (stopError) {
@@ -258,7 +354,7 @@ async function assertDistinctDatabaseRoles(runtime, privacy) {
         privacyIdentity.rows[0]?.current_user)
         throw new Error("Privacy executor must use a distinct least-privilege database role");
 }
-function readBotVersion() {
+export function readBotVersion() {
     const metadata = createRequire(import.meta.url)("../package.json");
     if (typeof metadata !== "object" ||
         metadata === null ||
@@ -266,6 +362,11 @@ function readBotVersion() {
         throw new Error("Bot package version is unavailable");
     return metadata.version;
 }
+function deploymentReference(processEnvironment) {
+    const value = processEnvironment.RAILWAY_GIT_COMMIT_SHA ??
+        processEnvironment.GIT_COMMIT_SHA;
+    return value?.trim().slice(0, 12) || undefined;
+}
 export function gatewayIntentsForModules(modules) {
     const intents = [GatewayIntentBits.Guilds];
     if (modules.some((module) => module.events?.messageReactionAdd?.length)) {

package/dist/interactions.d.ts

@@ -1,5 +1,5 @@
 import type { CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
-import { ModalBuilder, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+import { ModalBuilder, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
 export interface InteractionLogger {
     info(fields: Record<string, unknown>, message: string): void;
     warn(fields: Record<string, unknown>, message: string): void;
@@ -8,8 +8,14 @@ export interface InteractionLogger {
 export interface CommandRegistration {
     internalGuildId?: string;
     prepare?(client: Client<true>): Promise<void>;
+    synchronise?: boolean;
+    selfAuthorizingGuildModuleIds?: ReadonlySet<string>;
 }
 export declare function installInteractions(client: Client, modules: readonly ModuleDefinition[], registration: CommandRegistration, logger: InteractionLogger, services: ServiceAccess): Promise<void>;
+export declare function buildApplicationCommandDefinitions(modules: readonly ModuleDefinition[], internalGuildId?: string): {
+    global: ReturnType<typeof toCommandDefinition>[];
+    guild: ReturnType<typeof toCommandDefinition>[];
+};
 export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null): CommandContribution["execute"];
 export declare function toCommandDefinition(registered: {
     contribution: CommandContribution;
@@ -20,6 +26,7 @@ export declare function sendToChannel(client: Client, channelId: string, respons
 }>;
 export declare function deleteChannelMessage(client: Client, channelId: string, messageId: string): Promise<void>;
 export declare function editChannelMessage(client: Client, channelId: string, messageId: string, response: MessageResponse): Promise<void>;
+export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean): Promise<boolean>;
 export declare function normalizeDiscordPermission(permission: string): string;
 export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
 export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;