@helyx/bot 1.5.2 → 1.5.3

package/dist/guilds.d.ts

@@ -3,6 +3,7 @@ import type { MysqlPool } from "@helyx/database-mysql";
 import type { ModuleDefinition } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import type { InteractionLogger } from "./interactions.js";
+import type { MessageProtectionGuildObserver } from "./message-protection-coordinator.js";
 import type { HostedBotInviteGate, HostedGuildOwnerObserver, HostedGuildSafety } from "./hosted-server-moderation.js";
 export interface GuildReconciliationHealth {
     status: "pending" | "running" | "healthy" | "failed" | "stopped";
@@ -42,6 +43,6 @@ export interface GuildTrackingPersistence extends ReconciliationRepository {
     markGuildRemoved(guildId: string, ownership: GuildShardOwnership | undefined, applicationId: string | undefined): Promise<boolean>;
 }
 export declare function createMysqlGuildTrackingPersistence(database: MysqlPool): Promise<GuildTrackingPersistence>;
-export declare function installGuildTracking(client: Client, database: DatabasePool | GuildTrackingPersistence, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number, applicationId?: string, hostedSafety?: HostedGuildSafety, hostedInviteGate?: HostedBotInviteGate, hostedOwnerObserver?: HostedGuildOwnerObserver | undefined): GuildTrackingPreparation;
+export declare function installGuildTracking(client: Client, database: DatabasePool | GuildTrackingPersistence, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number, applicationId?: string, hostedSafety?: HostedGuildSafety, hostedInviteGate?: HostedBotInviteGate, hostedOwnerObserver?: HostedGuildOwnerObserver | undefined, protectionObserver?: MessageProtectionGuildObserver): GuildTrackingPreparation;
 export {};
 //# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -105,7 +105,7 @@ export async function createMysqlGuildTrackingPersistence(database) {
         },
     };
 }
