@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/role-hierarchy-workflow.js

@@ -0,0 +1,122 @@
+/**
+ * Role hierarchy checks that fetch the required guild data.
+ * Invariant: Checks describe the fetched data and never authorize an action.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import * as Effect from "effect/Effect";
+import { GuildOperationError } from "#sdk/guilds";
+import { composedStepFacts } from "#sdk/api-errors";
+import { mapFailureCause } from "./effect-failures.js";
+import { guildFetch, memberFetch, memberSelf, roleList } from "./guilds.js";
+import { identifier, record } from "./decode/primitives.js";
+import { suspendInput } from "./defects.js";
+import { evaluateMemberHierarchy } from "./role-hierarchy.js";
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation";
+const inputFailure = (failure) => new GuildOperationError({
+    operation: "members.fetchCanManage",
+    reason: "input",
+    outcome: "notDispatched",
+    inputValidation: failure.detail,
+});
+const timeoutFailure = () => new GuildOperationError({ operation: "members.fetchCanManage", reason: "timeout", outcome: "notDispatched" });
+function target(value) {
+    if (!record(value))
+        return inputValidationFailure("target", "type", "Hierarchy target must be an object");
+    const unsupported = unsupportedKeyFailure(value, ["guildId", "userId"], "target", "the hierarchy target");
+    if (unsupported)
+        return unsupported;
+    // Read each field once, so the validated IDs are the ones fetched
+    const guildId = value.guildId;
+    if (!identifier(guildId))
+        return inputValidationFailure("target.guildId", "format", "Guild IDs must be decimal strings");
+    const userId = value.userId;
+    if (!identifier(userId))
+        return inputValidationFailure("target.userId", "format", "User IDs must be decimal strings");
+    return { guildId, userId };
+}
+function options(value) {
+    if (value === undefined)
+        return {};
+    if (!record(value))
+        return inputValidationFailure("options", "type", "Hierarchy options must be an object");
+    const unsupported = unsupportedKeyFailure(value, ["timeoutMs", "signal", "actorUserId"], "options", "the hierarchy options");
+    if (unsupported)
+        return unsupported;
+    const actorUserId = value.actorUserId;
+    if (actorUserId !== undefined && !identifier(actorUserId))
+        return inputValidationFailure("options.actorUserId", "format", "User IDs must be decimal strings");
+    const timeoutMs = value.timeoutMs;
+    if (timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs < 1 ||
+            timeoutMs > 2_147_483_647))
+        return inputValidationFailure("options.timeoutMs", "range", "Hierarchy timeout must be an integer from 1 through 2,147,483,647 ms");
+    const signal = value.signal;
+    if (signal !== undefined &&
+        (!record(signal) ||
+            typeof signal.aborted !== "boolean" ||
+            typeof signal.addEventListener !== "function" ||
+            typeof signal.removeEventListener !== "function"))
+        return inputValidationFailure("options.signal", "type", "Hierarchy signal must be an AbortSignal");
+    // Keep only the validated actor and timeout: The requests use their own remaining deadlines
+    return { ...(actorUserId === undefined ? {} : { actorUserId }), ...(timeoutMs === undefined ? {} : { timeoutMs }) };
+}
+function remaining(deadline, now) {
+    const timeoutMs = Math.floor(deadline - now());
+    return timeoutMs > 0 ? { timeoutMs } : undefined;
+}
+function remoteFailure(error) {
+    if (error instanceof GuildOperationError)
+        return new GuildOperationError({
+            operation: "members.fetchCanManage",
+            reason: error.reason === "input" ? "response" : error.reason,
+            outcome: error.outcome,
+            status: error.status,
+            retryAfterMs: error.retryAfterMs,
+            apiError: error.apiError,
+            ...composedStepFacts(error),
+        });
+    return error;
+}
+/** Fetches the four independent hierarchy inputs in parallel under one deadline, then evaluates the pure local rule.
+ * The actor is the bot unless actorUserId names another member of the target's guild
+ */
+export function fetchCanManage(owner, input, suppliedOptions) {
+    // Reading and validating the caller target and options is marked as application input
+    return suspendInput(() => {
+        const member = target(input);
+        const validOptions = options(suppliedOptions);
+        if (member instanceof InputValidationFailure)
+            return Effect.fail(inputFailure(member));
+        if (validOptions instanceof InputValidationFailure)
+            return Effect.fail(inputFailure(validOptions));
+        return Effect.gen(function* () {
+            const now = () => owner.logical.now();
+            const deadline = now() + (validOptions.timeoutMs ?? owner.defaultTimeoutMs ?? 30_000);
+            const guildOptions = remaining(deadline, now);
+            const selfOptions = remaining(deadline, now);
+            const targetOptions = remaining(deadline, now);
+            const roleOptions = remaining(deadline, now);
+            if (!guildOptions || !selfOptions || !targetOptions || !roleOptions)
+                return yield* Effect.fail(timeoutFailure());
+            const [guild, actor, targetMember, roles] = yield* Effect.all([
+                owner.guild("guilds.fetch", () => guildFetch(member.guildId), guildOptions),
+                validOptions.actorUserId === undefined
+                    ? owner.guild("members.fetchSelf", () => memberSelf(member.guildId), selfOptions)
+                    : owner.guild("members.fetch", () => memberFetch({ guildId: member.guildId, userId: validOptions.actorUserId }), selfOptions),
+                owner.guild("members.fetch", () => memberFetch(member), targetOptions),
+                owner.guild("roles.fetchAll", () => roleList(member.guildId), roleOptions),
+            ], { concurrency: "unbounded" }).pipe(mapFailureCause(remoteFailure));
+            const manageable = evaluateMemberHierarchy({ guild, actor, target: targetMember, roles });
+            return manageable === undefined
+                ? yield* Effect.fail(new GuildOperationError({
+                    operation: "members.fetchCanManage",
+                    reason: "response",
+                    outcome: "unknown",
+                }))
+                : manageable;
+        });
+    });
+}
+//# sourceMappingURL=role-hierarchy-workflow.js.map

