@helyx/bot 1.5.1 → 1.5.3

package/dist/guild-command-projection.d.ts

@@ -1,4 +1,4 @@
-import type { GuildCommandVisibilityProfile } from "@helyx/database";
+import type { GuildCommandRootMappingRecord, GuildCommandVisibilityProfile } from "@helyx/database";
 import type { ModuleDefinition } from "@helyx/sdk";
 export { commandRegistrationPolicy } from "./command-registration-policy.js";
 export interface ProjectedGuildCommand {
@@ -15,6 +15,7 @@ export interface GuildCommandProjection {
     rootCount: number;
     subcommandCount: number;
     selectedModuleIds: readonly string[];
+    rootMappings?: readonly GuildCommandRootMappingRecord[];
 }
 export interface ObservedGuildCommand {
     id?: string;
@@ -39,6 +40,8 @@ export declare function projectGuildCommands(input: {
     globallyDisabledModuleIds?: ReadonlySet<string>;
     profile: GuildCommandVisibilityProfile;
     includeInternalCommands?: boolean;
+    rootMappings?: readonly GuildCommandRootMappingRecord[];
+    reservedCommandNames?: readonly string[];
 }): GuildCommandProjection;
 export declare function diffGuildCommands(desired: GuildCommandProjection, observedInput: readonly ObservedGuildCommand[]): GuildCommandDiff;
 export declare function guildCommandDefinitionHash(definitions: readonly Readonly<Record<string, unknown>>[]): string;

package/dist/guild-command-projection.js

@@ -1,4 +1,5 @@
 import { isCustomerSelectableModule } from "@helyx/module-manifest";
+import { collectReservedCommandNames } from "@helyx/sdk";
 import { createHash } from "node:crypto";
 import { collectCommandRegistrations, } from "./shared-commands.js";
 import { toCommandDefinition } from "./interactions.js";
@@ -46,6 +47,7 @@ export function projectGuildCommands(input) {
             (input.includeInternalCommands && policy === "internal-guild"));
     })
         .map(projectRegistration)
+        .map((command) => projectRootMapping(command, input))
         .sort(compareProjectedCommands);
     validateProjectedCommands(definitions);
     const canonicalDefinitions = definitions.map(({ definition }) => definition);
@@ -55,6 +57,29 @@ export function projectGuildCommands(input) {
         rootCount: definitions.length,
         subcommandCount: definitions.reduce((total, definition) => total + definition.executablePaths.length, 0),
         selectedModuleIds: [...selected].sort(),
+        ...(input.rootMappings ? { rootMappings: input.rootMappings } : {}),
+    };
+}
+function projectRootMapping(command, input) {
+    if (command.name !== "nexus" || command.type !== 1)
+        return command;
+    const mappings = (input.rootMappings ?? []).filter(({ canonicalRoot }) => canonicalRoot === "nexus");
+    if (mappings.length > 1)
+        throw new Error("Duplicate Nexus root mapping");
+    const mapping = mappings[0];
+    if (!mapping || mapping.desiredRoot === "nexus")
+        return command;
+    // Reserve every loaded command, including currently disabled modules and aliases.
+    const reserved = new Set([
+        ...collectReservedCommandNames(input.modules),
+        ...(input.reservedCommandNames ?? []),
+    ]);
+    if (reserved.has(mapping.desiredRoot))
+        throw new Error("Nexus root conflicts with a reserved command");
+    return {
+        ...command,
+        name: mapping.desiredRoot,
+        definition: { ...command.definition, name: mapping.desiredRoot },
     };
 }
 function projectionRegistrationPolicy(module, contribution) {

package/dist/guild-command-read-service.d.ts

@@ -16,6 +16,13 @@ export interface GuildCommandReadStatus {
         windowStartedAt: string;
     };
 }
