@helyx/bot 0.4.42 → 0.4.43

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.43
+
+### Patch Changes
+
+- Generalise the hosted Creator OAuth boundary with typed provider registrations,
+  neutral versioned consumer context, bounded Creator account slots and scheduled
+  cross-database orphan reconciliation without exposing credential material.
+- Complete the Nexus redemption experience with contextual custom-request modals,
+  a dedicated protected redemption report including stored unit price, and
+  structured Achievement balance amount and currency projections.
+- Report bounded aggregate bot readiness and keep status heartbeat preparation and delivery fail-open under timeouts and failures.
+- Updated dependencies
+- Updated dependencies
+- Updated dependencies
+  - @helyx/sdk@0.9.0
+  - @helyx/database@0.9.0
+  - @helyx/module-manifest@0.8.0
+
 ## 0.4.42
 
 ### Patch Changes

package/README.md

@@ -38,6 +38,13 @@ When `HELYX_BOT_CONTROL_SECRET` is configured, the bot also starts a private aut
 
 Optional Helyx Cloud Connect is a separate outbound management path for self-hosted deployments. It is disabled unless `HELYX_CLOUD_CONNECT_ENABLED=true` and requires a separate local `HELYX_DATA_ENCRYPTION_KEY`. Preserve that key across every restart and deployment. If it is lost or changed, revoke the old installation in the dashboard and use a new one-use code with `/helyx-cloud connect`; the connector stops retrying until that recovery is completed. The owner-only `/helyx-cloud` command supports connection-code enrolment, status, credential rotation, disconnection and bounded support consent. The bot never sends its Discord token, database URL or connector private key to Helyx Cloud, and local Discord operation continues when Cloud is unavailable.
 
+Production Status reporting is opt-in and disabled by default. Set
+`HELYX_STATUS_ENABLED=true` only with the reviewed `HELYX_STATUS_URL`, the
+bot-specific `HELYX_STATUS_HEARTBEAT_SECRET`,
+`HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS`, and a bot-specific
+`CF_ACCESS_CLIENT_ID`/`CF_ACCESS_CLIENT_SECRET` pair. Never reuse another
+producer's Access identity or heartbeat secret.
+
 Giveaways also requires the existing `HELYX_DATA_ENCRYPTION_KEY` so core can
 resume secure weighted-selection checkpoints without exposing the selection
 key to a module. Keep it stable across deployments; do not rotate it while a

package/dist/control-server.js