package/dist/internal/role-hierarchy-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy-workflow.js","sourceRoot":"","sources":["../../src/internal/role-hierarchy-workflow.ts"],"names":[],"mappings":"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"}

package/dist/internal/role-hierarchy.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure role hierarchy comparison.
+ * Invariant: Comparisons use position and then ID, and invalid or cross-guild roles compare as unknown.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { GuildRole } from "#sdk/guilds";
+import type { RoleHierarchyInput } from "#sdk/role-hierarchy";
+export declare function compareRoleHierarchy(left: GuildRole, right: GuildRole): -1 | 0 | 1 | undefined;
+export declare function isRoleAboveInHierarchy(left: GuildRole, right: GuildRole): boolean | undefined;
+export declare function evaluateMemberHierarchy(input: RoleHierarchyInput): boolean | undefined;
+//# sourceMappingURL=role-hierarchy.d.ts.map

package/dist/internal/role-hierarchy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy.d.ts","sourceRoot":"","sources":["../../src/internal/role-hierarchy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAa7D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,SAAS,CAK9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAG7F;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAatF"}

package/dist/internal/role-hierarchy.js

@@ -0,0 +1,87 @@
+import { identifier } from "./decode/primitives.js";
+const validRole = (value) => typeof value === "object" &&
+    value !== null &&
+    identifier(value.guildId) &&
+    identifier(value.id) &&
+    typeof value.position === "number" &&
+    Number.isInteger(value.position) &&
+    value.position >= 0 &&
+    value.position <= 2_147_483_647;
+export function compareRoleHierarchy(left, right) {
+    if (!validRole(left) || !validRole(right) || left.guildId !== right.guildId)
+        return undefined;
+    if (left.id === right.id)
+        return 0;
+    if (left.position !== right.position)
+        return left.position > right.position ? 1 : -1;
+    return BigInt(left.id) < BigInt(right.id) ? 1 : -1;
+}
+export function isRoleAboveInHierarchy(left, right) {
+    const comparison = compareRoleHierarchy(left, right);
+    return comparison === undefined ? undefined : comparison === 1;
+}
+export function evaluateMemberHierarchy(input) {
+    if (!validInput(input))
+        return undefined;
+    const { guild, actor, target, roles } = input;
+    if (actor.userId === target.userId)
+        return true;
+    if (actor.userId === guild.ownerId)
+        return true;
+    if (target.userId === guild.ownerId)
+        return false;
+    const roleById = new Map(roles.filter((role) => role.id !== guild.id).map((role) => [role.id, role]));
+    const actorRole = highestExplicitRole(actor.roleIds, roleById);
+    const targetRole = highestExplicitRole(target.roleIds, roleById);
+    if (!actorRole)
+        return false;
+    if (!targetRole)
+        return true;
+    return isRoleAboveInHierarchy(actorRole, targetRole);
+}
+function validMember(value, guildId) {
+    if (typeof value !== "object" ||
+        value === null ||
+        value.guildId !== guildId ||
+        !identifier(value.userId) ||
+        !Array.isArray(value.roleIds))
+        return false;
+    const ids = new Set();
+    for (const roleId of value.roleIds) {
+        if (!identifier(roleId) || roleId === guildId || ids.has(roleId))
+            return false;
+        ids.add(roleId);
+    }
+    return true;
+}
+function validInput(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const input = value;
+    if (!input.guild ||
+        !identifier(input.guild.id) ||
+        !identifier(input.guild.ownerId) ||
+        !validMember(input.actor, input.guild.id) ||
+        !validMember(input.target, input.guild.id) ||
+        !Array.isArray(input.roles))
+        return false;
+    const roleIds = new Set();
+    for (const role of input.roles) {
+        if (!validRole(role) || role.guildId !== input.guild.id || roleIds.has(role.id))
+            return false;
+        roleIds.add(role.id);
+    }
+    return [...input.actor.roleIds, ...input.target.roleIds].every((roleId) => roleIds.has(roleId));
+}
+function highestExplicitRole(roleIds, roles) {
+    let highest;
+    for (const roleId of roleIds) {
+        const role = roles.get(roleId);
+        if (!role)
+            return undefined;
+        if (!highest || isRoleAboveInHierarchy(role, highest))
+            highest = role;
+    }
+    return highest;
+}
+//# sourceMappingURL=role-hierarchy.js.map

