@helyx/bot 1.5.1 → 1.5.3

package/dist/shard-supervisor.js

@@ -1,18 +1,23 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InstallationRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, InteractionSessionRepository, EckoOperationsRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
-import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
-import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { createPlatformServices, createPostgresCommandRestrictionRecovery, createPostgresNexusCommandRecovery, createPostgresCommandCatalogueRecovery, createPostgresCommandPolicyDelivery, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, collectReservedCommandNames, } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
 import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
+import { loadBundledCommandCatalogue } from "./command-root-catalogue.js";
+import { completeShardCommandStartup, shardStartupCatalogueReady, } from "./shard-command-startup.js";
 import { join } from "node:path";
 import pino, {} from "pino";
 import { synchroniseApplicationCommands, } from "./command-sync.js";
-import { CloudConnectorController, } from "./cloud-connector.js";
+import { CloudConnectorController } from "./cloud-connector.js";
+import { commandPolicyLeaderIsCurrent, captureShardedCommandPolicyAdmission, shardCommandPolicyScope, } from "./command-policy-runtime.js";
+import { allocateShardDeploymentOrder, prepareShardDeploymentOrder, } from "./shard-core-readiness.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, createBotControlServer, mapBotControlError, } from "./control-server.js";
 import { createManagementModule } from "./management-module.js";
+import { creatorInviteWorkerKeyName, deriveCreatorInviteKey, } from "./creator-invite-key.js";
 import { createDiagnosticModule } from "./diagnostic-command.js";
 import { buildApplicationCommandDefinitions } from "./interactions.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
@@ -130,6 +135,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let numericRegistrations = [];
     let leaderLease;
     let cloudConnector;
+    let commandPolicyRuntime;
     let cloudStarted = false;
     let maintainingLeases = false;
     let rebalancingShards = false;
@@ -163,6 +169,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let guildCommandReleasePromise;
     let scheduledModules = [];
     let commandModules = [];