-export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount, applicationId, hostedSafety, hostedInviteGate, hostedOwnerObserver = hostedSafety) {
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount, applicationId, hostedSafety, hostedInviteGate, hostedOwnerObserver = hostedSafety, protectionObserver) {
     if (!Number.isSafeInteger(reconciliationIntervalMs) ||
         reconciliationIntervalMs < 60_000)
         throw new Error("Guild reconciliation interval must be at least one minute");
@@ -140,6 +140,7 @@ export function installGuildTracking(client, database, modules, logger, enabledB
         return operation;
     }
     async function syncGuild(guild, firstObservation = false) {
+        const accepted = protectionObserver?.beforeSync(guild);
         const cachedOwner = guild.members?.cache.get(guild.ownerId)?.user ??
             guild.client?.users.cache.get(guild.ownerId);
         await persistence.syncGuild({
@@ -156,6 +157,7 @@ export function installGuildTracking(client, database, modules, logger, enabledB
         });
         if (stopped)
             return;
+        accepted?.();
         if (cachedOwner && hostedOwnerObserver)
             await hostedOwnerObserver.observeOwner(guild);
         else
@@ -260,6 +262,7 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.GuildDelete, (guild) => {
         if (stopped)
             return;
+        protectionObserver?.invalidateGuild(guild.id);
         const retry = admissionRetries.get(guild.id);
         if (retry)
             clearTimeout(retry);
@@ -281,11 +284,13 @@ export function installGuildTracking(client, database, modules, logger, enabledB
         });
     });
     client.on(Events.GuildUnavailable, (guild) => {
+        protectionObserver?.invalidateGuild(guild.id);
         logger.warn({ event: "guild.unavailable", guildId: guild.id }, "Discord guild is temporarily unavailable; installation remains active");
     });
     async function runReconciliation(reason) {
         if (stopped || !prepared || !client.isReady())
             return;
+        protectionObserver?.ready();
         if (reconciliation)
             return reconciliation;
         reconciliation = (async () => {
@@ -423,12 +428,17 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.ShardResume, () => {
         void runReconciliation("resume");
     });
+    if (protectionObserver) {
+        client.on(Events.ShardDisconnect, () => protectionObserver.invalidateAll());
+        client.on(Events.ShardReconnecting, () => protectionObserver.invalidateAll());
+    }
     prepare.reconcile = runReconciliation;
     prepare.health = () => ({ ...health });
     prepare.stop = () => {
         if (stopPromise)
             return stopPromise;
         stopped = true;
+        protectionObserver?.invalidateAll();
         if (timer)
             clearInterval(timer);
         timer = undefined;

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

@@ -10,9 +10,9 @@ declare const resultSchema: z.ZodObject<{
         blacklist: "blacklist";
     }>;
     outcome: z.ZodEnum<{
+        failed: "failed";
         completed: "completed";
         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" | "requires_review" | "failed" | "queued" | "not_currently_installed" | "accepted_for_retry" | "already_blacklisted";
+        outcome: "failed" | "completed" | "requires_review" | "queued" | "not_currently_installed" | "accepted_for_retry" | "already_blacklisted";
         paidSlotsReleased: number;
     }>;
 }

package/dist/index.js

@@ -1,11 +1,12 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { StatusHeartbeatReporter } from "@helyx/status-client";
+import { admitStandaloneCommandPolicy, } from "./command-policy-runtime.js";
 import { safeError, ServiceRegistry } from "@helyx/core";
 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";
-import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createPlatformServices, createPostgresCommandRestrictionRecovery, createMysqlCommandRestrictionRecovery, createPostgresNexusCommandRecovery, createMysqlNexusCommandRecovery, createPostgresCommandCatalogueRecovery, createMysqlCommandCatalogueRecovery, createPostgresCommandPolicyDelivery, createMysqlCommandPolicyDelivery, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
+import { HELYX_SERVICE_NAMES, collectReservedCommandNames, } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
 import { randomUUID } from "node:crypto";
@@ -15,6 +16,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { ClientCloudDiscordDirectory, CloudConnectorController, } from "./cloud-connector.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { installInteractions } from "./interactions.js";
+import { loadBundledCommandCatalogue } from "./command-root-catalogue.js";
 import { installGuildTracking } from "./guilds.js";
 import { assertConfiguredModuleDatabaseCompatibility, loadConfiguredModulePackages, platformServiceOptions, } from "./modules.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
@@ -150,6 +152,8 @@ function assertNoPendingMigrations(scope, pending) {
 }
 async function startUnshardedBot(processEnvironment) {
     const environment = parseBotEnvironment(processEnvironment);
+    const unshardedSupervisorId = randomUUID();
+    let commandPolicyRuntime;
     const mysqlModulePackages = environment.DATABASE_ENGINE === "mysql"
         ? await loadConfiguredModulePackages(await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH, environment.HELYX_RUNTIME_PROFILE))
         : undefined;
@@ -157,6 +161,19 @@ async function startUnshardedBot(processEnvironment) {
         ? await openMysqlBotRuntimePersistence({
             environment,
             modulePackages: mysqlModulePackages,
+            ...(environment.HELYX_RUNTIME_PROFILE === "self-hosted"
+                ? {
+                    onCoreReady: async (pool) => {
+                        commandPolicyRuntime = await admitStandaloneCommandPolicy(createMysqlCommandPolicyDelivery(pool, {
+                            applicationId: environment.DISCORD_CLIENT_ID,
+                            scope: {
+                                mode: "standalone",
+                                instanceId: unshardedSupervisorId,
+                            },
+                        }));
+                    },
+                }
+                : {}),
         })
         : undefined;
     const database = mysql
@@ -220,6 +237,11 @@ async function startUnshardedBot(processEnvironment) {
                 ? await inspectRequiredCoreMigrations(database)
                 : await runCoreMigrations(database)
             : mysql.database.migrations.core;
+        if (database && environment.HELYX_RUNTIME_PROFILE === "self-hosted")
+            commandPolicyRuntime = await admitStandaloneCommandPolicy(createPostgresCommandPolicyDelivery(database, {
+                applicationId: environment.DISCORD_CLIENT_ID,
+                scope: { mode: "standalone", instanceId: unshardedSupervisorId },
+            }));
         bootstrapLogger.info({
             event: "database.ready",
             appliedMigrations: migrationResult.applied,
@@ -302,6 +324,8 @@ async function startUnshardedBot(processEnvironment) {
             coreVersion: readBotVersion(),
             logger: bootstrapLogger,
         });
+        if (commandPolicyRuntime)
+            await cloudConnector.setCommandPolicyDelivery(commandPolicyRuntime);
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
         const diagnosticInstallations = mysql
@@ -363,7 +387,6 @@ async function startUnshardedBot(processEnvironment) {
         ];
         let scheduledTasks;
         let guildCommandWorker;
-        const unshardedSupervisorId = randomUUID();
         const deployedCommit = deploymentReference(processEnvironment);
         const buildHealth = async () => {
             let databaseHealthy = true;
@@ -454,9 +477,21 @@ async function startUnshardedBot(processEnvironment) {
             ...publicModules,
             ...(operationsModule ? [operationsModule] : []),
         ];
+        const commandCatalogue = modules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+            ? mysql
+                ? createMysqlCommandCatalogueRecovery(mysql.pool, environment.DISCORD_CLIENT_ID)
+                : createPostgresCommandCatalogueRecovery(database, environment.DISCORD_CLIENT_ID)
+            : undefined;
+        if (commandCatalogue)
+            await commandCatalogue.publish(await loadBundledCommandCatalogue());
         const platformServices = new Map();
         const serviceAccess = new ServiceRegistry(platformServices);
-        const serviceOptions = platformServiceOptions(environment, publicModules);
+        const serviceOptions = {
+            ...platformServiceOptions(environment, publicModules),
+            ...(commandPolicyRuntime
+                ? { commandPolicyDeliveryScope: commandPolicyRuntime.owner.scope }
+                : {}),
+        };
         const platformFactory = mysql
             ? mysql.createPlatformServices(publicModules, {
                 ...serviceOptions,
@@ -575,6 +610,7 @@ async function startUnshardedBot(processEnvironment) {
             : undefined;
         const commandsReady = installInteractions(client, modules, {
             globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
+            resolveGuildCommandName: (input) => guildCommandReads.resolveInteractionCommand(input),
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
                 : {}),
@@ -719,6 +755,17 @@ async function startUnshardedBot(processEnvironment) {
             });
             scheduledTasks.start();
             guildCommandWorker = new GuildCommandWorker({
+                ...(commandPolicyRuntime
+                    ? { commandPolicyDelivery: commandPolicyRuntime.delivery }
+                    : {}),
+                ...(commandCatalogue ? { commandCatalogue } : {}),
+                ...(modules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                    ? {
+                        commandRestrictions: mysql
+                            ? createMysqlCommandRestrictionRecovery(mysql.pool, environment.DISCORD_CLIENT_ID)
+                            : createPostgresCommandRestrictionRecovery(database, environment.DISCORD_CLIENT_ID),
+                    }
+                    : {}),
                 ...(mysql
                     ? { repositories: mysql.commandWorker }
                     : { database: database }),
@@ -778,6 +825,22 @@ async function startUnshardedBot(processEnvironment) {
                     : undefined;
                 controlServer = await createBotControlServer({
                     service: controlService,
+                    ...(environment.HELYX_RUNTIME_PROFILE === "hosted" &&
+                        modules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                        ? {
+                            nexusCommandRecovery: mysql
+                                ? createMysqlNexusCommandRecovery(mysql.pool, {
+                                    applicationId: environment.DISCORD_CLIENT_ID,
+                                    persistedCommandCatalogue: true,
+                                    reservedCommandNames: collectReservedCommandNames(modules),
+                                })
+                                : createPostgresNexusCommandRecovery(database, {
+                                    applicationId: environment.DISCORD_CLIENT_ID,
+                                    persistedCommandCatalogue: true,
+                                    reservedCommandNames: collectReservedCommandNames(modules),
+                                }),
+                        }
+                        : {}),
                     secret: environment.HELYX_BOT_CONTROL_SECRET,
                     ...(hostedLeaveWorker && hostedOwnerObserver
                         ? {
@@ -893,6 +956,7 @@ export function gatewayIntentsForModules(modules, messageContentEnabled = false,
         messageContentEnabled) ||
         modules.some((module) => module.events?.guildMessageCreate?.length ||
             module.events?.guildMessageUpdate?.length ||
+            module.events?.guildMessageUpdateMetadata?.length ||
             module.events?.messageDelete?.length ||
             module.events?.guildMessageDeleteBulk?.length)) {
         intents.push(GatewayIntentBits.GuildMessages);

package/dist/interactions.d.ts

@@ -1,6 +1,7 @@
 import type { CommandAutocompleteContext, CommandAuthorization, CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
 import { type GlobalCommandRegistrationMode } from "./command-registration-policy.js";
 import { ModalBuilder, type AutocompleteInteraction, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+import type { GuildCommandInteractionRoute } from "./guild-command-read-service.js";
 export declare const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
 export declare const AUTOCOMPLETE_RESPONSE_DEADLINE_MS = 2000;
 export declare const DISCORD_DNS_REFRESH_INTERVAL_MS = 30000;
@@ -16,6 +17,7 @@ export interface CommandRegistration {
     synchroniseInternalGuild?: boolean;
     globalCommandMode?: GlobalCommandRegistrationMode;
     selfAuthorizingGuildModuleIds?: ReadonlySet<string>;
+    resolveGuildCommandName?(input: GuildCommandInteractionRoute): Promise<string | null>;
 }
 export declare function installInteractions(client: Client, modules: readonly ModuleDefinition[], registration: CommandRegistration, logger: InteractionLogger, services: ServiceAccess): Promise<void>;
 export declare function warmDiscordRestConnection(client: Client<true>, logger: InteractionLogger): Promise<void>;
@@ -44,5 +46,5 @@ export declare function normalizeDiscordPermission(permission: string): string;
 export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
 export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;
 export declare function toModal(definition: ModalDefinition): ModalBuilder;
-export declare function safeInteractionFailureMessage(error: unknown): string;
+export declare function safeInteractionFailureMessage(error: unknown, nexusRoot?: string | null): string;
 //# sourceMappingURL=interactions.d.ts.map

package/dist/interactions.js

@@ -1,5 +1,7 @@
 import { lookup as lookupDns } from "node:dns/promises";
-import { HELYX_SERVICE_NAMES, NexusEconomyError, UserFacingInteractionError, } from "@helyx/sdk";
+import { HELYX_SERVICE_NAMES, formatNexusCommandReference, NexusEconomyError, UserFacingInteractionError, } from "@helyx/sdk";
+import { nexusObservedRoot } from "./nexus-command-references.js";
+import { snapshotMemberRoleIds } from "./member-role-ids.js";
 import { canUseCommand, safeError } from "@helyx/core";
 import { commandRegistrationPolicy, contributionRegistrationPolicy, } from "./command-registration-policy.js";
 import { ActionRowBuilder, ButtonBuilder, ButtonStyle, ChannelSelectMenuBuilder, EmbedBuilder, Events, GuildMember, ApplicationIntegrationType, ChannelType, InteractionContextType, LabelBuilder, MessageFlags, MentionableSelectMenuBuilder, ModalBuilder, RoleSelectMenuBuilder, Routes, StringSelectMenuBuilder, SlashCommandBuilder, TextInputBuilder, TextInputStyle, UserSelectMenuBuilder, TextDisplayBuilder, PermissionFlagsBits, escapeMarkdown, } from "discord.js";
@@ -92,12 +94,44 @@ export function installInteractions(client, modules, registration, logger, servi
     client.on(Events.InteractionCreate, (interaction) => {
         void handleInteraction(interaction);
     });
+    function requiresGuildRootResolution(interaction) {
+        // Only known non-Nexus application globals are independent of guild root
+        // mappings. A newly loaded guild root can collide with an old observation.
+        return Boolean(registration.resolveGuildCommandName &&
+            (interaction.commandName === "nexus" ||
+                !commands.has(interaction.commandName) ||
+                interaction.commandGuildId !== null));
+    }
+    async function resolveRegisteredCommand(interaction) {
+        if (!registration.resolveGuildCommandName)
+            return commands.get(interaction.commandName);
+        try {
+            const canonicalName = await registration.resolveGuildCommandName({
+                applicationId: interaction.applicationId,
+                guildId: interaction.guildId,
+                commandGuildId: interaction.commandGuildId,
+                commandId: interaction.commandId,
+                commandName: interaction.commandName,
+            });
+            return canonicalName === null ? undefined : commands.get(canonicalName);
+        }
+        catch (error) {
+            logger.warn({
+                event: "interaction.command_route_unavailable",
+                ...interactionLogContext(interaction),
+                error: safeError(error),
+            }, "Observed guild command routing is unavailable");
+            return undefined;
+        }
+    }
     async function handleInteraction(interaction) {
         try {
             if (interaction.isAutocomplete()) {
                 const response = createAutocompleteResponseController(interaction, logger);
                 try {
-                    const registered = commands.get(interaction.commandName);
+                    const registered = requiresGuildRootResolution(interaction)
+                        ? await resolveRegisteredCommand(interaction)
+                        : commands.get(interaction.commandName);
                     const groupName = registered?.contribution.subcommandGroups?.length
                         ? interaction.options.getSubcommandGroup(false)
                         : null;
@@ -136,7 +170,9 @@ export function installInteractions(client, modules, registration, logger, servi
                 return;
             }
             else if (interaction.isChatInputCommand()) {
-                const registered = commands.get(interaction.commandName);
+                const registered = requiresGuildRootResolution(interaction)
+                    ? await resolveRegisteredCommand(interaction)
+                    : commands.get(interaction.commandName);
                 if (!registered) {
                     logger.warn({
                         event: "interaction.stale_command",
@@ -277,7 +313,7 @@ export function installInteractions(client, modules, registration, logger, servi
                 ...interactionLogContext(interaction),
                 error: safeError(error),
             }, "Module interaction failed");
-            await sendFailure(interaction, error);
+            await sendFailure(interaction, error, services);
         }
     }
     return registrationReady;
@@ -580,7 +616,13 @@ function createContext(interaction, services) {
         userId: interaction.user.id,
         userDisplayName: interaction.user.globalName ?? interaction.user.username,
         userRoleIds: interaction.member instanceof GuildMember
-            ? [...interaction.member.roles.cache.keys()]
+            ? snapshotMemberRoleIds({
+                member: interaction.member,
+                client: interaction.client,
+                guild: interaction.guild,
+                guildId: interaction.guildId,
+                actorUserId: interaction.user.id,
+            })
             : (interaction.member?.roles ?? []),
         ...(interaction.member instanceof GuildMember
             ? { userHighestRolePosition: interaction.member.roles.highest.position }
@@ -749,7 +791,13 @@ function createModalContext(interaction, services) {
         userId: interaction.user.id,
         userDisplayName: interaction.user.globalName ?? interaction.user.username,
         userRoleIds: interaction.member instanceof GuildMember
-            ? [...interaction.member.roles.cache.keys()]
+            ? snapshotMemberRoleIds({
+                member: interaction.member,
+                client: interaction.client,
+                guild: interaction.guild,
+                guildId: interaction.guildId,
+                actorUserId: interaction.user.id,
+            })
             : (interaction.member?.roles ?? []),
         ...(interaction.member instanceof GuildMember
             ? { userHighestRolePosition: interaction.member.roles.highest.position }
@@ -1012,7 +1060,13 @@ function permissionActor(interaction) {
     return {
         userId: interaction.user.id,
         roleIds: interaction.member instanceof GuildMember
-            ? [...interaction.member.roles.cache.keys()]
+            ? snapshotMemberRoleIds({
+                member: interaction.member,
+                client: interaction.client,
+                guild: interaction.guild,
+                guildId: interaction.guildId,
+                actorUserId: interaction.user.id,
+            })
             : (interaction.member?.roles ?? []),
         permissions: interaction.memberPermissions
             ?.toArray()
@@ -1346,15 +1400,19 @@ function discordChannelType(type) {
         return ChannelType.GuildMedia;
     return ChannelType.GuildText;
 }
-export function safeInteractionFailureMessage(error) {
+export function safeInteractionFailureMessage(error, nexusRoot = "nexus") {
     if (error instanceof UserFacingInteractionError) {
+        const redeem = formatNexusCommandReference(nexusRoot, "redeem", true);
+        const reopen = redeem
+            ? `Run ${redeem} again.`
+            : "Reopen the redeem command from Discord's command picker.";
         const messages = {
             nexus_exchange_slow: "The Exchange is taking too long to respond. Try again shortly.",
             nexus_exchange_item_unavailable: "That Exchange item is not available to you right now.",
             nexus_exchange_item_changed: "That Exchange item changed or is no longer available. Start again.",
             nexus_exchange_balance_changed: "Your Nexus balance changed after the preview. Start again.",
-            nexus_exchange_form_expired: "This request form expired. Run /nexus redeem again.",
-            nexus_exchange_form_replayed: "This request form was already submitted. Run /nexus redeem again.",
+            nexus_exchange_form_expired: `This request form expired. ${reopen}`,
+            nexus_exchange_form_replayed: `This request form was already submitted. ${reopen}`,
             nexus_exchange_preview_expired: "This redemption preview expired. Start the command again.",
             nexus_exchange_invalid_request: "This Exchange request is invalid. Start the command again.",
             nexus_exchange_response_required: "This custom request needs a response.",
@@ -1380,14 +1438,21 @@ export function safeInteractionFailureMessage(error) {
     }
     return "Something went wrong while handling that interaction.";
 }
-async function sendFailure(interaction, error) {
+async function sendFailure(interaction, error, services) {
     if (interaction.isAutocomplete()) {
         await interaction.respond([]).catch(() => undefined);
         return;
     }
     if (!interaction.isRepliable())
         return;
-    const message = safeInteractionFailureMessage(error);
+    const needsRoot = error instanceof UserFacingInteractionError &&
+        ["nexus_exchange_form_expired", "nexus_exchange_form_replayed"].includes(error.code);
+    const root = needsRoot
+        ? interaction.guildId
+            ? await nexusObservedRoot(services, interaction.guildId)
+            : null
+        : "nexus";
+    const message = safeInteractionFailureMessage(error, root);
     if (interaction.replied || interaction.deferred) {
         await interaction.editReply({ content: message }).catch(() => undefined);
         return;

package/dist/invite-rollup-maintenance.d.ts

@@ -0,0 +1,9 @@
+import type { ModuleDefinition } from "@helyx/sdk";
+/** Private historical-work exception; never grants the refresh/provider lane. */
+export declare function isInviteRollupMaintenanceTask(task: {
+    moduleId: string;
+    taskKind: string;
+    taskVersion: number;
+    delivery: string;
+}, module: ModuleDefinition | undefined): boolean;
+//# sourceMappingURL=invite-rollup-maintenance.d.ts.map

package/dist/invite-rollup-maintenance.js

@@ -0,0 +1,12 @@
+/** Private historical-work exception; never grants the refresh/provider lane. */
+export function isInviteRollupMaintenanceTask(task, module) {
+    return Boolean(task.moduleId === "helyx.invite-tracking" &&
+        task.taskKind === "invite-tracking.finalized-rollup" &&
+        task.taskVersion === 1 &&
+        task.delivery === "one-shot" &&
+        module?.manifest.id === task.moduleId &&
+        module.scheduledTasks?.some((contribution) => contribution.kind === task.taskKind &&
+            contribution.version === task.taskVersion &&
+            contribution.delivery === task.delivery));
+}
+//# sourceMappingURL=invite-rollup-maintenance.js.map

package/dist/managed-resource-authorization.d.ts

@@ -0,0 +1,15 @@
+import type { ManagedResourceContext, ModuleDefinition, ModuleManagedResource, PermissionActor } from "@helyx/sdk";
+import type { ManagedResourceOperation } from "./control-permissions.js";
+/** Explicit, target-bound delegation after the ordinary permission has denied. */
+export declare function authorizeManagedResourceContext(input: {
+    module: ModuleDefinition;
+    resource: ModuleManagedResource;
+    resourceType: string;
+    resourceId?: string;
+    actionId?: string;
+    operation: ManagedResourceOperation;
+    permissionId: string;
+    authorize(permissionId: string): Promise<PermissionActor>;
+    createContext(actor: PermissionActor, scope: "full" | "owner"): ManagedResourceContext;
+}): Promise<ManagedResourceContext>;
+//# sourceMappingURL=managed-resource-authorization.d.ts.map

package/dist/managed-resource-authorization.js

@@ -0,0 +1,37 @@
+import { BotControlForbiddenError } from "./control-errors.js";
+/** Explicit, target-bound delegation after the ordinary permission has denied. */
+export async function authorizeManagedResourceContext(input) {
+    let actor;
+    try {
+        actor = await input.authorize(input.permissionId);
+    }
+    catch (error) {
+        if (!(error instanceof BotControlForbiddenError))
+            throw error;
+        const declaration = input.module.manifest.dashboard?.resources?.find(({ id }) => id === input.resourceType);
+        const ownerPermissionId = input.operation === "update"
+            ? declaration?.ownerPermissions?.update
+            : input.operation === "action"
+                ? declaration?.actions?.find(({ id }) => id === input.actionId)
+                    ?.ownerPermissionId
+                : undefined;
+        if (!ownerPermissionId ||
+            !input.resourceId ||
+            !input.resource.resolveOwnerUserId)
+            throw error;
+        actor = await input.authorize(ownerPermissionId);
+        const context = input.createContext(actor, "owner");
+        let ownerUserId;
+        try {
+            ownerUserId = await input.resource.resolveOwnerUserId(context, input.resourceId);
+        }
+        catch {
+            throw new BotControlForbiddenError();
+        }
+        if (!ownerUserId || ownerUserId !== actor.userId)
+            throw new BotControlForbiddenError();
+        return context;
+    }
+    return input.createContext(actor, "full");
+}
+//# sourceMappingURL=managed-resource-authorization.js.map

package/dist/managed-resource-create-defaults.d.ts

@@ -0,0 +1,21 @@
+import type { ManagedResourceContext, ManagedResourceValue, ModuleDefinition, ModuleManagedResource } from "@helyx/sdk";
+export interface ManagedResourceCreateDefaultsInput {
+    guildId: string;
+    moduleId: string;
+    resourceType: string;
+    actorUserId: string;
+    correlationId: string;
+}
+export interface ManagedResourceCreateDefaultsControl {
+    getManagedResourceCreateDefaults?(input: ManagedResourceCreateDefaultsInput): Promise<{
+        value: Readonly<Record<string, ManagedResourceValue>>;
+    }>;
+}
+export declare function readManagedResourceCreateDefaults(input: {
+    module: ModuleDefinition;
+    resource: ModuleManagedResource;
+    context: ManagedResourceContext;
+}): Promise<{
+    value: Readonly<Record<string, ManagedResourceValue>>;
+}>;
+//# sourceMappingURL=managed-resource-create-defaults.d.ts.map

package/dist/managed-resource-create-defaults.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { BotControlNotFoundError, BotControlValidationError, } from "./control-errors.js";
+import { managedResourceObject } from "./control-server-schemas.js";
+import { requireDashboardFeatures, resourceFieldFeatureIds, validateManagedResourceInput, isBoundedManagedResourceValue, } from "./dashboard-feature-control.js";
+const optionalUrl = z
+    .string()
+    .max(2048)
+    .refine((value) => value === "" || /^https?:\/\//u.test(value));
+const embed = z
+    .object({
+    title: z.string().max(256).optional(),
+    description: z.string().max(4000).optional(),
+    url: optionalUrl.optional(),
+    imageUrl: optionalUrl.optional(),
+    thumbnailUrl: optionalUrl.optional(),
+    color: z.number().int().min(0).max(0xffffff).optional(),
+    timestamp: z.string().max(100).optional(),
+    author: z
+        .object({
+        name: z.string().max(256).optional(),
+        url: optionalUrl.optional(),
+        iconUrl: optionalUrl.optional(),
+    })
+        .strict()
+        .optional(),
+    footer: z
+        .object({
+        text: z.string().max(2048).optional(),
+        iconUrl: optionalUrl.optional(),
+    })
+        .strict()
+        .optional(),
+    fields: z
+        .array(z
+        .object({
+        name: z.string().max(256),
+        value: z.string().max(1024),
+        inline: z.boolean().optional(),
+    })
+        .strict())
+        .max(25)
+        .optional(),
+})
+    .strict();
+function validatePartialFields(fields, values) {
+    for (const [key, value] of Object.entries(values)) {
+        const field = fields.find((candidate) => candidate.key === key);
+        if (!field)
+            throw new BotControlValidationError("Creation defaults contain an undeclared field");
+        if (field.type === "list" || field.type === "discord-embeds") {
+            if (!Array.isArray(value) ||
+                value.length < field.minItems ||
+                value.length > field.maxItems)
+                throw new BotControlValidationError("Creation defaults contain an invalid list");
+            for (const item of value) {
+                if (field.type === "discord-embeds") {
+                    embed.parse(item);
+                    continue;
+                }
+                const entry = managedResourceObject.parse(item);
+                validateManagedResourceInput(field.fields, entry);
+            }
+        }
+        else
+            validateManagedResourceInput([{ ...field, required: false }], {
+                [key]: value,
+            });
+    }
+}
+export async function readManagedResourceCreateDefaults(input) {
+    const declaration = input.module.manifest.dashboard?.resources?.find(({ id }) => id === input.resource.id);
+    if (declaration?.createDefaults !== true || !input.resource.createDefaults)
+        throw new BotControlNotFoundError("Creation defaults are not declared by this module");
+    await requireDashboardFeatures(input.context.services, input.context.guildId, input.module.manifest.id, [declaration.featureId]);
+    const result = await input.resource.createDefaults(input.context);
+    if (!isBoundedManagedResourceValue(result))
+        throw new BotControlValidationError("Creation defaults contain unsafe or unbounded values");
+    const value = managedResourceObject.parse(result);
+    validatePartialFields(declaration.fields, value);
+    await requireDashboardFeatures(input.context.services, input.context.guildId, input.module.manifest.id, resourceFieldFeatureIds(declaration.fields, value));
+    return { value };
+}
+//# sourceMappingURL=managed-resource-create-defaults.js.map

package/dist/managed-resource-query.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleDefinition } from "@helyx/sdk";
+export declare function validateManagedResourceQuery(module: ModuleDefinition, resourceType: string, input: {
+    search?: string;
+    filters?: Readonly<Record<string, string>>;
+}): void;
+//# sourceMappingURL=managed-resource-query.d.ts.map