package/dist/internal/role-hierarchy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-hierarchy.js","sourceRoot":"","sources":["../../src/internal/role-hierarchy.ts"],"names":[],"mappings":"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"}

package/dist/internal/scheduled-tasks.d.ts

@@ -0,0 +1,46 @@
+import type * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { ConfigurationError } from "#sdk/errors";
+import type { FailureReporter } from "./failures.js";
+import type { LogicalScheduler } from "./logical-scheduler.js";
+import type { ClientLogger } from "./logging.js";
+/** When a task first runs, and for a repeating task how long it waits after each run ends */
+export interface ScheduleTiming {
+    readonly delayMs: number;
+    readonly intervalMs: number | undefined;
+}
+/**
+ * Read client.schedule options. Misuse returns ConfigurationError without the rejected value.
+ * Reading the options is application input, so the caller runs this under a defect boundary
+ */
+export declare function scheduleTiming(options: unknown): ScheduleTiming | ConfigurationError;
+/** The client's scheduled tasks. Each one is a fiber that waits on the logical scheduler and then runs its work */
+export declare class ScheduledTasks {
+    #private;
+    private readonly logical;
+    private readonly failures;
+    private readonly logging;
+    constructor(logical: LogicalScheduler, failures: FailureReporter, logging: ClientLogger);
+    /** Task runs in progress */
+    get running(): number;
+    /** Wait until the next run ends */
+    progress(): Effect.Effect<void>;
+    /** Whether the fiber runs a task, so a task that requests shutdown does not wait for itself */
+    owns(fiberId: number): boolean;
+    /**
+     * Start a task in a fiber of its own with the given services. It first runs after timing.delayMs and, when it repeats,
+     * again intervalMs after each run ends. Returns a close function that cancels later runs without interrupting a run
+     * in progress. Throws ClientClosedError once shutdown has begun
+     */
+    start(run: Effect.Effect<unknown, unknown>, timing: ScheduleTiming, context: Context.Context<never>): () => void;
+    /** Start no new run and accept no new task, while runs in progress continue. A draining shutdown begins with this */
+    seal(): void;
+    /** Stop every task and wait until their fibers end. Fails only with defects raised while they stopped */
+    shutdown(): Effect.Effect<void>;
+    /**
+     * Accept no new task and interrupt every task, including runs in progress, without waiting. The first call records
+     * in one Info record how many tasks shutdown ended with a run waiting or in progress, so none ends unrecorded
+     */
+    stop(): void;
+}
+//# sourceMappingURL=scheduled-tasks.d.ts.map