+    let commandCatalogue;
     let workersRoutable = false;
     let promoteToLeader = () => Promise.resolve(false);
     try {
@@ -172,6 +179,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
         const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
         const featureModules = modulePackages.map(({ definition }) => definition);
         assertReviewedPremiumCatalogue(featureModules);
+        const bundledCommandCatalogue = featureModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+            ? await loadBundledCommandCatalogue()
+            : null;
+        const catalogueIdentity = bundledCommandCatalogue
+            ? {
+                revision: bundledCommandCatalogue.revision,
+                fingerprint: bundledCommandCatalogue.fingerprint,
+            }
+            : null;
         const gateway = await fetchGatewayBotInformation(environment.DISCORD_TOKEN);
         shardCount =
             environment.HELYX_SHARD_MODE === "fixed"
@@ -300,11 +316,57 @@ export async function startShardSupervisor(environment, processEnvironment, work
             listAvailabilityModules: () => availabilityCatalogue(availabilityModules, statusModules, runtimeAvailability),
         };
         const initialiseLeader = async () => {
-            await runLeaderStartup(database, environment, modulePackages, modules, logger);
+            let commandPolicyAdmission;
+            let policyLeader;
+            let policyOwnerCurrent;
+            await runLeaderStartup(database, environment, modulePackages, modules, logger, {
+                catalogue: catalogueIdentity,
+                assertOwnership: assertStartupLeaseHealthy,
+                captureCommandPolicy: async () => {
+                    if (environment.HELYX_RUNTIME_PROFILE !== "self-hosted")
+                        return;
+                    const leader = leaderLease;
+                    if (!leader)
+                        throw new Error("Command policy requires the current shard leader");
+                    const delivery = createPostgresCommandPolicyDelivery(database, {
+                        applicationId: environment.DISCORD_CLIENT_ID,
+                        scope: shardCommandPolicyScope(generation, deploymentOrder),
+                    });
+                    policyLeader = leader;
+                    policyOwnerCurrent = coordinator
+                        ? () => withTimeout(commandPolicyLeaderIsCurrent({
+                            coordinator: coordinator,
+                            descriptor: generationDescriptor,
+                            deploymentOrder,
+                            leader,
+                        }), LEASE_VALIDATION_TIMEOUT_MS)
+                        : () => Promise.resolve(true);
+                    commandPolicyAdmission = await captureShardedCommandPolicyAdmission(delivery, leader.supervisorId);
+                },
+                prepareCommandPolicy: async () => {
+                    if (environment.HELYX_RUNTIME_PROFILE !== "self-hosted")
+                        return;
+                    if (!commandPolicyAdmission || !policyLeader || !policyOwnerCurrent)
+                        throw new Error("Command policy admission was not captured at database readiness");
+                    commandPolicyRuntime = await commandPolicyAdmission.claim(String(policyLeader.fencingToken), policyOwnerCurrent);
+                    await cloudConnector?.setCommandPolicyDelivery(commandPolicyRuntime);
+                },
+                publishCatalogue: async () => {
+                    if (!bundledCommandCatalogue)
+                        return;
+                    commandCatalogue = createPostgresCommandCatalogueRecovery(database, environment.DISCORD_CLIENT_ID);
+                    await commandCatalogue.publish(bundledCommandCatalogue);
+                },
+            });
             assertStartupLeaseHealthy();
             privacyDatabase = await createPrivacyDatabase(environment, database);
             assertStartupLeaseHealthy();
-            const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
+            const services = new Map(createPlatformServices(database, publicModules, {
+                ...platformServiceOptions(environment, publicModules),
+                ...(commandPolicyRuntime
+                    ? { commandPolicyDeliveryScope: commandPolicyRuntime.owner.scope }
+                    : {}),
+            }));
             runtimeAvailability = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
             leaderScannerRegistry = new BotAutoModerationScannerRegistry(publicModules, new ServiceRegistry(services), "hosted", undefined, environment.HELYX_DEPLOYMENT_ENVIRONMENT);
             if (numericWriteBehind)
@@ -349,9 +411,9 @@ export async function startShardSupervisor(environment, processEnvironment, work
             environment: environment.NODE_ENV,
             generation,
             shardCount,
-            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID, environment.HELYX_GLOBAL_COMMAND_MODE),
+            catalogueHash: shardRuntimeCompositionHash(modules, environment.DISCORD_INTERNAL_GUILD_ID, environment.HELYX_GLOBAL_COMMAND_MODE, bundledCommandCatalogue?.fingerprint),
         };
-        deploymentOrder = await nextShardDeploymentOrder(database);
+        deploymentOrder = await prepareShardDeploymentOrder(database, environment.HELYX_DATABASE_STARTUP_MODE);
         if (environment.HELYX_SHARD_SCOPE === "coordinated") {
             coordinator = new RedisShardCoordinator(environment.HELYX_SHARD_REDIS_URL, environment.HELYX_SHARD_REDIS_NAMESPACE, {
                 onError: (error) => logger.error({ event: "shard.redis_error", error: safeError(error) }, "Shard coordination failed"),
@@ -416,7 +478,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             await initialiseLeader();
         }
         else {
-            await waitForLeaderStartup(database, generation);
+            await waitForLeaderStartup(database, generation, catalogueIdentity);
             assertStartupLeaseHealthy();
         }
         const router = new ShardControlRouter({
@@ -483,6 +545,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 : undefined;
             controlServer = await createBotControlServer({
                 service: router,
+                ...(commandModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                    ? {
+                        nexusCommandRecovery: createPostgresNexusCommandRecovery(database, {
+                            applicationId: environment.DISCORD_CLIENT_ID,
+                            persistedCommandCatalogue: true,
+                            reservedCommandNames: collectReservedCommandNames(commandModules),
+                        }),
+                    }
+                    : {}),
                 secret: environment.HELYX_BOT_CONTROL_SECRET,
                 ...shardHostedControlCallbacks(router),
                 logger: { level: environment.LOG_LEVEL },
@@ -1217,6 +1288,15 @@ export async function startShardSupervisor(environment, processEnvironment, work
         }
         if (!guildCommandWorker) {
             guildCommandWorker = new GuildCommandWorker({
+                ...(commandPolicyRuntime
+                    ? { commandPolicyDelivery: commandPolicyRuntime.delivery }
+                    : {}),
+                ...(commandCatalogue ? { commandCatalogue } : {}),
+                ...(commandModules.some(({ manifest }) => manifest.id === "helyx.nexus-core")
+                    ? {
+                        commandRestrictions: createPostgresCommandRestrictionRecovery(database, environment.DISCORD_CLIENT_ID),
+                    }
+                    : {}),
                 database,
                 modules: commandModules,
                 logger,
@@ -1539,7 +1619,10 @@ export function splitNumericCommittedBatch(batch, index) {
         results: [result],
     };
 }
-async function runLeaderStartup(database, environment, modulePackages, modules, logger) {
+async function runLeaderStartup(database, environment, modulePackages, modules, logger, commandStartup) {
+    // Core readiness and durable order were established before election. Capture
+    // admission before any further migration/owner startup can wait asynchronously.
+    await commandStartup.captureCommandPolicy();
     const moduleMigrationSources = modulePackages.map(({ definition, packageRoot }) => ({
         moduleId: definition.manifest.id,
         moduleVersion: definition.manifest.version,
@@ -1565,23 +1648,36 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
         await runCoreMigrations(database);
         await runConfiguredModuleMigrations(database, moduleMigrationSources);
     }
+    await commandStartup.prepareCommandPolicy();
     await enforcePremiumCatalogue(database, logger);
     const repository = new RuntimeStateRepository(database);
-    await synchroniseApplicationCommands({
-        applicationId: environment.DISCORD_CLIENT_ID,
-        token: environment.DISCORD_TOKEN,
-        modules,
-        globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
-        ...(environment.DISCORD_INTERNAL_GUILD_ID
-            ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
-            : {}),
-        // Worker-owned guild collections stay untouched while command writes are off.
-        synchroniseInternalGuild: false,
-        state: new RuntimeCommandHashStore(repository),
-    });
-    await setRuntimeState(repository, `shards:${environment.HELYX_SHARD_GENERATION ?? "local"}:startup`, {
-        ready: true,
-        completedAt: new Date().toISOString(),
+    await completeShardCommandStartup({
+        assertOwnership: () => commandStartup.assertOwnership(),
+        publishCatalogue: () => commandStartup.publishCatalogue(),
+        synchronise: async () => {
+            await synchroniseApplicationCommands({
+                applicationId: environment.DISCORD_CLIENT_ID,
+                token: environment.DISCORD_TOKEN,
+                modules,
+                globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                // Worker-owned guild collections stay untouched while command writes are off.
+                synchroniseInternalGuild: false,
+                state: new RuntimeCommandHashStore(repository),
+            });
+        },
+        markReady: () => setRuntimeState(repository, `shards:${environment.HELYX_SHARD_GENERATION ?? "local"}:startup`, {
+            ready: true,
+            completedAt: new Date().toISOString(),
+            commandCatalogue: commandStartup.catalogue
+                ? {
+                    revision: commandStartup.catalogue.revision,
+                    fingerprint: commandStartup.catalogue.fingerprint,
+                }
+                : null,
+        }),
     });
     logger.info({ event: "shard.singleton_startup_complete" }, "Shard singleton startup complete");
 }
@@ -1618,15 +1714,12 @@ async function setRuntimeState(repository, key, value) {
     if (!updated)
         throw new Error("Runtime state changed concurrently");
 }
-async function waitForLeaderStartup(database, generation) {
+async function waitForLeaderStartup(database, generation, catalogue) {
     const deadline = Date.now() + STARTUP_WAIT_MS;
     while (Date.now() < deadline) {
         try {
             const state = await new RuntimeStateRepository(database).get(`shards:${generation}:startup`);
-            if (typeof state?.value === "object" &&
-                state.value !== null &&
-                !Array.isArray(state.value) &&
-                state.value.ready === true)
+            if (shardStartupCatalogueReady(state?.value, catalogue))
                 return;
         }
         catch {
@@ -1716,6 +1809,9 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
     const selectionKey = source.HELYX_DATA_ENCRYPTION_KEY
         ? Buffer.from(deriveSecureRandomSelectionKey(source.HELYX_DATA_ENCRYPTION_KEY)).toString("base64")
         : undefined;
+    const creatorInviteKey = source.HELYX_DATA_ENCRYPTION_KEY
+        ? deriveCreatorInviteKey(source.HELYX_DATA_ENCRYPTION_KEY).toString("base64")
+        : undefined;
     const hostedModerationCredential = source.HELYX_HOSTED_MODERATION_ENABLED === "true" &&
         source.HELYX_BOT_CONTROL_SECRET
         ? { HELYX_BOT_CONTROL_SECRET: source.HELYX_BOT_CONTROL_SECRET }
@@ -1726,6 +1822,9 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         ...(selectionKey
             ? { [secureRandomSelectionWorkerKeyName]: selectionKey }
             : {}),
+        ...(creatorInviteKey
+            ? { [creatorInviteWorkerKeyName]: creatorInviteKey }
+            : {}),
         SHARDING_MANAGER: "true",
         SHARDING_MANAGER_MODE: "process",
         SHARDS: String(identity.shardId),
@@ -1734,11 +1833,12 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         HELYX_SHARD_RESTART_COUNT: String(restartCount),
     };
 }
-export function shardRuntimeCompositionHash(modules, internalGuildId, globalCommandMode = "legacy") {
+export function shardRuntimeCompositionHash(modules, internalGuildId, globalCommandMode = "legacy", commandCatalogueFingerprint) {
     const commands = buildApplicationCommandDefinitions(modules, internalGuildId, globalCommandMode);
     return createHash("sha256")
         .update(JSON.stringify({
         botVersion: botVersion(),
+        ...(commandCatalogueFingerprint ? { commandCatalogueFingerprint } : {}),
         modules: modules
             .map(({ manifest }) => ({
             id: manifest.id,
@@ -1983,19 +2083,7 @@ function sameShardLease(left, right) {
         left.fencingToken === right.fencingToken);
 }
 export async function nextShardDeploymentOrder(database) {
-    let value;
-    try {
-        value = await new RuntimeStateRepository(database).nextShardDeploymentOrder();
-    }
-    catch (error) {
-        if (error.code !== "42P01")
-            throw error;
-        return 1;
-    }
-    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
-        throw new Error("Shard deployment order exceeds the safe runtime range");
-    }
-    return Number(value);
+    return allocateShardDeploymentOrder(database);
 }
 export async function renewStartupOwnership(coordinator, descriptor, deploymentOrder, leaderLease) {
     if (!(await coordinator.refreshGeneration(descriptor, deploymentOrder)))

package/dist/shard-worker.d.ts

@@ -23,6 +23,7 @@ export declare function startShardWorker(processEnvironment?: NodeJS.ProcessEnv,
 export declare function executeShardScheduledTaskRequest(identity: ShardIdentity, request: ShardScheduledTaskRequest, route: ScheduledTaskRoute, now?: number): Promise<ShardScheduledTaskResponse>;
 export declare function parseShardWorkerLaunchContract(value: string | undefined): ShardIdentity;
 export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.ProcessEnv, identity: ShardIdentity): {
+    HELYX_INTERNAL_CREATOR_INVITE_KEY?: string;
     HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY?: string;
     HELYX_DATA_ENCRYPTION_KEY: undefined;
     HELYX_SHARD_WORKERS_PER_REPLICA: number;

package/dist/shard-worker.js

@@ -1,4 +1,5 @@
 import { parseBotEnvironment } from "@helyx/config";
+import { shardCommandPolicyScope } from "./command-policy-runtime.js";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, InstallationRepository, } from "@helyx/database";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
@@ -15,6 +16,7 @@ import { HttpVerificationService } from "./verification-service.js";
 import { DiscordMessageDeliveryService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModerationMemberEnforcementAdapter } from "./discord-member-enforcement-service.js";
 import { installCreatorInvitePlatform } from "./creator-onboarding-platform.js";
+import { creatorInviteWorkerKeyName, decodeCreatorInviteKey, } from "./creator-invite-key.js";
 import { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
 import { createManagementModule } from "./management-module.js";
@@ -263,6 +265,11 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const serviceOptions = platformServiceOptions(environment, publicModules);
         for (const [name, service] of createPlatformServices(database, publicModules, {
             ...serviceOptions,
+            ...(environment.HELYX_RUNTIME_PROFILE === "self-hosted"
+                ? {
+                    commandPolicyDeliveryScope: shardCommandPolicyScope(identity.generation, identity.deploymentOrder),
+                }
+                : {}),
             recordRecoveryOwnership: {
                 mode: "shard",
                 shardId: identity.shardId,
@@ -318,6 +325,11 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 services: serviceAccess,
                 modules: publicModules,
                 encryptionKey: environment.HELYX_DATA_ENCRYPTION_KEY,
+                ...(environment.HELYX_INTERNAL_CREATOR_INVITE_KEY
+                    ? {
+                        inviteEncryptionKey: environment.HELYX_INTERNAL_CREATOR_INVITE_KEY,
+                    }
+                    : {}),
                 ...(environment.HELYX_CLOUD_API_URL &&
                     environment.HELYX_OAUTH_INTERNAL_SECRET
                     ? {
@@ -385,21 +397,24 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 shardCount: identity.shardCount,
             })
             : undefined;
-        const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
-            ...(environment.DISCORD_INTERNAL_GUILD_ID
-                ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
-                : {}),
-            prepare: prepareGuilds,
-            ...(operationsModule
-                ? { operationsModuleId: operationsModule.manifest.id }
-                : {}),
-            supportModuleId: supportModule.manifest.id,
-            diagnosticModuleId: diagnosticModule.manifest.id,
-            ...(premiumActivationModule
-                ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
-                : {}),
-            ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
-        }), logger, serviceAccess);
+        const commandsReady = installInteractions(client, modules, {
+            ...shardWorkerCommandRegistration({
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                prepare: prepareGuilds,
+                ...(operationsModule
+                    ? { operationsModuleId: operationsModule.manifest.id }
+                    : {}),
+                supportModuleId: supportModule.manifest.id,
+                diagnosticModuleId: diagnosticModule.manifest.id,
+                ...(premiumActivationModule
+                    ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
+                    : {}),
+                ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
+            }),
+            resolveGuildCommandName: (input) => guildCommandReads.resolveInteractionCommand(input),
+        }, logger, serviceAccess);
         moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess, {
             runtimeProfile: environment.HELYX_RUNTIME_PROFILE,
             evidenceStore: moderationPlatformServices.evidenceStore,
@@ -582,12 +597,18 @@ export function parseShardWorkerEnvironment(processEnvironment, identity) {
         environment.HELYX_SHARD_SCOPE !== identity.scope)
         throw new Error("Shard worker launch contract conflicts with configuration");
     const internalSelectionKey = processEnvironment[secureRandomSelectionWorkerKeyName];
+    const internalCreatorInviteKey = processEnvironment[creatorInviteWorkerKeyName];
+    if (internalCreatorInviteKey !== undefined)
+        decodeCreatorInviteKey(internalCreatorInviteKey);
     return {
         ...environment,
         HELYX_DATA_ENCRYPTION_KEY: undefined,
         ...(internalSelectionKey
             ? { HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY: internalSelectionKey }
             : {}),
+        ...(internalCreatorInviteKey
+            ? { HELYX_INTERNAL_CREATOR_INVITE_KEY: internalCreatorInviteKey }
+            : {}),
     };
 }
 export function shardWorkerCommandRegistration(input) {
@@ -657,6 +678,7 @@ async function handleControl(identity, service, hostedOwnerObserver, client, hos
                 ok: false,
                 status: mapped?.status ?? 500,
                 message: mapped?.message ?? "The owning shard rejected the request",
+                ...(mapped?.fieldError ? { fieldError: mapped.fieldError } : {}),
             };
         }
     }

package/documentation/README.md

@@ -13,6 +13,7 @@ and module guides.
 
 - [Install a self-hosted Helyx instance](guides/getting-started.md)
 - [Understand the self-hosting boundary](guides/self-hosting.md)
+- [Understand upcoming shared Nexus command names](guides/self-hosting.md#nexus-command-names-upcoming)
 - [Configure the environment](reference/environment.md)
 - [Operate installations and upgrades](runbooks/installation-and-upgrades.md)
 - [Plan backup and recovery](runbooks/backup-and-recovery.md)

package/documentation/guides/self-hosting.md

@@ -95,6 +95,60 @@ features continue if the hosted dashboard is temporarily unavailable.
 Set `HELYX_CLOUD_CONNECT_ENABLED=false` before startup when the installation
 must remain entirely local.
 
+## Nexus command names (upcoming)
+
+Nexus Rewards and Nexus Economy keep `/nexus` as their default command in this
+guide. Custom command naming is an upcoming feature, held until the current name
+policy is configured and controlled acceptance is complete. Having a compatible
+package or enabling Cloud Connect does not activate it.
+
+The shared Nexus settings own one command name per Discord server. When offered
+by an approved release, the same **Slash command name** will appear under either
+**Modules > Nexus Rewards > Settings** or **Modules > Nexus Economy > Settings**.
+Changing currency terminology does not change that command. A new root uses
+1-10 lowercase ASCII letters, digits, hyphens or underscores, excluding `/`, and
+must pass the current restricted-word and full command-reservation checks.
+Reservations include commands from disabled modules.
+
+In a supporting Self-Hosted release, Cloud Connect must verify the current
+centrally managed name policy before a new custom name can be accepted. An
+unpaired, disconnected or unsupported connection holds custom-name changes;
+reconnection checks the latest policy before making them available again. A
+previously stored list alone does not establish current verification. Existing
+confirmed commands and ordinary Nexus settings remain usable. **Restore nexus**
+can stage the default name while custom-name editing is held, subject to the
+same confirmation, cooldown and unresolved-update checks described below.
+
+A changed-name save requires **Confirm** or **Cancel**. Cancel, Escape or closing
+the dialog restores only the root draft without saving the other fields.
+Confirmation warns about the rolling 24-hour restriction, including a return to
+`nexus`, and Discord command permission overrides which must be reapplied after
+the update. Invalid/rejected requests create no future rename queue. Ordinary
+settings saves, unchanged names and delivery retries do not extend the timer.
+
+An accepted setting and a confirmed Discord command are different states. While
+an update is pending or failed, use the previously confirmed command in Discord;
+another customer rename remains blocked until the update is resolved, even after
+the timer expires. If no Nexus commands are enabled, a selected name can remain
+saved without an active slash command. Once a custom name is confirmed, replace
+only `/nexus` in examples: a confirmed `coins` root makes `/nexus balance` become
+`/coins balance`, with the same subcommands and access rules.
+
+A new reserved command or restricted-list update can select `nexus` again without
+extending the existing expiry or changing unrelated settings. Check the reset's
+pending/confirmed state and reapply Discord command permission overrides after
+the update.
+
+Private command-history inspection, timer reset and rename override by Helyx staff
+are a Hosted-only support path. Remote Self-Hosted and Cloud-connected
+installations do not have that recovery capability. Keep custom-name activation
+held when the required policy or recovery path is unavailable; do not bypass it
+by changing stored records or registering a competing command manually. Check
+your release, `npm run doctor`, module health and the current Discord command
+picker, then use the supported [privacy and support routes](privacy-and-support.md)
+without sharing credentials. Hosted dashboard workflow details are in the
+[shared Nexus Settings guide](https://docs.helyx.gg/modules/nexus-rewards/settings/).
+
 ## Before production use
 
 1. Prove `npm run doctor` from the production environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -30,6 +30,7 @@
   "type": "module",
   "files": [
     "dist",
+    "command-root-catalogue.json",
     "!dist/*.tsbuildinfo",
     "!dist/**/*.map",
     "documentation",
@@ -50,31 +51,31 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": ">=1.4.0 <2.0.0",
-    "@helyx/control-protocol": ">=0.8.0 <0.9.0",
+    "@helyx/config": ">=1.6.0 <2.0.0",
+    "@helyx/control-protocol": ">=0.9.0 <0.10.0",
     "@helyx/core": ">=0.2.0 <0.3.0",
-    "@helyx/database": ">=2.4.1 <3.0.0",
-    "@helyx/database-contracts": ">=0.2.0 <0.3.0",
+    "@helyx/database": ">=2.5.0 <3.0.0",
+    "@helyx/database-contracts": ">=0.3.0 <0.4.0",
     "@helyx/framework": ">=0.2.0 <0.3.0",
-    "@helyx/module-manifest": ">=0.13.0 <0.14.0",
+    "@helyx/module-manifest": ">=0.14.0 <0.15.0",
     "@helyx/platform": ">=1.3.0 <2.0.0",
-    "@helyx/sdk": ">=0.16.0 <0.17.0",
+    "@helyx/sdk": ">=0.17.0 <0.18.0",
     "@helyx/status-client": ">=0.3.0 <0.4.0",
-    "@helyx/verification-contracts": ">=0.4.0 <0.5.0",
+    "@helyx/verification-contracts": ">=0.5.0 <0.6.0",
     "discord.js": "14.27.0",
     "fastify": "5.12.7",
-    "pino": "10.3.1",
-    "redis": "6.1.0",
-    "undici": "6.29.0",
-    "ws": "8.21.1",
-    "zod": "4.4.3"
+    "pino": "10.4.0",
+    "redis": "6.3.0",
+    "undici": "6.29.1",
+    "ws": "8.22.0",
+    "zod": "4.6.7"
   },
   "optionalDependencies": {
-    "@helyx/database-mysql": ">=0.2.1 <0.3.0"
+    "@helyx/database-mysql": ">=0.3.0 <0.4.0"
   },
   "peerDependencies": {
-    "@helyx/module-automod": ">=1.1.1 <2.0.0",
-    "@helyx/module-moderation": ">=1.1.1 <2.0.0"
+    "@helyx/module-automod": ">=1.1.2 <2.0.0",
+    "@helyx/module-moderation": ">=1.1.2 <2.0.0"
   },
   "peerDependenciesMeta": {
     "@helyx/module-automod": {
@@ -85,6 +86,6 @@
     }
   },
   "devDependencies": {
-    "@types/ws": "8.18.1"
+    "@types/ws": "8.18.2"
   }
 }