@helyx/bot 0.4.9 → 0.4.13

package/dist/shard-contracts.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { signedAssessmentEnvelopeSchema } from "@helyx/verification-contracts";
 export const SHARD_CONTRACT_VERSION = 1;
-export const SHARD_CONTROL_MAX_BYTES = 64 * 1_024;
+// Guild dashboard state includes the bounded module catalogue as well as the
+// guild's Discord resources. Keep this aligned with the cloud-control message
+// ceiling so hosted and self-hosted transports accept the same valid state.
+export const SHARD_CONTROL_MAX_BYTES = 256 * 1_024;
 export const SHARD_CONTROL_TIMEOUT_MS = 30_000;
 export const SHARD_HEALTH_STALE_MS = 30_000;
 export const SHARD_LEASE_HEARTBEAT_TIMEOUT_MS = 20_000;
@@ -58,7 +62,7 @@ const managedResourceObject = z
     .refine(hasBoundedManagedResourceBytes);
 const managedResourceFilters = z
     .record(z.string().regex(/^[a-z][a-zA-Z0-9_]*$/u), z.string().trim().min(1).max(100))
-    .refine((value) => Object.keys(value).length <= 5);
+    .refine((value) => Object.keys(value).length <= 8);
 const scheduledTaskPayload = z
     .record(z.string().regex(/^[a-z][A-Za-z0-9]{0,62}Id$/u), z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u))
     .refine((value) => Object.keys(value).length <= 20)
@@ -218,6 +222,13 @@ export const shardHealthSnapshotSchema = z
 });
 export const shardControlOperationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("guild.state.get"), guildId: snowflake }).strict(),
+    z
+        .object({
+        kind: z.literal("guild.presence.list"),
+        guildIds: z.array(snowflake).min(1).max(200),
+        correlationId: z.uuid(),
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("guild.module.status.set"),
@@ -266,6 +277,16 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         ...mutationContext.shape,
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal("guild.module.resource.access"),
+        guildId: snowflake,
+        moduleId,
+        resourceType,
+        operation: z.enum(["list", "read"]),
+        actorUserId: snowflake,
+    })
+        .strict(),
     z
         .object({
         kind: z.literal("guild.module.resource.list"),
@@ -356,6 +377,7 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         actionId: resourceType,
         expectedRevision: z.number().int().min(0),
         value: managedResourceObject,
+        actorAuthenticatedAt: dateTime.optional(),
         ...mutationContext.shape,
     })
         .strict(),
@@ -387,6 +409,12 @@ export const shardControlOperationSchema = z.discriminatedUnion("kind", [
         }),
     })
         .strict(),
+    z
+        .object({
+        kind: z.literal("verification.result.accept"),
+        envelope: signedAssessmentEnvelopeSchema,
+    })
+        .strict(),
     z.object({ kind: z.literal("privacy.providers.list") }).strict(),
     z
         .object({
@@ -568,11 +596,246 @@ export const shardScheduledTaskResponseSchema = z
     result: scheduledTaskResult,
 })
     .strict();
