@helyx/bot 1.4.0 → 1.5.1

package/dist/discord-channel-audit.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "discord.js";
+import type { ChannelAuditInput, ChannelAuditModuleId, ChannelAuditReport } from "@helyx/sdk";
+/** Fresh guild roles/channels and the bot member only. Never reads messages or enumerates members. */
+export declare function inspectDiscordChannelAudit(client: Client, input: {
+    guildId: string;
+    moduleId: ChannelAuditModuleId;
+    assumptions: ChannelAuditInput;
+}): Promise<ChannelAuditReport>;
+//# sourceMappingURL=discord-channel-audit.d.ts.map

package/dist/discord-channel-audit.js

@@ -0,0 +1,195 @@
+import { PermissionFlagsBits } from "discord.js";
+import { channelAuditInputSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
+import { buildChannelAuditReport, } from "./channel-audit-permissions.js";
+import { dangerousRolePermissions } from "./discord-role-safety.js";
+async function readBefore(read, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("Channel audit read deadline reached");
+    let timer;
+    try {
+        return await Promise.race([
+            read(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Channel audit read deadline reached")), remaining);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Fresh guild roles/channels and the bot member only. Never reads messages or enumerates members. */
+export async function inspectDiscordChannelAudit(client, input) {
+    const assumptions = channelAuditInputSchema.parse(input.assumptions);
+    const deadline = Date.now() + 8_500;
+    const snapshot = {
+        guildId: input.guildId,
+        roles: [],
+        rolesComplete: false,
+        channels: [],
+        fetchedChannels: 0,
+        totalChannelsKnown: false,
+        fetchLimitations: [],
+    };
+    const guild = await readBefore(() => client.guilds.fetch(input.guildId), deadline).catch(() => null);
+    if (!guild) {
+        snapshot.fetchLimitations.push("The current Discord server could not be fetched; channel and role coverage is incomplete.");
+        return channelAuditReportSchema.parse(buildChannelAuditReport(snapshot, input.moduleId, assumptions, new Date().toISOString()));
+    }
+    if (guild.id !== input.guildId)
+        throw new Error("Discord returned a different server for this inspection");
+    const [rolesResult, channelsResult, memberResult] = await Promise.allSettled([
+        readBefore(() => guild.roles.fetch(), deadline),
+        readBefore(() => guild.channels.fetch(), deadline),
+        readBefore(() => guild.members.fetchMe({ force: true }), deadline),
+    ]);
+    const me = memberResult.status === "fulfilled" ? memberResult.value : null;
+    if (me && me.guild.id !== guild.id)
+        throw new Error("Discord bot member belongs to a different server");
+    if (!me)
+        snapshot.fetchLimitations.push("Helyx's current server member could not be fetched; bot publishing and assignment checks may be unknown.");
+    if (rolesResult.status === "fulfilled") {
+        snapshot.rolesComplete = true;
+        const canManage = me?.permissions.has(PermissionFlagsBits.ManageRoles) ?? false;
+        snapshot.roles = [...rolesResult.value.values()].map((role) => {
+            if (role.guild.id !== guild.id)
+                throw new Error("Discord role belongs to a different server");
+            const reason = role.id === guild.id
+                ? "The everyone role cannot be assigned."
+                : role.managed
+                    ? "This role is managed by Discord or an integration and cannot be assigned by Helyx."
+                    : !me
+                        ? undefined
+                        : !canManage
+                            ? "Helyx lacks Manage Roles in this server."
+                            : role.comparePositionTo(me.roles.highest) >= 0
+                                ? "The selected role is at or above Helyx's highest role."
+                                : undefined;
+            const dangerous = dangerousRolePermissions(role.permissions.bitfield);
+            return {
+                id: role.id,
+                permissions: role.permissions.bitfield,
+                managed: role.managed,
+                assignable: reason ? false : me ? true : null,
+                ...(reason ? { assignmentReason: reason } : {}),
+                ...(dangerous.length
+                    ? {
+                        assignmentPolicyReason: `Helyx's role-safety policy blocks managing roles with ${dangerous.join(", ")}. Discord hierarchy alone does not make this role eligible.`,
+                    }
+                    : {}),
+            };
+        });
+    }
+    else
+        snapshot.fetchLimitations.push("The current Discord role list could not be fetched; missing roles are unknown, not confirmed deleted.");
+    const observedIds = new Set();
+    if (channelsResult.status === "fulfilled") {
+        snapshot.fetchedChannels = channelsResult.value.size;
+        for (const channel of channelsResult.value.values()) {
+            if (!channel)
+                continue;
+            if (channel.guild.id !== guild.id)
+                throw new Error("Discord channel belongs to a different server");
+            observedIds.add(channel.id);
+            const flags = "flags" in channel ? BigInt(channel.flags.bitfield) : 0n;
+            const obfuscated = (flags & 131072n) !== 0n || channel.name === "___hidden___";
+            const overwrites = "permissionOverwrites" in channel
+                ? [...channel.permissionOverwrites.cache.values()].map((overwrite) => ({
+                    id: overwrite.id,
+                    type: overwrite.type,
+                    allow: overwrite.allow.bitfield,
+                    deny: overwrite.deny.bitfield,
+                }))
+                : [];
+            const botPermissions = !obfuscated && me
+                ? (channel.permissionsFor(me)?.bitfield ?? null)
+                : null;
+            snapshot.channels.push({
+                id: channel.id,
+                name: obfuscated ? "Unknown channel" : channel.name,
+                type: channel.type,
+                obfuscated,
+                overwrites: obfuscated ? [] : overwrites,
+                botPermissions,
+            });
+        }
+        snapshot.totalChannelsKnown =
+            me?.permissions.has(PermissionFlagsBits.Administrator) ?? false;
+    }
+    else
+        snapshot.fetchLimitations.push("Discord's channel list could not be fetched; cached metadata is not used as fresh permission evidence.");
+    // Bulk lists can omit invisible channels. Resolve only explicitly selected
+    // missing IDs; a permission failure or deadline remains unknown.
+    const selected = new Set([
+        assumptions.entryChannelId,
+        ...assumptions.allowedChannelIds,
+        ...(assumptions.reviewChannelId ? [assumptions.reviewChannelId] : []),
+    ]);
+    snapshot.invalidSelectedChannels = [];
+    for (const id of selected) {
+        if (observedIds.has(id))
+            continue;
+        try {
+            const channel = await readBefore(() => guild.channels.fetch(id, { force: true, cache: false }), deadline);
+            if (!channel)
+                continue;
+            if (channel.guild.id !== guild.id) {
+                snapshot.invalidSelectedChannels.push({ id, reason: "wrong_guild" });
+                continue;
+            }
+            observedIds.add(id);
+            const obfuscated = (BigInt("flags" in channel ? channel.flags.bitfield : 0) & 131072n) !==
+                0n || channel.name === "___hidden___";
+            snapshot.channels.push({
+                id,
+                name: obfuscated ? "Unknown channel" : channel.name,
+                type: channel.type,
+                obfuscated,
+                overwrites: !obfuscated && "permissionOverwrites" in channel
+                    ? [...channel.permissionOverwrites.cache.values()].map((overwrite) => ({
+                        id: overwrite.id,
+                        type: overwrite.type,
+                        allow: overwrite.allow.bitfield,
+                        deny: overwrite.deny.bitfield,
+                    }))
+                    : [],
+                botPermissions: !obfuscated && me
+                    ? (channel.permissionsFor(me)?.bitfield ?? null)
+                    : null,
+            });
+            snapshot.fetchedChannels += 1;
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            if (code === 10003 || code === "GuildChannelUnowned")
+                snapshot.invalidSelectedChannels.push({
+                    id,
+                    reason: code === 10003 ? "not_found" : "wrong_guild",
+                });
+        }
+    }
+    // Cache-only entries establish known inventory, never current permissions or deletion.
+    for (const channel of guild.channels.cache.values()) {
+        if (observedIds.has(channel.id))
+            continue;
+        snapshot.channels.push(unknownChannel(channel));
+        snapshot.totalChannelsKnown = false;
+    }
+    return channelAuditReportSchema.parse(buildChannelAuditReport(snapshot, input.moduleId, assumptions, new Date().toISOString()));
+}
+function unknownChannel(channel) {
+    return {
+        id: channel.id,
+        name: "Unknown channel",
+        type: channel.type,
+        obfuscated: true,
+        overwrites: [],
+        botPermissions: null,
+    };
+}
+//# sourceMappingURL=discord-channel-audit.js.map

package/dist/discord-guild-health.d.ts

@@ -163,8 +163,8 @@ export declare class DiscordGuildHealthInspection implements DiscordGuildHealthI
             resourceValidationValid: boolean | null;
             activationValid: boolean | null;
             catalogueMatches: boolean;
-            requiredCapabilities: readonly ("guild-members" | "message-content")[];
-            missingCapabilities: ("guild-members" | "message-content")[];
+            requiredCapabilities: readonly ("message-content" | "guild-members")[];
+            missingCapabilities: ("message-content" | "guild-members")[];
             missingPermissions: string[];
             healthStatus: "healthy" | "degraded" | "unhealthy";
             healthMessage: string | null;

package/dist/discord-role-safety.d.ts

@@ -0,0 +1,4 @@
+/** The existing Helyx role-grant policy, shared by delivery and inspection. */
+export declare const dangerousRolePermissionNames: Set<string>;
+export declare function dangerousRolePermissions(permissions: bigint): string[];
+//# sourceMappingURL=discord-role-safety.d.ts.map

package/dist/discord-role-safety.js

@@ -0,0 +1,30 @@
+import { PermissionsBitField } from "discord.js";
+/** The existing Helyx role-grant policy, shared by delivery and inspection. */
+export const dangerousRolePermissionNames = new Set([
+    "ADMINISTRATOR",
+    "BAN_MEMBERS",
+    "DEAFEN_MEMBERS",
+    "KICK_MEMBERS",
+    "MANAGE_CHANNELS",
+    "MANAGE_EVENTS",
+    "MANAGE_GUILD",
+    "MANAGE_GUILD_EXPRESSIONS",
+    "MANAGE_MESSAGES",
+    "MANAGE_NICKNAMES",
+    "MANAGE_ROLES",
+    "MANAGE_THREADS",
+    "MANAGE_WEBHOOKS",
+    "MENTION_EVERYONE",
+    "MODERATE_MEMBERS",
+    "MOVE_MEMBERS",
+    "MUTE_MEMBERS",
+    "VIEW_AUDIT_LOG",
+]);
+export function dangerousRolePermissions(permissions) {
+    return new PermissionsBitField(permissions)
+        .toArray()
+        .map((permission) => permission.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase())
+        .filter((permission) => dangerousRolePermissionNames.has(permission))
+        .sort();
+}
+//# sourceMappingURL=discord-role-safety.js.map

package/dist/events.d.ts

@@ -1,4 +1,5 @@
 import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, InstallationService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess, VerificationMemberService } from "@helyx/sdk";
+import { inspectDiscordChannelAudit } from "./discord-channel-audit.js";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
 import type { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
@@ -80,6 +81,7 @@ export declare class DiscordResourceInspection implements DiscordResourceInspect
     #private;
     private readonly client;
     constructor(client: Client);
+    inspectChannelAudit(input: Parameters<typeof inspectDiscordChannelAudit>[1]): Promise<import("@helyx/sdk").ChannelAuditReport>;
     inspectGuildCapabilities(input: {
         guildId: string;
     }): Promise<DiscordGuildCapabilityInspection>;

package/dist/events.js

@@ -1,4 +1,6 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { inspectDiscordChannelAudit } from "./discord-channel-audit.js";
+import { dangerousRolePermissionNames } from "./discord-role-safety.js";
 import { safeError } from "@helyx/core";
 import { ChannelType, Events, GatewayIntentBits, GuildMemberFlags, PermissionFlagsBits, RESTJSONErrorCodes, UserFlags, } from "discord.js";
 import { toReplyOptions } from "./interactions.js";
@@ -1272,26 +1274,6 @@ export function reactionCacheKey(emojiIdentifier) {
 const discordSnowflake = /^\d{17,20}$/u;
 const moduleIdentifier = /^helyx\.[a-z0-9][a-z0-9-]*$/u;
 const customEmojiIdentifier = /^(?:<a?:([A-Za-z0-9_]{2,32}):(\d{17,20})>|([A-Za-z0-9_]{2,32}):(\d{17,20}))$/u;
-const dangerousRolePermissionNames = new Set([
-    "ADMINISTRATOR",
-    "BAN_MEMBERS",
-    "DEAFEN_MEMBERS",
-    "KICK_MEMBERS",
-    "MANAGE_CHANNELS",
-    "MANAGE_EVENTS",
-    "MANAGE_GUILD",
-    "MANAGE_GUILD_EXPRESSIONS",
-    "MANAGE_MESSAGES",
-    "MANAGE_NICKNAMES",
-    "MANAGE_ROLES",
-    "MANAGE_THREADS",
-    "MANAGE_WEBHOOKS",
-    "MENTION_EVERYONE",
-    "MODERATE_MEMBERS",
-    "MOVE_MEMBERS",
-    "MUTE_MEMBERS",
-    "VIEW_AUDIT_LOG",
-]);
 const directMessageAttemptTimeoutMs = 5_000;
 const guildChannelAudienceInspectionLimit = 500;
 export class DiscordMessageDeliveryService {
@@ -1696,6 +1678,9 @@ export class DiscordResourceInspection {
     constructor(client) {
         this.client = client;
     }
+    inspectChannelAudit(input) {
+        return inspectDiscordChannelAudit(this.client, input);
+    }
     async inspectGuildCapabilities(input) {
         validateSnowflake(input.guildId, "guild");
         const guild = await this.client.guilds.fetch(input.guildId);

package/dist/hosted-server-moderation.d.ts

@@ -11,8 +11,8 @@ declare const resultSchema: z.ZodObject<{
     }>;
     outcome: z.ZodEnum<{
         completed: "completed";
-        failed: "failed";
         requires_review: "requires_review";
+        failed: "failed";
         queued: "queued";
         not_currently_installed: "not_currently_installed";
         accepted_for_retry: "accepted_for_retry";
@@ -45,7 +45,7 @@ export declare class HostedServerModerationClient implements DeveloperServerMode
         idempotencyKey: string;
     }): Promise<{
         operationId: string;
-        outcome: "completed" | "failed" | "requires_review" | "queued" | "not_currently_installed" | "accepted_for_retry" | "already_blacklisted";
+        outcome: "completed" | "requires_review" | "failed" | "queued" | "not_currently_installed" | "accepted_for_retry" | "already_blacklisted";
         paidSlotsReleased: number;
     }>;
 }

package/dist/index.js

@@ -1,7 +1,7 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { StatusHeartbeatReporter } from "@helyx/status-client";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, EckoOperationsRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, PremiumAllocationRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, EckoOperationsRepository, InstallationRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, PremiumAllocationRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
@@ -20,6 +20,7 @@ import { assertConfiguredModuleDatabaseCompatibility, loadConfiguredModulePackag
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { createPermissionsModule } from "./permissions-module.js";
 import { createManagementModule } from "./management-module.js";
+import { createDiagnosticModule, createMysqlDiagnosticLock, createPostgresDiagnosticLock, } from "./diagnostic-command.js";
 import { DiscordMessageDeliveryService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModerationMemberEnforcementAdapter } from "./discord-member-enforcement-service.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
@@ -303,6 +304,30 @@ async function startUnshardedBot(processEnvironment) {
         });
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
+        const diagnosticInstallations = mysql
+            ? new (await import("@helyx/database-mysql")).InstallationRepository(mysql.pool)
+            : new InstallationRepository(database);
+        const diagnosticModule = createDiagnosticModule({
+            client,
+            modules: featureModules,
+            runExclusive: mysql
+                ? createMysqlDiagnosticLock(mysql.pool)
+                : createPostgresDiagnosticLock(database),
+            assertGuildAvailable: async (guildId) => {
+                if (shuttingDown ||
+                    !(await diagnosticInstallations.getActiveGuild(guildId)))
+                    throw new Error("The server installation is not available");
+            },
+            listEnabledModules: (guildId) => diagnosticInstallations.listEnabledModules(guildId),
+            commandStatus: {
+                get: (guildId) => {
+                    return guildCommandReads.getStatus(guildId);
+                },
+                refresh: (input) => {
+                    return guildCommandReads.refreshStatus(input);
+                },
+            },
+        });
         const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
                 connector: cloudConnector,
@@ -327,6 +352,7 @@ async function startUnshardedBot(processEnvironment) {
             : undefined;
         const publicModules = [
             managementModule,
+            diagnosticModule,
             permissionsModule,
             supportModule,
             privacyModule,
@@ -405,6 +431,7 @@ async function startUnshardedBot(processEnvironment) {
                 ...(deployedCommit ? { deploymentReference: deployedCommit } : {}),
                 coreFunctions: [
                     managementModule,
+                    diagnosticModule,
                     permissionsModule,
                     supportModule,
                     privacyModule,
@@ -534,6 +561,7 @@ async function startUnshardedBot(processEnvironment) {
         });
         const enabledCoreModuleIds = new Set([
             managementModule.manifest.id,
+            diagnosticModule.manifest.id,
             permissionsModule.manifest.id,
             supportModule.manifest.id,
             ...(premiumActivationModule ? [premiumActivationModule.manifest.id] : []),
@@ -555,6 +583,7 @@ async function startUnshardedBot(processEnvironment) {
             synchroniseInternalGuild: false,
             prepare: prepareGuilds,
             selfAuthorizingGuildModuleIds: new Set([
+                diagnosticModule.manifest.id,
                 supportModule.manifest.id,
                 ...(premiumActivationModule
                     ? [premiumActivationModule.manifest.id]

package/dist/shard-contracts.d.ts

@@ -286,6 +286,35 @@ export declare const shardControlOperationSchema: z.ZodDiscriminatedUnion<[z.Zod
     moduleIds: z.ZodArray<z.ZodString>;
     expectedRevision: z.ZodString;
     idempotencyKey: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    actorUserId: z.ZodString;
+    correlationId: z.ZodString;
+    kind: z.ZodLiteral<"guild.module.channel-audit.config.read">;
+    guildId: z.ZodString;
+    moduleId: z.ZodEnum<{
+        "helyx.account-gate": "helyx.account-gate";
+        "helyx.verification": "helyx.verification";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    actorUserId: z.ZodString;
+    correlationId: z.ZodString;
+    kind: z.ZodLiteral<"guild.module.channel-audit.check">;
+    guildId: z.ZodString;
+    moduleId: z.ZodEnum<{
+        "helyx.account-gate": "helyx.account-gate";
+        "helyx.verification": "helyx.verification";
+    }>;
+    assumptions: z.ZodObject<{
+        entryChannelId: z.ZodString;
+        beforeRoleIds: z.ZodArray<z.ZodString>;
+        afterRoleId: z.ZodString;
+        entrance: z.ZodEnum<{
+            public: "public";
+            restricted: "restricted";
+        }>;
+        allowedChannelIds: z.ZodArray<z.ZodString>;
+        reviewChannelId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
 }, z.core.$strict>, z.ZodObject<{
     actorUserId: z.ZodString;
     correlationId: z.ZodString;
@@ -742,6 +771,35 @@ export declare const shardControlRequestSchema: z.ZodObject<{
         moduleIds: z.ZodArray<z.ZodString>;
         expectedRevision: z.ZodString;
         idempotencyKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.module.channel-audit.config.read">;
+        guildId: z.ZodString;
+        moduleId: z.ZodEnum<{
+            "helyx.account-gate": "helyx.account-gate";
+            "helyx.verification": "helyx.verification";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.module.channel-audit.check">;
+        guildId: z.ZodString;
+        moduleId: z.ZodEnum<{
+            "helyx.account-gate": "helyx.account-gate";
+            "helyx.verification": "helyx.verification";
+        }>;
+        assumptions: z.ZodObject<{
+            entryChannelId: z.ZodString;
+            beforeRoleIds: z.ZodArray<z.ZodString>;
+            afterRoleId: z.ZodString;
+            entrance: z.ZodEnum<{
+                public: "public";
+                restricted: "restricted";
+            }>;
+            allowedChannelIds: z.ZodArray<z.ZodString>;
+            reviewChannelId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;
         correlationId: z.ZodString;
@@ -1703,6 +1761,35 @@ export declare const supervisorMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         moduleIds: z.ZodArray<z.ZodString>;
         expectedRevision: z.ZodString;
         idempotencyKey: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.module.channel-audit.config.read">;
+        guildId: z.ZodString;
+        moduleId: z.ZodEnum<{
+            "helyx.account-gate": "helyx.account-gate";
+            "helyx.verification": "helyx.verification";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        actorUserId: z.ZodString;
+        correlationId: z.ZodString;
+        kind: z.ZodLiteral<"guild.module.channel-audit.check">;
+        guildId: z.ZodString;
+        moduleId: z.ZodEnum<{
+            "helyx.account-gate": "helyx.account-gate";
+            "helyx.verification": "helyx.verification";
+        }>;
+        assumptions: z.ZodObject<{
+            entryChannelId: z.ZodString;
+            beforeRoleIds: z.ZodArray<z.ZodString>;
+            afterRoleId: z.ZodString;
+            entrance: z.ZodEnum<{
+                public: "public";
+                restricted: "restricted";
+            }>;
+            allowedChannelIds: z.ZodArray<z.ZodString>;
+            reviewChannelId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         actorUserId: z.ZodString;
         correlationId: z.ZodString;

package/dist/shard-contracts.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { channelAuditModuleIdSchema, channelAuditInputSchema, channelAuditConfigurationSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
 import { CLOUD_MAX_RESOURCE_IMPORT_BYTES, creatorOnboardingRequestSchema, } from "@helyx/control-protocol";
 import { AUTOMOD_SCANNER_LIMITS } from "@helyx/sdk";
 import { signedAssessmentEnvelopeSchema } from "@helyx/verification-contracts";
@@ -355,6 +356,23 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         ...mutationContext.shape,
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.channel-audit.config.read"),
+        guildId: snowflake,
+        moduleId: channelAuditModuleIdSchema,
+        ...mutationContext.shape,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.channel-audit.check"),
+        guildId: snowflake,
+        moduleId: channelAuditModuleIdSchema,
+        assumptions: channelAuditInputSchema,
+        ...mutationContext.shape,
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("guild.module.configuration.update"),
@@ -1117,6 +1135,27 @@ export async function executeShardControlOperation(handler, operation) {
                 correlationId: operation.correlationId,
             });
         }
+        case "guild.module.channel-audit.config.read": {
+            if (!handler.readChannelAuditConfiguration)
+                throw new Error("Channel audit is not supported by this shard version");
+            return channelAuditConfigurationSchema.parse(await handler.readChannelAuditConfiguration({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+            }));
+        }
+        case "guild.module.channel-audit.check": {
+            if (!handler.checkChannelAudit)
+                throw new Error("Channel audit is not supported by this shard version");
+            return channelAuditReportSchema.parse(await handler.checkChannelAudit({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                actorUserId: operation.actorUserId,
+                correlationId: operation.correlationId,
+                assumptions: operation.assumptions,
+            }));
+        }
         case "guild.module.configuration.update": {
             return handler.updateConfiguration({
                 guildId: operation.guildId,

package/dist/shard-router.d.ts

@@ -48,6 +48,8 @@ export declare class ShardControlRouter implements BotControlHandler {
     listGuildPresence(input: Parameters<BotControlHandler["listGuildPresence"]>[0]): ReturnType<BotControlHandler["listGuildPresence"]>;
     setModuleStatus(input: Parameters<BotControlHandler["setModuleStatus"]>[0]): ReturnType<BotControlHandler["setModuleStatus"]>;
     completeFirstTimeCommandSetup(input: Parameters<BotControlHandler["completeFirstTimeCommandSetup"]>[0]): ReturnType<BotControlHandler["completeFirstTimeCommandSetup"]>;
+    readChannelAuditConfiguration(input: Parameters<NonNullable<BotControlHandler["readChannelAuditConfiguration"]>>[0]): ReturnType<NonNullable<BotControlHandler["readChannelAuditConfiguration"]>>;
+    checkChannelAudit(input: Parameters<NonNullable<BotControlHandler["checkChannelAudit"]>>[0]): ReturnType<NonNullable<BotControlHandler["checkChannelAudit"]>>;
     updateConfiguration(input: Parameters<BotControlHandler["updateConfiguration"]>[0]): ReturnType<BotControlHandler["updateConfiguration"]>;
     previewConfiguration(input: Parameters<BotControlHandler["previewConfiguration"]>[0]): ReturnType<BotControlHandler["previewConfiguration"]>;
     updatePermissions(input: Parameters<BotControlHandler["updatePermissions"]>[0]): ReturnType<BotControlHandler["updatePermissions"]>;

package/dist/shard-router.js

@@ -117,6 +117,18 @@ export class ShardControlRouter {
             expectedRevision: input.expectedRevision.toString(),
         });
     }
+    readChannelAuditConfiguration(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.channel-audit.config.read",
+            ...input,
+        }));
+    }
+    checkChannelAudit(input) {
+        return this.#route(shardControlOperationSchema.parse({
+            kind: "guild.module.channel-audit.check",
+            ...input,
+        }));
+    }
     updateConfiguration(input) {
         return this.#route(shardControlOperationSchema.parse({
             kind: "guild.module.configuration.update",

package/dist/shard-supervisor.js

@@ -13,6 +13,7 @@ import { CloudConnectorController, } from "./cloud-connector.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, createBotControlServer, mapBotControlError, } from "./control-server.js";
 import { createManagementModule } from "./management-module.js";
+import { createDiagnosticModule } from "./diagnostic-command.js";
 import { buildApplicationCommandDefinitions } from "./interactions.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { deriveSecureRandomSelectionKey, loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
@@ -217,6 +218,10 @@ export async function startShardSupervisor(environment, processEnvironment, work
         };
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, unavailableResources);
+        // The supervisor registers metadata; guild checks and repairs run in workers.
+        const diagnosticModule = createDiagnosticModule({
+            modules: featureModules,
+        });
         const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
                 connector: cloudConnector,
@@ -242,6 +247,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             : undefined;
         const publicModules = [
             managementModule,
+            diagnosticModule,
             permissionsModule,
             supportModule,
             privacyModule,
@@ -265,6 +271,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     : {}),
                 coreFunctions: [
                     managementModule,
+                    diagnosticModule,
                     permissionsModule,
                     supportModule,
                     privacyModule,

package/dist/shard-worker.d.ts

@@ -102,6 +102,7 @@ export declare function shardWorkerCommandRegistration(input: {
     prepare: NonNullable<CommandRegistration["prepare"]>;
     operationsModuleId?: string;
     supportModuleId: string;
+    diagnosticModuleId?: string;
     premiumActivationModuleId?: string;
     oauthModuleId?: string;
 }): CommandRegistration;