package/dist/internal/scheduled-tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled-tasks.d.ts","sourceRoot":"","sources":["../../src/internal/scheduled-tasks.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAE9C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAqB,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAOhD,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAC1C;AAMD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,GAAG,kBAAkB,CAoBpF;AAED,mHAAmH;AACnH,qBAAa,cAAc;;IAcnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH5B,YACqB,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,YAAY,EACtC;IAEJ,4BAA4B;IAC5B,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,mCAAmC;IACnC,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAE9B;IAED,+FAA+F;IAC/F,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG7B;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CA6D/G;IAED,qHAAqH;IACrH,IAAI,IAAI,IAAI,CAEX;IAED,yGAAyG;IACzG,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAc9B;IAED;;;OAGG;IACH,IAAI,IAAI,IAAI,CAmBX;CAOJ"}

package/dist/internal/scheduled-tasks.js

@@ -0,0 +1,190 @@
+/**
+ * Scheduled tasks: Application work that client.schedule runs once or repeatedly within the client's lifetime.
+ * Invariant: Every wait uses the client's logical scheduler, and each task runs in a fiber of its own, never in an event
+ * handler or command slot. A failed run reaches the client failure reporter, and a repeating task keeps its schedule. A
+ * draining shutdown starts no new run and waits for running ones, and shutdown interrupts the rest, awaits their cleanup
+ * and records in one summary how many tasks it ended with a run waiting or in progress. Implements [SDK contracts: User-handler failures](/docs/SDK-CONTRACTS.md#user-handler-failures)
+ */
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
+import { ClientClosedError, ConfigurationError } from "#sdk/errors";
+import { record } from "./decode/primitives.js";
+import { unsupportedKeyHint } from "./suggest.js";
+/** Longest delay or interval, the longest single timer delay */
+const maximumMs = 2_147_483_647;
+const optionKeys = ["delayMs", "intervalMs"];
+function milliseconds(value, minimum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum && value <= maximumMs;
+}
+/**
+ * Read client.schedule options. Misuse returns ConfigurationError without the rejected value.
+ * Reading the options is application input, so the caller runs this under a defect boundary
+ */
+export function scheduleTiming(options) {
+    if (options === undefined)
+        return { delayMs: 0, intervalMs: undefined };
+    if (!record(options))
+        return new ConfigurationError("configuration", "Schedule options must be an object");
+    const unsupported = Object.keys(options).find((key) => !optionKeys.includes(key));
+    if (unsupported !== undefined)
+        return new ConfigurationError("configuration", `Unsupported schedule option ${JSON.stringify(unsupported)}`, {
+            hint: unsupportedKeyHint(unsupported, optionKeys),
+        });
+    const { delayMs, intervalMs } = options;
+    if (delayMs !== undefined && !milliseconds(delayMs, 0))
+        return new ConfigurationError("delayMs", 'The option "delayMs" must be an integer from 0 through 2,147,483,647 milliseconds');
+    if (intervalMs !== undefined && !milliseconds(intervalMs, 1))
+        return new ConfigurationError("intervalMs", 'The option "intervalMs" must be an integer from 1 through 2,147,483,647 milliseconds');
+    return { delayMs: (delayMs ?? intervalMs ?? 0), intervalMs: intervalMs };
+}
+/** The client's scheduled tasks. Each one is a fiber that waits on the logical scheduler and then runs its work */
+export class ScheduledTasks {
+    logical;
+    failures;
+    logging;
+    /** Each task's fiber, with whether the application closed it and whether a run is in progress */
+    #tasks = new Map();
+    /** Task runs in progress, which a draining shutdown waits for */
+    #running = 0;
+    /** Released and replaced whenever a run ends, so a drain can wait for progress */
+    #progress = Deferred.makeUnsafe();
+    /** Set when shutdown begins, draining or not: No task starts another run and no task can be added */
+    #closing = false;
+    /** Tasks that ended during a draining shutdown with runs still to come, reported when the tasks stop */
+    #ended = 0;
+    #stopped = false;
+    constructor(logical, failures, logging) {
+        this.logical = logical;
+        this.failures = failures;
+        this.logging = logging;
+    }
+    /** Task runs in progress */
+    get running() {
+        return this.#running;
+    }
+    /** Wait until the next run ends */
+    progress() {
+        return Effect.suspend(() => Deferred.await(this.#progress));
+    }
+    /** Whether the fiber runs a task, so a task that requests shutdown does not wait for itself */
+    owns(fiberId) {
+        for (const fiber of this.#tasks.keys())
+            if (fiber.id === fiberId)
+                return true;
+        return false;
+    }
+    /**
+     * Start a task in a fiber of its own with the given services. It first runs after timing.delayMs and, when it repeats,
+     * again intervalMs after each run ends. Returns a close function that cancels later runs without interrupting a run
+     * in progress. Throws ClientClosedError once shutdown has begun
+     */
+    start(run, timing, context) {
+        if (this.#closing)
+            throw new ClientClosedError();
+        const owner = this;
+        const state = { closed: false, running: false };
+        const wait = (delayMs) => Effect.callback((resume) => {
+            const timer = owner.logical.set(() => resume(Effect.void), delayMs, "scheduled task");
+            return Effect.sync(() => owner.logical.clear(timer));
+        });
+        // A failed run is reported and the task continues. Interruption ends the task, after reporting any defect with it
+        const once = Effect.uninterruptibleMask((restore) => {
+            state.running = true;
+            owner.#running++;
+            return restore(run).pipe(Effect.catchCause((cause) => {
+                const report = Cause.hasInterruptsOnly(cause)
+                    ? Effect.void
+                    : Effect.withFiber((fiber) => Effect.sync(() => owner.failures.report({ kind: "task", cause }, fiber.context)));
+                return Cause.hasInterrupts(cause) ? report.pipe(Effect.andThen(Effect.interrupt)) : report;
+            }), Effect.ensuring(Effect.sync(() => {
+                state.running = false;
+                owner.#running--;
+                owner.#signalProgress();
+            })));
+        });
+        const task = Effect.gen(function* () {
+            let delayMs = timing.delayMs;
+            while (true) {
+                yield* wait(delayMs);
+                if (state.closed)
+                    return;
+                // During a draining shutdown a due run never starts, and stop reports the task as cancelled
+                if (owner.#closing) {
+                    owner.#ended++;
+                    return;
+                }
+                yield* once;
+                if (timing.intervalMs === undefined || state.closed)
+                    return;
+                // Likewise a repeating task whose run ended during the drain gets no later run
+                if (owner.#closing) {
+                    owner.#ended++;
+                    return;
+                }
+                delayMs = timing.intervalMs;
+            }
+        });
+        const fiber = Effect.runForkWith(context)(task.pipe(Effect.ensuring(Effect.sync(() => void owner.#tasks.delete(fiber)))));
+        this.#tasks.set(fiber, state);
+        return () => {
+            if (state.closed)
+                return;
+            state.closed = true;
+            // A run in progress finishes first, and the task then ends instead of waiting for another run
+            if (!state.running)
+                fiber.interruptUnsafe();
+        };
+    }
+    /** Start no new run and accept no new task, while runs in progress continue. A draining shutdown begins with this */
+    seal() {
+        this.#closing = true;
+    }
+    /** Stop every task and wait until their fibers end. Fails only with defects raised while they stopped */
+    shutdown() {
+        return Effect.suspend(() => {
+            this.stop();
+            return Effect.forEach([...this.#tasks.keys()], (fiber) => Fiber.await(fiber), {
+                concurrency: "unbounded",
+            }).pipe(Effect.flatMap((exits) => {
+                const reasons = exits.flatMap((exit) => Exit.isFailure(exit) ? exit.cause.reasons.filter((reason) => reason._tag === "Die") : []);
+                return reasons.length ? Effect.failCause(Cause.fromReasons(reasons)) : Effect.void;
+            }));
+        });
+    }
+    /**
+     * Accept no new task and interrupt every task, including runs in progress, without waiting. The first call records
+     * in one Info record how many tasks shutdown ended with a run waiting or in progress, so none ends unrecorded
+     */
+    stop() {
+        this.#closing = true;
+        if (this.#stopped)
+            return;
+        this.#stopped = true;
+        const running = this.#running;
+        let cancelled = this.#ended;
+        for (const [fiber, state] of this.#tasks) {
+            // A task the application closed has no run waiting, unless its last run is still in progress
+            if (state.running || !state.closed)
+                cancelled++;
+            fiber.interruptUnsafe();
+        }
+        if (cancelled === 0)
+            return;
+        this.logging.log({
+            level: "info",
+            category: "lifecycle",
+            code: "lifecycle.tasksCancelled",
+            message: `The client is closing, so it cancelled ${cancelled} scheduled ${cancelled === 1 ? "task" : "tasks"} that had a run waiting or in progress${running ? `, including ${running} ${running === 1 ? "run" : "runs"} in progress` : ""}`,
+            fields: { cancelled, running },
+        });
+    }
+    #signalProgress() {
+        const released = this.#progress;
+        this.#progress = Deferred.makeUnsafe();
+        Deferred.doneUnsafe(released, Effect.void);
+    }
+}
+//# sourceMappingURL=scheduled-tasks.js.map

package/dist/internal/scheduled-tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduled-tasks.js","sourceRoot":"","sources":["../../src/internal/scheduled-tasks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AACnC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AACrC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACnE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAI/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEjD,gEAAgE;AAChE,MAAM,SAAS,GAAG,aAAa,CAAA;AAC/B,MAAM,UAAU,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAA;AAQ5C,SAAS,YAAY,CAAC,KAAc,EAAE,OAAe;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,OAAO,IAAI,KAAK,IAAI,SAAS,CAAA;AAC7G,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC3C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAA;IACvE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,kBAAkB,CAAC,eAAe,EAAE,oCAAoC,CAAC,CAAA;IAC1G,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;IACjF,IAAI,WAAW,KAAK,SAAS;QACzB,OAAO,IAAI,kBAAkB,CAAC,eAAe,EAAE,+BAA+B,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,EAAE;YACzG,IAAI,EAAE,kBAAkB,CAAC,WAAW,EAAE,UAAU,CAAC;SACpD,CAAC,CAAA;IACN,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAA;IACvC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC;QAClD,OAAO,IAAI,kBAAkB,CACzB,SAAS,EACT,mFAAmF,CACtF,CAAA;IACL,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;QACxD,OAAO,IAAI,kBAAkB,CACzB,YAAY,EACZ,sFAAsF,CACzF,CAAA;IACL,OAAO,EAAE,OAAO,EAAE,CAAC,OAAO,IAAI,UAAU,IAAI,CAAC,CAAW,EAAE,UAAU,EAAE,UAAgC,EAAE,CAAA;AAC5G,CAAC;AAED,mHAAmH;AACnH,MAAM,OAAO,cAAc;IAcF,OAAO;IACP,QAAQ;IACR,OAAO;IAf5B,iGAAiG;IACxF,MAAM,GAAG,IAAI,GAAG,EAA4D,CAAA;IACrF,iEAAiE;IACjE,QAAQ,GAAG,CAAC,CAAA;IACZ,kFAAkF;IAClF,SAAS,GAAG,QAAQ,CAAC,UAAU,EAAQ,CAAA;IACvC,qGAAqG;IACrG,QAAQ,GAAG,KAAK,CAAA;IAChB,wGAAwG;IACxG,MAAM,GAAG,CAAC,CAAA;IACV,QAAQ,GAAG,KAAK,CAAA;IAEhB,YACqB,OAAyB,EACzB,QAAyB,EACzB,OAAqB;uBAFrB,OAAO;wBACP,QAAQ;uBACR,OAAO;IACzB,CAAC;IAEJ,4BAA4B;IAC5B,IAAI,OAAO;QACP,OAAO,IAAI,CAAC,QAAQ,CAAA;IACxB,CAAC;IAED,mCAAmC;IACnC,QAAQ;QACJ,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,+FAA+F;IAC/F,IAAI,CAAC,OAAe;QAChB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,IAAI,KAAK,CAAC,EAAE,KAAK,OAAO;gBAAE,OAAO,IAAI,CAAA;QAC7E,OAAO,KAAK,CAAA;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAoC,EAAE,MAAsB,EAAE,OAA+B;QAC/F,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAA;QAChD,MAAM,KAAK,GAAG,IAAI,CAAA;QAClB,MAAM,KAAK,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;QAC/C,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CAC7B,MAAM,CAAC,QAAQ,CAAO,CAAC,MAAM,EAAE,EAAE;YAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAA;YACrF,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;QACxD,CAAC,CAAC,CAAA;QACN,kHAAkH;QAClH,MAAM,IAAI,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC,OAAO,EAAE,EAAE;YAChD,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;YACpB,KAAK,CAAC,QAAQ,EAAE,CAAA;YAChB,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CACpB,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE;gBACxB,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC;oBACzC,CAAC,CAAC,MAAM,CAAC,IAAI;oBACb,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CACvB,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CACnF,CAAA;gBACP,OAAO,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;YAC9F,CAAC,CAAC,EACF,MAAM,CAAC,QAAQ,CACX,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;gBACb,KAAK,CAAC,OAAO,GAAG,KAAK,CAAA;gBACrB,KAAK,CAAC,QAAQ,EAAE,CAAA;gBAChB,KAAK,CAAC,eAAe,EAAE,CAAA;YAC3B,CAAC,CAAC,CACL,CACJ,CAAA;QACL,CAAC,CAAC,CAAA;QACF,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;YAC7B,IAAI,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;YAC5B,OAAO,IAAI,EAAE,CAAC;gBACV,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;gBACpB,IAAI,KAAK,CAAC,MAAM;oBAAE,OAAM;gBACxB,4FAA4F;gBAC5F,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;oBACjB,KAAK,CAAC,MAAM,EAAE,CAAA;oBACd,OAAM;gBACV,CAAC;gBACD,KAAK,CAAC,CAAC,IAAI,CAAA;gBACX,IAAI,MAAM,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM;oBAAE,OAAM;gBAC3D,+EAA+E;gBAC/E,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;oBACjB,KAAK,CAAC,MAAM,EAAE,CAAA;oBACd,OAAM;gBACV,CAAC;gBACD,OAAO,GAAG,MAAM,CAAC,UAAU,CAAA;YAC/B,CAAC;QACL,CAAC,CAAC,CAAA;QACF,MAAM,KAAK,GAAsB,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CACxD,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CACjF,CAAA;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QAC7B,OAAO,GAAG,EAAE;YACR,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAM;YACxB,KAAK,CAAC,MAAM,GAAG,IAAI,CAAA;YACnB,8FAA8F;YAC9F,IAAI,CAAC,KAAK,CAAC,OAAO;gBAAE,KAAK,CAAC,eAAe,EAAE,CAAA;QAC/C,CAAC,CAAA;IACL,CAAC;IAED,qHAAqH;IACrH,IAAI;QACA,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;IACxB,CAAC;IAED,yGAAyG;IACzG,QAAQ;QACJ,OAAO,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE;YACvB,IAAI,CAAC,IAAI,EAAE,CAAA;YACX,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;gBAC1E,WAAW,EAAE,WAAW;aAC3B,CAAC,CAAC,IAAI,CACH,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;gBACrB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CACnC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAC3F,CAAA;gBACD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,WAAW,CAAQ,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAA;YAC7F,CAAC,CAAC,CACL,CAAA;QACL,CAAC,CAAC,CAAA;IACN,CAAC;IAED;;;OAGG;IACH,IAAI;QACA,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAM;QACzB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAA;QAC7B,IAAI,SAAS,GAAG,IAAI,CAAC,MAAM,CAAA;QAC3B,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,6FAA6F;YAC7F,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM;gBAAE,SAAS,EAAE,CAAA;YAC/C,KAAK,CAAC,eAAe,EAAE,CAAA;QAC3B,CAAC;QACD,IAAI,SAAS,KAAK,CAAC;YAAE,OAAM;QAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;YACb,KAAK,EAAE,MAAM;YACb,QAAQ,EAAE,WAAW;YACrB,IAAI,EAAE,0BAA0B;YAChC,OAAO,EAAE,0CAA0C,SAAS,cAAc,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,yCAAyC,OAAO,CAAC,CAAC,CAAC,eAAe,OAAO,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE;YAC5O,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE;SACjC,CAAC,CAAA;IACN,CAAC;IAED,eAAe;QACX,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAA;QAC/B,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,UAAU,EAAQ,CAAA;QAC5C,QAAQ,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;IAC9C,CAAC;CACJ"}

package/dist/internal/sharding.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shard plan: Validation of the fixed local shard assignment, automatic plan sizing, scaling hooks and guild-to-shard
+ * routing.
+ * Invariant: A plan is immutable once known and decides guild ownership, never cache contents or discovery hints. An
+ * automatic plan is computed at the first connect from the bot's guild count, and omitted settings start with one shard.
+ * The client replaces either with a new, larger automatic plan only when Fluxer closes a shard with 4011 (sharding
+ * required), and an explicit plan never changes.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { ConfigurationError } from "#sdk/errors";
+import type { IdentifyCoordinator, SessionSnapshot, SessionStore } from "#sdk/sharding";
+/** Largest total shard count Fluxer accepts */
+export declare const maximumShardCount = 16384;
+/**
+ * Average guilds per shard that automatic sharding aims for, four fifths of Fluxer's per-shard ceiling.
+ * Fluxer counts the guilds routed to each shard, not the average. The validate_session_guild_count function in
+ * fluxer_gateway/src/gateway/gateway_sharding.erl at fluxerapp/fluxer commit 858a2d9e2b987330edd81711bb53e4f7edc0bbcc
+ * rejects Identify with 4011 when one shard's own guilds exceed 2,500. Routing by (id >> 22) % totalShards is uneven,
+ * so a plan sized to the ceiling almost always overfills a shard above about 20,000 guilds. At 2,000 the fullest of
+ * 16,384 shards stays near 2,200 and leaves room for growth before a 4011 closure makes the client move to a larger plan
+ */
+export declare const guildsPerShard: number;
+export interface ShardPlan {
+    readonly totalShards: number;
+    readonly shardIds: readonly number[];
+    readonly identifyShards: boolean;
+}
+/** Validated sharding settings: A known plan or "auto", plus the optional scaling hooks */
+export interface ShardingConfiguration {
+    readonly plan: ShardPlan | "auto";
+    /** Whether a 4011 (sharding required) closure moves to a larger automatic plan: For "auto" and omitted settings */
+    readonly reshard: boolean;
+    readonly identify: IdentifyCoordinator | undefined;
+    readonly sessions: SessionStore | undefined;
+    /** Whether shards that resume a stored session refill the guild, role and channel caches through REST */
+    readonly refillCaches: boolean;
+}
+/** Validate and copy the one-time sharding settings without changing caller-owned input */
+export declare function parseSharding(input: unknown): ShardingConfiguration | ConfigurationError;
+/** The plan automatic sharding picks for a guild count: Every shard, at most guildsPerShard guilds each on average */
+export declare function automaticShardPlan(guildCount: number): ShardPlan;
+/**
+ * The plan an automatic client moves to after Fluxer closed one of its shards with 4011 (sharding required): The plan
+ * for the new guild count, or one shard more than before when that count still fits the old total, because Fluxer
+ * found a shard above its ceiling whatever the average. Callers check that the old total is below maximumShardCount
+ */
+export declare function largerShardPlan(guildCount: number, previousTotalShards: number): ShardPlan;
+/**
+ * Admit a move to a larger automatic plan at now, recording it in history, or return why it is refused: The plan
+ * already has the largest total, or reshardLimit moves happened within reshardWindowMs. The history keeps only moves
+ * inside the window
+ */
+export declare function admitReshard(history: number[], now: number, totalShards: number): string | undefined;
+/** Route a guild snowflake to its planned shard. Callers provide a validated plan total */
+export declare function guildShardId(guildId: string, totalShards: number): number;
+/** Check a loaded snapshot: The frozen copy to resume, or why it cannot be resumed */
+export declare function checkSnapshot(value: unknown, gatewayUrl: string, totalShards: number, nowMs: number): {
+    readonly snapshot: SessionSnapshot;
+} | {
+    readonly problem: string;
+};
+//# sourceMappingURL=sharding.d.ts.map

package/dist/internal/sharding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharding.d.ts","sourceRoot":"","sources":["../../src/internal/sharding.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAMvF,+CAA+C;AAC/C,eAAO,MAAM,iBAAiB,QAAS,CAAA;AAEvC;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,QAA8B,CAAA;AAEzD,MAAM,WAAW,SAAS;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;CACnC;AAED,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAA;IACjC,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAA;IAC3C,yGAAyG;IACzG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CACjC;AAiCD,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,GAAG,kBAAkB,CA0FxF;AAED,sHAAsH;AACtH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAK1F;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQpG;AAUD,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEzE;AAaD,sFAAsF;AACtF,wBAAgB,aAAa,CACzB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACd;IAAE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiCvE"}