@helyx/bot 1.3.1 → 1.4.0

package/dist/shard-supervisor.js

@@ -1,5 +1,6 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, EckoOperationsRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
+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 { Client, ShardingManager } from "discord.js";
@@ -102,6 +103,7 @@ function sameNumericIdentity(left, right) {
         left.fencingToken === right.fencingToken);
 }
 export async function startShardSupervisor(environment, processEnvironment, workerEntry) {
+    assertRepositoryEngineSupported(environment.DATABASE_ENGINE, ["postgresql"], "Bot shard supervisor");
     if (environment.HELYX_SHARD_MODE === "off")
         throw new Error("Shard supervisor requires sharding to be enabled");
     const shardMode = environment.HELYX_SHARD_MODE;
@@ -185,7 +187,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             maxConcurrency: gateway.session_start_limit.max_concurrency,
             observedAt: new Date().toISOString(),
         };
-        const supervisorDirectory = new SupervisorCloudDiscordDirectory(environment.DISCORD_TOKEN, database, environment.HELYX_OWNER_USER_IDS);
+        const supervisorDirectory = new SupervisorCloudDiscordDirectory(environment.DISCORD_TOKEN, new InstallationRepository(database), environment.HELYX_OWNER_USER_IDS);
         const eckoOperations = new EckoOperationsRepository(database);
         cloudConnector = new CloudConnectorController({
             environment,
@@ -255,6 +257,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
                 approvedRoleIds: environment.APPROVED_ROLES,
                 botVersion: botVersion(),
+                databaseEngine: environment.DATABASE_ENGINE,
                 ...(processEnvironment.RAILWAY_GIT_COMMIT_SHA
                     ? {
                         deploymentReference: processEnvironment.RAILWAY_GIT_COMMIT_SHA.slice(0, 12),
@@ -282,6 +285,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             ...(operationsModule ? [operationsModule] : []),
         ];
         commandModules = modules;
+        const guildCommandReads = new GuildCommandReadService(database, environment.DISCORD_CLIENT_ID, () => guildCommandWorker?.getHealth(), environment.DISCORD_TOKEN, environment.HELYX_GUILD_COMMAND_WRITES_ENABLED, environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS, environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all", commandModules);
         const availabilityModules = availabilityCatalogueDefinitions(modules);
         const statusModules = statusCatalogueDefinitions(featureModules);
         let runtimeAvailability;
@@ -328,7 +332,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                         notificationGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
                     }
                     : {}),
-            }));
+            }), guildCommandReads);
             await startLeaderSingletons();
             assertStartupLeaseHealthy();
         };
@@ -425,7 +429,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 : {}),
         });
         if (!leaderLease)