+const numericWireValueSchema = z.discriminatedUnion("type", [
+    z
+        .object({ type: z.literal("string"), value: z.string().max(4_000) })
+        .strict(),
+    z.object({ type: z.literal("boolean"), value: z.boolean() }).strict(),
+    z.object({ type: z.literal("number"), value: z.number().finite() }).strict(),
+    z.object({ type: z.literal("date"), value: dateTime }).strict(),
+]);
+const numericWireRecordSchema = z
+    .record(z.string().regex(/^[a-z][a-z0-9_]*$/u), numericWireValueSchema)
+    .refine((value) => Object.keys(value).length <= 50);
+const numericScopeSchema = z.object({
+    moduleId,
+    collection: z.string().regex(/^[a-z][a-z0-9_]*$/u),
+});
+const numericMemberScopeSchema = {
+    ...numericScopeSchema.shape,
+    guildId: snowflake,
+    subjectId: safeIdentifier,
+};
+const numericOperationSchema = z
+    .discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("enqueue"),
+        ...numericMemberScopeSchema,
+        occurredAt: dateTime,
+        cooldownSeconds: z.number().int().min(1).max(86_400),
+        identity: numericWireRecordSchema,
+        insert: numericWireRecordSchema,
+        increments: z
+            .record(z.string().regex(/^[a-z][a-z0-9_]*$/u), z.number().int().positive())
+            .refine((value) => {
+            const length = Object.keys(value).length;
+            return length >= 1 && length <= 20;
+        }),
+        maxima: z
+            .record(z.string().regex(/^[a-z][a-z0-9_]*$/u), dateTime)
+            .refine((value) => Object.keys(value).length <= 20)
+            .optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("pending.member"),
+        ...numericMemberScopeSchema,
+    })
+        .strict(),
+    z
+        .object({ kind: z.literal("flush.member"), ...numericMemberScopeSchema })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("flush.guild"),
+        ...numericScopeSchema.shape,
+        guildId: snowflake,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("flush.subject"),
+        ...numericScopeSchema.shape,
+        subjectId: safeIdentifier,
+    })
+        .strict(),
+    z
+        .object({ kind: z.literal("flush.module"), ...numericScopeSchema.shape })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("barrier.acquire"),
+        ...numericScopeSchema.shape,
+        barrierType: z.enum({
+            member: "member",
+            guild: "guild",
+            subject: "subject",
+        }),
+        guildId: snowflake.optional(),
+        subjectId: safeIdentifier.optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("barrier.release"),
+        ...numericScopeSchema.shape,
+        barrierType: z.enum({
+            member: "member",
+            guild: "guild",
+            subject: "subject",
+        }),
+        guildId: snowflake.optional(),
+        subjectId: safeIdentifier.optional(),
+        barrierId: z.uuid(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("barrier.renew"),
+        ...numericScopeSchema.shape,
+        barrierType: z.enum({
+            member: "member",
+            guild: "guild",
+            subject: "subject",
+        }),
+        guildId: snowflake.optional(),
+        subjectId: safeIdentifier.optional(),
+        barrierId: z.uuid(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("suppress.subject"),
+        ...numericScopeSchema.shape,
+        subjectId: safeIdentifier,
+        cutoff: dateTime,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("suppress.guild"),
+        ...numericScopeSchema.shape,
+        guildId: snowflake,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("release.guild"),
+        ...numericScopeSchema.shape,
+        guildId: snowflake,
+        suppressionId: z.uuid(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("release.subject"),
+        ...numericScopeSchema.shape,
+        subjectId: safeIdentifier,
+        suppressionId: z.uuid(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("cooldown.member.clear"),
+        ...numericMemberScopeSchema,
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("cooldown.subject.clear"),
+        ...numericScopeSchema.shape,
+        subjectId: safeIdentifier,
+    })
+        .strict(),
+])
+    .superRefine((operation, context) => {
+    if (operation.kind !== "barrier.acquire" &&
+        operation.kind !== "barrier.release" &&
+        operation.kind !== "barrier.renew")
+        return;
+    const valid = operation.barrierType === "member"
+        ? operation.guildId !== undefined && operation.subjectId !== undefined
+        : operation.barrierType === "guild"
+            ? operation.guildId !== undefined && operation.subjectId === undefined
+            : operation.guildId === undefined &&
+                operation.subjectId !== undefined;
+    if (!valid)
+        context.addIssue({
+            code: "custom",
+            message: "Numeric barrier scope does not match its barrier type",
+        });
+});
+export const shardNumericRequestSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.numeric.request"),
+    requestId: z.uuid(),
+    deadlineAt: dateTime,
+    identity: shardIdentitySchema,
+    operation: numericOperationSchema,
+})
+    .strict();
+export const shardNumericResponseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.numeric.response"),
+        requestId: z.uuid(),
+        ok: z.literal(true),
+        result: z.unknown(),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.numeric.response"),
+        requestId: z.uuid(),
+        ok: z.literal(false),
+        safeCode: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,99}$/u),
+    })
+        .strict(),
+]);
+export const shardNumericCommittedSchema = z
+    .object({
+    version: z.literal(SHARD_CONTRACT_VERSION),
+    type: z.literal("helyx.numeric.committed"),
+    requestId: z.uuid(),
+    deadlineAt: dateTime,
+    identity: shardIdentitySchema,
+    scope: numericScopeSchema.strict(),
+    payload: z.unknown(),
+})
+    .strict();
+export const shardNumericCommittedResponseSchema = z.discriminatedUnion("ok", [
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.numeric.committed.response"),
+        requestId: z.uuid(),
+        identity: shardIdentitySchema,
+        ok: z.literal(true),
+    })
+        .strict(),
+    z
+        .object({
+        version: z.literal(SHARD_CONTRACT_VERSION),
+        type: z.literal("helyx.numeric.committed.response"),
+        requestId: z.uuid(),
+        identity: shardIdentitySchema,
+        ok: z.literal(false),
+        safeCode: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,99}$/u),
+    })
+        .strict(),
+]);
 export const supervisorMessageSchema = z.discriminatedUnion("type", [
     shardControlRequestSchema,
     shardCloudResponseSchema,
     shardOperationsHealthResponseSchema,
     shardScheduledTaskRequestSchema,
+    shardNumericResponseSchema,
+    shardNumericCommittedSchema,
     z
         .object({
         version: z.literal(SHARD_CONTRACT_VERSION),
@@ -599,6 +862,8 @@ export const workerMessageSchema = z.discriminatedUnion("type", [
     shardCloudRequestSchema,
     shardOperationsHealthRequestSchema,
     shardScheduledTaskResponseSchema,
+    shardNumericRequestSchema,
+    shardNumericCommittedResponseSchema,
     z
         .object({
         version: z.literal(SHARD_CONTRACT_VERSION),
@@ -615,7 +880,13 @@ export function guildIdToShardId(guildId, shardCount) {
     return Number((BigInt(parsedGuildId) >> 22n) % BigInt(shardCount));
 }
 export function controlOperationGuildId(operation) {
-    return "guildId" in operation ? operation.guildId : undefined;
+    if ("guildId" in operation)
+        return operation.guildId;
+    if (operation.kind === "verification.result.accept")
+        return operation.envelope.payload.guildId;
+    return operation.kind === "guild.presence.list"
+        ? operation.guildIds[0]
+        : undefined;
 }
 export function assertShardMessageSize(value) {
     if (Buffer.byteLength(JSON.stringify(value), "utf8") > SHARD_CONTROL_MAX_BYTES)
@@ -623,8 +894,21 @@ export function assertShardMessageSize(value) {
 }
 export async function executeShardControlOperation(handler, operation) {
     switch (operation.kind) {
+        case "guild.presence.list":
+            return handler.listGuildPresence({
+                guildIds: operation.guildIds,
+                correlationId: operation.correlationId,
+            });
         case "guild.state.get":
             return handler.getGuildState(operation.guildId);
+        case "guild.module.resource.access":
+            return handler.canAccessManagedResource({
+                guildId: operation.guildId,
+                moduleId: operation.moduleId,
+                resourceType: operation.resourceType,
+                operation: operation.operation,
+                actorUserId: operation.actorUserId,
+            });
         case "guild.module.status.set": {
             return handler.setModuleStatus({
                 guildId: operation.guildId,
@@ -759,6 +1043,9 @@ export async function executeShardControlOperation(handler, operation) {
                 value: operation.value,
                 actorUserId: operation.actorUserId,
                 correlationId: operation.correlationId,
+                ...(operation.actorAuthenticatedAt
+                    ? { actorAuthenticatedAt: operation.actorAuthenticatedAt }
+                    : {}),
             });
         case "support.notification.send": {
             return handler.sendSupportNotification({
@@ -770,6 +1057,8 @@ export async function executeShardControlOperation(handler, operation) {
                 source: operation.source,
             });
         }
+        case "verification.result.accept":
+            return handler.acceptVerificationResult(operation.envelope);
         case "privacy.providers.list":
             return handler.listPrivacyProviders();
         case "privacy.capture": {

package/dist/shard-router.d.ts

@@ -16,6 +16,8 @@ export declare class ShardControlRouter implements BotControlHandler {
         notificationGuildId?: string;
     });
     getGuildState(guildId: string): ReturnType<BotControlHandler["getGuildState"]>;
+    canAccessManagedResource(input: Parameters<BotControlHandler["canAccessManagedResource"]>[0]): ReturnType<BotControlHandler["canAccessManagedResource"]>;
+    listGuildPresence(input: Parameters<BotControlHandler["listGuildPresence"]>[0]): ReturnType<BotControlHandler["listGuildPresence"]>;
     setModuleStatus(input: Parameters<BotControlHandler["setModuleStatus"]>[0]): ReturnType<BotControlHandler["setModuleStatus"]>;
     updateConfiguration(input: Parameters<BotControlHandler["updateConfiguration"]>[0]): ReturnType<BotControlHandler["updateConfiguration"]>;
     updatePermissions(input: Parameters<BotControlHandler["updatePermissions"]>[0]): ReturnType<BotControlHandler["updatePermissions"]>;
@@ -30,6 +32,7 @@ export declare class ShardControlRouter implements BotControlHandler {
     deleteManagedResource(input: Parameters<BotControlHandler["deleteManagedResource"]>[0]): ReturnType<BotControlHandler["deleteManagedResource"]>;
     executeManagedResourceAction(input: Parameters<BotControlHandler["executeManagedResourceAction"]>[0]): ReturnType<BotControlHandler["executeManagedResourceAction"]>;
     sendSupportNotification(input: Parameters<BotControlHandler["sendSupportNotification"]>[0]): ReturnType<BotControlHandler["sendSupportNotification"]>;
+    acceptVerificationResult(envelope: Parameters<BotControlHandler["acceptVerificationResult"]>[0]): ReturnType<BotControlHandler["acceptVerificationResult"]>;
     listPrivacyProviders(): ReturnType<BotControlHandler["listPrivacyProviders"]>;
     capturePrivacy(input: Parameters<BotControlHandler["capturePrivacy"]>[0]): ReturnType<BotControlHandler["capturePrivacy"]>;
     erasePrivacy(input: Parameters<BotControlHandler["erasePrivacy"]>[0]): ReturnType<BotControlHandler["erasePrivacy"]>;

package/dist/shard-router.js

@@ -10,6 +10,42 @@ export class ShardControlRouter {
     getGuildState(guildId) {
         return this.#route({ kind: "guild.state.get", guildId });
     }
+    canAccessManagedResource(input) {
+        return this.#route({
+            kind: "guild.module.resource.access",
+            ...input,
+        });
+    }
+    async listGuildPresence(input) {
+        const observations = new Map();
+        const byShard = new Map();
+        for (const guildId of [...new Set(input.guildIds)]) {
+            const shardId = guildIdToShardId(guildId, this.input.shardCount);
+            const guildIds = byShard.get(shardId) ?? [];
+            guildIds.push(guildId);
+            byShard.set(shardId, guildIds);
+        }
+        await Promise.all([...byShard.values()].map(async (guildIds) => {
+            try {
+                const result = await this.#route({
+                    kind: "guild.presence.list",
+                    guildIds,
+                    correlationId: input.correlationId,
+                });
+                for (const observation of result)
+                    observations.set(observation.guildId, observation);
+            }
+            catch {
+                // A starting, draining, or reassigned shard is unknown, never absent.
+            }
+        }));
+        const observedAt = new Date().toISOString();
+        return [...new Set(input.guildIds)].map((guildId) => observations.get(guildId) ?? {
+            guildId,
+            state: "unknown",
+            observedAt,
+        });
+    }
     setModuleStatus(input) {
         return this.#route({ kind: "guild.module.status.set", ...input });
     }
@@ -85,6 +121,12 @@ export class ShardControlRouter {
             ...input,
         });
     }
+    acceptVerificationResult(envelope) {
+        return this.#route({
+            kind: "verification.result.accept",
+            envelope,
+        });
+    }
     listPrivacyProviders() {
         return this.#routeLeader({ kind: "privacy.providers.list" });
     }

package/dist/shard-supervisor.d.ts

@@ -1,15 +1,17 @@
 import type { BotEnvironment } from "@helyx/config";
 import { type DatabasePool } from "@helyx/database";
-import type { ModuleDefinition, ScheduledTaskExecutionResult } from "@helyx/sdk";
+import type { ModuleDefinition, NumericWriteBehindCommittedBatch, ScheduledTaskExecutionResult } from "@helyx/sdk";
 import { type ShardCloudRequest, type ShardIdentity, type ShardProcessHealth } from "./shard-contracts.js";
 import { type ShardCoordinator, type ShardGenerationDescriptor, type ShardLeaderLease, type ShardLease } from "./shard-coordinator.js";
 import type { BotHandle } from "./index.js";
 export declare const STEADY_STATE_LEASE_LOSS_BOUND_MS: number;
+export declare function supervisorShutdownExitCode(reason: string): number | undefined;
 export declare function createStartupWorkerHeartbeatMaintenance(heartbeat: () => void, intervalMs?: number): {
     stop(): void;
 };
 export declare function deferScheduledRoutingFailures(route: () => Promise<ScheduledTaskExecutionResult>): Promise<ScheduledTaskExecutionResult>;
 export declare function startShardSupervisor(environment: BotEnvironment, processEnvironment: NodeJS.ProcessEnv, workerEntry: string): Promise<BotHandle>;
+export declare function splitNumericCommittedBatch(batch: NumericWriteBehindCommittedBatch, index: number): NumericWriteBehindCommittedBatch;
 export declare function buildShardWorkerEnvironment(source: NodeJS.ProcessEnv, identity: ShardIdentity, restartCount: number): NodeJS.ProcessEnv;
 export declare function shardRuntimeCompositionHash(modules: readonly ModuleDefinition[], internalGuildId?: string): string;
 export declare function boundedRespawnDelay(attempt: number): number;
@@ -19,6 +21,7 @@ export interface SteadyStateOwnershipRenewal {
     leaderRenewed: boolean;
     leaderAvailable: boolean;
 }
+export declare function retryOwnershipRenewal<T>(renew: () => Promise<T>, attempts?: number): Promise<T>;
 export declare function selectFencedShardHealth(input: {
     generation: string;
     shardCount: number;