@helyx/bot 1.5.0 → 1.5.2

package/dist/diagnostic-command.js

@@ -0,0 +1,1962 @@
+import { guildCommandDefinitionHash, } from "./guild-command-projection.js";
+import { canUseCommand, hasHelyxAccessLevel } from "@helyx/core";
+import { isCustomerSelectableModule, } from "@helyx/module-manifest";
+import { defineModule, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { ChannelType, PermissionsBitField, DiscordAPIError, Routes, GatewayIntentBits, PermissionFlagsBits, } from "discord.js";
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { performance } from "node:perf_hooks";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
+import { canAccessModule } from "./premium-access.js";
+const DIAGNOSTIC_MODULE_ID = "helyx.diagnostics";
+const RED = 0xdc2626;
+const ORANGE = 0xf59e0b;
+const GREEN = 0x16a34a;
+const MIN_STAGE_MS = 1_500;
+const MAX_RUN_MS = 10 * 60_000;
+const MAX_PROBES = 500;
+const CORE_MODULE_IDS = new Set([
+    DIAGNOSTIC_MODULE_ID,
+    "helyx.management",
+    "helyx.permissions",
+    "helyx.support",
+    "helyx.oauth",
+    "helyx.privacy",
+    "helyx.cloud-connect",
+    "helyx.premium-activation",
+    "helyx.developer-operations",
+]);
+class DiagnosticInterrupted extends Error {
+}
+/** A core command, never a selectable module or a module-repair hook. */
+export function createDiagnosticModule(options) {
+    const active = new Set();
+    const localGuilds = new Set();
+    const shutdown = new AbortController();
+    let stopping = false;
+    const administratorPolicy = {
+        everyone: false,
+        accessLevel: "administrator",
+        requiredPermissions: [],
+        allowedRoleIds: [],
+        deniedRoleIds: [],
+        allowedUserIds: [],
+        deniedUserIds: [],
+    };
+    return defineModule({
+        manifest: {
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
+            id: DIAGNOSTIC_MODULE_ID,
+            name: "Helyx Diagnostics",
+            version: "0.1.0",
+            releaseStatus: "live",
+            description: "Checks this server and verifies supported repairs.",
+            entry: "./dist/diagnostic-command.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["diag"], events: [] },
+        },
+        defaultPermissions: {
+            module: administratorPolicy,
+            commands: { diag: administratorPolicy },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "diag",
+                    permissionId: "diag",
+                    description: "Check Helyx modules and repair supported problems",
+                    registrationPolicy: "platform-global",
+                    contexts: ["guild"],
+                    integrationTypes: ["guild_install"],
+                    authorization: "self-authorized",
+                    acknowledgement: "immediate-response",
+                    options: [
+                        {
+                            name: "ephemeral",
+                            description: "Keep the whole report private",
+                            type: "boolean",
+                            required: false,
+                        },
+                    ],
+                    async execute(context) {
+                        const ephemeral = context.getBooleanOption("ephemeral") ?? false;
+                        // Visibility is selected before any database or Discord work.
+                        if (context.deferReply)
+                            await context.deferReply(ephemeral);
+                        else
+                            await context.reply(report(ephemeral, ORANGE, ["Starting server checks..."]));
+                        const guildId = context.serverId;
+                        if (!guildId) {
+                            await context.reply(report(ephemeral, ORANGE, ["Use /diag in a Discord server."]));
+                            return;
+                        }
+                        if (stopping ||
+                            !options.runExclusive ||
+                            !options.assertGuildAvailable ||
+                            (!options.client && !options.resources)) {
+                            await context.reply(report(ephemeral, RED, [
+                                "Diagnostics is unavailable on this bot. Ask the operator to check its setup.",
+                            ]));
+                            return;
+                        }
+                        const resources = options.resources?.(guildId) ??
+                            createNativeDiagnosticResources(options.client, guildId);
+                        resourceGuildIds.set(resources, guildId);
+                        try {
+                            await assertAdministrator(context.services, resources, context.userId);
+                            await options.assertGuildAvailable(guildId);
+                        }
+                        catch {
+                            await context.reply(report(ephemeral, ORANGE, [
+                                "Only the server owner, Discord Administrators and Helyx Administrators can run /diag on an active server.",
+                            ]));
+                            return;
+                        }
+                        if (localGuilds.has(guildId)) {
+                            await context.reply(report(ephemeral, ORANGE, [
+                                "A diagnostic run is already in progress for this server.",
+                            ]));
+                            return;
+                        }
+                        localGuilds.add(guildId);
+                        const operation = (async () => {
+                            try {
+                                const acquired = await options.runExclusive(guildId, async (lease) => {
+                                    const timeout = AbortSignal.timeout(options.maximumRunMilliseconds ?? MAX_RUN_MS);
+                                    const signal = AbortSignal.any([
+                                        shutdown.signal,
+                                        lease.signal,
+                                        timeout,
+                                    ]);
+                                    await executeDiagnostic({
+                                        context,
+                                        options,
+                                        resources,
+                                        lease,
+                                        signal,
+                                        ephemeral,
+                                    });
+                                });
+                                if (!acquired)
+                                    await context.reply(report(ephemeral, ORANGE, [
+                                        "A diagnostic run is already in progress for this server.",
+                                    ]));
+                            }
+                            catch {
+                                if (!shutdown.signal.aborted) {
+                                    // No raw errors, resource IDs or private configuration enter a public report.
+                                    await context
+                                        .reply(report(ephemeral, RED, [
+                                        "The diagnostic run could not finish.",
+                                        "No further repairs will be attempted. Use /helyx bug if the problem continues.",
+                                    ]))
+                                        .catch(() => undefined);
+                                }
+                            }
+                            finally {
+                                localGuilds.delete(guildId);
+                            }
+                        })();
+                        active.add(operation);
+                        try {
+                            await operation;
+                        }
+                        finally {
+                            active.delete(operation);
+                        }
+                    },
+                },
+            ],
+        },
+        start() {
+            return Promise.resolve();
+        },
+        async stop() {
+            stopping = true;
+            shutdown.abort();
+            await Promise.allSettled([...active]);
+        },
+    });
+}
+async function assertAdministrator(services, resources, userId) {
+    const actor = await resources.actor(userId);
+    const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
+    const guildId = diagnosticGuildId(resources);
+    const policy = permissions.getGuildAccessPolicy && guildId
+        ? await permissions.getGuildAccessPolicy(guildId)
+        : undefined;
+    if (!hasHelyxAccessLevel(actor, "administrator", policy))
+        throw new DiagnosticInterrupted("authority_changed");
+}
+// Resource implementations carry their server scope without exposing it in reports.
+const resourceGuildIds = new WeakMap();
+function diagnosticGuildId(resources) {
+    return resourceGuildIds.get(resources);
+}
+async function executeDiagnostic(input) {
+    const { context, options, resources, lease, signal, ephemeral } = input;
+    const guildId = context.serverId;
+    resourceGuildIds.set(resources, guildId);
+    const started = performance.now();
+    const stageMs = options.stageMilliseconds ?? MIN_STAGE_MS;
+    const observations = new Map();
+    let checked = 0;
+    let expected = 0;
+    let customerCount = 0;
+    let originalEnabledIds = [];
+    let deliveryLost = false;
+    const assertRunning = async () => {
+        if (signal.aborted)
+            throw new DiagnosticInterrupted("run_stopped");
+        await lease.assertOwned();
+        await options.assertGuildAvailable(guildId);
+        if (signal.aborted)
+            throw new DiagnosticInterrupted("run_stopped");
+    };
+    const show = async (lines, color = currentColor(observations)) => {
+        if (deliveryLost)
+            throw new DiagnosticInterrupted("report_unavailable");
+        try {
+            await context.reply(report(ephemeral, color, lines));
+        }
+        catch {
+            deliveryLost = true;
+            throw new DiagnosticInterrupted("report_unavailable");
+        }
+    };
+    const stage = async (lines, work) => {
+        await assertRunning();
+        const stageStarted = performance.now();
+        await show(lines);
+        const result = await work();
+        if (signal.aborted)
+            throw new DiagnosticInterrupted("run_stopped");
+        const remaining = stageMs - (performance.now() - stageStarted);
+        if (remaining > 0)
+            await delay(remaining, undefined, { signal });
+        return result;
+    };
+    const installations = context.services.get(HELYX_SERVICE_NAMES.installations);
+    const configuration = context.services.get(HELYX_SERVICE_NAMES.configuration);
+    const frozen = new Map();
+    try {
+        const discovered = await stage(["Scanning for active modules..."], async () => {
+            const loaded = new Map(options.modules.map((m) => [m.manifest.id, m]));
+            const enabled = options.listEnabledModules
+                ? await options.listEnabledModules(guildId)
+                : (await Promise.all(options.modules.map(async (module) => ({
+                    moduleId: module.manifest.id,
+                    enabled: await installations.isModuleEnabled(guildId, module.manifest.id),
+                })))).filter((x) => x.enabled);
+            const missing = enabled.filter((x) => !loaded.has(x.moduleId) && !CORE_MODULE_IDS.has(x.moduleId));
+            originalEnabledIds = [
+                ...new Set(enabled.map((x) => x.moduleId)),
+            ].sort();
+            const selected = enabled
+                .map((x) => loaded.get(x.moduleId))
+                .filter((m) => !!m && isCustomerSelectableModule(m.manifest));
+            customerCount = selected.length;
+            const visit = async (module, customer) => {
+                const existing = frozen.get(module.manifest.id);
+                if (existing) {
+                    if (customer)
+                        existing.customer = true;
+                    return;
+                }
+                const state = await installations.getModuleState(guildId, module.manifest.id);
+                frozen.set(module.manifest.id, {
+                    module,
+                    customer,
+                    enabledAt: state?.enabled ? state.enabledAt.getTime() : null,
+                    configuration: await configuration.get(guildId, module.manifest.id),
+                });
+                for (const dependency of module.manifest.dependencies) {
+                    const definition = loaded.get(dependency.id);
+                    if (definition)
+                        await visit(definition, false);
+                    else
+                        missing.push({ moduleId: dependency.id });
+                }
+            };
+            for (const module of selected)
+                await visit(module, true);
+            return { missing: [...new Set(missing.map((x) => x.moduleId))] };
+        });
+        await stage([
+            `${customerCount} active modules found.`,
+            "Checking setup, permissions and supported saved records.",
+        ], () => Promise.resolve(undefined));
+        const assertCanMutate = async (moduleId) => {
+            await assertRunning();
+            await assertAdministrator(context.services, resources, context.userId);
+            const entry = frozen.get(moduleId);
+            if (!entry?.customer)
+                throw new DiagnosticInterrupted("scope_changed");
+            const current = await installations.getModuleState(guildId, moduleId);
+            if (!current?.enabled || current.enabledAt.getTime() !== entry.enabledAt)
+                throw new DiagnosticInterrupted("module_changed");
+            const config = await configuration.get(guildId, moduleId);
+            if (!sameConfiguration(entry.configuration, config))
+                throw new DiagnosticInterrupted("configuration_changed");
+            if (!context.services.has(HELYX_SERVICE_NAMES.moduleAvailability) ||
+                !(await context.services
+                    .get(HELYX_SERVICE_NAMES.moduleAvailability)
+                    .isAvailable(moduleId)))
+                throw new DiagnosticInterrupted("availability_changed");
+            if (entry.module.configuration) {
+                if (entry.configuration &&
+                    entry.configuration.schemaVersion !==
+                        entry.module.configuration.schemaVersion)
+                    throw new DiagnosticInterrupted("configuration_schema_changed");
+                try {
+                    entry.module.configuration.validate(structuredClone(entry.configuration?.value ?? {}));
+                }
+                catch {
+                    throw new DiagnosticInterrupted("configuration_invalid");
+                }
+            }
+            if (!(await canAccessModule(context.services, guildId, entry.module)))
+                throw new DiagnosticInterrupted("access_changed");
+            await assertRunning();
+        };
+        const probes = [];
+        probes.push({
+            id: "scope.current",
+            label: "Current module scope",
+            inspect: async () => {
+                if (options.listEnabledModules) {
+                    const current = [
+                        ...new Set((await options.listEnabledModules(guildId)).map((x) => x.moduleId)),
+                    ].sort();
+                    if (!isDeepStrictEqual(current, originalEnabledIds))
+                        return {
+                            kind: "incomplete",
+                            message: "The enabled modules changed during this run. Run /diag again to check the current selection.",
+                        };
+                }
+                for (const entry of frozen.values()) {
+                    if (!entry.customer)
+                        continue;
+                    const current = await installations.getModuleState(guildId, entry.module.manifest.id);
+                    if (!current?.enabled ||
+                        current.enabledAt.getTime() !== entry.enabledAt)
+                        return {
+                            kind: "incomplete",
+                            message: "A module was disabled or restarted during this run. Run /diag again to check its current state.",
+                        };
+                }
+                return null;
+            },
+        });
+        for (const id of discovered.missing) {
+            probes.push(fixedIssue(`package:${id}`, "Installed module package", "incomplete", "An enabled module or required shared service is not loaded. Ask the operator to check installed packages."));
+        }
+        for (const entry of frozen.values())
+            probes.push(...moduleProbes(entry, context.services, guildId, resources));
+        probes.push(...coreProbes(options, context, resources, assertRunning));
+        probes.push(...permissionProbes([...frozen.values()], context.services, guildId));
+        if (context.services.has(HELYX_SERVICE_NAMES.records)) {
+            const recordProbes = await stage(["Inspecting this server's declared saved records..."], () => createRecordProbes({
+                guildId,
+                actorUserId: context.userId,
+                correlationId: context.interactionId,
+                modules: [...frozen.values()]
+                    .filter((x) => x.customer)
+                    .map((x) => x.module),
+                records: context.services.get(HELYX_SERVICE_NAMES.records),
+                services: context.services,
+                assertCanInspect: assertRunning,
+                assertCanMutate,
+                inspectMessage: (channel, message) => resources.message(channel, message),
+                now: () => new Date(),
+            }));
+            probes.push(...recordProbes);
+        }
+        else
+            probes.push(fixedIssue("records-unavailable", "Saved records", "incomplete", "Saved-record checks are unavailable."));
+        const unique = [
+            ...new Map(probes.map((probe) => [probe.id, probe])).values(),
+        ];
+        for (const probe of unique) {
+            const entry = probe.moduleId ? frozen.get(probe.moduleId) : undefined;
+            if (!entry?.customer)
+                continue;
+            const inspect = probe.inspect;
+            probe.inspect = async () => {
+                const current = await installations.getModuleState(guildId, entry.module.manifest.id);
+                const latestConfig = await configuration.get(guildId, entry.module.manifest.id);
+                if (!current?.enabled ||
+                    current.enabledAt.getTime() !== entry.enabledAt ||
+                    !sameConfiguration(entry.configuration, latestConfig))
+                    return {
+                        kind: "incomplete",
+                        message: "This module's setup changed during the run. Its newer state was preserved; run /diag again.",
+                    };
+                return inspect();
+            };
+        }
+        if (unique.length > MAX_PROBES) {
+            unique.splice(MAX_PROBES - 1);
+            unique.push(fixedIssue("scan-limit", "Remaining records", "incomplete", "This run reached its record limit. Additional records have not been checked."));
+        }
+        expected = unique.length;
+        // Complete every initial probe before entering either repair round.
+        for (const probe of unique) {
+            const issue = await stage([
+                `Checking ${customerCount} active modules · ${checked}/${expected} checks.`,
+                probe.label,
+                `${countIssues(observations)} findings so far.`,
+            ], () => inspectSafely(probe));
+            observations.set(probe.id, { probe, issue, fixed: false });
+            checked++;
+        }
+        const findings = [...observations.values()].filter((x) => x.issue);
+        for (let i = 0; i < findings.length; i += 2) {
+            await stage([
+                `${findings.length} findings after all ${checked} checks.`,
+                ...findings.slice(i, i + 2).map((x) => publicFinding(x)),
+            ], () => Promise.resolve(undefined));
+        }
+        for (const round of [1, 2]) {
+            const eligible = [...observations.values()].filter((x) => !x.fixed &&
+                x.issue?.kind === "repairable" &&
+                typeof x.probe.repair === "function");
+            if (!eligible.length)
+                break;
+            for (const observed of eligible) {
+                const issue = observed.issue;
+                try {
+                    await stage([
+                        `Recovery round ${round} · ${eligible.length} supported findings.`,
+                        observed.probe.label,
+                        round === 1
+                            ? "Refreshing and confirming the current evidence."
+                            : "Attempting the supported repair.",
+                    ], async () => {
+                        if (observed.probe.moduleId)
+                            await assertCanMutate(observed.probe.moduleId);
+                        else {
+                            await assertRunning();
+                            await assertAdministrator(context.services, resources, context.userId);
+                        }
+                        const result = await observed.probe.repair(round, issue);
+                        if (result === "stale")
+                            observed.issue = {
+                                kind: "human",
+                                message: "Settings or records changed. Review the newer state and run /diag again.",
+                            };
+                    });
+                }
+                catch (error) {
+                    if (deliveryLost ||
+                        signal.aborted ||
+                        error instanceof DiagnosticInterrupted)
+                        throw error;
+                    observed.issue = {
+                        kind: "technical",
+                        message: "The repair could not safely complete. No further change was attempted.",
+                    };
+                }
+            }
+            for (const observed of eligible) {
+                if (observed.issue?.kind !== "repairable")
+                    continue;
+                const previous = observed.issue;
+                await stage([
+                    `Verifying recovery round ${round}.`,
+                    observed.probe.label,
+                    "Checking the saved result again.",
+                ], async () => {
+                    let verified;
+                    try {
+                        verified = observed.probe.verify
+                            ? await observed.probe.verify(previous)
+                            : (await inspectSafely(observed.probe)) === null;
+                    }
+                    catch {
+                        observed.issue = {
+                            kind: "incomplete",
+                            message: "The saved repair result could not be checked. Run /diag again before relying on it.",
+                        };
+                        return;
+                    }
+                    if (verified) {
+                        observed.fixed = true;
+                        observed.verifiedSnapshot = previous;
+                        observed.issue = null;
+                    }
+                    else
+                        observed.issue = (await inspectSafely(observed.probe)) ?? {
+                            kind: "technical",
+                            message: "The repair result could not be verified.",
+                        };
+                });
+                await stage([
+                    `Recovery round ${round} checked.`,
+                    `${observed.probe.label} · ${observed.fixed ? "Fixed" : "Needs attention"}`,
+                    observed.fixed && previous.afterRepair
+                        ? previous.afterRepair
+                        : "Only a successful fresh check is reported as Fixed.",
+                ], () => Promise.resolve(undefined));
+            }
+        }
+        // Preserve verified fixes, but reread every remaining dependent setup/access check.
+        for (const observed of observations.values()) {
+            if (observed.fixed || observed.issue?.kind === "technical")
+                continue;
+            await assertRunning();
+            observed.issue = await inspectSafely(observed.probe);
+        }
+        await assertRunning();
+        await show(finalLines(customerCount, checked, expected, observations), currentColor(observations));
+    }
+    catch (error) {
+        if (deliveryLost)
+            return;
+        const remaining = Math.max(0, expected - checked);
+        await show([
+            `Checks stopped · ${checked}/${expected || "unknown"} completed.`,
+            `${verifiedCount(observations)} verified repairs · ${remaining || "remaining"} checks incomplete.`,
+            signal.aborted
+                ? "The run stopped or timed out. No further repairs will be attempted."
+                : "Access, ownership or a required service changed. Run /diag again or use /helyx bug.",
+        ], RED).catch(() => undefined);
+        if (!(error instanceof DiagnosticInterrupted) && !signal.aborted) {
+            // The outer runtime receives no raw database or Discord exception.
+        }
+    }
+    finally {
+        void started;
+    }
+}
+function sameConfiguration(a, b) {
+    return (a?.version === b?.version &&
+        a?.schemaVersion === b?.schemaVersion &&
+        isDeepStrictEqual(a?.value, b?.value));
+}
+async function inspectSafely(probe) {
+    try {
+        return await probe.inspect();
+    }
+    catch {
+        return {
+            kind: "incomplete",
+            message: "This check could not finish. Retry later or ask support.",
+        };
+    }
+}
+function fixedIssue(id, label, kind, message) {
+    return { id, label, inspect: () => Promise.resolve({ kind, message }) };
+}
+function report(ephemeral, accentColor, lines) {
+    return {
+        ephemeral,
+        componentsV2: {
+            accentColor,
+            text: [
+                { content: "## Helyx Diagnostic Report" },
+                { content: lines.slice(0, 3).map(safeLine).join("\n") },
+            ],
+        },
+    };
+}
+function safeLine(value) {
+    return value
+        .replace(/[\r\n]+/g, " ")
+        .replace(/[@<>]/g, "")
+        .replace(/([\\`*_{}[\]()])/g, "\\$1")
+        .slice(0, 450);
+}
+function countIssues(items) {
+    return [...items.values()].filter((x) => x.issue).length;
+}
+function verifiedCount(items) {
+    return [...items.values()].filter((x) => x.fixed).length;
+}
+function publicFinding(item) {
+    return `${item.probe.label} · ${item.issue?.kind === "repairable" ? "Supported repair available" : (item.issue?.message ?? "Checked")}`;
+}
+function currentColor(items) {
+    const values = [...items.values()];
+    if (values.some((x) => x.issue?.kind === "technical" || x.issue?.kind === "repairable"))
+        return RED;
+    if (values.some((x) => x.issue || x.verifiedSnapshot?.afterRepair))
+        return ORANGE;
+    return GREEN;
+}
+function finalLines(modules, checked, total, items) {
+    const values = [...items.values()];
+    const incomplete = values.filter((x) => x.issue?.kind === "incomplete").length;
+    const followups = values.filter((x) => x.fixed && x.verifiedSnapshot?.afterRepair);
+    const unresolved = values.filter((x) => x.issue && x.issue.kind !== "incomplete");
+    const needs = unresolved.length + followups.length;
+    return [
+        `${modules} active modules · ${checked}/${total} checks completed.`,
+        `${verifiedCount(items)} verified repairs · ${needs} need attention · ${incomplete} incomplete checks.`,
+        needs || incomplete
+            ? `${followups[0]?.verifiedSnapshot?.afterRepair ?? unresolved[0]?.issue?.message ?? "Some checks could not finish."} Use /helyx bug if unresolved.`
+            : "No outstanding problem was detected in the checked scope.",
+    ];
+}
+function coreProbes(options, context, resources, assertRunning) {
+    if (!options.commandStatus || !resources.guildCommands)
+        return [
+            fixedIssue("commands.coverage", "Discord command status", "incomplete", "Discord command status cannot be checked on this bot."),
+        ];
+    const status = options.commandStatus;
+    const guildId = context.serverId;
+    const read = async () => {
+        const raw = await status.get(guildId);
+        if (!raw ||
+            typeof raw !== "object" ||
+            !("state" in raw) ||
+            !raw.state ||
+            typeof raw.state !== "object")
+            throw new Error("Missing command state");
+        const state = raw.state;
+        if (typeof state.desiredRevision !== "string" ||
+            typeof state.visibilityProfile !== "string")
+            throw new Error("Invalid command state");
+        const observed = await resources.guildCommands();
+        return {
+            state,
+            observed,
+            busy: "activeRequest" in raw && raw.activeRequest != null,
+        };
+    };
+    return [
+        {
+            id: "commands.stale-observation",
+            label: "Discord command status",
+            async inspect() {
+                const { state, observed, busy } = await read();
+                if (busy || state.state === "pending" || state.state === "running")
+                    return {
+                        kind: "human",
+                        message: "A command update is already pending. Check Commands in the dashboard after it finishes.",
+                    };
+                if (state.desiredDefinitionHash !== observed.definitionHash ||
+                    state.desiredRootCount !== observed.rootCount)
+                    return {
+                        kind: "human",
+                        message: "Discord commands do not match this server's command setup. Review Commands in the dashboard.",
+                    };
+                if (state.lastObservedDefinitionHash !== observed.definitionHash ||
+                    state.installedRootCount !== observed.rootCount)
+                    return {
+                        kind: "repairable",
+                        message: "The saved command status is out of date; the commands themselves already match.",
+                        evidence: {
+                            desiredRevision: state.desiredRevision,
+                            visibilityProfile: state.visibilityProfile,
+                            definitionHash: observed.definitionHash,
+                            rootCount: observed.rootCount,
+                        },
+                    };
+                return null;
+            },
+            async repair(round, issue) {
+                // Both rounds use the same revision-guarded, metadata-only refresh.
+                // No command reconciliation, profile change or Discord write is requested.
+                void round;
+                const current = await read();
+                if (current.busy ||
+                    current.state.desiredRevision !== issue.evidence?.desiredRevision ||
+                    current.state.visibilityProfile !==
+                        issue.evidence?.visibilityProfile ||
+                    current.state.desiredDefinitionHash !==
+                        issue.evidence?.definitionHash ||
+                    current.observed.definitionHash !== issue.evidence?.definitionHash ||
+                    current.observed.rootCount !== issue.evidence?.rootCount)
+                    return "stale";
+                await assertRunning();
+                await assertAdministrator(context.services, resources, context.userId);
+                await status.refresh({
+                    guildId,
+                    actorUserId: context.userId,
+                    correlationId: context.interactionId,
+                });
+                return "attempted";
+            },
+            async verify(issue) {
+                const { state, observed, busy } = await read();
+                return (!busy &&
+                    state.desiredRevision === issue.evidence?.desiredRevision &&
+                    state.visibilityProfile === issue.evidence?.visibilityProfile &&
+                    state.desiredDefinitionHash === observed.definitionHash &&
+                    observed.definitionHash === issue.evidence?.definitionHash &&
+                    state.lastObservedDefinitionHash === observed.definitionHash &&
+                    state.desiredRootCount === observed.rootCount &&
+                    state.installedRootCount === observed.rootCount);
+            },
+        },
+    ];
+}
+function permissionProbes(entries, services, guildId) {
+    // Closed outcome catalogue. Public member submissions/votes and an "everyone"
+    // flag on unrelated policies are never treated as dangerous exposure.
+    const moderation = entries.find((x) => x.customer && x.module.manifest.id === "helyx.moderation");
+    if (!moderation)
+        return [];
+    const routeExists = moderation.module.interactions?.commands?.some((root) => root.subcommands?.some((command) => command.permissionId === "moderation.unban" &&
+        command.authorization === "resource-scoped"));
+    if (!routeExists)
+        return [
+            fixedIssue("permissions.moderation-coverage", "Moderation command access", "incomplete", "This installed Moderation version needs a separate command-access review."),
+        ];
+    return [
+        {
+            id: "permissions.moderation-unban",
+            moduleId: moderation.module.manifest.id,
+            label: "Moderation unban access",
+            async inspect() {
+                const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
+                const policy = await permissions.getEffectivePolicy(guildId, moderation.module.manifest.id, "moderation.unban");
+                const access = await permissions.getGuildAccessPolicy?.(guildId);
+                // An unban has no target hierarchy gate. Its resource authorization service
+                // evaluates this exact effective policy; checking it never executes an action.
+                const ordinaryMember = {
+                    userId: "diagnostic-non-member",
+                    roleIds: [guildId],
+                    permissions: [],
+                    isServerOwner: false,
+                    isAdministrator: false,
+                };
+                if (canUseCommand(ordinaryMember, policy, access))
+                    return {
+                        kind: "human",
+                        message: "The unban permission allows ordinary members. Restrict it in Moderation's Permissions settings.",
+                    };
+                return null;
+            },
+        },
+    ];
+}
+const DIAGNOSTIC_LOCK_QUERY_TIMEOUT_MS = 10_000;
+const diagnosticLockCapacity = new WeakMap();
+function diagnosticPostgresLockQuery(text, key) {
+    // pg supports query_timeout at runtime although QueryConfig omits it. A
+    // named structural config preserves the deadline without an unsafe type cast.
+    return {
+        text,
+        values: [key],
+        query_timeout: DIAGNOSTIC_LOCK_QUERY_TIMEOUT_MS,
+    };
+}
+function reserveDiagnosticLockCapacity(pool, maxConnections) {
+    const budget = Number.isSafeInteger(maxConnections)
+        ? Math.min(4, maxConnections - 2)
+        : 0;
+    const current = diagnosticLockCapacity.get(pool) ?? 0;
+    if (budget < 1 || current >= budget) {
+        throw new Error("Diagnostic database lock capacity is unavailable; retry later");
+    }
+    // Synchronous reservation before awaiting a connection: no local wait queue.
+    diagnosticLockCapacity.set(pool, current + 1);
+    return () => {
+        const remaining = (diagnosticLockCapacity.get(pool) ?? 1) - 1;
+        if (remaining === 0)
+            diagnosticLockCapacity.delete(pool);
+        else
+            diagnosticLockCapacity.set(pool, remaining);
+    };
+}
+function diagnosticLockKey(guildId) {
+    if (!/^[0-9]{1,22}$/u.test(guildId)) {
+        throw new Error("Diagnostic guild ID must be a Discord snowflake");
+    }
+    return `helyx:diag:${guildId}`;
+}
+/** Reserve at most four sessions, leaving at least two pool slots for repairs. */
+export function createPostgresDiagnosticLock(pool) {
+    return async (guildId, operation) => {
+        const key = diagnosticLockKey(guildId);
+        const releaseCapacity = reserveDiagnosticLockCapacity(pool, pool.options.max);
+        try {
+            const connection = await pool.connect();
+            const controller = new AbortController();
+            let acquired = false;
+            let reusable = false;
+            const loseLease = (cause) => {
+                reusable = false;
+                controller.abort(new Error("Diagnostic database lock ownership was lost", { cause }));
+            };
+            const endLease = () => loseLease();
+            connection.on("error", loseLease);
+            connection.on("end", endLease);
+            const lease = {
+                signal: controller.signal,
+                async assertOwned() {
+                    controller.signal.throwIfAborted();
+                    try {
+                        // Advisory locks are reentrant. Checking pg_locks avoids acquiring a
+                        // second lock (and avoids hiding a lost first lock by reacquiring it).
+                        const result = await connection.query(diagnosticPostgresLockQuery(`SELECT EXISTS (
+                     SELECT 1 FROM pg_locks
+                      WHERE locktype = 'advisory' AND pid = pg_backend_pid()
+                        AND database = (SELECT oid FROM pg_database WHERE datname = current_database())
+                        AND granted AND objsubid = 1
+                        AND classid::bigint = ((hashtextextended($1, 0) >> 32) & 4294967295)
+                        AND objid::bigint = (hashtextextended($1, 0) & 4294967295)
+                   ) AS owned`, key));
+                        if (result.rows[0]?.owned !== true)
+                            loseLease();
+                    }
+                    catch (error) {
+                        loseLease(error);
+                    }
+                    controller.signal.throwIfAborted();
+                },
+            };
+            try {
+                const result = await connection.query(diagnosticPostgresLockQuery("SELECT pg_try_advisory_lock(hashtextextended($1, 0)) AS acquired", key));
+                controller.signal.throwIfAborted();
+                if (result.rows[0]?.acquired === false) {
+                    reusable = true;
+                    return false;
+                }
+                if (result.rows[0]?.acquired !== true) {
+                    throw new Error("Diagnostic database lock acquisition could not be confirmed");
+                }
+                acquired = true;
+                await lease.assertOwned();
+                // No timeout race: keep the reserved session until all callback work has
+                // drained, including cancellation handling and any in-flight repair.
+                await operation(lease);
+                await lease.assertOwned();
+                return true;
+            }
+            finally {
+                if (acquired && !controller.signal.aborted) {
+                    try {
+                        const result = await connection.query(diagnosticPostgresLockQuery("SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS released", key));
+                        reusable =
+                            result.rows[0]?.released === true && !controller.signal.aborted;
+                    }
+                    catch (error) {
+                        loseLease(error);
+                    }
+                }
+                controller.abort(new Error("Diagnostic database lock lease has ended"));
+                connection.off("error", loseLease);
+                connection.off("end", endLease);
+                connection.release(!reusable);
+            }
+        }
+        finally {
+            releaseCapacity();
+        }
+    };
+}
+function diagnosticMysqlScalar(rows, field) {
+    if (!Array.isArray(rows))
+        return undefined;
+    const row = rows[0];
+    if (typeof row !== "object" || row === null || !(field in row))
+        return undefined;
+    return row[field];
+}
+/** Reserve at most four sessions, leaving at least two pool slots for repairs. */
+export function createMysqlDiagnosticLock(pool) {
+    return async (guildId, operation) => {
+        const key = diagnosticLockKey(guildId);
+        const releaseCapacity = reserveDiagnosticLockCapacity(pool.pool, pool.pool.config.connectionLimit ?? 0);
+        try {
+            const connection = await pool.getConnection();
+            const controller = new AbortController();
+            let acquired = false;
+            let reusable = false;
+            const loseLease = (cause) => {
+                reusable = false;
+                controller.abort(new Error("Diagnostic database lock ownership was lost", { cause }));
+            };
+            const endLease = () => loseLease();
+            connection.on("error", loseLease);
+            connection.on("end", endLease);
+            const queryScalar = async (sql, field) => {
+                const [rows] = await connection.query({
+                    sql,
+                    timeout: DIAGNOSTIC_LOCK_QUERY_TIMEOUT_MS,
+                }, [key]);
+                return diagnosticMysqlScalar(rows, field);
+            };
+            const lease = {
+                signal: controller.signal,
+                async assertOwned() {
+                    controller.signal.throwIfAborted();
+                    try {
+                        // IS_USED_LOCK reads ownership without taking a reentrant GET_LOCK.
+                        const owned = await queryScalar("SELECT (IS_USED_LOCK(?) = CONNECTION_ID()) AS owned", "owned");
+                        if (owned !== 1 && owned !== "1")
+                            loseLease();
+                    }
+                    catch (error) {
+                        loseLease(error);
+                    }
+                    controller.signal.throwIfAborted();
+                },
+            };
+            try {
+                const result = await queryScalar("SELECT GET_LOCK(?, 0) AS acquired", "acquired");
+                controller.signal.throwIfAborted();
+                if (result === 0 || result === "0") {
+                    reusable = true;
+                    return false;
+                }
+                if (result !== 1 && result !== "1") {
+                    throw new Error("Diagnostic database lock acquisition could not be confirmed");
+                }
+                acquired = true;
+                await lease.assertOwned();
+                await operation(lease);
+                await lease.assertOwned();
+                return true;
+            }
+            finally {
+                if (acquired && !controller.signal.aborted) {
+                    try {
+                        const result = await queryScalar("SELECT RELEASE_LOCK(?) AS released", "released");
+                        reusable =
+                            (result === 1 || result === "1") && !controller.signal.aborted;
+                    }
+                    catch (error) {
+                        loseLease(error);
+                    }
+                }
+                controller.abort(new Error("Diagnostic database lock lease has ended"));
+                connection.off("error", loseLease);
+                connection.off("end", endLease);
+                if (reusable)
+                    connection.release();
+                else
+                    connection.destroy();
+            }
+        }
+        finally {
+            releaseCapacity();
+        }
+    };
+}
+async function createRecordProbes(env) {
+    const probes = [];
+    const specs = [
+        {
+            moduleId: "helyx.sticky-messages",
+            collection: "stickies",
+            key: "sticky_id",
+            label: "Sticky Messages",
+            mode: "sticky",
+            pointer: "current_message_id",
+        },
+        {
+            moduleId: "helyx.message-embedder",
+            collection: "messages",
+            key: "definition_id",
+            label: "Message Embedder",
+            mode: "embedder",
+            pointer: "message_id",
+        },
+        {
+            moduleId: "helyx.message-embedder",
+            collection: "ownedMessageCleanup",
+            key: "cleanup_id",
+            label: "Message Embedder cleanup",
+            mode: "orphan",
+            pointer: "message_id",
+        },
+    ];
+    for (const spec of specs) {
+        await env.assertCanInspect();
+        const module = env.modules.find((item) => item.manifest.id === spec.moduleId);
+        if (!module)
+            continue;
+        const collection = module.records?.[spec.collection];
+        const unavailable = (message) => probes.push({
+            id: `${spec.moduleId}.${spec.collection}.coverage`,
+            moduleId: spec.moduleId,
+            label: `${spec.label} saved records`,
+            inspect: () => Promise.resolve({ kind: "incomplete", message }),
+        });
+        if (!collection || !diagnosticRecordSchemaSupported(spec, collection)) {
+            unavailable(`${spec.label} record checks are unavailable for this installed version. No saved records were changed.`);
+            continue;
+        }
+        if (spec.mode !== "orphan") {
+            try {
+                env.services.get(HELYX_SERVICE_NAMES.messageBuilder);
+            }
+            catch {
+                unavailable(`${spec.label} message validation is unavailable. Its saved records were not repaired.`);
+                continue;
+            }
+        }
+        // Exact server filter and declared unique ascending order. Never use the
+        // deployment-wide recovery API. Overflow invalidates the whole collection.
+        const rows = [];
+        let cursor;
+        let complete = false;
+        try {
+            while (rows.length < 200) {
+                await env.assertCanInspect();
+                const page = await env.records.findMany({
+                    moduleId: spec.moduleId,
+                    collection: spec.collection,
+                    select: collection.readableFields,
+                    where: { guild_id: env.guildId },
+                    orderBy: [{ field: spec.key, direction: "asc" }],
+                    ...(cursor ? { cursor } : {}),
+                    limit: Math.min(50, 200 - rows.length),
+                });
+                if (page.records.length > Math.min(50, 200 - rows.length))
+                    throw new Error("Invalid bounded page");
+                for (const row of page.records) {
+                    if (row.guild_id !== env.guildId ||
+                        typeof row[spec.key] !== "string" ||
+                        !row[spec.key])
+                        throw new Error("Invalid scoped record");
+                    if (rows.some((existing) => existing[spec.key] === row[spec.key]))
+                        throw new Error("Repeated keyset page");
+                    rows.push(structuredClone(row));
+                }
+                if (!page.nextCursor) {
+                    complete = true;
+                    break;
+                }
+                if (!page.records.length ||
+                    diagnosticRecordSame(page.nextCursor, cursor))
+                    throw new Error("Nonadvancing keyset page");
+                cursor = page.nextCursor;
+            }
+        }
+        catch (error) {
+            if (error instanceof DiagnosticInterrupted ||
+                (error instanceof Error && error.name === "AbortError"))
+                throw error;
+            unavailable(`${spec.label} saved records could not be read completely. No records in this collection were repaired.`);
+            continue;
+        }
+        if (!complete) {
+            unavailable(`${spec.label} has more records than this run can safely check (200). No records in this collection were repaired.`);
+            continue;
+        }
+        if (!rows.length) {
+            probes.push({
+                id: `${spec.moduleId}.${spec.collection}.empty`,
+                moduleId: spec.moduleId,
+                label: `${spec.label} saved records`,
+                inspect: () => Promise.resolve(null),
+            });
+        }
+        for (const row of rows) {
+            const key = String(row[spec.key]);
+            if (!diagnosticRecordValid(spec, collection, row, env)) {
+                probes.push({
+                    id: `${spec.moduleId}.${spec.collection}.${key}.invalid`,
+                    moduleId: spec.moduleId,
+                    label: `${spec.label} saved record`,
+                    inspect: () => Promise.resolve({
+                        kind: "human",
+                        message: `${spec.label} has an invalid saved record. Review it in the dashboard; its content has been preserved.`,
+                    }),
+                });
+                continue;
+            }
+            if (spec.mode === "orphan") {
+                probes.push(diagnosticRecordProbe(env, spec, collection, row, "orphan"));
+            }
+            else {
+                // One lifecycle probe owns this row. Two probes with the same frozen
+                // revision would otherwise misreport our own verified cleanup as a
+                // concurrent edit during the final dependent recheck.
+                probes.push(diagnosticRecordProbe(env, spec, collection, row, row.cleanup_message_id || row.cleanup_channel_id
+                    ? "cleanup"
+                    : "delivery"));
+            }
+        }
+    }
+    return probes;
+}
+function diagnosticRecordProbe(env, spec, collection, initial, purpose) {
+    const key = String(initial[spec.key]);
+    const fixId = purpose === "orphan"
+        ? "message-embedder.orphan-cleanup-status"
+        : `${spec.mode === "sticky" ? "sticky" : "message-embedder"}.${purpose === "delivery" ? "dead-delivery-pointer" : "completed-cleanup-pointer"}`;
+    let expected;
+    let wrote = false;
+    const find = () => env.records.findOne({
+        moduleId: spec.moduleId,
+        collection: spec.collection,
+        select: collection.readableFields,
+        // Cleanup collection has an exact declared compound key; keep guild scope
+        // even though cleanup_id is globally unique.
+        where: purpose === "orphan"
+            ? {
+                guild_id: env.guildId,
+                channel_id: String(initial.channel_id),
+                message_id: String(initial.message_id),
+            }
+            : { guild_id: env.guildId, [spec.key]: key },
+    });
+    const applicable = (row) => {
+        if (purpose === "orphan")
+            return row.status === "pending";
+        if (purpose === "delivery")
+            return ((row.status === "active" ||
+                row.status ===
+                    (spec.mode === "sticky" ? "missing" : "message_missing")) &&
+                !row.cleanup_message_id &&
+                !row.cleanup_channel_id);
+        return ((spec.mode === "sticky"
+            ? row.status === "cleanup"
+            : row.status === "active" || row.status === "needs_attention") &&
+            !!row.cleanup_channel_id &&
+            !!row.cleanup_message_id);
+    };
+    const evidence = async (row) => {
+        if (purpose !== "cleanup") {
+            if (!row[spec.pointer])
+                return "present";
+            return env.inspectMessage(String(row.channel_id), String(row[spec.pointer]));
+        }
+        // Clearing a cleanup marker cannot make a missing replacement post healthy.
+        // Require fresh existence evidence for that replacement before status active.
+        if (!row[spec.pointer])
+            return "unknown";
+        if ((await env.inspectMessage(String(row.channel_id), String(row[spec.pointer]))) !== "present")
+            return "unknown";
+        return env.inspectMessage(String(row.cleanup_channel_id), String(row.cleanup_message_id));
+    };
+    const probe = {
+        id: `${fixId}:${key}`,
+        moduleId: spec.moduleId,
+        label: `${spec.label} ${purpose === "delivery" ? "message link" : "completed cleanup"}`,
+        async inspect() {
+            const row = await find();
+            if (!row)
+                return {
+                    kind: "incomplete",
+                    message: `${spec.label} changed during the check. Run /diag again.`,
+                };
+            if (!diagnosticRecordSame(row, initial))
+                return {
+                    kind: "incomplete",
+                    message: `${spec.label} changed during the check. Its newer settings were preserved.`,
+                };
+            // The paired cleanup probe owns this lifecycle and rechecks both messages.
+            // Do not leave an unrelated human warning after verified cleanup succeeds.
+            if (purpose === "delivery" &&
+                row.cleanup_channel_id &&
+                row.cleanup_message_id &&
+                (spec.mode === "sticky"
+                    ? row.status === "cleanup"
+                    : row.status === "active" || row.status === "needs_attention"))
+                return null;
+            if (!applicable(row)) {
+                if (row.status === "paused")
+                    return null;
+                return {
+                    kind: "human",
+                    message: `${spec.label} needs review or has work in progress. Use its dashboard controls; diagnostics will not reset that state.`,
+                };
+            }
+            if (purpose === "delivery" && !row[spec.pointer]) {
+                return {
+                    kind: "human",
+                    message: `${spec.label} has no published message. Use its dashboard repair or publish control.`,
+                };
+            }
+            const state = await evidence(row);
+            if (state === "unknown")
+                return {
+                    kind: "incomplete",
+                    message: `${spec.label} message access could not be confirmed. Check channel access and try again; nothing was removed.`,
+                };
+            if (state === "present") {
+                if (purpose === "orphan")
+                    return {
+                        kind: "human",
+                        message: `${spec.label} still has pending message cleanup. Its normal recovery process must complete it.`,
+                    };
+                if (purpose === "delivery" && row.status !== "active")
+                    return {
+                        kind: "human",
+                        message: `${spec.label} has a message but its saved status needs review. Use its dashboard controls.`,
+                    };
+                return null;
+            }
+            if (purpose === "orphan")
+                return {
+                    kind: "human",
+                    message: `${spec.label} retains a cleanup record for a deleted message. Its normal recovery process must finish removing that record; diagnostics leaves it unchanged.`,
+                };
+            return {
+                kind: "repairable",
+                message: purpose === "delivery"
+                    ? `${spec.label} points to a message Discord confirms was deleted.`
+                    : `${spec.label} retains cleanup state for a message Discord confirms was deleted.`,
+                evidence: { fixId, initial: structuredClone(row) },
+                ...(purpose === "delivery"
+                    ? {
+                        afterRepair: `${spec.label} message link was corrected. Use its dashboard repair or publish control to restore the message.`,
+                    }
+                    : {}),
+            };
+        },
+        async repair(round, issue) {
+            // Read-only orphan probes never expose this method. Keep a defensive
+            // guard here so later refactoring cannot accidentally enable deletion.
+            if (purpose === "orphan")
+                return "unchanged";
+            if (round === 1)
+                return "unchanged";
+            if (issue.evidence?.fixId !== fixId ||
+                !diagnosticRecordSame(issue.evidence.initial, initial))
+                return "stale";
+            const row = await find();
+            if (!row ||
+                !diagnosticRecordSame(row, initial) ||
+                !diagnosticRecordValid(spec, collection, row, env) ||
+                !applicable(row))
+                return "stale";
+            if ((await evidence(row)) !== "absent")
+                return "stale";
+            // Check authority, distributed lease, enabled/admitted module and frozen
+            // module/configuration versions immediately before the guarded write.
+            await env.assertCanMutate(spec.moduleId);
+            const values = {
+                revision: Number(row.revision) + 1,
+                updated_at: env.now(),
+                ...(spec.mode === "sticky"
+                    ? { generation: Number(row.generation) + 1 }
+                    : {}),
+                ...(purpose === "delivery"
+                    ? {
+                        [spec.pointer]: null,
+                        status: spec.mode === "sticky" ? "missing" : "message_missing",
+                    }
+                    : {
+                        cleanup_channel_id: null,
+                        cleanup_message_id: null,
+                        status: "active",
+                    }),
+            };
+            expected = { ...row, ...values };
+            const result = await env.records.updateOne({
+                moduleId: spec.moduleId,
+                collection: spec.collection,
+                where: { guild_id: env.guildId, [spec.key]: key },
+                expected: { field: "revision", value: row.revision },
+                requireModuleEnabledForGuildId: env.guildId,
+                values,
+                audit: diagnosticRecordAudit(env, spec, fixId, key, row),
+            });
+            wrote = result.updated;
+            return wrote ? "attempted" : "stale";
+        },
+        async verify() {
+            if (!wrote)
+                return false;
+            const fresh = await find();
+            if (!fresh || !expected || !diagnosticRecordSame(fresh, expected))
+                return false;
+            // Exact full-row comparison includes content, destination, authorship and
+            // every other readable protected field, not merely a successful SQL write.
+            return (await evidence(initial)) === "absent";
+        },
+    };
+    // SDK deleteOne cannot lock/recheck module enablement in its transaction.
+    // The guild record fence is unrelated to installation-state locks, so it
+    // cannot close that race. Orphan cleanup remains inspection-only.
+    return purpose === "orphan"
+        ? {
+            id: probe.id,
+            moduleId: spec.moduleId,
+            label: probe.label,
+            inspect: probe.inspect,
+        }
+        : probe;
+}
+function diagnosticRecordSchemaSupported(spec, collection) {
+    const required = [
+        spec.key,
+        "guild_id",
+        "channel_id",
+        spec.pointer,
+        "revision",
+        "status",
+        "created_at",
+        "updated_at",
+        ...(spec.mode === "orphan"
+            ? ["definition_id", "attempts"]
+            : [
+                "name",
+                "name_normalized",
+                "message_content",
+                "embeds_json",
+                "suppress_notifications",
+                "cleanup_channel_id",
+                "cleanup_message_id",
+            ]),
+        ...(spec.mode === "sticky" ? ["generation", "cooldown_seconds"] : []),
+    ];
+    return (!!collection.readableFields &&
+        !!collection.writableFields &&
+        !!collection.uniqueKeys &&
+        required.every((field) => collection.readableFields?.includes(field) &&
+            !!collection.fields[field]) &&
+        collection.orderKeys?.some((fields) => fields.length === 1 && fields[0] === spec.key) === true &&
+        collection.uniqueKeys.some((fields) => diagnosticRecordSame(fields, spec.mode === "orphan"
+            ? ["guild_id", "channel_id", "message_id"]
+            : ["guild_id", spec.key])) &&
+        (spec.mode === "orphan" ||
+            [
+                spec.pointer,
+                "status",
+                "revision",
+                "updated_at",
+                "cleanup_channel_id",
+                "cleanup_message_id",
+                ...(spec.mode === "sticky" ? ["generation"] : []),
+            ].every((field) => collection.writableFields?.includes(field))));
+}
+function diagnosticRecordValid(spec, collection, row, env) {
+    if (row.guild_id !== env.guildId ||
+        typeof row[spec.key] !== "string" ||
+        !row[spec.key])
+        return false;
+    for (const field of collection.readableFields) {
+        const declaration = collection.fields[field];
+        if (!declaration)
+            return false;
+        const value = row[field];
+        if (value === null || value === undefined) {
+            if (!declaration.optional)
+                return false;
+            continue;
+        }
+        if (declaration.type === "date") {
+            if (!(value instanceof Date) || Number.isNaN(value.getTime()))
+                return false;
+        }
+        else if (declaration.type === "json") {
+            if (typeof value !== "string")
+                return false;
+            try {
+                JSON.parse(value);
+            }
+            catch {
+                return false;
+            }
+        }
+        else if (typeof value !== declaration.type)
+            return false;
+    }
+    if (!Number.isSafeInteger(row.revision) ||
+        Number(row.revision) < 1 ||
+        Number(row.revision) >= Number.MAX_SAFE_INTEGER)
+        return false;
+    if (!/^\d{17,20}$/u.test(String(row.channel_id)))
+        return false;
+    for (const field of [
+        spec.pointer,
+        "cleanup_channel_id",
+        "cleanup_message_id",
+    ])
+        if (row[field] != null && !/^\d{17,20}$/u.test(String(row[field])))
+            return false;
+    if (spec.mode === "orphan")
+        return (Number.isSafeInteger(row.attempts) &&
+            Number(row.attempts) >= 0 &&
+            Number(row.attempts) < 10 &&
+            ["pending", "requires_review"].includes(String(row.status)));
+    if (spec.mode === "sticky" &&
+        (!Number.isSafeInteger(row.generation) ||
+            Number(row.generation) < 1 ||
+            Number(row.generation) >= Number.MAX_SAFE_INTEGER))
+        return false;
+    const states = spec.mode === "sticky"
+        ? ["active", "paused", "missing", "review", "cleanup"]
+        : [
+            "active",
+            "message_missing",
+            "needs_attention",
+            "publishing",
+            "deleting",
+        ];
+    if (!states.includes(String(row.status)))
+        return false;
+    if (!!row.cleanup_channel_id !== !!row.cleanup_message_id)
+        return false;
+    try {
+        const embeds = JSON.parse(String(row.embeds_json));
+        if (!Array.isArray(embeds))
+            return false;
+        env.services
+            .get(HELYX_SERVICE_NAMES.messageBuilder)
+            .buildRich({
+            ...(typeof row.message_content === "string"
+                ? { content: row.message_content }
+                : {}),
+            embeds: embeds,
+            suppressNotifications: row.suppress_notifications === true,
+        });
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function diagnosticRecordAudit(env, spec, fixId, key, row) {
+    return {
+        guildId: env.guildId,
+        actorUserId: env.actorUserId,
+        source: "discord",
+        action: "diagnostic.record_repaired",
+        correlationId: env.correlationId,
+        idempotencyKey: `diag:${env.correlationId}:${fixId}:${key}:${String(row.revision)}`,
+        targetType: spec.collection,
+        targetId: key,
+        metadata: { fixId, previousRevision: row.revision },
+    };
+}
+function diagnosticRecordSame(left, right) {
+    if (left instanceof Date || right instanceof Date)
+        return (left instanceof Date &&
+            right instanceof Date &&
+            left.getTime() === right.getTime());
+    if (left === null ||
+        right === null ||
+        typeof left !== "object" ||
+        typeof right !== "object")
+        return left === right;
+    if (Array.isArray(left) || Array.isArray(right))
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => diagnosticRecordSame(value, right[index])));
+    const leftRecord = left;
+    const rightRecord = right;
+    const keys = Object.keys(leftRecord);
+    return (keys.length === Object.keys(rightRecord).length &&
+        keys.every((key) => Object.hasOwn(rightRecord, key) &&
+            diagnosticRecordSame(leftRecord[key], rightRecord[key])));
+}
+function createNativeDiagnosticResources(client, guildId) {
+    const incomplete = (message) => ({
+        kind: "incomplete",
+        message,
+    });
+    const human = (message) => ({
+        kind: "human",
+        message,
+    });
+    const validId = (value) => /^\d{17,20}$/u.test(value);
+    const permissionName = (value) => value.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+    async function freshGuild() {
+        if (!validId(guildId))
+            throw new Error("Invalid diagnostic server scope");
+        const guild = await client.guilds.fetch({
+            guild: guildId,
+            force: true,
+            cache: true,
+        });
+        if (guild.id !== guildId)
+            throw new Error("Diagnostic server scope changed");
+        return guild;
+    }
+    async function freshMember(guild, userId) {
+        if (!validId(userId))
+            throw new Error("Invalid diagnostic member");
+        // Updating the role cache ensures newly assigned roles are represented by
+        // member.roles.cache. Only the returned fresh role collection grants bits.
+        const roles = await guild.roles.fetch(undefined, { cache: true });
+        const member = await guild.members.fetch({
+            user: userId,
+            force: true,
+            cache: false,
+        });
+        if (member.id !== userId || member.guild.id !== guildId)
+            throw new Error("Diagnostic member scope changed");
+        const membership = new Set(member.roles.cache.keys());
+        const currentRoles = [...roles.values()].filter((role) => role.id === guildId || membership.has(role.id));
+        const permissions = new PermissionsBitField(currentRoles.reduce((bits, role) => bits | role.permissions.bitfield, 0n));
+        return { member, roles, currentRoles, permissions, membership };
+    }
+    async function freshBot(guild) {
+        if (!client.user)
+            throw new Error("Diagnostic bot identity is unavailable");
+        return freshMember(guild, client.user.id);
+    }
+    // Compute from fresh member roles and freshly fetched channel overwrites,
+    // rather than a possibly stale member.permissions getter.
+    function channelPermissions(channel, bot) {
+        if (bot.member.id === channel.guild.ownerId ||
+            bot.permissions.has(PermissionFlagsBits.Administrator))
+            return new PermissionsBitField(PermissionsBitField.All);
+        let bits = bot.permissions.bitfield;
+        const everyone = channel.permissionOverwrites.cache.get(guildId);
+        if (everyone)
+            bits = (bits & ~everyone.deny.bitfield) | everyone.allow.bitfield;
+        let deny = 0n;
+        let allow = 0n;
+        for (const role of bot.currentRoles) {
+            if (role.id === guildId)
+                continue;
+            const overwrite = channel.permissionOverwrites.cache.get(role.id);
+            if (overwrite) {
+                deny |= overwrite.deny.bitfield;
+                allow |= overwrite.allow.bitfield;
+            }
+        }
+        bits = (bits & ~deny) | allow;
+        const member = channel.permissionOverwrites.cache.get(bot.member.id);
+        if (member)
+            bits = (bits & ~member.deny.bitfield) | member.allow.bitfield;
+        return new PermissionsBitField(bits);
+    }
+    async function freshChannel(channelId) {
+        if (!validId(channelId))
+            return null;
+        const channel = await client.channels.fetch(channelId, {
+            force: true,
+            cache: false,
+        });
+        if (!channel ||
+            channel.isDMBased() ||
+            !("guild" in channel) ||
+            channel.guild.id !== guildId)
+            return null;
+        return channel;
+    }
+    return {
+        async actor(userId) {
+            const guild = await freshGuild();
+            const current = await freshMember(guild, userId);
+            return {
+                userId,
+                roleIds: current.currentRoles.map((role) => role.id),
+                permissions: current.permissions.toArray().map(permissionName),
+                isServerOwner: guild.ownerId === userId,
+                isAdministrator: current.permissions.has(PermissionFlagsBits.Administrator),
+                highestRolePosition: Math.max(0, ...current.currentRoles.map((role) => role.position)),
+            };
+        },
+        async message(channelId, messageId) {
+            if (!validId(channelId) || !validId(messageId))
+                return "unknown";
+            try {
+                const guild = await freshGuild();
+                const bot = await freshBot(guild);
+                const channel = await freshChannel(channelId);
+                // A thread can require membership, parent access and archive handling;
+                // these checks never turn an unsupported thread into deletion evidence.
+                if (!channel ||
+                    (channel.type !== ChannelType.GuildText &&
+                        channel.type !== ChannelType.GuildAnnouncement))
+                    return "unknown";
+                const permissions = channelPermissions(channel, bot);
+                if (!permissions.has(PermissionFlagsBits.ViewChannel) ||
+                    !permissions.has(PermissionFlagsBits.ReadMessageHistory))
+                    return "unknown";
+                try {
+                    const message = await channel.messages.fetch({
+                        message: messageId,
+                        force: true,
+                        cache: false,
+                    });
+                    return message.id === messageId &&
+                        message.channelId === channelId &&
+                        // An uncached REST message need not carry guild_id. Its freshly
+                        // fetched channel above proves server ownership; a conflicting
+                        // non-null guild ID still fails closed.
+                        (message.guildId === null || message.guildId === guildId) &&
+                        message.author.id === client.user?.id
+                        ? "present"
+                        : "unknown";
+                }
+                catch (error) {
+                    // Only Discord's exact Unknown Message response, after successful
+                    // scoped channel/access checks, is evidence of absence.
+                    if (!(error instanceof DiscordAPIError) || error.code !== 10008)
+                        return "unknown";
+                    const currentGuild = await freshGuild();
+                    const currentBot = await freshBot(currentGuild);
+                    const currentChannel = await freshChannel(channelId);
+                    if (!currentChannel ||
+                        (currentChannel.type !== ChannelType.GuildText &&
+                            currentChannel.type !== ChannelType.GuildAnnouncement))
+                        return "unknown";
+                    const currentPermissions = channelPermissions(currentChannel, currentBot);
+                    return currentPermissions.has(PermissionFlagsBits.ViewChannel) &&
+                        currentPermissions.has(PermissionFlagsBits.ReadMessageHistory)
+                        ? "absent"
+                        : "unknown";
+                }
+            }
+            catch {
+                return "unknown";
+            }
+        },
+        async channel(channelId, types, requiredPermissions) {
+            try {
+                const guild = await freshGuild();
+                const bot = await freshBot(guild);
+                const channel = await freshChannel(channelId);
+                if (!channel)
+                    return incomplete("The configured channel could not be checked. Review its access and selection in Settings.");
+                if (channel.isThread())
+                    return incomplete("This channel check does not support threads. Review the channel selection in Settings.");
+                const type = channel.type === ChannelType.GuildText
+                    ? "guild_text"
+                    : channel.type === ChannelType.GuildAnnouncement
+                        ? "guild_announcement"
+                        : channel.type === ChannelType.GuildCategory
+                            ? "guild_category"
+                            : channel.type === ChannelType.GuildForum
+                                ? "guild_forum"
+                                : channel.type === ChannelType.GuildMedia
+                                    ? "guild_media"
+                                    : undefined;
+                if (!type)
+                    return incomplete("The selected channel type cannot be checked here. Review its selection in Settings.");
+                if (types.length && !types.includes(type))
+                    return human("The configured channel has the wrong type. Choose a supported channel in Settings.");
+                const permissions = channelPermissions(channel, bot);
+                if (!permissions.has(PermissionFlagsBits.ViewChannel))
+                    return human("Helyx cannot view the configured channel. Update its channel permissions.");
+                const known = new Set(Object.keys(PermissionFlagsBits).map(permissionName));
+                if (requiredPermissions.some((name) => !known.has(name)))
+                    return incomplete("A required channel permission could not be checked. Ask support to review the module requirements.");
+                const allowed = new Set(permissions.toArray().map(permissionName));
+                if (requiredPermissions.some((name) => !allowed.has(name)))
+                    return human("Helyx is missing a required channel permission. Review the module's Permissions guide.");
+                return null;
+            }
+            catch {
+                return incomplete("The configured channel could not be checked. Retry later or review Helyx's access.");
+            }
+        },
+        async role(roleId, managed) {
+            if (!validId(roleId))
+                return incomplete("The configured role could not be checked. Review its selection in Settings.");
+            try {
+                const guild = await freshGuild();
+                const bot = await freshBot(guild);
+                const role = bot.roles.get(roleId);
+                if (!role)
+                    return human("The configured role no longer exists. Choose a role in Settings.");
+                if (role.guild.id !== guildId)
+                    return incomplete("The configured role does not belong to this server.");
+                if (!managed)
+                    return null;
+                if (role.id === guildId || role.managed)
+                    return human("Helyx cannot assign the selected role. Choose a role that is not managed by Discord or another integration.");
+                if (!bot.permissions.has(PermissionFlagsBits.ManageRoles))
+                    return human("Helyx needs Manage Roles to use the configured role.");
+                const highest = bot.currentRoles.reduce((selected, current) => !selected || current.comparePositionTo(selected) > 0
+                    ? current
+                    : selected, undefined);
+                if (!highest || role.comparePositionTo(highest) >= 0)
+                    return human("Move Helyx's highest role above the configured role in Discord's role list.");
+                return null;
+            }
+            catch {
+                return incomplete("The configured role could not be checked. Retry later or review Helyx's role access.");
+            }
+        },
+        capabilities() {
+            return {
+                guildMembers: client.options.intents.has(GatewayIntentBits.GuildMembers),
+                messageContent: client.options.intents.has(GatewayIntentBits.MessageContent),
+            };
+        },
+        async guildCommands() {
+            if (!validId(guildId) || !client.application?.id)
+                throw new Error("Diagnostic command observation is unavailable");
+            const observed = await client.rest.get(Routes.applicationGuildCommands(client.application.id, guildId));
+            const isCommand = (value) => {
+                if (typeof value !== "object" ||
+                    value === null ||
+                    Array.isArray(value) ||
+                    !("name" in value) ||
+                    typeof value.name !== "string")
+                    return false;
+                if (("id" in value && typeof value.id !== "string") ||
+                    ("application_id" in value &&
+                        typeof value.application_id !== "string") ||
+                    ("guild_id" in value && typeof value.guild_id !== "string") ||
+                    ("version" in value && typeof value.version !== "string"))
+                    return false;
+                return ((!("type" in value) || typeof value.type === "number") &&
+                    (!("guild_id" in value) || value.guild_id === guildId) &&
+                    (!("application_id" in value) ||
+                        value.application_id === client.application?.id));
+            };
+            if (!Array.isArray(observed) || !observed.every(isCommand))
+                throw new Error("Discord returned an invalid command observation");
+            return {
+                definitionHash: guildCommandDefinitionHash(observed),
+                rootCount: observed.length,
+            };
+        },
+    };
+}
+const DIAGNOSTIC_APPROVED_RECORD_MODULES = new Set([
+    "helyx.sticky-messages",
+    "helyx.message-embedder",
+]);
+const DIAGNOSTIC_WRITE_CHANNEL_SETTINGS = new Set([
+    "helyx.welcome:channelId",
+    "helyx.birthdays:announcementChannelId",
+    "helyx.levels:announcementChannelId",
+    "helyx.starboard:destinationChannelId",
+    "helyx.suggestions:channelId",
+    "helyx.feedback:channelId",
+    "helyx.feedback:panelChannelId",
+    "helyx.logging:channelId",
+]);
+function diagnosticSettingValue(value, path) {
+    // Prefer an explicitly stored key, then support nested configuration paths.
+    if (Object.hasOwn(value, path))
+        return value[path];
+    let current = value;
+    for (const key of path.split(".")) {
+        if (typeof current !== "object" ||
+            current === null ||
+            !Object.hasOwn(current, key))
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+function diagnosticSettingVisible(setting, settings, value, seen = new Set()) {
+    const condition = setting.visibleWhen;
+    if (!condition)
+        return true;
+    if (seen.has(setting.key))
+        return false;
+    seen.add(setting.key);
+    const parent = settings.find((candidate) => candidate.key === condition.field);
+    if (parent && !diagnosticSettingVisible(parent, settings, value, seen))
+        return false;
+    const stored = diagnosticSettingValue(value, condition.field);
+    const actual = stored === undefined && parent && "default" in parent
+        ? parent.default
+        : stored;
+    return actual === condition.equals;
+}
+function diagnosticActiveResourceSetting(moduleId, setting, settings, value) {
+    if (!diagnosticSettingVisible(setting, settings, value))
+        return false;
+    // Levels predates visibleWhen for milestones. Unused or disabled milestone
+    // roles must not generate errors or acquire additional Discord permissions.
+    if (moduleId === "helyx.levels") {
+        const reward = /^rewardRole([1-9]|10)$/u.exec(setting.key);
+        if (reward) {
+            const milestone = Number(reward[1]);
+            const count = diagnosticSettingValue(value, "rewardMilestoneCount") ?? 5;
+            if (typeof count !== "number" || milestone > count)
+                return false;
+            return (diagnosticSettingValue(value, `rewardRoleMode${milestone}`) ===
+                "existing");
+        }
+    }
+    return true;
+}
+function diagnosticReadConfiguration(entry) {
+    const saved = structuredClone(entry.configuration?.value ?? {});
+    // validate is the pure schema parser. Never invoke validateUpdate,
+    // validateActivation, lifecycle, managed-resource or recovery hooks here.
+    return entry.module.configuration?.validate(saved) ?? saved;
+}
+function moduleProbes(entry, services, guildId, resources) {
+    const module = entry.module;
+    const moduleId = module.manifest.id;
+    const name = module.manifest.name;
+    const settings = module.manifest.dashboard?.settings ?? [];
+    const probes = [];
+    const add = (id, label, inspect) => {
+        probes.push({
+            id: `${moduleId}.${id}`,
+            moduleId,
+            label: `${name} ${label}`,
+            inspect: async () => {
+                const current = await services
+                    .get(HELYX_SERVICE_NAMES.configuration)
+                    .get(guildId, moduleId);
+                if (!sameConfiguration(current, entry.configuration))
+                    return {
+                        kind: "human",
+                        message: `${name} settings changed during this run. Run /diag again to check the newer setup.`,
+                    };
+                return inspect();
+            },
+        });
+    };
+    add("availability", "availability", async () => {
+        if (!services.has(HELYX_SERVICE_NAMES.moduleAvailability)) {
+            return {
+                kind: "incomplete",
+                message: `${name} availability could not be checked.`,
+            };
+        }
+        if (!(await services
+            .get(HELYX_SERVICE_NAMES.moduleAvailability)
+            .isAvailable(moduleId))) {
+            return {
+                kind: "human",
+                message: `${name} is currently unavailable. Ask the operator to review its availability.`,
+            };
+        }
+        return null;
+    });
+    add("entitlement", "access", async () => (await canAccessModule(services, guildId, module))
+        ? null
+        : {
+            kind: "human",
+            message: `${name} needs Premium access assigned to this server. Review Billing or use /activate.`,
+        });
+    if (module.configuration) {
+        add("configuration", "settings", () => {
+            if (entry.configuration &&
+                entry.configuration.schemaVersion !==
+                    module.configuration.schemaVersion) {
+                return {
+                    kind: "incomplete",
+                    message: `${name} settings use a different version. Ask the operator to check module updates.`,
+                };
+            }
+            try {
+                diagnosticReadConfiguration(entry);
+            }
+            catch {
+                return {
+                    kind: "human",
+                    message: `${name} has missing or invalid settings. Open its Settings page and save corrected values.`,
+                };
+            }
+            return null;
+        });
+    }
+    const required = new Set(module.requiredDiscordCapabilities ?? []);
+    for (const capability of required) {
+        add(`capability.${capability}`, "Discord access", () => {
+            const available = resources.capabilities();
+            const enabled = capability === "guild-members"
+                ? available.guildMembers
+                : available.messageContent;
+            return enabled
+                ? null
+                : {
+                    kind: "human",
+                    message: `${name} needs the ${capability === "guild-members" ? "Server Members" : "Message Content"} intent. Ask the bot operator to enable it in Discord and the bot configuration.`,
+                };
+        });
+    }
+    for (const setting of settings) {
+        // Selected options can require an intent even when the entire module does
+        // not. Do not treat an inactive option as an active Discord requirement.
+        if (setting.type === "select" &&
+            setting.options.some((option) => option.requiredDiscordCapability)) {
+            add(`setting-capability.${setting.key}`, setting.label, () => {
+                let value;
+                try {
+                    value = diagnosticReadConfiguration(entry);
+                }
+                catch {
+                    return {
+                        kind: "incomplete",
+                        message: `${name} option access could not be checked until its settings are corrected.`,
+                    };
+                }
+                if (!diagnosticSettingVisible(setting, settings, value))
+                    return null;
+                const selected = diagnosticSettingValue(value, setting.key) ?? setting.default;
+                const capability = setting.options.find((option) => option.value === selected)?.requiredDiscordCapability;
+                if (capability === "message-content" &&
+                    !resources.capabilities().messageContent) {
+                    return {
+                        kind: "human",
+                        message: `${name} ${setting.label} needs Message Content access. Change that option or ask the bot operator to enable the intent.`,
+                    };
+                }
+                return null;
+            });
+        }
+        if (setting.type !== "discord-channel" && setting.type !== "discord-role")
+            continue;
+        add(`resource.${setting.key}`, setting.label, async () => {
+            if (module.configuration &&
+                entry.configuration &&
+                entry.configuration.schemaVersion !== module.configuration.schemaVersion) {
+                return {
+                    kind: "incomplete",
+                    message: `${name} configured channels and roles need compatible settings before they can be checked.`,
+                };
+            }
+            let value;
+            try {
+                value = diagnosticReadConfiguration(entry);
+            }
+            catch {
+                return {
+                    kind: "incomplete",
+                    message: `${name} configured channels and roles could not be checked until its settings are corrected.`,
+                };
+            }
+            if (!diagnosticActiveResourceSetting(moduleId, setting, settings, value))
+                return null;
+            const selected = diagnosticSettingValue(value, setting.key);
+            const ids = selected === "" || selected === null || selected === undefined
+                ? []
+                : Array.isArray(selected)
+                    ? selected
+                    : [selected];
+            if (!ids.length)
+                return setting.required || (setting.minItems ?? 0) > 0
+                    ? {
+                        kind: "human",
+                        message: `${name} needs a value for ${setting.label}. Choose it in Settings.`,
+                    }
+                    : null;
+            if (ids.length > 100)
+                return {
+                    kind: "incomplete",
+                    message: `${name} has too many configured resources for this check. Review its Settings.`,
+                };
+            if (ids.some((id) => typeof id !== "string" || !/^\d{17,20}$/u.test(id))) {
+                return {
+                    kind: "human",
+                    message: `${name} ${setting.label} contains an invalid Discord selection. Choose it again in Settings.`,
+                };
+            }
+            for (const id of ids) {
+                const issue = setting.type === "discord-channel"
+                    ? await resources.channel(id, setting.channelTypes, DIAGNOSTIC_WRITE_CHANNEL_SETTINGS.has(`${moduleId}:${setting.key}`)
+                        ? ["VIEW_CHANNEL", "SEND_MESSAGES"]
+                        : ["VIEW_CHANNEL"])
+                    : await resources.role(id, (moduleId === "helyx.welcome" && setting.key === "roleId") ||
+                        (moduleId === "helyx.levels" &&
+                            /^rewardRole([1-9]|10)$/u.test(setting.key)));
+                if (issue)
+                    return issue;
+            }
+            return null;
+        });
+    }
+    if (entry.customer &&
+        Object.keys(module.records ?? {}).length > 0 &&
+        !DIAGNOSTIC_APPROVED_RECORD_MODULES.has(moduleId)) {
+        add("record-coverage", "saved data", () => ({
+            kind: "incomplete",
+            message: `${name} saved-record checks are not supported by this version of /diag. Its stored data was left unchanged.`,
+        }));
+    }
+    // health() has no guild argument. Current hooks include cross-server failure
+    // trackers or external provider checks; none are approved server-only probes.
+    // Do not invoke them or turn an unrelated server's failure into this report.
+    return probes;
+}
+//# sourceMappingURL=diagnostic-command.js.map