@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/internal/rest/owner.js

@@ -0,0 +1,1292 @@
+/**
+ * One client's REST owner: Request validation per operation group, instance resolution, uploads, bounded read retries,
+ * rate-limit waits and cache guards around each operation.
+ * Invariant: Every operation registers its cache guards before discovery and queue or rate waits, releases upload
+ * reservations and transfer sources however it ends, and no rate-limit learning crosses REST owners, credentials or
+ * instance selections. Reads retry only under the bounded read policy, and mutations retry only after a confirmed
+ * rate-limit rejection. Implements
+ * [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { randomUUID } from "node:crypto";
+import * as Cause from "effect/Cause";
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Random from "effect/Random";
+import { ClientClosedError } from "#sdk/errors";
+import { responseFieldText } from "#sdk/api-errors";
+import { MessageError, MessageOperationError } from "#sdk/message-errors";
+import { InputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation";
+import { AttachmentRefreshError } from "#sdk/attachments";
+import { GuildOperationError } from "#sdk/guilds";
+import { ChannelOperationError } from "#sdk/channels";
+import { WebhookOperationError } from "#sdk/webhooks";
+import { UserOperationError } from "#sdk/users";
+import { BotApplicationOperationError, } from "#sdk/application";
+import { identifier, record, snapshotArray } from "../decode/primitives.js";
+import { failingFieldPath } from "../decode/trace.js";
+import { inputDefect, suspendInput } from "../defects.js";
+import { mapFailureCause, withDeadline } from "../effect-failures.js";
+import { decodeCrosspostSource, encodeEdit, encodeForward, encodeHistory, encodeMessage, snapshotReference, } from "../message.js";
+import { decodeUploadPlans } from "../uploads.js";
+import { readResponseJson } from "../response-json.js";
+import { AttachmentTransferSource } from "../transfer-source.js";
+import { encodeReactionEmoji, encodeReactionUsersQuery, decodeReactionUsersPage } from "../reactions.js";
+import { decodePinsPage, encodePinsQuery } from "../pins.js";
+import { decodeMessageSearchPage, encodeMessageSearch } from "../message-search.js";
+import { auditSettings } from "../audit.js";
+import { directMessageOpen } from "../users.js";
+import { attachmentRefresh } from "../attachment-refresh.js";
+import { metrics } from "../metrics.js";
+import { emitObservation } from "../observer.js";
+import { linkRejectionError } from "../rejection-scope.js";
+import { rateRoute, routeTemplate } from "../rate-limits.js";
+import { defaultHttpTransport } from "../transport/index.js";
+import { RestAdmission } from "./admission.js";
+import { defaultRestConfiguration } from "./options.js";
+import { RestRequestError, } from "#sdk/rest";
+import { completeCleanup, runAttempt } from "./attempt.js";
+import { encodeRestRequest, readRestResponse } from "./request.js";
+import { inputFailure, instanceFailure, localInputFailure, operationFailure, RestFailure, } from "./classify.js";
+import { UnobservedDownloadDefects, downloadAttachment, openAttachmentStream, } from "./download.js";
+/** Longest single timer delay, and the largest accepted timeoutMs */
+const maximumTimerMs = 2_147_483_647;
+/** Bounded retries for a GET after a transient failure */
+const maximumReadRetries = 2;
+/** Minimum backoff before the first and later read retries, before jitter */
+const firstReadRetryMs = 125;
+const laterReadRetryMs = 250;
+/** Rate-limit waits of at least this long are logged at Warn */
+const longRateLimitWaitMs = 1_000;
+/** Largest upload-planning and upload-completion response */
+const uploadResponseMaxBytes = 1_048_576;
+/** Least time between two rest.busy Warn records of one client */
+const busyWarnIntervalMs = 60_000;
+/** Mutable state shared by one owner's operations, attempts and downloads */
+export class RestRuntime {
+    /** Set by stop. No operation starts or continues its request after closure */
+    closed = false;
+    /** The owner's resolved instance, kept after the first successful discovery */
+    instance;
+    /** Attachment file bytes reserved by running operations */
+    uploadBytes = 0;
+    /** Stream cleanup failures that no caller observed, surfaced by shutdown */
+    unobservedDownloadDefects = new UnobservedDownloadDefects();
+    controllers = new Set();
+    downloads = new Set();
+    /** Completion signals for every running operation, awaited by shutdown */
+    operations = new Set();
+    admission;
+    http;
+    /** Scheduling limits and the default deadline for operations and downloads that omit timeoutMs */
+    settings;
+    cache;
+    resources;
+    channels;
+    users;
+    logical;
+    logging;
+    resolveInstance;
+    /** Logical time of the last rest.busy Warn, repeated at most once per busyWarnIntervalMs */
+    #busyWarnedAt;
+    /**
+     * Logical time of the last ratelimit.deadline Warn for requests refused before dispatch, per route template.
+     * Each new Warn first removes entries older than busyWarnIntervalMs, which no longer hold back a Warn, so the map
+     * holds only routes warned within one interval of the latest Warn
+     */
+    deadlineWarnedAt = new Map();
+    constructor(options) {
+        this.settings = options.settings ?? defaultRestConfiguration;
+        this.admission = new RestAdmission(options.logical, this.settings, () => this.busy("queue"), options.shareGlobalPause);
+        this.http = options.http ?? defaultHttpTransport;
+        this.cache = options.cache;
+        this.resources = options.resources;
+        this.channels = options.channels;
+        this.users = options.users;
+        this.logical = options.logical;
+        this.logging = options.logging;
+        this.resolveInstance = options.resolveInstance;
+    }
+    /**
+     * Count a request that failed with busy, and warn at most once a minute that a REST budget is full, naming the full
+     * budget. Busy failures are returned to the caller, so the Warn exists only to make a saturated client visible
+     */
+    busy(budget) {
+        this.logging?.count("restBusy");
+        const now = this.logical.now();
+        if (this.#busyWarnedAt !== undefined && now - this.#busyWarnedAt < busyWarnIntervalMs)
+            return;
+        this.#busyWarnedAt = now;
+        const queue = this.admission.diagnostics();
+        const full = budget === "uploads"
+            ? "attachments reserved by running uploads reached uploads.maxBytes"
+            : queue.queuedRequests >= queue.queuedCapacity
+                ? `${queue.queuedRequests} requests already wait for a slot (rest.maxQueued)`
+                : "the bodies of waiting requests reached rest.queuedJsonMaxBytes";
+        this.logging?.log({
+            level: "warn",
+            category: "rest",
+            code: "rest.busy",
+            message: `The REST queue is full because ${full}, so new requests fail with reason busy until it drains. Send fewer requests at once, or raise that limit. Further busy failures within a minute are counted in diagnostics().counters.restBusy without another record`,
+            fields: {
+                budget,
+                activeRequests: queue.activeRequests,
+                queuedRequests: queue.queuedRequests,
+                queuedCapacity: queue.queuedCapacity,
+            },
+        });
+    }
+}
+async function readMessage(response, channel, id, signal, decode) {
+    const decoded = await readDecoded(response, signal, decode);
+    if (decoded.channelId !== channel)
+        throw responseFailure(response, "channelMismatch");
+    if (id !== undefined && decoded.id !== id)
+        throw responseFailure(response, "idMismatch");
+    return decoded;
+}
+async function readHistory(response, channel, query, signal, decode) {
+    const body = await readResponseJson(response, undefined, signal);
+    const invalid = (field) => responseFailure(response, field);
+    if (!Array.isArray(body))
+        throw invalid("body");
+    if (body.length > query.limit)
+        throw invalid("tooMany");
+    const messages = [];
+    const before = query.params.get("before");
+    const after = query.params.get("after");
+    let previous;
+    for (const [index, item] of body.entries()) {
+        const message = decode(item);
+        if (!message)
+            throw invalid(`${index}.${failingFieldPath(decode, item) ?? "message"}`);
+        if (message.channelId !== channel)
+            throw invalid("channelMismatch");
+        const id = BigInt(message.id);
+        if ((previous !== undefined && id >= previous) ||
+            (before !== null && id >= BigInt(before)) ||
+            (after !== null && id <= BigInt(after)))
+            throw invalid("order");
+        previous = id;
+        messages.push(message);
+    }
+    return Object.freeze(messages);
+}
+/** A response failure for a decoded value that did not match the operation's expected shape. The field names the
+ * response field path or check that failed, never a value
+ */
+const responseFailure = (response, field) => new RestFailure({ reason: "response", outcome: "unknown", status: response.status, responseField: field ?? null });
+/** Read and decode a JSON response with a pure decoder, failing with the field where the decoder stopped */
+async function readDecoded(response, signal, decode) {
+    const value = await readResponseJson(response, undefined, signal);
+    const decoded = decode(value);
+    if (decoded === undefined)
+        throw responseFailure(response, failingFieldPath(decode, value));
+    return decoded;
+}
+/** Read operation options and their requested deadline once. Only an application getter or proxy can throw here */
+function deadlineOption(options) {
+    if (options !== undefined && !record(options))
+        return { valid: false, timeoutMs: undefined };
+    return { valid: true, timeoutMs: options?.timeoutMs };
+}
+/** Options every REST operation accepts. The Effect API has no signal, but accepting it keeps both APIs' checks equal */
+const operationOptionKeys = ["timeoutMs", "signal"];
+/** Reject the first options key outside keys, naming it with the closest supported key */
+function unsupportedOptionFailure(options, keys) {
+    const unsupported = record(options)
+        ? unsupportedKeyFailure(options, keys, "options", "the operation options")
+        : undefined;
+    return unsupported && inputFailure(unsupported.detail);
+}
+/** Reject options that are not an object or contain fields other than timeoutMs and signal */
+function timeoutOptionsFailure(options) {
+    if (options !== undefined && !record(options))
+        return localInputFailure("options", "type", "the operation options must be an object");
+    return unsupportedOptionFailure(options, operationOptionKeys);
+}
+/** One client's transient REST scheduler, without shared-token coordination or durable delivery */
+export class RestOwner {
+    #runtime;
+    #uploadMaxBytes;
+    #decodeMessage;
+    constructor(options) {
+        this.#runtime = new RestRuntime(options);
+        this.#uploadMaxBytes = options.uploadMaxBytes;
+        this.#decodeMessage = options.decodeMessage;
+    }
+    /** The client's default operation deadline in milliseconds, from rest.defaultTimeoutMs */
+    get defaultTimeoutMs() {
+        return this.#runtime.settings.defaultTimeoutMs;
+    }
+    /** Size the default API request slots for the client's local shard count */
+    scaleConcurrency(localShards) {
+        this.#runtime.admission.scaleConcurrency(localShards);
+    }
+    /** Apply a global pause another process learned, lasting waitMs from now, without sharing it again */
+    pauseGlobal(waitMs) {
+        this.#runtime.admission.pauseGlobal(this.#runtime.logical.now() + waitMs, true);
+    }
+    /** Completion signals of the operations and downloads running now, queued ones included, for a draining shutdown */
+    inFlight() {
+        return [...this.#runtime.operations];
+    }
+    diagnostics() {
+        return {
+            ...this.#runtime.admission.diagnostics(),
+            reservedUploadBytes: this.#runtime.uploadBytes,
+            uploadByteCapacity: this.#uploadMaxBytes,
+        };
+    }
+    refreshAttachmentUrls(token, urls, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = attachmentRefresh(urls);
+            if (input instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(input.detail));
+            const invalid = timeoutOptionsFailure(options);
+            if (invalid)
+                return Effect.fail(invalid);
+            return this.#execute(token, {
+                channel: "attachments",
+                bucket: "attachments:refresh",
+                cache: false,
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                body: { json: input.json, files: [] },
+                decode: async (response, _instance, signal) => {
+                    return readDecoded(response, signal, (value) => input.decode(value));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, AttachmentRefreshError, "attachments.refreshUrls")));
+    }
+    openDownload(attachment, options) {
+        return openAttachmentStream(this.#runtime, attachment, options);
+    }
+    download(attachment, options) {
+        return downloadAttachment(this.#runtime, attachment, options);
+    }
+    reply(token, target, input, options) {
+        return this.#send(token, target.channelId, () => encodeMessage(target.channelId, input, randomUUID().replaceAll("-", ""), target), options);
+    }
+    send(token, channel, input, options, directMessageUser) {
+        return this.#send(token, channel, () => encodeMessage(channel, input, randomUUID().replaceAll("-", ""), undefined, directMessageUser !== undefined), options, directMessageUser);
+    }
+    forward(token, channel, input, options) {
+        return this.#send(token, channel, () => encodeForward(channel, input, randomUUID().replaceAll("-", "")), options);
+    }
+    #send(token, channel, encode, options, directMessageUser) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const body = encode();
+            if (body instanceof MessageError)
+                return Effect.fail(body);
+            return this.#execute(token, {
+                method: "POST",
+                channel,
+                body,
+                path: `/channels/${channel}/messages`,
+                ...(directMessageUser === undefined ? {} : { directMessageUser }),
+                decodeDirectMessage: (response, channelId, signal) => readMessage(response, channelId, undefined, signal, this.#decodeMessage),
+                observe: (message, guard) => this.#runtime.cache.complete(guard, [message]),
+                decode: (response, _instance, signal) => readMessage(response, channel, undefined, signal, this.#decodeMessage),
+            }, options).pipe(mapFailureCause((error) => error instanceof RestFailure
+                ? linkRejectionError(new MessageError({
+                    reason: error.reason === "notFound" ? "rejected" : error.reason,
+                    outcome: error.outcome,
+                    status: error.status,
+                    retryAfterMs: error.retryAfterMs,
+                    apiError: error.apiError,
+                    inputValidation: error.inputValidation,
+                    providerCode: error.providerCode,
+                    responseField: error.responseField,
+                    // Keep the transport failure visible, as the other operation errors do
+                    ...(error.cause === undefined ? {} : { cause: error.cause }),
+                }), error)
+                : error));
+        });
+    }
+    fetch(token, target, options) {
+        return this.#manage(token, "fetch", target, undefined, options, (response, ref, signal) => readMessage(response, ref.channelId, ref.id, signal, this.#decodeMessage), (message, guard) => this.#runtime.cache.complete(guard, [message]));
+    }
+    publish(token, target, options) {
+        return this.#manage(token, "publish", target, undefined, options, (response, ref, signal) => readMessage(response, ref.channelId, ref.id, signal, this.#decodeMessage), (message, guard) => this.#runtime.cache.complete(guard, [message]));
+    }
+    fetchCrosspostSource(token, target, options) {
+        return this.#manage(token, "fetchCrosspostSource", target, undefined, options, (response, _ref, signal) => readDecoded(response, signal, decodeCrosspostSource));
+    }
+    typing(token, channel, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            if (!identifier(channel))
+                return Effect.fail(localInputFailure("channelId", "format", "Channel IDs must be decimal strings"));
+            const invalid = timeoutOptionsFailure(options);
+            if (invalid)
+                return Effect.fail(invalid);
+            return this.#execute(token, {
+                method: "POST",
+                channel,
+                bucket: "typing",
+                cache: false,
+                path: `/channels/${channel}/typing`,
+                body: undefined,
+                status: 204,
+                decode: async () => { },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "typing")));
+    }
+    fetchHistory(token, channel, query, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const encoded = encodeHistory(channel, query);
+            if (encoded instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(encoded.detail));
+            return this.#execute(token, {
+                method: "GET",
+                channel,
+                bucket: "history",
+                path: `/channels/${channel}/messages?${encoded.params}`,
+                body: undefined,
+                status: 200,
+                decode: (response, _instance, signal) => readHistory(response, channel, encoded, signal, this.#decodeMessage),
+                observe: (messages, guard) => this.#runtime.cache.complete(guard, messages),
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "fetchHistory")));
+    }
+    search(token, context, query, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const encoded = encodeMessageSearch(context, query);
+            if (encoded instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(encoded.detail));
+            return this.#execute(token, {
+                method: "POST",
+                channel: encoded.context.channelId ?? encoded.context.guildId,
+                bucket: "search",
+                cache: false,
+                path: "/search/messages",
+                body: { json: encoded.json, files: [] },
+                status: 200,
+                decode: async (response, _instance, signal) => {
+                    return readDecoded(response, signal, (value) => decodeMessageSearchPage(value, this.#decodeMessage));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "search")));
+    }
+    edit(token, target, input, options) {
+        return this.#manage(token, "edit", target, input, options, (response, ref, signal) => readMessage(response, ref.channelId, ref.id, signal, this.#decodeMessage), (message, guard) => this.#runtime.cache.complete(guard, [message]));
+    }
+    delete(token, target, options) {
+        return this.#manage(token, "delete", target, undefined, options, async () => { });
+    }
+    deleteAttachment(token, target, attachmentId, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const ref = snapshotReference(target);
+            if (ref === undefined)
+                return Effect.fail(localInputFailure("target", "format", "Message targets require decimal id and channelId strings"));
+            if (!identifier(attachmentId))
+                return Effect.fail(localInputFailure("attachmentId", "format", "Attachment IDs must be decimal strings"));
+            return this.#execute(token, {
+                method: "DELETE",
+                channel: ref.channelId,
+                target: ref.id,
+                path: `/channels/${ref.channelId}/messages/${ref.id}/attachments/${attachmentId}`,
+                body: undefined,
+                status: 204,
+                decode: async () => { },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "deleteAttachment")));
+    }
+    deleteMany(token, channelId, ids, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            if (!identifier(channelId))
+                return Effect.fail(localInputFailure("channelId", "format", "Channel IDs must be decimal strings"));
+            if (!Array.isArray(ids))
+                return Effect.fail(localInputFailure("messageIds", "type", "Message IDs must be an array"));
+            // Copy the caller array once and validate the copy, so the validated IDs are the ones sent
+            const snapshot = snapshotArray(ids, 100);
+            if (snapshot === undefined || snapshot.length < 1)
+                return Effect.fail(localInputFailure("messageIds", "length", "Bulk deletion requires 1 through 100 message IDs"));
+            if (!snapshot.every(identifier))
+                return Effect.fail(localInputFailure("messageIds[]", "format", "Message IDs must be decimal strings"));
+            if (new Set(snapshot).size !== snapshot.length)
+                return Effect.fail(localInputFailure("messageIds", "unique", "Message IDs must be unique"));
+            const audit = auditSettings(options);
+            if (audit instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(audit.detail));
+            return this.#execute(token, {
+                method: "POST",
+                channel: channelId,
+                bucket: "bulk-delete",
+                ...(audit.auditReason === undefined ? {} : { auditReason: audit.auditReason }),
+                cache: false,
+                deleteIds: snapshot,
+                path: `/channels/${channelId}/messages/bulk-delete`,
+                body: { json: JSON.stringify({ message_ids: snapshot }), files: [] },
+                status: 204,
+                decode: async () => { },
+            }, options, [...operationOptionKeys, "auditReason"]);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "deleteMany")));
+    }
+    deleteOwnMessages(token, channelId, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            if (!identifier(channelId))
+                return Effect.fail(localInputFailure("channelId", "format", "Channel IDs must be decimal strings"));
+            const invalid = timeoutOptionsFailure(options);
+            if (invalid)
+                return Effect.fail(invalid);
+            return this.#execute(token, {
+                method: "POST",
+                channel: channelId,
+                bucket: "bulk-delete-mine",
+                cache: false,
+                invalidateMessages: true,
+                path: `/channels/${channelId}/messages/bulk-delete-mine`,
+                body: undefined,
+                status: 202,
+                decode: async () => { },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "deleteOwnMessages")));
+    }
+    fetchReactionUsers(token, target, emoji, query, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const encoded = encodeReactionEmoji(emoji);
+            const page = encodeReactionUsersQuery(query);
+            const ref = snapshotReference(target);
+            if (ref === undefined)
+                return Effect.fail(localInputFailure("target", "format", "Message targets require decimal id and channelId strings"));
+            if (encoded === undefined)
+                return Effect.fail(localInputFailure("emoji", "format", "Reaction emoji must be Unicode text or a custom emoji with a decimal ID"));
+            if (page instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(page.detail));
+            return this.#execute(token, {
+                method: "GET",
+                channel: ref.channelId,
+                bucket: "reaction",
+                path: `/channels/${ref.channelId}/messages/${ref.id}/reactions/${encoded}/users?${page.params}`,
+                body: undefined,
+                status: 200,
+                decode: async (response, _instance, signal) => {
+                    return readDecoded(response, signal, (value) => decodeReactionUsersPage(value, page));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "fetchReactionUsers")));
+    }
+    fetchPins(token, channel, query, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const page = encodePinsQuery(channel, query);
+            if (page instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(page.detail));
+            return this.#execute(token, {
+                method: "GET",
+                channel,
+                bucket: "pins",
+                path: `/channels/${channel}/messages/pins?${page.params}`,
+                body: undefined,
+                status: 200,
+                decode: async (response, _instance, signal) => {
+                    return readDecoded(response, signal, (value) => decodePinsPage(value, channel, page, this.#decodeMessage));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, "fetchPins")));
+    }
+    pin(token, operation, target, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const ref = snapshotReference(target);
+            if (ref === undefined)
+                return Effect.fail(localInputFailure("target", "format", "Message targets require decimal id and channelId strings"));
+            const audit = auditSettings(options);
+            if (audit instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(audit.detail));
+            return this.#execute(token, {
+                method: operation === "pin" ? "PUT" : "DELETE",
+                ...(audit.auditReason === undefined ? {} : { auditReason: audit.auditReason }),
+                channel: ref.channelId,
+                target: ref.id,
+                bucket: "pins",
+                path: `/channels/${ref.channelId}/pins/${ref.id}`,
+                body: undefined,
+                status: 204,
+                decode: async () => { },
+            }, options, [...operationOptionKeys, "auditReason"]);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, operation)));
+    }
+    reaction(token, operation, target, emoji, options, userId) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const encoded = operation === "clearReactions" ? "" : encodeReactionEmoji(emoji);
+            const ref = snapshotReference(target);
+            if (ref === undefined)
+                return Effect.fail(localInputFailure("target", "format", "Message targets require decimal id and channelId strings"));
+            if (encoded === undefined)
+                return Effect.fail(localInputFailure("emoji", "format", "Reaction emoji must be Unicode text or a custom emoji with a decimal ID"));
+            if (operation === "removeUserReaction" && !identifier(userId))
+                return Effect.fail(localInputFailure("userId", "format", "User IDs must be decimal strings"));
+            const suffix = operation === "clearReactions"
+                ? ""
+                : operation === "clearReaction"
+                    ? `/${encoded}`
+                    : `/${encoded}/${operation === "removeUserReaction" ? userId : "@me"}`;
+            return this.#execute(token, {
+                method: operation === "addReaction" ? "PUT" : "DELETE",
+                channel: ref.channelId,
+                bucket: "reaction",
+                path: `/channels/${ref.channelId}/messages/${ref.id}/reactions${suffix}`,
+                body: undefined,
+                status: 204,
+                decode: async () => { },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, operation)));
+    }
+    #manage(token, operation, target, input, options, decode, observe) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const ref = snapshotReference(target);
+            if (ref === undefined)
+                return Effect.fail(localInputFailure("target", "format", "Message targets require decimal id and channelId strings"));
+            const body = operation === "edit" ? encodeEdit(input) : undefined;
+            if (body instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(body.detail));
+            const audit = operation === "delete" ? auditSettings(options) : undefined;
+            if (audit instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(audit.detail));
+            return this.#execute(token, {
+                method: operation === "fetch" || operation === "fetchCrosspostSource"
+                    ? "GET"
+                    : operation === "publish"
+                        ? "POST"
+                        : operation === "edit"
+                            ? "PATCH"
+                            : "DELETE",
+                channel: ref.channelId,
+                target: ref.id,
+                ...(operation === "publish"
+                    ? { bucket: "channel:message:crosspost", messageMutation: true }
+                    : operation === "fetchCrosspostSource"
+                        ? { bucket: "channel:message:crosspost_source", cache: false }
+                        : {}),
+                path: `/channels/${ref.channelId}/messages/${ref.id}${operation === "publish"
+                    ? "/crosspost"
+                    : operation === "fetchCrosspostSource"
+                        ? "/crosspost-source"
+                        : ""}`,
+                body,
+                status: operation === "delete" ? 204 : 200,
+                ...(audit?.auditReason === undefined ? {} : { auditReason: audit.auditReason }),
+                decode: (response, _instance, signal) => decode(response, ref, signal),
+                ...(observe === undefined ? {} : { observe }),
+            }, options, operation === "delete" ? [...operationOptionKeys, "auditReason"] : operationOptionKeys);
+        }).pipe(mapFailureCause((error) => operationFailure(error, MessageOperationError, operation)));
+    }
+    /** Run attempts for one request until it succeeds, fails permanently, runs out of read retries or passes its deadline */
+    #exchange(token, options) {
+        const runtime = this.#runtime;
+        const { request, progress, generation, deadline, retainedBytes = 0 } = options;
+        // A long pause can refuse every request on a route, so only the first refusal per route and minute is a Warn
+        const deadlineLevel = (template, retryAfterMs) => {
+            if (retryAfterMs < longRateLimitWaitMs)
+                return "debug";
+            const now = runtime.logical.now();
+            const last = runtime.deadlineWarnedAt.get(template);
+            if (last !== undefined && now - last < busyWarnIntervalMs)
+                return "debug";
+            for (const [warned, at] of runtime.deadlineWarnedAt)
+                if (now - at >= busyWarnIntervalMs)
+                    runtime.deadlineWarnedAt.delete(warned);
+            runtime.deadlineWarnedAt.set(template, now);
+            return "warn";
+        };
+        const route = rateRoute(request.method, request.path, request.channel, request.bucket, request.webhookId);
+        const template = request.template ?? routeTemplate(request.put ? "/attachments/upload" : request.path, request.webhookId);
+        const bytes = retainedBytes + Buffer.byteLength(request.body?.json ?? "");
+        return Effect.gen(function* () {
+            const fiber = yield* Effect.withFiber((fiber) => Effect.succeed(fiber));
+            let retries = 0;
+            let attempts = 0;
+            let until = 0;
+            while (true) {
+                const retryCount = attempts++;
+                const attempt = yield* Effect.uninterruptibleMask((restore) => Effect.exit(restore(Effect.acquireUseRelease(Effect.interruptible(runtime.admission.acquire({ route: route.key, bytes, until, deadline })).pipe(mapFailureCause((error) => error instanceof RestFailure ? error.withOutcome(progress.outcome) : error)), () => runtime.logical.now() >= deadline
+                    ? Effect.fail(new RestFailure({ reason: "timeout", outcome: progress.outcome }))
+                    : runAttempt({
+                        runtime,
+                        token,
+                        request,
+                        route,
+                        progress,
+                        generation,
+                        fiber,
+                        retryCount,
+                    }), (release) => Effect.sync(release)))).pipe(Effect.flatMap((exit) => Exit.isFailure(exit) && (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause))
+                    ? Effect.failCause(exit.cause)
+                    : Effect.succeed(exit))));
+                if (Exit.isFailure(attempt)) {
+                    const reason = attempt.cause.reasons.find((reason) => reason._tag === "Fail");
+                    if (reason?._tag !== "Fail")
+                        return yield* Effect.die(new Error("REST request failed without a cause"));
+                    const error = reason.error;
+                    // Admission fails a request whose learned wait outlasts its deadline. That is the only rate-limit
+                    // failure without an HTTP status, and it is logged like a 429 whose wait passes the deadline
+                    if (error instanceof RestFailure &&
+                        error.reason === "rateLimit" &&
+                        error.status === null &&
+                        error.retryAfterMs !== null)
+                        runtime.logging?.log({
+                            level: deadlineLevel(template, error.retryAfterMs),
+                            category: "ratelimit",
+                            code: "ratelimit.deadline",
+                            message: `${request.method} ${template} is rate-limited for another ${error.retryAfterMs} ms, which is past its timeout, so it fails without waiting`,
+                            route: template,
+                            delayMs: error.retryAfterMs,
+                            fields: { method: request.method },
+                        }, fiber.context);
+                    // An unusable success response usually means a Fluxer schema change or a wrong test fixture,
+                    // so it is logged once per route and field, mirroring gateway.dispatchRejected. A caller-described
+                    // route has no expected shape, so its failure is only returned to the caller
+                    if (error instanceof RestFailure && error.reason === "response" && !request.callerDescribed)
+                        runtime.logging?.log({
+                            level: "warn",
+                            category: "rest",
+                            code: "rest.responseRejected",
+                            message: `${request.method} ${template} returned an answer in an unexpected format${error.responseField === null ? "" : `: ${responseFieldText(error.responseField)}`}`,
+                            route: template,
+                            ...(error.status === null ? {} : { status: error.status }),
+                            fields: { method: request.method, field: error.responseField ?? undefined },
+                        }, fiber.context);
+                    if (request.method !== "GET" ||
+                        !(error instanceof RestFailure) ||
+                        !error.retryableRead ||
+                        retries === maximumReadRetries)
+                        return yield* Effect.fail(error);
+                    const minimum = retries++ === 0 ? firstReadRetryMs : laterReadRetryMs;
+                    const delay = Math.max(minimum * (1 + (yield* Random.next)), error.retryAfterMs ?? 0);
+                    // A retry that cannot start before the deadline would only end as a timeout, so the received failure is returned now
+                    if (runtime.logical.now() + Math.ceil(delay) >= deadline)
+                        return yield* Effect.fail(error);
+                    until = runtime.logical.now() + Math.ceil(delay);
+                    runtime.logging?.drop("restRetries", {
+                        level: "debug",
+                        category: "rest",
+                        code: "rest.retry",
+                        message: `Retrying ${request.method} ${template} after ${error.status === null ? `a ${error.reason} failure` : `HTTP ${error.status}`} in ${Math.ceil(delay)} ms`,
+                        route: template,
+                        attempt: attempts + 1,
+                        delayMs: Math.ceil(delay),
+                        ...(error.status === null ? {} : { status: error.status }),
+                        fields: { method: request.method, reason: error.reason },
+                    }, fiber.context);
+                    continue;
+                }
+                const response = attempt.value;
+                if (response.kind === "success")
+                    return response.value;
+                if ((request.inlineAttachments || request.webhookId) &&
+                    request.sources?.some((source) => !source.replayable))
+                    return yield* Effect.fail(new RestFailure({
+                        reason: "rateLimit",
+                        outcome: progress.outcome,
+                        status: 429,
+                        retryAfterMs: response.retry,
+                        apiError: response.apiError,
+                        providerCode: response.providerCode ?? null,
+                    }));
+                until = runtime.logical.now() + response.retry;
+                if (response.global)
+                    runtime.admission.pauseGlobal(until);
+                if (until >= deadline) {
+                    // No wait happens: The request fails now, so this is not counted as a rate-limit wait
+                    runtime.logging?.log({
+                        level: response.retry >= longRateLimitWaitMs ? "warn" : "debug",
+                        category: "ratelimit",
+                        code: "ratelimit.deadline",
+                        message: `${request.method} ${template} was rate-limited${response.global ? " globally" : ""} for ${response.retry} ms, which is past its timeout, so it fails without waiting`,
+                        route: template,
+                        status: 429,
+                        delayMs: response.retry,
+                        attempt: attempts,
+                        fields: { method: request.method, global: response.global },
+                    }, fiber.context);
+                    return yield* Effect.fail(new RestFailure({
+                        reason: "rateLimit",
+                        outcome: progress.outcome,
+                        status: 429,
+                        retryAfterMs: response.retry,
+                        apiError: response.apiError,
+                        providerCode: response.providerCode ?? null,
+                    }));
+                }
+                metrics.rateLimitWait(response.retry, fiber.context);
+                emitObservation(runtime.logging, {
+                    type: "rateLimit",
+                    method: request.method,
+                    route: template,
+                    waitMs: response.retry,
+                    global: response.global,
+                });
+                runtime.logging?.drop("rateLimitWaits", {
+                    level: response.retry >= longRateLimitWaitMs ? "warn" : "debug",
+                    category: "ratelimit",
+                    code: "ratelimit.wait",
+                    message: `${request.method} ${template} was rate-limited${response.global ? " globally" : ""}, so it waits ${response.retry} ms before retrying`,
+                    route: template,
+                    status: 429,
+                    delayMs: response.retry,
+                    attempt: attempts,
+                    fields: { method: request.method, global: response.global },
+                }, fiber.context);
+            }
+        });
+    }
+    /** Plan and upload attachment files through presigned destinations, or fall back to inline multipart */
+    #prepareUploads(token, body, sources, context) {
+        const owner = this;
+        const { channel, instance, progress, generation, deadline } = context;
+        return Effect.gen(function* () {
+            const inline = () => {
+                const payload = JSON.parse(body.json);
+                payload.attachments = payload.attachments.map((item) => {
+                    const file = body.files.find((file) => file.id === item.id);
+                    if (!file)
+                        return item;
+                    return { ...item, filename: file.filename, content_type: file.contentType };
+                });
+                body.json = JSON.stringify(payload);
+                return "inline";
+            };
+            if (!instance.presignedAttachmentUploads)
+                return inline();
+            const retainedBytes = Buffer.byteLength(body.json);
+            const attachments = body.files.map((file) => ({
+                id: file.id,
+                filename: file.filename,
+                file_size: file.size,
+                content_type: file.contentType,
+            }));
+            const planned = yield* owner.#exchange(token, {
+                request: {
+                    method: "POST",
+                    channel,
+                    bucket: "upload",
+                    preparation: true,
+                    instance,
+                    path: `/channels/${channel}/attachments`,
+                    body: { json: JSON.stringify({ attachments }), files: [] },
+                    decode: async (response, _instance, signal) => {
+                        const plans = decodeUploadPlans(await readResponseJson(response, uploadResponseMaxBytes, signal), body.files, instance.allowInsecure);
+                        if (!plans)
+                            throw new RestFailure({
+                                reason: "response",
+                                outcome: "notDispatched",
+                                status: response.status,
+                            });
+                        return { kind: "plans", plans };
+                    },
+                    featureDisabled: () => ({ kind: "disabled" }),
+                },
+                progress,
+                generation,
+                deadline,
+                retainedBytes,
+            });
+            if (planned.kind === "disabled")
+                return inline();
+            const plans = planned.plans;
+            // Charge retained plan capabilities too while queued. They are never exposed as diagnostics
+            const queuedBytes = retainedBytes + Buffer.byteLength(JSON.stringify(plans));
+            for (const plan of plans) {
+                const file = body.files.find((file) => file.id === plan.id);
+                const source = sources[body.files.indexOf(file)];
+                if (!source)
+                    return yield* Effect.fail(new RestFailure({ reason: "response", outcome: "notDispatched" }));
+                for (const part of plan.parts) {
+                    yield* owner.#exchange(token, {
+                        request: {
+                            method: "PUT",
+                            channel,
+                            preparation: true,
+                            instance,
+                            path: "",
+                            body: undefined,
+                            put: {
+                                ...part,
+                                source,
+                                ...(plan.uploadId ? {} : { contentType: plan.contentType }),
+                            },
+                            decode: async () => { },
+                        },
+                        progress,
+                        generation,
+                        deadline,
+                        retainedBytes: queuedBytes,
+                    });
+                }
+            }
+            const uploads = plans
+                .filter((plan) => plan.uploadId !== undefined)
+                .map((plan) => ({ upload_filename: plan.key, upload_id: plan.uploadId }));
+            if (uploads.length)
+                yield* owner.#exchange(token, {
+                    request: {
+                        method: "POST",
+                        channel,
+                        bucket: "upload",
+                        preparation: true,
+                        instance,
+                        path: `/channels/${channel}/attachments/complete`,
+                        body: { json: JSON.stringify({ uploads }), files: [] },
+                        decode: async (response, _instance, signal) => {
+                            const value = await readResponseJson(response, uploadResponseMaxBytes, signal);
+                            if (!record(value) ||
+                                !Array.isArray(value.uploads) ||
+                                value.uploads.length !== uploads.length ||
+                                uploads.some((upload) => !Array.isArray(value.uploads) ||
+                                    value.uploads.filter((item) => record(item) && item.upload_filename === upload.upload_filename).length !== 1))
+                                throw new RestFailure({
+                                    reason: "response",
+                                    outcome: "notDispatched",
+                                    status: response.status,
+                                });
+                        },
+                    },
+                    progress,
+                    generation,
+                    deadline,
+                    retainedBytes: queuedBytes,
+                });
+            const payload = JSON.parse(body.json);
+            payload.attachments = payload.attachments.map((item) => {
+                const plan = plans.find((plan) => plan.id === item.id);
+                if (!plan)
+                    return item;
+                const file = body.files.find((file) => file.id === plan.id);
+                return {
+                    ...item,
+                    filename: plan.filename,
+                    content_type: plan.contentType,
+                    file_size: file.size,
+                    upload_filename: plan.key,
+                };
+            });
+            body.json = JSON.stringify(payload);
+            return "preuploaded";
+        });
+    }
+    guild(token, operation, build, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = build();
+            if (input instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(input.detail));
+            if (options !== undefined && !record(options))
+                return Effect.fail(localInputFailure("options", "type", "Operation options must be an object"));
+            const audit = input.audited ? auditSettings(options) : undefined;
+            if (audit instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(audit.detail));
+            const auditReason = input.auditReason ?? audit?.auditReason;
+            const acceptedOptions = [
+                "timeoutMs",
+                "signal",
+                ...(input.moderation || input.audited ? ["auditReason"] : []),
+                ...(input.timeoutReason ? ["timeoutReason"] : []),
+                ...(input.method === "DELETE" && ["guild:emojis", "guild:stickers"].includes(input.bucket)
+                    ? ["purge"]
+                    : []),
+            ];
+            return this.#execute(token, {
+                // The scheduler's major-resource key is the guild here, never a message-cache channel
+                channel: input.guildId,
+                bucket: input.bucket,
+                cache: false,
+                ...(input.cache === undefined ? {} : { resourceCache: input.cache }),
+                ...(input.channelCache === undefined ? {} : { channelCache: input.channelCache }),
+                ...(input.moderation === undefined ? {} : { moderation: input.moderation }),
+                ...(auditReason === undefined ? {} : { auditReason }),
+                ...(input.deleteAuthorId === undefined ? {} : { deleteAuthorId: input.deleteAuthorId }),
+                ...(input.invalidateMessages === undefined ? {} : { invalidateMessages: input.invalidateMessages }),
+                ...(input.features === undefined ? {} : { features: input.features }),
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                body: input.json === undefined ? undefined : { json: input.json, files: [] },
+                decode: async (response, instance, signal) => {
+                    if (input.status === 202 || input.status === 204)
+                        return undefined;
+                    return readDecoded(response, signal, (value) => input.decode(value, instance));
+                },
+            }, options, acceptedOptions);
+        }).pipe(mapFailureCause((error) => operationFailure(error, GuildOperationError, operation)));
+    }
+    channel(token, operation, build, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = build();
+            if (input instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(input.detail));
+            if (options !== undefined && !record(options))
+                return Effect.fail(localInputFailure("options", "type", "Operation options must be an object"));
+            const audit = input.audited ? auditSettings(options) : undefined;
+            if (audit instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(audit.detail));
+            const acceptedOptions = input.audited ? [...operationOptionKeys, "auditReason"] : operationOptionKeys;
+            const accepted = input.accepted;
+            return this.#execute(token, {
+                channel: input.majorId,
+                bucket: input.bucket,
+                cache: false,
+                ...(input.cache === undefined ? {} : { channelCache: input.cache }),
+                ...(audit?.auditReason === undefined ? {} : { auditReason: audit.auditReason }),
+                ...(input.features === undefined ? {} : { features: input.features }),
+                path: input.path,
+                method: input.method,
+                // A route that can also answer 202 has its status checked here instead
+                ...(accepted === undefined ? { status: input.status } : {}),
+                body: input.body ?? (input.json === undefined ? undefined : { json: input.json, files: [] }),
+                // Presigned uploads rewrite top-level attachments, while a forum post nests them in its message
+                ...(input.body?.files.length ? { inlineAttachments: true } : {}),
+                decode: async (response, _instance, signal) => {
+                    if (input.status === 204)
+                        return undefined;
+                    if (accepted !== undefined && response.status === 202)
+                        return readDecoded(response, signal, (value) => accepted(value));
+                    if (response.status !== input.status)
+                        throw responseFailure(response, "status");
+                    return readDecoded(response, signal, (value) => input.decode(value));
+                },
+            }, options, acceptedOptions);
+        }).pipe(mapFailureCause((error) => operationFailure(error, ChannelOperationError, operation)));
+    }
+    user(token, operation, build, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = build();
+            if (input instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(input.detail));
+            const invalid = timeoutOptionsFailure(options);
+            if (invalid)
+                return Effect.fail(invalid);
+            return this.#execute(token, {
+                channel: input.majorId,
+                bucket: `user:${operation}`,
+                cache: false,
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                body: input.json === undefined ? undefined : { json: input.json, files: [] },
+                decode: async (response, _instance, signal) => {
+                    if (input.status === 204)
+                        return undefined;
+                    return readDecoded(response, signal, (value) => input.decode(value));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, UserOperationError, operation)));
+    }
+    application(token, operation, build, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = build();
+            const invalid = timeoutOptionsFailure(options);
+            if (invalid)
+                return Effect.fail(invalid);
+            return this.#execute(token, {
+                channel: "application",
+                bucket: "application:current",
+                cache: false,
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                body: undefined,
+                decode: async (response, _instance, signal) => {
+                    return readDecoded(response, signal, (value) => input.decode(value));
+                },
+            }, options);
+        }).pipe(mapFailureCause((error) => operationFailure(error, BotApplicationOperationError, operation)));
+    }
+    webhook(token, operation, build, options) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const input = build();
+            if (input instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(input.detail));
+            if (options !== undefined && !record(options))
+                return Effect.fail(localInputFailure("options", "type", "Operation options must be an object"));
+            const acceptedOptions = input.method !== "GET" && !input.tokenAuth
+                ? [...operationOptionKeys, "auditReason"]
+                : input.threadOption
+                    ? [...operationOptionKeys, "threadId"]
+                    : operationOptionKeys;
+            return this.#execute(token, {
+                channel: input.majorId,
+                bucket: `webhook:${input.tokenAuth ? "token" : operation}`,
+                cache: false,
+                ...(input.tokenAuth ? { webhookId: input.majorId } : {}),
+                ...(input.auditReason === undefined ? {} : { auditReason: input.auditReason }),
+                path: input.path,
+                method: input.method,
+                status: input.status,
+                body: input.body,
+                decode: async (response, _instance, signal) => {
+                    if (input.status === 204)
+                        return undefined;
+                    return readDecoded(response, signal, (value) => input.decode(value));
+                },
+            }, options, acceptedOptions);
+        }).pipe(mapFailureCause((error) => operationFailure(error, WebhookOperationError, operation)));
+    }
+    /**
+     * Validate the options and deadline, reserve upload bytes, register cache guards and run the operation to completion.
+     * The options may contain only optionKeys, which each operation family lists beside its own validation
+     */
+    #execute(token, request, options, optionKeys = operationOptionKeys) {
+        const owner = this;
+        const runtime = this.#runtime;
+        return Effect.suspend(() => {
+            if (runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            let requested;
+            let unsupported;
+            try {
+                requested = deadlineOption(options);
+                unsupported = unsupportedOptionFailure(options, optionKeys);
+            }
+            catch (error) {
+                return Effect.failCause(inputDefect(error));
+            }
+            if (!requested.valid)
+                return Effect.fail(localInputFailure("options", "type", "Operation options must be an object"));
+            if (unsupported)
+                return Effect.fail(unsupported);
+            const timeout = requested.timeoutMs === undefined ? runtime.settings.defaultTimeoutMs : requested.timeoutMs;
+            if (typeof timeout !== "number" ||
+                !Number.isSafeInteger(timeout) ||
+                timeout <= 0 ||
+                timeout > maximumTimerMs)
+                return Effect.fail(localInputFailure("options.timeoutMs", "range", "Operation timeoutMs must be an integer from 1 through 2,147,483,647 ms"));
+            const bytes = Buffer.byteLength(request.body?.json ?? "");
+            const uploadBytes = request.body?.files.reduce((sum, file) => sum + file.size, 0) ?? 0;
+            if (!Number.isSafeInteger(uploadBytes) || uploadBytes > owner.#uploadMaxBytes - runtime.uploadBytes) {
+                runtime.busy("uploads");
+                return Effect.fail(new RestFailure({ reason: "busy", outcome: "notDispatched" }));
+            }
+            // Check JSON/count admission before allocating binary snapshots, then reserve before any wait
+            if (!runtime.admission.hasRoom(bytes)) {
+                runtime.busy("queue");
+                return Effect.fail(new RestFailure({ reason: "busy", outcome: "notDispatched" }));
+            }
+            runtime.uploadBytes += uploadBytes;
+            try {
+                if (request.body) {
+                    request.body.files = request.body.files.map((file) => ({
+                        ...file,
+                        source: file.source.kind === "bytes"
+                            ? { kind: "bytes", data: new Uint8Array(file.source.data) }
+                            : file.source,
+                    }));
+                    request.sources = request.body.files.map((file) => new AttachmentTransferSource(file));
+                }
+            }
+            catch {
+                // allow-silent: An unreadable caller source becomes the typed input failure returned below
+                runtime.uploadBytes -= uploadBytes;
+                return Effect.fail(localInputFailure("attachments[].data", "type", "Attachment byte data must stay readable until the operation has copied it"));
+            }
+            const deadline = runtime.logical.now() + timeout;
+            const generation = runtime.cache?.generation ?? 0;
+            const progress = { outcome: "notDispatched" };
+            const deletionGuard = request.deleteIds && runtime.cache?.begin(request.channel, undefined, true, generation);
+            // Register before discovery and queue/rate waits so events, writes and gaps invalidate the whole operation
+            const resourceGuard = request.resourceCache && runtime.resources?.begin(request.resourceCache);
+            if (resourceGuard)
+                request = { ...request, resourceGuard };
+            const channelGuard = request.channelCache && runtime.channels?.begin(request.channelCache);
+            if (channelGuard)
+                request = { ...request, channelGuard };
+            const operation = Deferred.makeUnsafe();
+            runtime.operations.add(operation);
+            return Effect.gen(function* () {
+                const resolved = runtime.instance;
+                const instance = resolved ??
+                    (yield* Effect.acquireUseRelease(
+                    // Discovery is not an API request, so a global pause, such as one another child learned,
+                    // cannot hold it past the operation's deadline
+                    Effect.interruptible(runtime.admission.acquire({ route: "discovery", bytes, rateLimited: false })), () => runtime.resolveInstance(), (release) => Effect.sync(release)).pipe(mapFailureCause(instanceFailure)));
+                if (!resolved)
+                    runtime.instance = instance;
+                request = { ...request, instance };
+                if (request.directMessageUser !== undefined) {
+                    const open = directMessageOpen(request.directMessageUser);
+                    if (open instanceof InputValidationFailure)
+                        return yield* Effect.fail(inputFailure(open.detail));
+                    const userGuard = runtime.users?.begin("directMessages", { mutation: true });
+                    const channel = yield* owner
+                        .#exchange(token, {
+                        request: {
+                            method: "POST",
+                            channel: "@me",
+                            bucket: "user:directMessages.open",
+                            cache: false,
+                            instance,
+                            path: open.path,
+                            body: { json: open.json, files: [] },
+                            status: 200,
+                            preparation: true,
+                            decode: async (response, _instance, signal) => {
+                                const channel = open.decode(await readResponseJson(response, undefined, signal));
+                                if (!channel)
+                                    throw new RestFailure({
+                                        reason: "response",
+                                        outcome: "notDispatched",
+                                        status: response.status,
+                                    });
+                                return channel;
+                            },
+                        },
+                        progress: { outcome: "notDispatched" },
+                        generation,
+                        deadline,
+                        retainedBytes: bytes,
+                    })
+                        .pipe(mapFailureCause((error) => error instanceof RestFailure ? error.withOutcome("notDispatched") : error), Effect.onExit((exit) => Effect.sync(() => {
+                        if (exit._tag === "Failure" && userGuard !== undefined)
+                            runtime.users.failed(userGuard);
+                    })));
+                    if (userGuard !== undefined)
+                        runtime.users.complete(userGuard, [channel]);
+                    request = {
+                        ...request,
+                        channel: channel.id,
+                        path: `/channels/${channel.id}/messages`,
+                        decode: (response, _instance, signal) => request.decodeDirectMessage(response, channel.id, signal),
+                    };
+                }
+                if (request.body?.files.length && !request.webhookId && !request.inlineAttachments) {
+                    const uploadMode = yield* owner.#prepareUploads(token, request.body, request.sources ?? [], {
+                        channel: request.channel,
+                        instance,
+                        progress,
+                        generation,
+                        deadline,
+                    });
+                    if (uploadMode === "inline")
+                        request = { ...request, inlineAttachments: true };
+                }
+                return yield* owner.#exchange(token, { request, progress, generation, deadline });
+            }).pipe(withDeadline(timeout, () => new RestFailure({ reason: "timeout", outcome: progress.outcome })), Effect.provideService(Clock.Clock, runtime.logical.clock), Effect.ensuring(Effect.promise(() => completeCleanup((request.sources ?? []).map((source) => () => source.close()))).pipe(Effect.ensuring(Effect.sync(() => {
+                if (request.deleteIds && progress.outcome !== "notDispatched")
+                    runtime.cache?.deleteMany(request.channel, request.deleteIds);
+                if (deletionGuard)
+                    runtime.cache.end(deletionGuard);
+                if (resourceGuard)
+                    runtime.resources.end(resourceGuard, request.moderation
+                        ? progress.outcome !== "notDispatched"
+                        : progress.outcome === "unknown");
+                if (request.deleteAuthorId && progress.outcome !== "notDispatched")
+                    runtime.cache?.deleteAuthor(request.deleteAuthorId);
+                // A read begun after deletion dispatch can still observe pre-deletion data, so clear again at completion
+                if (request.invalidateMessages && progress.outcome !== "notDispatched")
+                    runtime.cache?.gap();
+                // A rejected multi-entry reorder can have applied earlier entries before its failure
+                if (channelGuard)
+                    runtime.channels.end(channelGuard, progress.outcome !== "notDispatched");
+                if (request.channelCache?.mutation &&
+                    request.method === "DELETE" &&
+                    request.bucket === "channel:delete" &&
+                    progress.outcome === "unknown")
+                    runtime.cache?.deleteChannel(request.channel);
+                if (request.body)
+                    request.body.files.length = 0;
+                runtime.uploadBytes -= uploadBytes;
+                runtime.operations.delete(operation);
+                Deferred.doneUnsafe(operation, Effect.void);
+            })))));
+        }).pipe(
+        // A read that failed after dispatch cannot have changed remote state, so its unknown outcome stays retryable.
+        // Mark it in place: The failure's Cause, including any cleanup defects beside it, stays unchanged
+        Effect.onExit((exit) => Effect.sync(() => {
+            if (request.method !== "GET" || Exit.isSuccess(exit))
+                return;
+            for (const reason of exit.cause.reasons)
+                if (reason._tag === "Fail" && reason.error instanceof RestFailure)
+                    reason.error.read = true;
+        })));
+    }
+    /**
+     * Send one caller-described request through the same discovery, admission, rate-limit learning, 429 waits,
+     * deadline, logging and retry rules as wrapped operations, without message or resource cache coordination.
+     * Files are always sent inline as multipart, never through presigned uploads, because the route is unknown
+     */
+    request(token, input) {
+        return suspendInput(() => {
+            if (this.#runtime.closed)
+                return Effect.fail(new ClientClosedError());
+            const encoded = encodeRestRequest(input);
+            if (encoded instanceof InputValidationFailure)
+                return Effect.fail(inputFailure(encoded.detail));
+            return this.#execute(token, {
+                method: encoded.method,
+                channel: encoded.major,
+                // Requests to one caller route share provisional rate-limit state until Fluxer names its bucket
+                bucket: `rest:${encoded.method} ${encoded.template}`,
+                cache: false,
+                callerDescribed: true,
+                path: encoded.path,
+                template: encoded.template,
+                body: encoded.body,
+                ...(encoded.body?.files.length ? { inlineAttachments: true } : {}),
+                ...(encoded.auditReason === undefined ? {} : { auditReason: encoded.auditReason }),
+                decode: (response, _instance, signal) => readRestResponse(response, signal),
+            }, encoded.timeoutMs === undefined ? undefined : { timeoutMs: encoded.timeoutMs });
+        }).pipe(mapFailureCause((error) => operationFailure(error, RestRequestError, "rest.request")));
+    }
+    /** Close admission and abort every request and download without waiting */
+    stop() {
+        const runtime = this.#runtime;
+        runtime.closed = true;
+        runtime.instance = undefined;
+        runtime.admission.close();
+        for (const source of runtime.downloads)
+            source.fail(new ClientClosedError());
+        for (const controller of runtime.controllers)
+            controller.abort();
+    }
+    /** Stop, then wait for every running operation and surface unobserved stream cleanup failures */
+    shutdown() {
+        return Effect.suspend(() => {
+            this.stop();
+            const runtime = this.#runtime;
+            return Effect.forEach([...runtime.operations], (operation) => Deferred.await(operation), {
+                discard: true,
+                concurrency: "unbounded",
+            }).pipe(Effect.andThen(Effect.suspend(() => {
+                const defects = runtime.unobservedDownloadDefects.take();
+                return defects ? Effect.failCause(defects) : Effect.void;
+            })));
+        });
+    }
+}
+//# sourceMappingURL=owner.js.map