@@ -628,6 +628,10 @@ export class BotControlService {
         });
     }
     async completeFirstTimeCommandSetup(input) {
+        for (const moduleIdValue of new Set(input.moduleIds)) {
+            this.#requireDashboardModule(moduleIdValue);
+            await this.#requireModuleAvailable(moduleIdValue);
+        }
         return completeFirstTimeCommandSetup({
             installations: this.#installations,
             dashboardModuleIds: this.#dashboardModules.map(({ id }) => id),

package/dist/events.d.ts

@@ -1,6 +1,7 @@
-import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess, VerificationMemberService } from "@helyx/sdk";
+import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, InstallationService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess, VerificationMemberService } from "@helyx/sdk";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
+export declare function availabilityAwareInstallations(services: ServiceAccess): Pick<InstallationService, "isModuleEnabled">;
 export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): ModuleEventHandle;
 export interface ModuleEventHandle {
     stop(): Promise<void>;

package/dist/events.js

@@ -3,7 +3,7 @@ import { ChannelType, Events, GatewayIntentBits, GuildMemberFlags, PermissionFla
 import { toReplyOptions } from "./interactions.js";
 import { createHash } from "node:crypto";
 import { classifyGuildMessage, unavailableGuildMessageClassification, } from "./message-classification.js";
-function availabilityAwareInstallations(services) {
+export function availabilityAwareInstallations(services) {
     const installations = services.get(HELYX_SERVICE_NAMES.installations);
     const candidate = typeof services.has === "function" &&
         services.has(HELYX_SERVICE_NAMES.moduleAvailability)

package/dist/index.d.ts

@@ -1,10 +1,12 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import { GatewayIntentBits } from "discord.js";
+import { type ShardHealthSnapshot } from "./shard-contracts.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
 export interface BotHandle {
     shutdown(reason?: string): Promise<void>;
+    statusHealth?(): Promise<ShardHealthSnapshot>;
 }
 export declare function startBot(processEnvironment?: NodeJS.ProcessEnv): Promise<BotHandle>;
 export declare function resolveBotWorkerEntryPoint(entryUrl?: string): string;

package/dist/index.js

@@ -26,7 +26,7 @@ import { HttpVerificationService } from "./verification-service.js";
 import { startShardSupervisor } from "./shard-supervisor.js";
 import { parseShardWorkerLaunchContract, startShardWorker, } from "./shard-worker.js";
 import { createDeveloperOperationsModule } from "./developer-operations-module.js";
-import { shardHealthSnapshotSchema } from "./shard-contracts.js";
+import { shardHealthSnapshotSchema, } from "./shard-contracts.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
@@ -42,12 +42,14 @@ import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createLocalScheduledTaskRoute, createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
 import { discordRestOptions } from "./discord-rest.js";
+import { discordBotStatusService } from "./status-producer.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
 const bootstrapLogger = pino({ base: { component: "bot" } });
 const RETENTION_CLEANUP_INTERVAL_MS = 60 * 60 * 1_000;
 export async function startBot(processEnvironment = process.env) {
+    const processStartedAt = new Date().toISOString();
     if (processEnvironment.HELYX_SHARD_WORKER_CONTRACT !== undefined)
         return startShardWorker(processEnvironment, parseShardWorkerLaunchContract(processEnvironment.HELYX_SHARD_WORKER_CONTRACT));
     const environment = parseBotEnvironment(processEnvironment);
@@ -57,7 +59,6 @@ export async function startBot(processEnvironment = process.env) {
         : await startUnshardedBot(processEnvironment);
     if (!environment.HELYX_STATUS_ENABLED)
         return handle;
-    const processStartedAt = new Date().toISOString();
     const reporter = new StatusHeartbeatReporter({
         producer: "bot",
         baseUrl: environment.HELYX_STATUS_URL,
@@ -65,21 +66,32 @@ export async function startBot(processEnvironment = process.env) {
         accessClientId: environment.CF_ACCESS_CLIENT_ID,
         accessClientSecret: environment.CF_ACCESS_CLIENT_SECRET,
         intervalSeconds: environment.HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS,
-        services: () => [
-            {
-                key: "discord-bot",
-                state: "operational",
-                processStartedAt,
-                release: readBotVersion(),
-            },
-            {
-                key: "creator-connections",
-                state: environment.HELYX_OAUTH_ENABLED ? "operational" : "major_outage",
-                reasonCode: environment.HELYX_OAUTH_ENABLED ? null : "feature_disabled",
-                processStartedAt,
-                release: readBotVersion(),
-            },
-        ],
+        services: async () => {
+            const release = readBotVersion();
+            const health = await handle.statusHealth?.();
+            return [
+                health
+                    ? discordBotStatusService({ health, processStartedAt, release })
+                    : {
+                        key: "discord-bot",
+                        state: "major_outage",
+                        reasonCode: "runtime_not_ready",
+                        processStartedAt,
+                        release,
+                    },
+                {
+                    key: "creator-connections",
+                    state: environment.HELYX_OAUTH_ENABLED
+                        ? "operational"
+                        : "major_outage",
+                    reasonCode: environment.HELYX_OAUTH_ENABLED
+                        ? null
+                        : "feature_disabled",
+                    processStartedAt,
+                    release,
+                },
+            ];
+        },
         onError(error) {
             bootstrapLogger.warn({ event: "status.heartbeat_failed", reason: error.message }, "Status heartbeat could not be delivered");
         },
@@ -226,6 +238,60 @@ async function startUnshardedBot(processEnvironment) {
         let guildCommandWorker;
         const unshardedSupervisorId = randomUUID();
         const deployedCommit = deploymentReference(processEnvironment);
+        const buildHealth = async () => {
+            let databaseHealthy = true;
+            try {
+                await checkDatabaseConnection(database);
+            }
+            catch {
+                databaseHealthy = false;
+            }
+            const ready = client.isReady();
+            const scheduler = scheduledTasks
+                ? await scheduledTasks
+                    .getHealth()
+                    .then(schedulerOperationalHealth)
+                    .catch(() => ({ status: "unavailable" }))
+                : { status: "unavailable" };
+            const observedAt = new Date().toISOString();
+            const gatewayPingMs = Number.isFinite(client.ws.ping)
+                ? client.ws.ping
+                : -1;
+            return shardHealthSnapshotSchema.parse({
+                version: 1,
+                mode: "off",
+                scope: "local",
+                status: ready && databaseHealthy && scheduler.status === "available"
+                    ? "healthy"
+                    : ready
+                        ? "degraded"
+                        : "starting",
+                observedAt,
+                generation: "unsharded",
+                supervisorId: unshardedSupervisorId,
+                configuredShardCount: 1,
+                readyShardCount: ready ? 1 : 0,
+                coordination: {
+                    redis: "not_required",
+                    database: databaseHealthy ? "healthy" : "unavailable",
+                },
+                scheduler,
+                shards: [
+                    {
+                        shardId: 0,
+                        status: ready ? "ready" : "starting",
+                        guildCount: client.guilds.cache.size,
+                        gatewayPingMs,
+                        uptimeSeconds: process.uptime(),
+                        restartCount: 0,
+                        eventLoopDelayMs: 0,
+                        memoryRssBytes: process.memoryUsage().rss,
+                        queueDepth: 0,
+                        observedAt,
+                    },
+                ],
+            });
+        };
         const operationsModule = environment.DISCORD_INTERNAL_GUILD_ID
             ? createDeveloperOperationsModule({
                 internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
@@ -244,60 +310,7 @@ async function startUnshardedBot(processEnvironment) {
                 processLabel: "unsharded bot process",
                 triviaData: new PostgresTriviaDataProvider(database),
                 health: {
-                    getHealth: async () => {
-                        let databaseHealthy = true;
-                        try {
-                            await checkDatabaseConnection(database);
-                        }
-                        catch {
-                            databaseHealthy = false;
-                        }
-                        const ready = client.isReady();
-                        const scheduler = scheduledTasks
-                            ? await scheduledTasks
-                                .getHealth()
-                                .then(schedulerOperationalHealth)
-                                .catch(() => ({ status: "unavailable" }))
-                            : { status: "unavailable" };
-                        const observedAt = new Date().toISOString();
-                        const gatewayPingMs = Number.isFinite(client.ws.ping)
-                            ? client.ws.ping
-                            : -1;
-                        return shardHealthSnapshotSchema.parse({
-                            version: 1,
-                            mode: "off",
-                            scope: "local",
-                            status: ready && databaseHealthy && scheduler.status === "available"
-                                ? "healthy"
-                                : ready
-                                    ? "degraded"
-                                    : "starting",
-                            observedAt,
-                            generation: "unsharded",
-                            supervisorId: unshardedSupervisorId,
-                            configuredShardCount: 1,
-                            readyShardCount: ready ? 1 : 0,
-                            coordination: {
-                                redis: "not_required",
-                                database: databaseHealthy ? "healthy" : "unavailable",
-                            },
-                            scheduler,
-                            shards: [
-                                {
-                                    shardId: 0,
-                                    status: ready ? "ready" : "starting",
-                                    guildCount: client.guilds.cache.size,
-                                    gatewayPingMs,
-                                    uptimeSeconds: process.uptime(),
-                                    restartCount: 0,
-                                    eventLoopDelayMs: 0,
-                                    memoryRssBytes: process.memoryUsage().rss,
-                                    queueDepth: 0,
-                                    observedAt,
-                                },
-                            ],
-                        });
-                    },
+                    getHealth: buildHealth,
                 },
             })
             : undefined;
@@ -561,7 +574,7 @@ async function startUnshardedBot(processEnvironment) {
             await client.destroy();
             throw error;
         }
-        return { shutdown };
+        return { shutdown, statusHealth: buildHealth };
     }
     catch (error) {
         if (retentionCleanupTimer)

package/dist/interactions.d.ts

@@ -44,4 +44,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;
 //# sourceMappingURL=interactions.d.ts.map

package/dist/interactions.js

@@ -1,5 +1,5 @@
 import { lookup as lookupDns } from "node:dns/promises";
-import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { HELYX_SERVICE_NAMES, NexusEconomyError, UserFacingInteractionError, } from "@helyx/sdk";
 import { canUseCommand } 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";
@@ -282,7 +282,7 @@ export function installInteractions(client, modules, registration, logger, servi
                 ...interactionLogContext(interaction),
                 error: safeError(error),
             }, "Module interaction failed");
-            await sendFailure(interaction);
+            await sendFailure(interaction, error);
         }
     }
     return registrationReady;
@@ -578,6 +578,7 @@ function staleComponentResponse() {
 function createContext(interaction, services) {
     return {
         interactionId: interaction.id,
+        interactionCreatedAt: new Date(interaction.createdTimestamp),
         ...("customId" in interaction ? { customId: interaction.customId } : {}),
         userId: interaction.user.id,
         userDisplayName: interaction.user.globalName ?? interaction.user.username,
@@ -739,6 +740,7 @@ function createModalContext(interaction, services) {
         : undefined;
     return {
         interactionId: interaction.id,
+        interactionCreatedAt: new Date(interaction.createdTimestamp),
         customId: interaction.customId,
         userId: interaction.user.id,
         userDisplayName: interaction.user.globalName ?? interaction.user.username,
@@ -1289,14 +1291,48 @@ function discordChannelType(type) {
         return ChannelType.GuildCategory;
     return ChannelType.GuildText;
 }
-async function sendFailure(interaction) {
+export function safeInteractionFailureMessage(error) {
+    if (error instanceof UserFacingInteractionError) {
+        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_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.",
+        };
+        return messages[error.code];
+    }
+    if (error instanceof NexusEconomyError) {
+        const messages = {
+            invalid_input: "This Exchange request is invalid. Start again.",
+            module_disabled: "Nexus Economy is not enabled for this server.",
+            item_unavailable: "That Exchange item is not available to you right now.",
+            ineligible: "You are not eligible to redeem that Exchange item.",
+            insufficient_stock: "There is not enough stock for this redemption.",
+            limit_reached: "You have reached this Exchange item's redemption limit.",
+            cooldown_active: "That Exchange item is still on cooldown for your account.",
+            already_owned: "You already own that non-stackable Exchange item.",
+            insufficient_balance: "Your Nexus balance is too low for this item.",
+            operation_conflict: "This redemption was already handled or changed. Start again.",
+            privacy_erased: "This Nexus account cannot redeem items after privacy erasure.",
+        };
+        return (messages[error.code] ??
+            "Something went wrong while handling that interaction.");
+    }
+    return "Something went wrong while handling that interaction.";
+}
+async function sendFailure(interaction, error) {
     if (interaction.isAutocomplete()) {
         await interaction.respond([]).catch(() => undefined);
         return;
     }
     if (!interaction.isRepliable())
         return;
-    const message = "Something went wrong while handling that interaction.";
+    const message = safeInteractionFailureMessage(error);
     if (interaction.replied || interaction.deferred) {
         await interaction.editReply({ content: message }).catch(() => undefined);
         return;

package/dist/oauth-service.d.ts

@@ -1,4 +1,4 @@
-import type { OAuthConnectionSummary, OAuthEligibilityResult, OAuthService } from "@helyx/sdk";
+import type { OAuthConnectionSummary, OAuthConnectionIdentity, OAuthEligibilityResult, OAuthService } from "@helyx/sdk";
 export declare class HttpOAuthService implements OAuthService {
     #private;
     private readonly internalSecret;
@@ -8,7 +8,8 @@ export declare class HttpOAuthService implements OAuthService {
     }): Promise<readonly OAuthConnectionSummary[]>;
     connectionStatus(input: {
         discordUserId: string;
-    }): Promise<readonly ("youtube" | "twitch")[]>;
+        purpose?: "creator";
+    }): Promise<readonly OAuthConnectionIdentity[]>;
     createAuthorization(input: Parameters<OAuthService["createAuthorization"]>[0]): ReturnType<OAuthService["createAuthorization"]>;
     verifyEligibility(input: Parameters<OAuthService["verifyEligibility"]>[0]): Promise<OAuthEligibilityResult>;
     revoke(input: Parameters<OAuthService["revoke"]>[0]): ReturnType<OAuthService["revoke"]>;

package/dist/oauth-service.js

@@ -11,7 +11,7 @@ export class HttpOAuthService {
     }
     async connectionStatus(input) {
         const result = await this.#request("/v1/internal/oauth/status", input);
-        return result.providers;
+        return result.connections;
     }
     createAuthorization(input) {
         return this.#request("/v1/internal/oauth/authorizations", input);

package/dist/shard-supervisor.js

@@ -447,7 +447,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             shardCount,
             localShardCount: claimedIds.length,
         }, "Shard supervisor started");
-        return { shutdown };
+        return { shutdown, statusHealth: buildHealth };
     }
     catch (error) {
         await shutdown("startup-failed");

package/dist/status-producer.d.ts

@@ -0,0 +1,13 @@
+import type { StatusHeartbeatService } from "@helyx/status-client";
+import type { ShardHealthSnapshot } from "./shard-contracts.js";
+/**
+ * Reduce the private shard-health contract to the bounded state accepted by the
+ * public status service. No shard IDs, guild counts, host details or errors
+ * leave the bot process.
+ */
+export declare function discordBotStatusService(input: {
+    health: ShardHealthSnapshot;
+    processStartedAt: string;
+    release: string;
+}): StatusHeartbeatService;
+//# sourceMappingURL=status-producer.d.ts.map

package/dist/status-producer.js

@@ -0,0 +1,34 @@
+/**
+ * Reduce the private shard-health contract to the bounded state accepted by the
+ * public status service. No shard IDs, guild counts, host details or errors
+ * leave the bot process.
+ */
+export function discordBotStatusService(input) {
+    const health = input.health;
+    const dependencyUnavailable = health.coordination.database === "unavailable" ||
+        health.coordination.redis === "unavailable";
+    const noReadyWorkers = health.configuredShardCount > 0 && health.readyShardCount === 0;
+    const runtimeUnavailable = health.status === "unavailable" || dependencyUnavailable || noReadyWorkers;
+    const fullyReady = health.status === "healthy" &&
+        health.readyShardCount === health.configuredShardCount &&
+        health.scheduler?.status === "available" &&
+        !dependencyUnavailable;
+    return {
+        key: "discord-bot",
+        state: runtimeUnavailable
+            ? "major_outage"
+            : fullyReady
+                ? "operational"
+                : "degraded",
+        reasonCode: runtimeUnavailable
+            ? dependencyUnavailable
+                ? "dependency_unavailable"
+                : "runtime_not_ready"
+            : fullyReady
+                ? null
+                : "runtime_not_ready",
+        processStartedAt: input.processStartedAt,
+        release: input.release,
+    };
+}
+//# sourceMappingURL=status-producer.js.map

package/documentation/guides/self-hosting.md

@@ -11,11 +11,29 @@ database, the reviewed core packages, and independently selected modules. Keep
 module boundaries intact: a module must be installable, configurable, testable,
 and removable without relying on unrelated module behaviour.
 
+Every selectable module runs from that generated bot and its normal local
+runtime. A self-host-compatible module does not require a provider API key,
+OAuth application or separate third-party integration service. Provider-backed
+features are Hosted-only and excluded from the generated project. The Helyx
+Dashboard and optional Cloud Connect are the explicit hosted-service exceptions;
+local Discord module work continues if either is unavailable.
+
 Helyx supports Docker Compose and direct Node.js operation. The generated
 project is the source of truth for its pinned public packages and module
 catalogue. Do not copy source trees from the Helyx repository into an
 installation.
 
+Every implemented catalogue entry carries a manifest-backed deployment label
+and credential-risk label. A planned entry without a canonical v0.4 manifest
+is explicitly `unclassified`; that label makes no promise about its future
+deployment support and it cannot be selected. The builder accepts only Live
+modules whose
+`deploymentSupport` is `self-hosted` or `both`, copies that policy into the
+downloaded build manifest and resolves only eligible dependencies. The
+dashboard shows the deployment and credential label beside each selectable
+module. A `hosted` module cannot be selected or introduced by editing the
+downloaded manifest.
+
 ## Secrets and access
 
 - Store `.env` outside version control and restrict who can read it.

package/documentation/modules/building-a-module.md

@@ -30,6 +30,42 @@ must exactly match executable command contributions. Declare Discord
 permissions and privileged capabilities only when the module actually needs
 them.
 
+## Deployment and credential policy
+
+Use manifest version `0.4` and make deployment eligibility explicit:
+
+- `deploymentSupport` is `hosted`, `self-hosted` or `both`;
+- `credentialRisk` is `none`, `low`, `medium`, `high` or `very-high`; and
+- `deploymentReason` is a short internal explanation with no secret values.
+
+The classification is a release decision, not a runtime guess. A hosted-only
+manifest is rejected from self-host selection and generated projects. A
+self-host-only manifest is rejected from hosted composition. The separate
+hosted-only package list remains a defence-in-depth check and must agree with
+the canonical manifest.
+
+Self-host-compatible modules must be complete within the generated bot and
+must not require a provider credential or separate integration service. If a
+future design changes that boundary, review the deployment and credential risk
+before implementation; do not weaken the manifest to make composition pass.
+
+## Commands and dashboard policy
+
+Normal customer-module commands use
+`registrationPolicy: "enabled-guild"`, server context and guild installation.
+Helyx projects those commands only into servers that select the module; a
+module change may remain pending while the per-server Discord command update
+is coalesced. Do not use the legacy `registration: "global" | "guild"` field
+in new code. `platform-global`, `deployment` and `internal-guild` are reserved
+for their explicit platform, deployment or Helyx operational purposes.
+
+Use manifest-defined settings, dashboard actions and managed resources before
+requesting a custom interface. Keep Permissions available for module-level and
+resource access even when the module has no commands; command overrides exist
+only for real commands. Present record details as labelled sections, fields,
+lists and tables rather than serialized JSON, and provide bounded loading,
+empty, disabled, conflict and failure states.
+
 ## Preserve modularity
 
 A module owns its commands, configuration, data, migrations, health, and tests.

package/documentation/modules/testing-a-module.md

@@ -21,6 +21,11 @@ boundary values, wrong types, and missing required settings against the
 module's configuration contribution. Each dashboard setting key must have one
 matching validator field.
 
+For resources and actions, test declared operations, permissions, status
+gates, revisions, pagination and safe errors. Verify normal, empty, disabled,
+conflict and failed states, and confirm that read-only details expose labelled
+values rather than raw JSON.
+
 ## Slash commands
 
 Assert that manifest command IDs and executable command names are identical.
@@ -29,6 +34,19 @@ generated application-command payload, and execute the handler with a fake SDK
 context. Test acknowledgement, context, integration type, option limits, and a
 representative response without contacting Discord.
 
+Assert the explicit registration policy too. A normal customer-module command
+uses `enabled-guild`; new code must not use the legacy `registration` field.
+Test that disabled-module and denied-policy execution is rejected even while a
+stale command may still be visible during Discord reconciliation.
+
+## Privacy and multi-worker behaviour
+
+Test the privacy declaration and executable provider together. A provider must
+find matching retained records even when its module is disabled, and a missing
+or failed provider must not be interpreted as an empty result. Stateful
+modules also test duplicate delivery, concurrent claims, retry, restart and
+stale-worker behaviour where those failures are possible.
+
 ## Before packaging
 
 Run the module's build and test scripts, then inspect exactly what npm would

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.42",
+  "version": "0.4.43",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -53,11 +53,11 @@
     "@helyx/config": ">=0.5.0 <0.6.0",
     "@helyx/control-protocol": ">=0.4.0 <0.5.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=0.8.6 <0.9.0",
+    "@helyx/database": ">=0.9.0 <0.10.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
-    "@helyx/module-manifest": ">=0.7.0 <0.8.0",
+    "@helyx/module-manifest": ">=0.8.0 <0.9.0",
     "@helyx/platform": ">=0.6.2 <0.7.0",
-    "@helyx/sdk": ">=0.8.4 <0.9.0",
+    "@helyx/sdk": ">=0.9.0 <0.10.0",
     "@helyx/status-client": ">=0.1.0 <0.2.0",
     "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
     "discord.js": "14.27.0",