-            cloudConnector.setControlHandler(router);
+            cloudConnector.setControlHandler(router, guildCommandReads);
         const claimedIds = await claimInitialShards();
         manager = new ShardingManager(workerEntry, {
             totalShards: shardCount,
@@ -480,7 +484,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 },
                 shardHealth: buildHealth,
                 readiness: buildDeploymentReadiness,
-                guildCommands: new GuildCommandReadService(database, environment.DISCORD_CLIENT_ID, () => guildCommandWorker?.getHealth(), environment.DISCORD_TOKEN, environment.HELYX_GUILD_COMMAND_WRITES_ENABLED, environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS, environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all", commandModules),
+                guildCommands: guildCommandReads,
                 ...(ecko ? { ecko } : {}),
             });
             await controlServer.listen({
@@ -1529,12 +1533,31 @@ export function splitNumericCommittedBatch(batch, index) {
     };
 }
 async function runLeaderStartup(database, environment, modulePackages, modules, logger) {
-    await runCoreMigrations(database);
-    await runConfiguredModuleMigrations(database, modulePackages.map(({ definition, packageRoot }) => ({
+    const moduleMigrationSources = modulePackages.map(({ definition, packageRoot }) => ({
         moduleId: definition.manifest.id,
         moduleVersion: definition.manifest.version,
         migrationsDirectory: join(packageRoot, "migrations"),
-    })));
+    }));
+    if (environment.HELYX_RUNTIME_PROFILE === "hosted" &&
+        modulePackages.some(({ definition }) => definition.manifest.id === "helyx.creator-connections")) {
+        if (environment.HELYX_DATABASE_STARTUP_MODE === "inspect") {
+            const inspection = await inspectCreatorOnboardingMigrations(database);
+            assertNoPendingLeaderMigrations("hosted creator onboarding", inspection.pending);
+        }
+        else
+            await runCreatorOnboardingMigrations(database);
+    }
+    if (environment.HELYX_DATABASE_STARTUP_MODE === "inspect") {
+        const coreInspection = await inspectCoreMigrations(database);
+        assertNoPendingLeaderMigrations("core", coreInspection.pending);
+        const moduleInspections = await inspectConfiguredModuleMigrations(database, moduleMigrationSources);
+        for (const inspection of moduleInspections)
+            assertNoPendingLeaderMigrations(`module ${inspection.moduleId}`, inspection.pending);
+    }
+    else {
+        await runCoreMigrations(database);
+        await runConfiguredModuleMigrations(database, moduleMigrationSources);
+    }
     await enforcePremiumCatalogue(database, logger);
     const repository = new RuntimeStateRepository(database);
     await synchroniseApplicationCommands({
@@ -1545,7 +1568,8 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
         ...(environment.DISCORD_INTERNAL_GUILD_ID
             ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
             : {}),
-        synchroniseInternalGuild: !environment.HELYX_GUILD_COMMAND_WRITES_ENABLED,
+        // 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`, {
@@ -1554,6 +1578,10 @@ async function runLeaderStartup(database, environment, modulePackages, modules,
     });
     logger.info({ event: "shard.singleton_startup_complete" }, "Shard singleton startup complete");
 }
+function assertNoPendingLeaderMigrations(scope, pending) {
+    if (pending.length > 0)
+        throw new Error(`Hosted ${scope} migrations must be applied by the dedicated primary migration identity before bot startup: ${pending.join(", ")}`);
+}
 class RuntimeCommandHashStore {
     repository;
     constructor(repository) {
@@ -1635,6 +1663,7 @@ async function fetchGatewayBotInformation(token) {
 }
 export function buildShardWorkerEnvironment(source, identity, restartCount) {
     const allowed = new Set([
+        "DATABASE_ENGINE",
         "DATABASE_URL",
         "DATABASE_SSL",
         "DISCORD_TOKEN",
@@ -1680,8 +1709,13 @@ 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 hostedModerationCredential = source.HELYX_HOSTED_MODERATION_ENABLED === "true" &&
+        source.HELYX_BOT_CONTROL_SECRET
+        ? { HELYX_BOT_CONTROL_SECRET: source.HELYX_BOT_CONTROL_SECRET }
+        : {};
     return {
         ...environment,
+        ...hostedModerationCredential,
         ...(selectionKey
             ? { [secureRandomSelectionWorkerKeyName]: selectionKey }
             : {}),

package/dist/shard-worker.d.ts

@@ -28,8 +28,6 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_SHARD_WORKERS_PER_REPLICA: number;
     HELYX_SHARD_SUPERVISOR_DATABASE_POOL_MAX: number | undefined;
     HELYX_SHARD_WORKER_DATABASE_POOL_MAX: number | undefined;
-    DATABASE_URL: string;
-    DATABASE_SSL: "disable" | "require" | "verify-full";
     HELYX_RUNTIME_PROFILE: "hosted" | "self-hosted";
     DISCORD_TOKEN: string;
     DISCORD_CLIENT_ID: string;
@@ -70,6 +68,10 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_CLOUD_CREDENTIAL_AUDIT_RETENTION_DAYS: number;
     LOG_LEVEL: "error" | "fatal" | "warn" | "info" | "debug" | "trace" | "silent";
     NODE_ENV: "development" | "test" | "production";
+    DATABASE_ENGINE: "postgresql" | "mysql";
+    DATABASE_URL: string;
+    DATABASE_SSL: "disable" | "require" | "verify-full";
+    HELYX_DATABASE_STARTUP_MODE: "apply" | "inspect";
     HELYX_STATUS_ENABLED: boolean;
     HELYX_STATUS_URL: string;
     HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS: number;
@@ -80,6 +82,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_SUPPORT_SERVICE_SECRET?: string | undefined;
     HELYX_VERIFICATION_INSTALLATION_ID?: string | undefined;
     HELYX_VERIFICATION_URL?: string | undefined;
+    HELYX_VERIFICATION_PUBLIC_URL?: string | undefined;
     HELYX_VERIFICATION_INTERNAL_SECRET?: string | undefined;
     HELYX_GUILD_COMMAND_RELEASE_ID?: string | undefined;
     HELYX_PRIVACY_EXECUTOR_DATABASE_URL?: string | undefined;

package/dist/shard-worker.js

@@ -1,6 +1,7 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, } from "@helyx/database";
+import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
@@ -13,6 +14,7 @@ import { BotControlService, BotControlTransportError, DiscordGuildResourceDirect
 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 { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
 import { createManagementModule } from "./management-module.js";
@@ -64,6 +66,7 @@ export function createLeaseHeartbeatWatchdog(onExpired, timeoutMs = SHARD_LEASE_
 }
 export async function startShardWorker(processEnvironment = process.env, identity = parseShardWorkerLaunchContract(processEnvironment.HELYX_SHARD_WORKER_CONTRACT)) {
     const environment = parseShardWorkerEnvironment(processEnvironment, identity);
+    assertRepositoryEngineSupported(environment.DATABASE_ENGINE, ["postgresql"], "Bot shard worker");
     const logger = pino({
         level: environment.LOG_LEVEL,
         base: {
@@ -109,14 +112,16 @@ export async function startShardWorker(processEnvironment = process.env, identit
     let hostedLeaveWorker;
     let leaseHeartbeatWatchdog;
     let forcedLeaseExit;
+    let creatorInvitePlatform;
     let numericWriteBehind;
     async function shutdown(reason = "programmatic") {
         if (shuttingDown)
             return;
         shuttingDown = true;
         status = "stopped";
-        guildTracking?.stop();
+        await guildTracking?.stop();
         await hostedLeaveWorker?.stop();
+        await creatorInvitePlatform?.stop();
         if (healthTimer)
             clearInterval(healthTimer);
         leaseHeartbeatWatchdog?.stop();
@@ -193,6 +198,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID,
                 approvedRoleIds: environment.APPROVED_ROLES,
                 botVersion: readBotVersion(),
+                databaseEngine: environment.DATABASE_ENGINE,
                 ...(processEnvironment.RAILWAY_GIT_COMMIT_SHA
                     ? {
                         deploymentReference: processEnvironment.RAILWAY_GIT_COMMIT_SHA.slice(0, 12),
@@ -232,6 +238,15 @@ export async function startShardWorker(processEnvironment = process.env, identit
         })) {
             platformServices.set(name, service);
         }
+        const applicationUrls = serviceAccess.get(HELYX_SERVICE_NAMES.applicationUrls);
+        platformServices.set(HELYX_SERVICE_NAMES.applicationUrls, {
+            dashboardBaseUrl: applicationUrls.dashboardBaseUrl,
+            get dashboardInstallationId() {
+                return environment.HELYX_RUNTIME_PROFILE === "self-hosted"
+                    ? cloudProxy?.status().installationId
+                    : undefined;
+            },
+        });
         await serviceAccess
             .get(HELYX_SERVICE_NAMES.moduleAvailability)
             .refresh();
@@ -262,6 +277,25 @@ export async function startShardWorker(processEnvironment = process.env, identit
         platformServices.set(HELYX_SERVICE_NAMES.memberRoles, memberRoles);
         platformServices.set(HELYX_SERVICE_NAMES.memberRoleGrants, new PlatformMemberRoleGrantOwnershipService(new PostgresMemberRoleGrantOwnershipStore(database), memberRoles));
         platformServices.set(HELYX_SERVICE_NAMES.discordResources, new DiscordResourceInspection(client));
+        if (environment.HELYX_RUNTIME_PROFILE === "hosted")
+            creatorInvitePlatform = await installCreatorInvitePlatform({
+                client,
+                database,
+                services: serviceAccess,
+                modules: publicModules,
+                encryptionKey: environment.HELYX_DATA_ENCRYPTION_KEY,
+                ...(environment.HELYX_CLOUD_API_URL &&
+                    environment.HELYX_OAUTH_INTERNAL_SECRET
+                    ? {
+                        oauthBroker: {
+                            baseUrl: environment.HELYX_CLOUD_API_URL,
+                            secret: environment.HELYX_OAUTH_INTERNAL_SECRET,
+                        },
+                    }
+                    : {}),
+                register: (name, service) => platformServices.set(name, service),
+                warn: (event) => logger.warn({ event }, "Creator invite cleanup will retry"),
+            });
         const moderationPlatformServices = await installModerationPlatformServices({
             services: platformServices,
             serviceAccess,
@@ -310,10 +344,12 @@ export async function startShardWorker(processEnvironment = process.env, identit
         };
         const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount, environment.DISCORD_CLIENT_ID, hostedSafety, hostedInviteGate, hostedOwnerObserver);
         guildTracking = prepareGuilds;
-        hostedLeaveWorker = new HostedServerLeaveWorker(database, client, logger, {
-            shardId: identity.shardId,
-            shardCount: identity.shardCount,
-        });
+        hostedLeaveWorker = environment.HELYX_HOSTED_MODERATION_ENABLED
+            ? new HostedServerLeaveWorker(database, client, logger, {
+                shardId: identity.shardId,
+                shardCount: identity.shardCount,
+            })
+            : undefined;
         const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }

package/dist/supervisor-cloud-directory.d.ts

@@ -1,11 +1,17 @@
-import type { DatabasePool } from "@helyx/database";
 import type { CloudDiscordDirectory, CloudDiscordSnapshot } from "./cloud-connector.js";
 export declare const CLOUD_HELLO_GUILD_LIMIT = 1000;
+export interface SupervisorInstallationDirectory {
+    listActiveGuilds(): Promise<readonly {
+        guildId: string;
+        name: string | null;
+        ownerUserId: string | null;
+    }[]>;
+}
 export declare class SupervisorCloudDiscordDirectory implements CloudDiscordDirectory {
     #private;
-    private readonly database;
+    private readonly installations;
     private readonly configuredOwnerUserIds;
-    constructor(token: string, database: DatabasePool, configuredOwnerUserIds: readonly string[]);
+    constructor(token: string, installations: SupervisorInstallationDirectory, configuredOwnerUserIds: readonly string[]);
     snapshot(): Promise<CloudDiscordSnapshot>;
 }
 //# sourceMappingURL=supervisor-cloud-directory.d.ts.map

package/dist/supervisor-cloud-directory.js

@@ -25,23 +25,19 @@ const userSchema = z
     .object({ id: snowflake, username: z.string().min(1).max(100) })
     .passthrough();
 export class SupervisorCloudDiscordDirectory {
-    database;
+    installations;
     configuredOwnerUserIds;
     #rest;
-    constructor(token, database, configuredOwnerUserIds) {
-        this.database = database;
+    constructor(token, installations, configuredOwnerUserIds) {
+        this.installations = installations;
         this.configuredOwnerUserIds = configuredOwnerUserIds;
         this.#rest = new REST({ version: "10" }).setToken(token);
     }
     async snapshot() {
-        const [applicationValue, botValue, guildResult] = await Promise.all([
+        const [applicationValue, botValue, activeGuilds] = await Promise.all([
             this.#rest.get(Routes.oauth2CurrentApplication()),
             this.#rest.get(Routes.user("@me")),
-            this.database.query(`SELECT guild_id, name, owner_user_id
-           FROM discord_guilds
-          WHERE active = true
-          ORDER BY guild_id
-           LIMIT ${String(CLOUD_HELLO_GUILD_LIMIT)}`),
+            this.installations.listActiveGuilds(),
         ]);
         const application = applicationSchema.parse(applicationValue);
         const bot = userSchema.parse(botValue);
@@ -55,10 +51,10 @@ export class SupervisorCloudDiscordDirectory {
             ownerUserIds: [
                 ...new Set([...this.configuredOwnerUserIds, ...applicationOwnerIds]),
             ],
-            guilds: guildResult.rows.map((guild) => ({
-                guildId: guild.guild_id,
+            guilds: activeGuilds.slice(0, CLOUD_HELLO_GUILD_LIMIT).map((guild) => ({
+                guildId: guild.guildId,
                 name: guild.name ?? "Unknown server",
-                ownerUserId: guild.owner_user_id,
+                ownerUserId: guild.ownerUserId,
             })),
         };
     }

package/dist/trivia-data-provider.d.ts

@@ -18,9 +18,20 @@ export interface TriviaDataSummary {
 export interface TriviaDataProvider {
     getSummary(): Promise<TriviaDataSummary>;
 }
+interface MysqlTriviaExecutor {
+    query<Row extends Record<string, unknown>>(sql: string): Promise<{
+        rows: readonly Row[];
+    }>;
+}
 export declare class PostgresTriviaDataProvider implements TriviaDataProvider {
     #private;
     constructor(database: DatabasePool);
     getSummary(): Promise<TriviaDataSummary>;
 }
+export declare class MysqlTriviaDataProvider implements TriviaDataProvider {
+    #private;
+    constructor(database: MysqlTriviaExecutor);
+    getSummary(): Promise<TriviaDataSummary>;
+}
+export {};
 //# sourceMappingURL=trivia-data-provider.d.ts.map

package/dist/trivia-data-provider.js

@@ -14,34 +14,54 @@ export class PostgresTriviaDataProvider {
           GROUP BY category, difficulty, type
           ORDER BY category, difficulty, type`),
         ]);
-        const counts = new Map();
-        for (const row of countResult.rows) {
-            if (!TRIVIA_CATEGORIES.includes(row.category) ||
-                !difficulties.includes(row.difficulty) ||
-                !["text_choice", "text_input", "true_false"].includes(row.type))
-                throw new Error("Trivia data contains an unsupported group");
-            counts.set(`${row.category}:${row.difficulty}`, (counts.get(`${row.category}:${row.difficulty}`) ?? 0) +
-                nonNegativeInteger(row.questions, "Trivia question count"));
-        }
-        const typeCount = (type) => countResult.rows
-            .filter((row) => row.type === type)
-            .reduce((total, row) => total + nonNegativeInteger(row.questions, "Trivia type count"), 0);
-        return {
-            uniqueQuestions: nonNegativeInteger(uniqueResult.rows[0]?.unique_questions, "Unique trivia question count"),
-            types: {
-                multipleChoice: typeCount("text_choice"),
-                guess: typeCount("text_input"),
-                trueFalse: typeCount("true_false"),
-            },
-            categories: TRIVIA_CATEGORIES.map((category) => ({
-                category,
-                easy: counts.get(`${category}:easy`) ?? 0,
-                medium: counts.get(`${category}:medium`) ?? 0,
-                hard: counts.get(`${category}:hard`) ?? 0,
-            })),
-        };
+        return summarizeTriviaData(uniqueResult.rows[0]?.unique_questions, countResult.rows);
     }
 }
+export class MysqlTriviaDataProvider {
+    #database;
+    constructor(database) {
+        this.#database = database;
+    }
+    async getSummary() {
+        const [uniqueResult, countResult] = await Promise.all([
+            this.#database.query(`SELECT count(DISTINCT lower(trim(JSON_UNQUOTE(JSON_EXTRACT(question, '$.text'))))) AS unique_questions
+           FROM trivia_questions`),
+            this.#database.query(`SELECT category, difficulty, type, count(*) AS questions
+           FROM trivia_questions
+          GROUP BY category, difficulty, type
+          ORDER BY category, difficulty, type`),
+        ]);
+        return summarizeTriviaData(uniqueResult.rows[0]?.unique_questions, countResult.rows);
+    }
+}
+function summarizeTriviaData(uniqueQuestions, groupedRows) {
+    const counts = new Map();
+    for (const row of groupedRows) {
+        if (!TRIVIA_CATEGORIES.includes(row.category) ||
+            !difficulties.includes(row.difficulty) ||
+            !["text_choice", "text_input", "true_false"].includes(row.type))
+            throw new Error("Trivia data contains an unsupported group");
+        counts.set(`${row.category}:${row.difficulty}`, (counts.get(`${row.category}:${row.difficulty}`) ?? 0) +
+            nonNegativeInteger(row.questions, "Trivia question count"));
+    }
+    const typeCount = (type) => groupedRows
+        .filter((row) => row.type === type)
+        .reduce((total, row) => total + nonNegativeInteger(row.questions, "Trivia type count"), 0);
+    return {
+        uniqueQuestions: nonNegativeInteger(uniqueQuestions, "Unique trivia question count"),
+        types: {
+            multipleChoice: typeCount("text_choice"),
+            guess: typeCount("text_input"),
+            trueFalse: typeCount("true_false"),
+        },
+        categories: TRIVIA_CATEGORIES.map((category) => ({
+            category,
+            easy: counts.get(`${category}:easy`) ?? 0,
+            medium: counts.get(`${category}:medium`) ?? 0,
+            hard: counts.get(`${category}:hard`) ?? 0,
+        })),
+    };
+}
 function nonNegativeInteger(value, label) {
     const parsed = typeof value === "string" ? Number(value) : value;
     if (typeof parsed !== "number" || !Number.isSafeInteger(parsed) || parsed < 0)

package/dist/verification-service.d.ts

@@ -1,6 +1,6 @@
-import { type ActionReceipt, type ChallengeCreateRequest, type ChallengeCreateResponse, type DashboardAttemptPage, type DashboardAttemptQuery, type DashboardSafeAttemptDetail, type SignedAssessmentEnvelope, type VerificationInstallationClaims } from "@helyx/verification-contracts";
+import { type ActionReceipt, type ChallengeCreateRequest, type ChallengeCreateResponse, type DashboardAttemptPage, type DashboardAttemptQuery, type DashboardSafeAttemptDetail, type SignedAssessmentEnvelope, type VerificationInstallationClaims, type VerificationResponseUrlOptions } from "@helyx/verification-contracts";
 import type { VerificationResultContext, VerificationService } from "@helyx/sdk";
-export interface HttpVerificationServiceOptions {
+export interface HttpVerificationServiceOptions extends VerificationResponseUrlOptions {
     baseUrl: string;
     internalSecret: string;
     publicSigningKeys: Readonly<Record<string, string>>;

package/dist/verification-service.js

@@ -1,4 +1,4 @@
-import { actionReceiptSchema, challengeCreateRequestSchema, challengeCreateResponseSchema, dashboardAttemptPageSchema, dashboardAttemptQuerySchema, dashboardSafeAttemptDetailSchema, signedAssessmentEnvelopeSchema, } from "@helyx/verification-contracts";
+import { actionReceiptSchema, challengeCreateRequestSchema, createChallengeCreateResponseSchema, dashboardAttemptPageSchema, dashboardAttemptQuerySchema, dashboardSafeAttemptDetailSchema, signedAssessmentEnvelopeSchema, } from "@helyx/verification-contracts";
 import { VerificationChallengeActiveError } from "@helyx/sdk";
 import { createPublicKey, verify } from "node:crypto";
 import { z } from "zod";
@@ -21,6 +21,7 @@ export class HttpVerificationService {
     #publicSigningKeys;
     #fetch;
     #installationId;
+    #challengeResponseSchema;
     #challengeCache = new Map();
     #handler;
     constructor(options) {
@@ -29,6 +30,8 @@ export class HttpVerificationService {
         this.#publicSigningKeys = { ...options.publicSigningKeys };
         this.#installationId = options.installationId;
         this.#fetch = options.fetchImplementation ?? fetch;
+        this.#challengeResponseSchema =
+            createChallengeCreateResponseSchema(options);
     }
     getInstallationContext() {
         return Promise.resolve({
@@ -54,9 +57,9 @@ export class HttpVerificationService {
         if (input.replaceActive !== true &&
             cached &&
             Date.parse(cached.expiresAt) > Date.now()) {
-            return challengeCreateResponseSchema.parse({ ...cached, reused: true });
+            return this.#challengeResponseSchema.parse({ ...cached, reused: true });
         }
-        const created = challengeCreateResponseSchema.parse(await this.#request("/internal/v1/challenges", {
+        const created = this.#challengeResponseSchema.parse(await this.#request("/internal/v1/challenges", {
             method: "POST",
             body: challengeCreateRequestSchema.parse(input),
         }));

package/documentation/README.md

@@ -23,9 +23,11 @@ and module guides.
 - [Operate the Moderation module](modules/moderation.md)
 - [Operate the Auto Moderation module](modules/auto-moderation.md)
 
-The complete working example is published separately as
-`@helyx/module-example`. It is intentionally independent: module-specific
-commands, settings, tests, and lifecycle behaviour remain inside that module.
+The standalone authoring reference is published separately as
+`@helyx/module-example`. Adapt its compatibility manifest and compose the
+required privacy contribution before bot installation, as described in
+[the author guide](modules/building-a-module.md). Module-specific commands,
+settings, tests and lifecycle behaviour remain inside that module.
 
 ## Choose the right path
 

package/documentation/examples/.env.example

@@ -10,7 +10,8 @@ DISCORD_CLIENT_ID=12345678901234567
 # requires message content and it is enabled in the Discord developer portal.
 HELYX_MESSAGE_CONTENT_ENABLED=false
 # Enhanced Auto Moderation stays inside this bot process. One worker is the
-# recommended default; increase only after measuring local CPU and memory.
+# recommended default (range 1-4); increase only after measuring CPU and memory.
+# Hosted scanning uses the separate Helyx Ecko service, not these settings.
 HELYX_AUTOMOD_EMBEDDED_WORKERS=1
 # Optional conservative queue overrides (hard ceilings: 5000 items, 64 MiB,
 # 100 items per server). Defaults are used when these remain commented.
@@ -18,13 +19,19 @@ HELYX_AUTOMOD_EMBEDDED_WORKERS=1
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES=67108864
 # HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD=100
 # HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS=300
-# Enable only when member inspection modules are loaded and the Discord Server
-# Members Intent is enabled in the Discord developer portal.
+# Enable for loaded member workflows such as Welcome, Access Control or Levels,
+# with Server Members Intent also enabled in the Discord developer portal.
 HELYX_GUILD_MEMBERS_ENABLED=false
 # Database
 # Docker: keep the URL. Direct Node.js/managed hosting: use your provider URL.
+DATABASE_ENGINE=postgresql
 DATABASE_URL=postgresql://database:5432/helyx
 DATABASE_SSL=disable
+# Self-host startup applies pending migrations automatically (the default).
+# Hosted-only inspect mode is not a self-host setting; leave this commented.
+# HELYX_DATABASE_STARTUP_MODE=apply
+# Match your provider: disable=no TLS; require=TLS without certificate
+# verification; verify-full=TLS with certificate verification.
 
 # Included Docker database — both password values must match.
 PGUSER=helyx
@@ -51,8 +58,8 @@ LOG_LEVEL=info
 # SHARDING: OFF BY DEFAULT
 
 # `off` is the compatible self-host default. Keep shard-only values commented
-# in this mode; an empty value is still rejected as configured. Advanced local
-# self-hosting may use `auto` to obtain Discord's recommendation under one
+# in this mode; an empty value is still rejected as configured. MySQL must stay
+# off. Advanced PostgreSQL self-hosting may use `auto` under one
 # supervisor, or `fixed` with a deliberate total count. Local mode never needs
 # Redis. Coordinated multi-host self-hosting is outside the first release.
 HELYX_SHARD_MODE=off
@@ -80,18 +87,15 @@ HELYX_SHARD_MODE=off
 HELYX_HOSTED_MODERATION_ENABLED=false
 
 # Guild command writes remain off until explicitly enabled for known guild IDs.
+# For enabled-module server commands, set writes=true, retain allowlist scope,
+# add comma-separated Discord server IDs below, and use global mode platform-only.
+# See README.md before changing these defaults. Legacy mode still allows globals.
 HELYX_GUILD_COMMAND_WRITES_ENABLED=false
 HELYX_GUILD_COMMAND_WRITE_SCOPE=allowlist
 # HELYX_GUILD_COMMAND_RELEASE_ID=
 HELYX_GLOBAL_COMMAND_MODE=legacy
 # HELYX_GUILD_COMMAND_WRITE_GUILD_IDS=
 
-# Privacy tooling ships with self-hosted Helyx but stays disabled until the
-# dedicated least-privilege executor connection has been configured.
-HELYX_PRIVACY_ENABLED=false
-# HELYX_PRIVACY_EXECUTOR_DATABASE_URL=<dedicated-privacy-executor-postgresql-url>
-# HELYX_PRIVACY_EXECUTOR_DATABASE_SSL=disable
-
 # Alternative Cloud Connect enrolment — the Discord command is preferred
 # HELYX_CLOUD_ENROLMENT_TOKEN=replace-with-a-short-lived-enrolment-code
 # HELYX_CLOUD_ENROLMENT_FILE=./helyx.cloud-enrolment.json