+export interface GuildCommandInteractionRoute {
+    applicationId: string;
+    guildId: string | null;
+    commandGuildId: string | null;
+    commandId: string;
+    commandName: string;
+}
 export interface GuildCommandReadHandler {
     getStatus(guildId: string): Promise<GuildCommandReadStatus>;
     requestReconciliation(input: {
@@ -79,7 +86,7 @@ export interface GuildCommandReadHandler {
         scheduledGuildCount: number;
     }>;
 }
-type ReadCommandMethod = "getState" | "getActiveRequest" | "getCapacity" | "ensureState" | "schedule" | "recordStatusRefresh" | "changeVisibilityProfile" | "setMigrationHold" | "listHistory" | "getHealth";
+type ReadCommandMethod = "getState" | "getActiveRequest" | "getCapacity" | "ensureState" | "schedule" | "recordStatusRefresh" | "changeVisibilityProfile" | "setMigrationHold" | "listHistory" | "getHealth" | "getRootMapping" | "isRetiredRootCommandId";
 export interface GuildCommandReadRepositories {
     commands: Pick<GuildCommandRepository, ReadCommandMethod> & Pick<MysqlGuildCommandRepository, ReadCommandMethod>;
     installations: Pick<InstallationRepository, "listActiveGuildIdsWithEnabledModule"> & Pick<MysqlInstallationRepository, "listActiveGuildIdsWithEnabledModule">;
@@ -94,6 +101,8 @@ export declare class GuildCommandReadService implements GuildCommandReadHandler
     private readonly writeAllGuilds;
     private readonly modules;
     constructor(databaseOrRepositories: Pool | GuildCommandReadRepositories, applicationId: string, workerHealth?: (() => Promise<GuildCommandWorkerHealth> | undefined) | undefined, discordToken?: string | undefined, guildCommandWritesEnabled?: boolean, writeGuildIds?: readonly string[], writeAllGuilds?: boolean, modules?: readonly ModuleDefinition[]);
+    /** Resolve only Discord-observed guild roots; desired settings never alias. */
+    resolveInteractionCommand(input: GuildCommandInteractionRoute): Promise<string | null>;
     previewFirstTimeSetup(moduleIds: string[]): Promise<{
         selectedModuleIds: string[];
         rootCount: number;

package/dist/guild-command-read-service.js

@@ -31,6 +31,43 @@ export class GuildCommandReadService {
         this.#repository = repositories.commands;
         this.#installations = repositories.installations;
     }
+    /** Resolve only Discord-observed guild roots; desired settings never alias. */
+    async resolveInteractionCommand(input) {
+        if (input.applicationId !== this.applicationId)
+            return null;
+        if (!input.guildId)
+            return input.commandName === "nexus" ? null : input.commandName;
+        if (typeof this.#repository.getRootMapping !== "function" ||
+            typeof this.#repository.isRetiredRootCommandId !== "function")
+            throw new Error("Guild command routing requires root mapping and retired ID capabilities");
+        const mapping = await this.#repository.getRootMapping(this.applicationId, input.guildId, "nexus");
+        if (mapping &&
+            (mapping.applicationId !== this.applicationId ||
+                mapping.guildId !== input.guildId ||
+                mapping.canonicalRoot !== "nexus"))
+            throw new Error("Guild command routing mapping has an invalid scope");
+        if (mapping && input.commandName === mapping.observedRoot) {
+            return mapping.observedCommandId &&
+                input.commandId === mapping.observedCommandId &&
+                input.commandGuildId === input.guildId
+                ? "nexus"
+                : null;
+        }
+        // A Discord ID retained by an in-place rename still belongs to Nexus;
+        // a stale name cannot send that same ID to a newly registered owner.
+        if (mapping && input.commandId === mapping.observedCommandId)
+            return null;
+        // Only the exact active observed name/ID is accepted ahead of retirement.
+        // Reusing an old root name for another contribution cannot revive its ID.
+        if (mapping &&
+            (input.commandName === "nexus" ||
+                input.commandName === mapping.desiredRoot))
+            return null;
+        if (input.commandGuildId === input.guildId &&
+            (await this.#repository.isRetiredRootCommandId(this.applicationId, input.guildId, input.commandId)))
+            return null;
+        return input.commandName;
+    }
     previewFirstTimeSetup(moduleIds) {
         const requested = new Set(moduleIds);
         const byId = new Map(this.modules.map((module) => [module.manifest.id, module]));

package/dist/guild-command-worker.d.ts

@@ -1,6 +1,8 @@
 import { GuildCommandRepository, InstallationRepository, ModuleAvailabilityRepository, type GuildCommandHealth, type GuildCommandRequestRecord } from "@helyx/database";
 import { type GuildCommandRepository as MysqlGuildCommandRepository, type InstallationRepository as MysqlInstallationRepository, type ModuleAvailabilityRepository as MysqlModuleAvailabilityRepository } from "@helyx/database-mysql";
 import type { Logger, ModuleDefinition } from "@helyx/sdk";
+import type { CommandRestrictionRecovery } from "@helyx/platform";
+import type { CommandPolicyDeliveryGate } from "@helyx/database-contracts";
 import type { Pool } from "pg";
 import { type GuildCommandDiff, type GuildCommandProjection } from "./guild-command-projection.js";
 import type { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
@@ -10,7 +12,14 @@ export interface GuildCommandWorkerHealth extends GuildCommandHealth {
     workerRunning: boolean;
     activeCount: number;
 }
-type WorkerCommandRepository = Pick<GuildCommandRepository, "claimDue" | "getHealth" | "heartbeat" | "getState" | "completeDryRun" | "defer" | "markBlocked" | "markFailed" | "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation"> & Pick<MysqlGuildCommandRepository, "claimDue" | "getHealth" | "heartbeat" | "getState" | "completeDryRun" | "defer" | "markBlocked" | "markFailed" | "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation">;
+export interface GuildCommandCataloguePort {
+    recheck(limit?: number): Promise<{
+        examined: number;
+        reset: number;
+    }>;
+    getReservedCommandNames(): Promise<readonly string[]>;
+}
+type WorkerCommandRepository = Pick<GuildCommandRepository, "claimDue" | "getHealth" | "heartbeat" | "getState" | "listRootMappings" | "completeDryRun" | "defer" | "markBlocked" | "markFailed" | "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation" | "retireRootObservation" | "isRetiredRootCommandId"> & Pick<MysqlGuildCommandRepository, "claimDue" | "getHealth" | "heartbeat" | "getState" | "listRootMappings" | "completeDryRun" | "defer" | "markBlocked" | "markFailed" | "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation" | "retireRootObservation" | "isRetiredRootCommandId">;
 export interface GuildCommandWorkerRepositories {
     commands: WorkerCommandRepository;
     installations: Pick<InstallationRepository, "listEnabledModules"> & Pick<MysqlInstallationRepository, "listEnabledModules">;
@@ -27,10 +36,15 @@ export declare class GuildCommandWorker {
     #private;
     constructor(input: {
         modules: readonly ModuleDefinition[];
+        commandRestrictions?: Pick<CommandRestrictionRecovery, "getPolicy" | "recheck">;
+        commandCatalogue?: GuildCommandCataloguePort;
+        commandPolicyDelivery?: {
+            readGate(): Promise<CommandPolicyDeliveryGate>;
+        };
         logger: Logger;
         workerId?: string;
         fencingToken: bigint;
-        discord?: Pick<GuildCommandDiscordClient, "canWrite" | "observe" | "replace">;
+        discord?: Pick<GuildCommandDiscordClient, "canWrite" | "observe" | "replace" | "remove">;
         internalGuildId?: string;
         pollIntervalMs?: number;
         leaseMs?: number;
@@ -43,10 +57,10 @@ export declare class GuildCommandWorker {
     stop(): Promise<void>;
     getHealth(): Promise<GuildCommandWorkerHealth>;
 }
-type LiveRepository = Pick<GuildCommandRepository, "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation"> & Pick<MysqlGuildCommandRepository, "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation">;
+type LiveRepository = Pick<GuildCommandRepository, "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation" | "retireRootObservation" | "isRetiredRootCommandId"> & Pick<MysqlGuildCommandRepository, "completeLive" | "isLeaseCurrent" | "reserveCreations" | "settleCreation" | "retireRootObservation" | "isRetiredRootCommandId">;
 export declare function reconcileLiveGuildCommands(input: {
     repository: LiveRepository;
-    discord: Pick<GuildCommandDiscordClient, "observe" | "replace">;
+    discord: Pick<GuildCommandDiscordClient, "observe" | "replace" | "remove">;
     request: GuildCommandRequestRecord;
     projection: GuildCommandProjection;
     workerId: string;
@@ -54,6 +68,7 @@ export declare function reconcileLiveGuildCommands(input: {
     leaseMs: number;
     verificationDelayMs?: number;
     signal?: AbortSignal;
+    validateWrite?(): Promise<void>;
 }): Promise<{
     outcome: "completed" | "stale" | "fenced";
     diff: GuildCommandDiff;