@helyx/bot 1.0.1 → 1.2.0

package/dist/shard-supervisor.js

@@ -1,7 +1,7 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, HostedServerSafetyRepository, InteractionSessionRepository, EckoOperationsRepository, PremiumAllocationRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
-import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
 import { createHash, randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
@@ -19,6 +19,11 @@ import { createPermissionsModule } from "./permissions-module.js";
 import { SHARD_CONTROL_MAX_BYTES, SHARD_CONTROL_TIMEOUT_MS, SHARD_HEALTH_STALE_MS, assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, gatewayBotInformationSchema, guildIdToShardId, shardCloudRequestSchema, shardHealthSnapshotSchema, workerMessageSchema, } from "./shard-contracts.js";
 import { RedisShardCoordinator, } from "./shard-coordinator.js";
 import { ShardControlRouter } from "./shard-router.js";
+import { BotAutoModerationScannerRegistry } from "./auto-moderation-scanner-registry.js";
+import { ShardEckoScannerRegistry } from "./shard-ecko-scanner-registry.js";
+import { EckoEvidenceReceiver } from "./ecko-evidence-receiver.js";
+import { EckoTransportAuthenticator } from "./ecko-transport-auth.js";
+import { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
 import { createDeveloperOperationsModule } from "./developer-operations-module.js";
 import { SupervisorCloudDiscordDirectory } from "./supervisor-cloud-directory.js";
 import { createSupportModule } from "./support-module.js";
@@ -148,6 +153,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
     let deploymentOrder = 1;
     let shardCount = 1;
     let privacyService;
+    let leaderScannerRegistry;
     let manager;
     let scheduledTasks;
     let guildCommandWorker;
@@ -180,6 +186,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             observedAt: new Date().toISOString(),
         };
         const supervisorDirectory = new SupervisorCloudDiscordDirectory(environment.DISCORD_TOKEN, database, environment.HELYX_OWNER_USER_IDS);
+        const eckoOperations = new EckoOperationsRepository(database);
         cloudConnector = new CloudConnectorController({
             environment,
             database,
@@ -288,6 +295,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             assertStartupLeaseHealthy();
             const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
             runtimeAvailability = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
+            leaderScannerRegistry = new BotAutoModerationScannerRegistry(publicModules, new ServiceRegistry(services), "hosted", undefined, environment.HELYX_DEPLOYMENT_ENVIRONMENT);
             if (numericWriteBehind)
                 services.set(HELYX_SERVICE_NAMES.numericWriteBehind, numericWriteBehind);
             privacyService = new BotControlService(database, [
@@ -311,6 +319,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 localLeases,
                 dispatchLocal,
                 privacy: privacyService,
+                leaderScannerRegistry,
                 availability: availabilityService,
                 localLeaderLease: leaderLease,
                 ...(coordinator ? { coordinator } : {}),
@@ -405,6 +414,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             localLeases,
             dispatchLocal,
             ...(privacyService ? { privacy: privacyService } : {}),
+            ...(leaderScannerRegistry ? { leaderScannerRegistry } : {}),
             availability: availabilityService,
             ...(leaderLease ? { localLeaderLease: leaderLease } : {}),
             ...(coordinator ? { coordinator } : {}),
@@ -437,13 +447,41 @@ export async function startShardSupervisor(environment, processEnvironment, work
             startScheduledTasks();
         assertStartupLeaseHealthy();
         if (environment.HELYX_BOT_CONTROL_SECRET) {
+            const supervisorEvidenceStore = new TransientViolationEvidenceStore();
+            const shardEckoRegistry = new ShardEckoScannerRegistry({
+                configurationRegistry: () => leaderScannerRegistry,
+                routeConfiguration: (input) => router.getHostedEckoConfigurationPage(input),
+                evidenceStore: supervisorEvidenceStore,
+                routeResult: (input) => router.acceptHostedEckoResult(input),
+            });
+            const ecko = environment.HELYX_ECKO_TRANSPORT_SECRET
+                ? {
+                    authenticator: new EckoTransportAuthenticator(environment.HELYX_DEPLOYMENT_ENVIRONMENT, [
+                        environment.HELYX_ECKO_TRANSPORT_SECRET,
+                        ...(environment.HELYX_ECKO_TRANSPORT_PREVIOUS_SECRET
+                            ? [environment.HELYX_ECKO_TRANSPORT_PREVIOUS_SECRET]
+                            : []),
+                    ]),
+                    registry: shardEckoRegistry,
+                    evidence: new EckoEvidenceReceiver(supervisorEvidenceStore, environment.HELYX_DEPLOYMENT_ENVIRONMENT, Buffer.from(environment.HELYX_ECKO_TRANSPORT_SECRET, "base64")),
+                    gateState: () => eckoOperations.readGate(),
+                    telemetry: {
+                        accept: (batch) => eckoOperations.acceptTelemetry(batch),
+                    },
+                }
+                : undefined;
             controlServer = await createBotControlServer({
                 service: router,
                 secret: environment.HELYX_BOT_CONTROL_SECRET,
+                ...shardHostedControlCallbacks(router),
                 logger: { level: environment.LOG_LEVEL },
+                runtimeConfiguration: {
+                    hostedModerationEnabled: environment.HELYX_HOSTED_MODERATION_ENABLED,
+                },
                 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),
+                ...(ecko ? { ecko } : {}),
             });
             await controlServer.listen({
                 host: "::",
@@ -855,7 +893,10 @@ export async function startShardSupervisor(environment, processEnvironment, work
         });
     }
     async function executeLeaderControl(request) {
-        if (!leaderLease || !privacyService)
+        if (!leaderLease ||
+            !privacyService ||
+            (request.operation.kind === "automod.enhanced.configuration.page" &&
+                !leaderScannerRegistry))
             return unavailableControl(request.requestId);
         if (request.generation !== leaderLease.generation ||
             request.fencingToken !== leaderLease.fencingToken ||
@@ -867,7 +908,22 @@ export async function startShardSupervisor(environment, processEnvironment, work
                 type: "helyx.control.response",
                 requestId: request.requestId,
                 ok: true,
-                result: await executeShardControlOperation(privacyService, request.operation),
+                result: request.operation.kind === "automod.enhanced.configuration.page"
+                    ? await leaderScannerRegistry?.getConfigurationPage({
+                        adapter: "hosted_ecko",
+                        providerId: AUTOMOD_ENHANCED_PROVIDER_ID,
+                        contractVersion: AUTOMOD_ENHANCED_CONTRACT_VERSION,
+                        limit: request.operation.limit,
+                        ...(request.operation.cursor
+                            ? { cursor: request.operation.cursor }
+                            : {}),
+                        ...(request.operation.knownFingerprint
+                            ? {
+                                knownFingerprint: request.operation.knownFingerprint,
+                            }
+                            : {}),
+                    })
+                    : await executeShardControlOperation(privacyService, request.operation),
             };
         }
         catch (error) {
@@ -1454,6 +1510,12 @@ export async function startShardSupervisor(environment, processEnvironment, work
         logger.info({ event: "shard.supervisor_stopped", reason }, "Shard supervisor stopped");
     }
 }
+export function shardHostedControlCallbacks(router) {
+    return {
+        deliverHostedServerLeave: (input) => router.deliverHostedServerLeave(input),
+        refreshHostedServerOwner: (guildId) => router.refreshHostedServerOwner(guildId),
+    };
+}
 export function splitNumericCommittedBatch(batch, index) {
     const mutation = batch.mutations[index];
     const result = batch.results[index];
@@ -1583,6 +1645,7 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         "HELYX_MESSAGE_CONTENT_ENABLED",
         "HELYX_GUILD_MEMBERS_ENABLED",
         "HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS",
+        "HELYX_HOSTED_MODERATION_ENABLED",
         "HELYX_MODULE_CATALOGUE_PATH",
         "STRIPE_ENVIRONMENT",
         "HELYX_CLOUD_CONNECT_ENABLED",
@@ -1697,11 +1760,12 @@ function failedCloud(requestId, message) {
 }
 async function cleanupExpiredCoreRecords(database, logger) {
     try {
-        const [sessions, rateLimits, verificationAudit, commandRecords] = await Promise.all([
+        const [sessions, rateLimits, verificationAudit, commandRecords, hostedLeaveDeliveries,] = await Promise.all([
             new InteractionSessionRepository(database).deleteExpired(),
             new RateLimitRepository(database).deleteExpired(),
             new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
             new GuildCommandRepository(database).deleteExpired(12),
+            new HostedServerSafetyRepository(database).deleteTerminalLeaveDeliveriesOlderThanMonths(24),
         ]);
         const commandRecordCount = commandRecords.history +
             commandRecords.idempotencyKeys +
@@ -1710,13 +1774,15 @@ async function cleanupExpiredCoreRecords(database, logger) {
         if (sessions > 0 ||
             rateLimits > 0 ||
             verificationAudit > 0 ||
-            commandRecordCount > 0)
+            commandRecordCount > 0 ||
+            hostedLeaveDeliveries > 0)
             logger.info({
                 event: "database.retention_cleaned",
                 interactionSessions: sessions,
                 rateLimitWindows: rateLimits,
                 verificationAuditEvents: verificationAudit,
                 commandRecords: commandRecordCount,
+                hostedLeaveDeliveries,
             }, "Expired core records removed");
     }
     catch (error) {

package/dist/shard-worker.d.ts

@@ -1,5 +1,7 @@
 import { type CommandRegistration } from "./interactions.js";
-import { type ShardIdentity, type ShardScheduledTaskRequest, type ShardScheduledTaskResponse } from "./shard-contracts.js";
+import type { BotAutoModerationScannerRegistry } from "./auto-moderation-scanner-registry.js";
+import type { TransientViolationEvidenceStore } from "./transient-violation-evidence.js";
+import { type ShardControlOperation, type ShardIdentity, type ShardScheduledTaskRequest, type ShardScheduledTaskResponse } from "./shard-contracts.js";
 import { type BotHandle } from "./index.js";
 import { type ScheduledTaskRoute } from "./scheduled-task-runner.js";
 export declare const WORKER_ORPHAN_TERMINATION_BOUND_MS: number;
@@ -28,6 +30,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     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;
     DISCORD_INTERNAL_GUILD_ID: string | undefined;
@@ -35,6 +38,8 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_MODULE_PACKAGES: string[];
     HELYX_MODULE_CATALOGUE_PATH: string | undefined;
     HELYX_DASHBOARD_PUBLIC_URL: string;
+    HELYX_DEPLOYMENT_ENVIRONMENT: string;
+    HELYX_HOSTED_MODERATION_ENABLED: boolean;
     HELYX_SUPPORT_STAFF_CHANNEL_ID: string | undefined;
     HELYX_VERIFICATION_ENABLED: boolean;
     HELYX_VERIFICATION_SIGNING_PUBLIC_KEYS: Record<string, string>;
@@ -46,6 +51,11 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_GUILD_COMMAND_WRITE_GUILD_IDS: string[];
     HELYX_PRIVACY_ENABLED: boolean;
     HELYX_MESSAGE_CONTENT_ENABLED: boolean;
+    HELYX_AUTOMOD_EMBEDDED_WORKERS: number;
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS: number;
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES: number;
+    HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD: number;
+    HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS: number;
     HELYX_GUILD_MEMBERS_ENABLED: boolean;
     HELYX_CLOUD_CONNECT_ENABLED: boolean;
     HELYX_CLOUD_ENROLMENT_TOKEN: string | undefined;
@@ -65,6 +75,8 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS: number;
     STRIPE_ENVIRONMENT?: "sandbox" | "live" | undefined;
     HELYX_BOT_CONTROL_SECRET?: string | undefined;
+    HELYX_ECKO_TRANSPORT_SECRET?: string | undefined;
+    HELYX_ECKO_TRANSPORT_PREVIOUS_SECRET?: string | undefined;
     HELYX_SUPPORT_SERVICE_SECRET?: string | undefined;
     HELYX_VERIFICATION_INSTALLATION_ID?: string | undefined;
     HELYX_VERIFICATION_URL?: string | undefined;
@@ -90,4 +102,7 @@ export declare function shardWorkerCommandRegistration(input: {
     premiumActivationModuleId?: string;
     oauthModuleId?: string;
 }): CommandRegistration;
+export declare function acceptEnhancedAutoModerationResult(registry: Pick<BotAutoModerationScannerRegistry, "acceptResult"> | undefined, evidenceStore: TransientViolationEvidenceStore | undefined, operation: Extract<ShardControlOperation, {
+    kind: "automod.enhanced.result.accept";
+}>): Promise<import("@helyx/sdk").AutoModerationEnhancedResultOutcome>;
 //# sourceMappingURL=shard-worker.d.ts.map

package/dist/shard-worker.js

@@ -4,14 +4,15 @@ import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepositor
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
-import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { AUTOMOD_ENHANCED_CONTRACT_VERSION, AUTOMOD_ENHANCED_PROVIDER_ID, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, Partials } from "discord.js";
 import { monitorEventLoopDelay } from "node:perf_hooks";
 import pino from "pino";
 import { createCloudManagementModule } from "./cloud-management-module.js";
-import { BotControlService, DiscordGuildResourceDirectory, mapBotControlError, } from "./control-server.js";
+import { BotControlService, BotControlTransportError, DiscordGuildResourceDirectory, mapBotControlError, } from "./control-server.js";
 import { HttpVerificationService } from "./verification-service.js";
-import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
+import { DiscordMessageDeliveryService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
+import { DiscordModerationMemberEnforcementAdapter } from "./discord-member-enforcement-service.js";
 import { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
 import { createManagementModule } from "./management-module.js";
@@ -24,6 +25,7 @@ import { DiscordPremiumGuildAuthority } from "./premium-guild-authority.js";
 import { assertReviewedPremiumCatalogue, requirePremiumProviderEnvironment, } from "./premium-access.js";
 import { WorkerCloudConnectorProxy } from "./shard-cloud-proxy.js";
 import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
+import { installModerationPlatformServices } from "./moderation-platform-services.js";
 import { DiscordGuildHealthInspection } from "./discord-guild-health.js";
 import { DiscordAnalyticsInspection } from "./discord-analytics.js";
 import { DiscordInviteInspection } from "./discord-invites.js";
@@ -32,6 +34,7 @@ import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
 import { assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, guildIdToShardId, SHARD_LEASE_HEARTBEAT_TIMEOUT_MS, shardIdentitySchema, supervisorMessageSchema, } from "./shard-contracts.js";
 import { gatewayIntentsForModules, readBotVersion, } from "./index.js";
+import { HostedBotInviteGateClient, HostedServerLeaveWorker, HostedServerModerationClient, PostgresHostedGuildSafety, } from "./hosted-server-moderation.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
@@ -79,6 +82,16 @@ export async function startShardWorker(processEnvironment = process.env, identit
             ? {}
             : { maxConnections: environment.HELYX_SHARD_WORKER_DATABASE_POOL_MAX }),
     });
+    const hostedOwnerObserver = new PostgresHostedGuildSafety(database);
+    const hostedSafety = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? hostedOwnerObserver
+        : undefined;
+    const developerModeration = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedServerModerationClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
+    const hostedInviteGate = environment.HELYX_HOSTED_MODERATION_ENABLED
+        ? new HostedBotInviteGateClient(environment.HELYX_CLOUD_API_URL, environment.HELYX_BOT_CONTROL_SECRET)
+        : undefined;
     const eventLoopDelay = monitorEventLoopDelay({ resolution: 20 });
     eventLoopDelay.enable();
     let status = "starting";
@@ -90,6 +103,10 @@ export async function startShardWorker(processEnvironment = process.env, identit
     let client;
     let cloudProxy;
     let shardHealthProvider;
+    let embeddedScanner;
+    let autoModerationScannerRegistry;
+    let violationEvidenceStore;
+    let hostedLeaveWorker;
     let leaseHeartbeatWatchdog;
     let forcedLeaseExit;
     let numericWriteBehind;
@@ -99,6 +116,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         shuttingDown = true;
         status = "stopped";
         guildTracking?.stop();
+        await hostedLeaveWorker?.stop();
         if (healthTimer)
             clearInterval(healthTimer);
         leaseHeartbeatWatchdog?.stop();
@@ -108,6 +126,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         await cloudProxy?.stop().catch(() => undefined);
         shardHealthProvider?.stop();
         await moduleEvents?.stop().catch(() => undefined);
+        await embeddedScanner?.stop().catch(() => undefined);
         if (runtimeStarted)
             await runtime?.stop().catch(() => undefined);
         await numericWriteBehind?.stop();
@@ -125,7 +144,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         assertReviewedPremiumCatalogue(featureModules);
         client = new Client({
             rest: discordRestOptions,
-            intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED, environment.HELYX_GUILD_MEMBERS_ENABLED),
+            intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED, environment.HELYX_GUILD_MEMBERS_ENABLED, environment.HELYX_RUNTIME_PROFILE),
             partials: [Partials.Message, Partials.Channel, Partials.Reaction],
             allowedMentions: { parse: [] },
             shards: [identity.shardId],
@@ -192,6 +211,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 processLabel: `shard worker ${identity.shardId}`,
                 triviaData: new PostgresTriviaDataProvider(database),
                 health: shardHealthProvider,
+                ...(developerModeration ? { moderation: developerModeration } : {}),
             })
             : undefined;
         const modules = [
@@ -232,11 +252,29 @@ export async function startShardWorker(processEnvironment = process.env, identit
         platformServices.set(HELYX_SERVICE_NAMES.resourceAuthorization, new CoreResourceAuthorizationService(platformServices.get(HELYX_SERVICE_NAMES.permissions)));
         platformServices.set(HELYX_SERVICE_NAMES.discordMessages, new DiscordMessageDeliveryService(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordOwnedMessages, new DiscordOwnedMessageDeletionService(client));
-        platformServices.set(HELYX_SERVICE_NAMES.memberEnforcement, new DiscordMemberEnforcementService(client));
+        platformServices.set(HELYX_SERVICE_NAMES.memberEnforcement, new DiscordModerationMemberEnforcementAdapter(client));
         const memberRoles = new DiscordMemberRoleService(client);
         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));
+        const moderationPlatformServices = installModerationPlatformServices({
+            services: platformServices,
+            serviceAccess,
+            client,
+            modules: publicModules,
+            runtimeProfile: environment.HELYX_RUNTIME_PROFILE,
+            deploymentEnvironment: environment.HELYX_DEPLOYMENT_ENVIRONMENT,
+            embedded: {
+                workers: environment.HELYX_AUTOMOD_EMBEDDED_WORKERS,
+                maximumItems: environment.HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS,
+                maximumBytes: environment.HELYX_AUTOMOD_EMBEDDED_QUEUE_BYTES,
+                maximumItemsPerGuild: environment.HELYX_AUTOMOD_EMBEDDED_QUEUE_ITEMS_PER_GUILD,
+                refreshIntervalMs: environment.HELYX_AUTOMOD_EMBEDDED_REFRESH_SECONDS * 1_000,
+            },
+        });
+        embeddedScanner = moderationPlatformServices.embeddedScanner;
+        autoModerationScannerRegistry = moderationPlatformServices.scannerRegistry;
+        violationEvidenceStore = moderationPlatformServices.evidenceStore;
         platformServices.set(HELYX_SERVICE_NAMES.discordGuildHealth, new DiscordGuildHealthInspection(client, publicModules, serviceAccess));
         platformServices.set(HELYX_SERVICE_NAMES.discordAnalytics, new DiscordAnalyticsInspection(client));
         if (serviceOptions.inviteFingerprintKey)
@@ -265,8 +303,12 @@ export async function startShardWorker(processEnvironment = process.env, identit
             shardId: identity.shardId,
             fencingToken: BigInt(identity.fencingToken),
         };
-        const prepareGuilds = installGuildTracking(client, database, publicModules, logger, enabledCoreModuleIds, shardOwnership, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, identity.shardCount, environment.DISCORD_CLIENT_ID);
+        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,
+        });
         const commandsReady = installInteractions(client, modules, shardWorkerCommandRegistration({
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
@@ -281,7 +323,10 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 : {}),
             ...(oauthModule ? { oauthModuleId: oauthModule.manifest.id } : {}),
         }), logger, serviceAccess);
-        moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess);
+        moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess, {
+            runtimeProfile: environment.HELYX_RUNTIME_PROFILE,
+            evidenceStore: moderationPlatformServices.evidenceStore,
+        });
         const controlService = new BotControlService(database, publicModules, guildResources, serviceAccess, undefined, environment.DISCORD_INTERNAL_GUILD_ID &&
             environment.HELYX_SUPPORT_STAFF_CHANNEL_ID
             ? {
@@ -294,7 +339,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             if (!parsed.success)
                 return;
             if (parsed.data.type === "helyx.control.request") {
-                void handleControl(identity, controlService, parsed.data, logger);
+                void handleControl(identity, controlService, hostedOwnerObserver, client, hostedLeaveWorker, autoModerationScannerRegistry, violationEvidenceStore, parsed.data, logger);
             }
             else if (parsed.data.type === "helyx.lease.heartbeat") {
                 if (sameShardIdentity(parsed.data.identity, identity))
@@ -356,8 +401,12 @@ export async function startShardWorker(processEnvironment = process.env, identit
             await cloudProxy.start();
         await runtime.start();
         runtimeStarted = true;
+        await embeddedScanner?.synchronize().catch((error) => {
+            logger.warn({ event: "automod.embedded_sync_failed", error: safeError(error) }, "Embedded Auto Moderation scanner started in Standard fallback");
+        });
         await client.login(environment.DISCORD_TOKEN);
         await commandsReady;
+        hostedLeaveWorker?.start();
         healthTimer = setInterval(() => sendHealth(identity, health(identity, client, status, eventLoopDelay.mean, moduleEvents?.queueDepth() ?? 0)), HEALTH_INTERVAL_MS);
         healthTimer.unref();
         process.once("SIGTERM", () => void shutdown("SIGTERM"));
@@ -481,7 +530,7 @@ export function shardWorkerCommandRegistration(input) {
         ]),
     };
 }
-async function handleControl(identity, service, request, logger) {
+async function handleControl(identity, service, hostedOwnerObserver, client, hostedLeaveWorker, scannerRegistry, evidenceStore, request, logger) {
     let response;
     const guildId = controlOperationGuildId(request.operation);
     if (request.generation !== identity.generation ||
@@ -505,7 +554,13 @@ async function handleControl(identity, service, request, logger) {
                 type: "helyx.control.response",
                 requestId: request.requestId,
                 ok: true,
-                result: await executeShardControlOperation(service, request.operation),
+                result: request.operation.kind === "automod.enhanced.result.accept"
+                    ? await acceptEnhancedAutoModerationResult(scannerRegistry, evidenceStore, request.operation)
+                    : request.operation.kind === "hosted-server.leave.deliver"
+                        ? await deliverHostedLeave(hostedLeaveWorker, request.operation)
+                        : request.operation.kind === "hosted-server.owner.refresh"
+                            ? await refreshHostedOwner(hostedOwnerObserver, client, request.operation.guildId)
+                            : await executeShardControlOperation(service, request.operation),
             };
         }
         catch (error) {
@@ -550,6 +605,49 @@ async function handleControl(identity, service, request, logger) {
     }
     process.send?.(response);
 }
+export async function acceptEnhancedAutoModerationResult(registry, evidenceStore, operation) {
+    if (!registry || !evidenceStore)
+        return {
+            outcome: "rejected",
+            code: "module_unavailable",
+        };
+    const resultGuildId = operation.result && typeof operation.result === "object"
+        ? operation.result["guildId"]
+        : undefined;
+    if (resultGuildId !== operation.guildId)
+        return { outcome: "rejected", code: "wrong_owner" };
+    const evidenceReference = operation.evidence
+        ? evidenceStore.capture({
+            source: "enhanced_scanner",
+            ...operation.evidence,
+        })
+        : null;
+    if (operation.evidence && !evidenceReference)
+        return {
+            outcome: "rejected",
+            code: "module_unavailable",
+        };
+    return registry.acceptResult({
+        adapter: "hosted_ecko",
+        providerId: AUTOMOD_ENHANCED_PROVIDER_ID,
+        contractVersion: AUTOMOD_ENHANCED_CONTRACT_VERSION,
+        result: operation.result,
+        ...(evidenceReference ? { evidenceReference } : {}),
+    });
+}
+function deliverHostedLeave(worker, input) {
+    if (!worker)
+        throw new BotControlTransportError(503, "Hosted server moderation delivery is unavailable");
+    return worker.deliverOperation(input);
+}
+function refreshHostedOwner(ownerObserver, client, guildId) {
+    if (!client)
+        throw new BotControlTransportError(503, "Hosted server owner refresh is unavailable");
+    const guild = client.guilds.cache.get(guildId);
+    if (!guild)
+        throw new BotControlTransportError(404, "The hosted server is not installed");
+    return ownerObserver.refreshOwner(guild);
+}
 function health(identity, client, status, eventLoopDelayNanoseconds, queueDepth) {
     return {
         shardId: identity.shardId,

package/dist/transient-violation-evidence.d.ts

@@ -0,0 +1,39 @@
+import { type ViolationEvidenceReference } from "@helyx/sdk";
+export interface TransientViolationEvidenceStoreLimits {
+    entries?: number;
+    totalBytes?: number;
+}
+export type TransientEvidenceReadResult = {
+    outcome: "available";
+    content: string;
+} | {
+    outcome: "unavailable";
+} | {
+    outcome: "mismatch";
+};
+export type TransientViolationEvidenceCaptureInput = (Omit<Extract<ViolationEvidenceReference, {
+    source: "discord_auto_moderation";
+}>, "key"> & {
+    content: string;
+}) | (Omit<Extract<ViolationEvidenceReference, {
+    source: "enhanced_scanner";
+}>, "key"> & {
+    content: string;
+});
+/**
+ * Bot-private, memory-only hand-off for message content. The opaque reference is
+ * safe to cross module boundaries; the content and this vault are not.
+ */
+export declare class TransientViolationEvidenceStore {
+    #private;
+    private readonly now;
+    private readonly createKey;
+    constructor(now?: () => number, createKey?: () => string, limits?: TransientViolationEvidenceStoreLimits);
+    capture(input: TransientViolationEvidenceCaptureInput): ViolationEvidenceReference | null;
+    consume(reference: ViolationEvidenceReference): TransientEvidenceReadResult;
+    /** Read without discarding so a failed Discord send can be retried. */
+    read(reference: ViolationEvidenceReference): TransientEvidenceReadResult;
+    discard(reference: ViolationEvidenceReference): void;
+    get size(): number;
+}
+//# sourceMappingURL=transient-violation-evidence.d.ts.map

package/dist/transient-violation-evidence.js

@@ -0,0 +1,132 @@
+import { VIOLATION_THREAD_LIMITS, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+const MAX_EVIDENCE_ENTRIES = 10_000;
+const MAX_EVIDENCE_TOTAL_BYTES = 16 * 1_024 * 1_024;
+/**
+ * Bot-private, memory-only hand-off for message content. The opaque reference is
+ * safe to cross module boundaries; the content and this vault are not.
+ */
+export class TransientViolationEvidenceStore {
+    now;
+    createKey;
+    #records = new Map();
+    #maximumEntries;
+    #maximumTotalBytes;
+    #totalBytes = 0;
+    constructor(now = Date.now, createKey = randomUUID, limits = {}) {
+        this.now = now;
+        this.createKey = createKey;
+        this.#maximumEntries = boundedPositiveInteger(limits.entries ?? MAX_EVIDENCE_ENTRIES, MAX_EVIDENCE_ENTRIES, "entry limit");
+        this.#maximumTotalBytes = boundedPositiveInteger(limits.totalBytes ?? MAX_EVIDENCE_TOTAL_BYTES, MAX_EVIDENCE_TOTAL_BYTES, "byte limit");
+    }
+    capture(input) {
+        validateIdentity(input.guildId);
+        validateIdentity(input.channelId);
+        if (input.messageId !== null)
+            validateIdentity(input.messageId);
+        validateIdentity(input.authorUserId);
+        validateBinding(input.sourceEventId, "source event");
+        if (input.source === "enhanced_scanner")
+            validateBinding(input.configurationRevision, "configuration revision");
+        const contentBytes = Buffer.byteLength(input.content, "utf8");
+        if (input.content.length < 1 ||
+            input.content.length > VIOLATION_THREAD_LIMITS.evidenceCharacters ||
+            contentBytes > VIOLATION_THREAD_LIMITS.evidenceUtf8Bytes)
+            return null;
+        this.#pruneExpired();
+        if (this.#records.size >= this.#maximumEntries ||
+            this.#totalBytes + contentBytes > this.#maximumTotalBytes)
+            return null;
+        const key = this.createKey();
+        if (this.#records.has(key))
+            return null;
+        const base = {
+            key,
+            sourceEventId: input.sourceEventId,
+            guildId: input.guildId,
+            channelId: input.channelId,
+            messageId: input.messageId,
+            authorUserId: input.authorUserId,
+        };
+        const reference = Object.freeze(input.source === "enhanced_scanner"
+            ? {
+                ...base,
+                source: input.source,
+                configurationRevision: input.configurationRevision,
+            }
+            : { ...base, source: input.source });
+        this.#records.set(reference.key, {
+            reference,
+            content: input.content,
+            bytes: contentBytes,
+            expiresAt: this.now() + VIOLATION_THREAD_LIMITS.evidenceLifetimeSeconds * 1_000,
+        });
+        this.#totalBytes += contentBytes;
+        return reference;
+    }
+    consume(reference) {
+        const result = this.read(reference);
+        if (result.outcome === "available")
+            this.discard(reference);
+        return result;
+    }
+    /** Read without discarding so a failed Discord send can be retried. */
+    read(reference) {
+        const record = this.#records.get(reference.key);
+        if (!record)
+            return { outcome: "unavailable" };
+        if (record.expiresAt <= this.now()) {
+            this.#delete(reference.key, record);
+            return { outcome: "unavailable" };
+        }
+        if (!sameReference(record.reference, reference))
+            return { outcome: "mismatch" };
+        return { outcome: "available", content: record.content };
+    }
+    discard(reference) {
+        const record = this.#records.get(reference.key);
+        if (record && sameReference(record.reference, reference))
+            this.#delete(reference.key, record);
+    }
+    get size() {
+        this.#pruneExpired();
+        return this.#records.size;
+    }
+    #pruneExpired() {
+        const now = this.now();
+        for (const [key, record] of this.#records)
+            if (record.expiresAt <= now)
+                this.#delete(key, record);
+    }
+    #delete(key, record) {
+        if (!this.#records.delete(key))
+            return;
+        this.#totalBytes = Math.max(0, this.#totalBytes - record.bytes);
+    }
+}
+function boundedPositiveInteger(value, maximum, subject) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`Violation evidence ${subject} is invalid`);
+    return value;
+}
+function sameReference(left, right) {
+    return (left.source === right.source &&
+        left.key === right.key &&
+        left.sourceEventId === right.sourceEventId &&
+        left.guildId === right.guildId &&
+        left.channelId === right.channelId &&
+        left.messageId === right.messageId &&
+        left.authorUserId === right.authorUserId &&
+        (left.source !== "enhanced_scanner" ||
+            (right.source === "enhanced_scanner" &&
+                left.configurationRevision === right.configurationRevision)));
+}
+function validateIdentity(value) {
+    if (!/^\d{17,20}$/u.test(value))
+        throw new Error("Violation evidence identity is invalid");
+}
+function validateBinding(value, subject) {
+    if (value.trim().length < 1 || value.length > 160 || /[\r\n]/u.test(value))
+        throw new Error(`Violation evidence ${subject} is invalid`);
+}
+//# sourceMappingURL=transient-violation-evidence.js.map