@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/reaction-pages.ts

@@ -0,0 +1,260 @@
+/**
+ * Reaction pages: One message whose page changes on ◀ and ▶ clicks, read through one reaction collector.
+ * Invariant: Clicks are turned one at a time by the collector's callback, the SDK never removes reactions other than its
+ * own arrows and, with removeClicks, the clicker's arrow, and the bot's arrows are removed once listening ends, however
+ * it ends. A failure, cancellation or interruption wins over a later cleanup failure.
+ * Implements [SDK contracts: Results and failures](/docs/SDK-CONTRACTS.md#results-and-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 { ConfigurationError } from "#sdk/errors"
+import type { EditMessageInput, MessageCore, MessageInput } from "#sdk/messages"
+import type { MessageReaction } from "#sdk/reactions"
+import type { PageInput, PageTurners, PaginateFailure, PaginateOptions, PaginateResult } from "#sdk/reaction-pages"
+import type { ClientOwner } from "./client.js"
+import { collectorBudgetMessage } from "./collector.js"
+import { record } from "./decode/primitives.js"
+import { readInput } from "./defects.js"
+import { collectReactions, type ReactionCollector } from "./reaction-collector.js"
+import { unsupportedKeyHint } from "./suggest.js"
+
+/** The arrows the bot adds, previous first. Clicks also match the text-presentation forms without U+FE0F */
+const arrows = ["◀️", "▶️"] as const
+
+/** Page step for a clicked emoji name: -1 for previous, 1 for next and 0 for anything else */
+function step(name: string): -1 | 0 | 1 {
+    const plain = name.replace("️", "")
+    return plain === "◀" ? -1 : plain === "▶" ? 1 : 0
+}
+
+type Page = string | { readonly content?: string; readonly embeds?: readonly unknown[] }
+
+interface Settings {
+    readonly pages: readonly Page[]
+    readonly users: PageTurners
+    readonly idleMs: number
+    readonly timeoutMs: number
+    readonly removeClicks: boolean
+}
+
+const optionKeys = ["users", "idleMs", "timeoutMs", "removeClicks", "signal"]
+
+/** Copy and check the pages once. Page bodies are checked by send and edit, so only their shape is checked here */
+function copyPages(pages: unknown): readonly Page[] | ConfigurationError {
+    if (!Array.isArray(pages) || pages.length === 0)
+        return new ConfigurationError("pages", "Pages must be a nonempty array of strings or page objects")
+    const copied: Page[] = []
+    for (const page of Array.from(pages as unknown[])) {
+        if (typeof page === "string") {
+            if (page.length === 0) return new ConfigurationError("pages", "A text page must not be empty")
+            copied.push(page)
+            continue
+        }
+        if (!record(page)) return new ConfigurationError("pages", "Each page must be a string or a page object")
+        const unsupported = Object.keys(page).find((key) => key !== "content" && key !== "embeds")
+        if (unsupported !== undefined)
+            return new ConfigurationError("pages", `Unsupported page property ${JSON.stringify(unsupported)}`, {
+                hint: unsupportedKeyHint(unsupported, ["content", "embeds"]),
+            })
+        const { content, embeds } = page
+        if (content !== undefined && typeof content !== "string")
+            return new ConfigurationError("pages", "Page content must be a string")
+        if (embeds !== undefined && !Array.isArray(embeds))
+            return new ConfigurationError("pages", "Page embeds must be an array")
+        const list = embeds === undefined ? undefined : Object.freeze(Array.from(embeds as unknown[]))
+        if (!content && !list?.length)
+            return new ConfigurationError("pages", "Each page object needs nonempty content or at least one embed")
+        copied.push(
+            Object.freeze({
+                ...(content === undefined ? {} : { content }),
+                ...(list === undefined ? {} : { embeds: list }),
+            }),
+        )
+    }
+    return Object.freeze(copied)
+}
+
+/** Copy and check pages and options once, before anything is sent */
+function settings(pages: unknown, options: unknown): Settings | ConfigurationError {
+    const copied = copyPages(pages)
+    if (copied instanceof ConfigurationError) return copied
+    const input = options === undefined ? {} : options
+    if (!record(input)) return new ConfigurationError("paginateOptions", "Page options must be an object")
+    const unsupported = Object.keys(input).find((key) => !optionKeys.includes(key))
+    if (unsupported !== undefined)
+        return new ConfigurationError("paginateOptions", `Unsupported page option ${JSON.stringify(unsupported)}`, {
+            hint: unsupportedKeyHint(unsupported, optionKeys),
+        })
+    const { users, idleMs = 60_000, timeoutMs = 300_000 } = input
+    const removeClicks = input.removeClicks ?? false
+    if (!milliseconds(idleMs)) return new ConfigurationError("idleMs", collectorBudgetMessage("idleMs"))
+    if (!milliseconds(timeoutMs)) return new ConfigurationError("timeoutMs", collectorBudgetMessage("timeoutMs"))
+    if (typeof removeClicks !== "boolean")
+        return new ConfigurationError("removeClicks", 'The page option "removeClicks" must be true or false')
+    let turners: PageTurners
+    if (typeof users === "function") turners = users as PageTurners
+    else if (
+        Array.isArray(users) &&
+        users.every((id: unknown) => typeof id === "string" && /^[1-9][0-9]{0,19}$/.test(id))
+    )
+        turners = Object.freeze([...(users as string[])])
+    else
+        return new ConfigurationError(
+            "users",
+            users === undefined
+                ? 'The page option "users" is required, as a list of user IDs or a check such as () => true'
+                : 'The page option "users" must be a list of decimal user IDs or a function',
+        )
+    return { pages: copied, users: turners, idleMs, timeoutMs, removeClicks }
+}
+
+const milliseconds = (value: unknown): value is number =>
+    typeof value === "number" && Number.isSafeInteger(value) && value > 0 && value <= 2_147_483_647
+
+const sendInput = (page: Page) => page as MessageInput | string
+
+/** A page change replaces both text and embeds, so nothing from the previous page stays */
+const editInput = (page: Page) =>
+    (typeof page === "string"
+        ? { content: page, embeds: [] }
+        : { content: page.content ?? "", embeds: page.embeds ?? [] }) as EditMessageInput
+
+/**
+ * Send the first page to a channel, add the arrows and turn pages on clicks until idle, timeout, failure or
+ * interruption. Command contexts supply their author as users through askerPageOptions
+ */
+export function paginate<M extends MessageCore>(
+    owner: ClientOwner<M>,
+    channelId: string,
+    pages: readonly PageInput[],
+    options: PaginateOptions | undefined,
+): Effect.Effect<PaginateResult<M>, PaginateFailure> {
+    return Effect.gen(function* () {
+        const config = yield* readInput(() => settings(pages, options))
+        if (config instanceof ConfigurationError) return yield* Effect.fail(config)
+        const first = yield* owner.send(channelId, sendInput(config.pages[0]!))
+        if (config.pages.length === 1) return Object.freeze({ message: first, page: 0, reason: "singlePage" as const })
+        return yield* listen(owner, first, config)
+    })
+}
+
+function listen<M extends MessageCore>(
+    owner: ClientOwner<M>,
+    first: M,
+    config: Settings,
+): Effect.Effect<PaginateResult<M>, PaginateFailure> {
+    const target = { id: first.id, channelId: first.channelId }
+    const botId = first.author.id
+    const { pages, users } = config
+    let page = 0
+    let message = first
+    let failure: PaginateFailure | undefined
+    let collector: ReactionCollector | undefined
+    // The users check is application code, so the collector reports its throws and non-boolean returns as filter failures
+    const filter = (reaction: MessageReaction) =>
+        reaction.userId !== botId &&
+        reaction.emoji.id === undefined &&
+        step(reaction.emoji.name) !== 0 &&
+        (typeof users === "function" ? users(reaction) : users.includes(reaction.userId))
+    // SDK requests fail the pages rather than the collector callback, so they are not reported as application failures
+    const turn = (reaction: MessageReaction) =>
+        Effect.gen(function* () {
+            const next = (page + step(reaction.emoji.name) + pages.length) % pages.length
+            message = yield* owner.edit(target, editInput(pages[next]!))
+            page = next
+            if (config.removeClicks)
+                yield* owner.reaction("removeUserReaction", target, reaction.emoji, undefined, reaction.userId)
+        }).pipe(
+            Effect.catch((error: PaginateFailure) =>
+                Effect.sync(() => {
+                    failure ??= error
+                    collector?.stop()
+                }),
+            ),
+        )
+    return Effect.uninterruptibleMask((restore) =>
+        Effect.gen(function* () {
+            const registered = yield* collectReactions(
+                owner,
+                target,
+                {
+                    maxReactions: Number.MAX_SAFE_INTEGER,
+                    idleMs: config.idleMs,
+                    timeoutMs: config.timeoutMs,
+                    filter,
+                    ...(first.guildId === undefined ? {} : { guildId: first.guildId }),
+                },
+                false,
+                turn,
+                !config.removeClicks,
+            )
+            collector = registered
+            const exit = yield* Effect.exit(
+                restore(
+                    Effect.gen(function* () {
+                        for (const arrow of arrows) yield* owner.reaction("addReaction", target, arrow)
+                        const ended = yield* Deferred.await(registered.closed)
+                        if (failure !== undefined) return yield* Effect.fail(failure)
+                        return Object.freeze({ message, page, reason: ended.reason === "idle" ? "idle" : "timeout" })
+                    }),
+                ),
+            )
+            registered.stop()
+            // Wait for an active page change to finish, so it cannot run after the arrows are gone
+            yield* Effect.exit(Deferred.await(registered.closed))
+            let removal: PaginateFailure | undefined
+            let defects: Cause.Cause<never> = Cause.empty
+            for (const arrow of arrows) {
+                const removed = yield* Effect.exit(owner.reaction("removeReaction", target, arrow))
+                if (Exit.isSuccess(removed)) continue
+                const failed = removed.cause.reasons.find((reason) => reason._tag === "Fail")
+                if (failed?._tag === "Fail") removal ??= failed.error
+                defects = Cause.combine(
+                    defects,
+                    Cause.fromReasons<never>(removed.cause.reasons.filter((reason) => reason._tag === "Die")),
+                )
+            }
+            if (Exit.isFailure(exit)) return yield* Effect.failCause(Cause.combine(exit.cause, defects))
+            if (defects.reasons.length) return yield* Effect.failCause(defects)
+            if (removal !== undefined) return yield* Effect.fail(removal)
+            return exit.value as PaginateResult<M>
+        }),
+    )
+}
+
+/**
+ * Options for a command context's paginate: The users option defaults to the command's author, and a default-API
+ * handler signal is combined with any supplied signal. Getters defer each read to the operation, so a throwing caller
+ * getter is still marked as application input there, and malformed options pass through to be rejected there
+ */
+export function askerPageOptions<O extends object>(
+    options: O | undefined,
+    asker: string,
+    signal?: AbortSignal,
+): O & { readonly users: PageTurners } {
+    if (options === undefined) return { users: [asker], ...(signal === undefined ? {} : { signal }) } as never
+    if (typeof options !== "object" || options === null || Array.isArray(options)) return options as never
+    let combined: unknown
+    const read = (property: string | symbol): unknown => {
+        if (property === "users") return Reflect.get(options, "users", options) ?? [asker]
+        if (property !== "signal" || signal === undefined) return Reflect.get(options, property, options)
+        if (combined !== undefined) return combined
+        const own: unknown = Reflect.get(options, "signal", options)
+        // An invalid caller signal passes through unchanged, so the operation rejects it with ConfigurationError
+        return (combined =
+            own === undefined ? signal : own instanceof AbortSignal ? AbortSignal.any([signal, own]) : own)
+    }
+    const added = signal === undefined ? ["users"] : ["users", "signal"]
+    return new Proxy(Object.create(null) as O & { readonly users: PageTurners }, {
+        get: (_target, property) => read(property),
+        ownKeys: () => [...new Set([...Reflect.ownKeys(options), ...added])],
+        getOwnPropertyDescriptor: (_target, property) => {
+            if (added.includes(property as string))
+                return { value: read(property), enumerable: true, configurable: true, writable: false }
+            const descriptor = Reflect.getOwnPropertyDescriptor(options, property)
+            return descriptor === undefined ? undefined : { ...descriptor, configurable: true }
+        },
+    })
+}

package/src/internal/reactions.ts

@@ -0,0 +1,174 @@
+/**
+ * Reaction operations, reaction user pages and reaction gateway projections.
+ * Invariant: Reaction events never change cached message snapshots.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { ReactionEmoji, ReactionEmojiInput, ReactionTarget, ReactionUser, ReactionUsersPage } from "#sdk/reactions"
+import { inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { format } from "#sdk/helpers"
+import { identifier, record } from "./decode/primitives.js"
+import { rejectCheck } from "./decode/trace.js"
+
+export function encodeReactionUsersQuery(query: unknown) {
+    const input = query === undefined ? {} : query
+    if (!record(input)) return inputValidationFailure("query", "type", "Reaction user query must be an object")
+    const unsupported = unsupportedKeyFailure(input, ["limit", "after"], "query", "the reaction user query")
+    if (unsupported) return unsupported
+    const limitInput = input.limit
+    const after = input.after
+    const limit = limitInput === undefined ? 25 : limitInput
+    if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 100)
+        return inputValidationFailure(
+            "query.limit",
+            "range",
+            "Reaction user limit must be an integer from 1 through 100",
+        )
+    if (after !== undefined && !identifier(after))
+        return inputValidationFailure("query.after", "format", "Reaction user cursor must be a decimal ID string")
+    const params = new URLSearchParams({ limit: String(limit) })
+    if (after !== undefined) params.set("after", after)
+    return { limit, after, params }
+}
+
+export function decodeReactionUsersPage(
+    value: unknown,
+    query: { readonly limit: number; readonly after: string | undefined; readonly params: URLSearchParams },
+): ReactionUsersPage | undefined {
+    if (
+        !record(value) ||
+        !Array.isArray(value.items) ||
+        value.items.length > query.limit ||
+        typeof value.has_more !== "boolean"
+    )
+        return undefined
+    const items: ReactionUser[] = []
+    let previous = query.after === undefined ? undefined : BigInt(query.after)
+    for (const item of value.items) {
+        if (
+            !record(item) ||
+            !identifier(item.id) ||
+            typeof item.username !== "string" ||
+            (item.bot !== undefined && typeof item.bot !== "boolean")
+        )
+            return undefined
+        const id = BigInt(item.id)
+        if (previous !== undefined && id <= previous) return rejectCheck("order")
+        previous = id
+        items.push(Object.freeze({ id: item.id, username: item.username, isBot: item.bot === true }))
+    }
+    if (value.has_more) {
+        if (items.length === 0 || value.next_after !== items.at(-1)!.id) return undefined
+    } else if (value.next_after !== null) return undefined
+    return Object.freeze({
+        items: Object.freeze(items),
+        hasMore: value.has_more,
+        nextAfter: value.next_after as string | null,
+    })
+}
+
+const name = (value: unknown): value is string =>
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= 128 &&
+    value.isWellFormed() &&
+    // oxlint-disable-next-line no-control-regex -- rejects control characters and spaces in emoji names
+    !/[\x00-\x20\x7f]/.test(value)
+
+export function resolveReactionEmoji(
+    value: ReactionEmojiInput,
+): string | { readonly name: string; readonly id: string } | undefined {
+    if (typeof value === "string") {
+        if (!value.startsWith("<")) return name(value) && !/[%/:<>]/.test(value) ? value : undefined
+        const parsed = format.tryParseCustomEmoji(value)
+        if (parsed.isErr()) return undefined
+        value = parsed.value
+    }
+    if (!record(value)) return undefined
+    const hasGuildId = "guildId" in value
+    const hasAnimated = "animated" in value
+    const guildId = hasGuildId ? value.guildId : undefined
+    const animated = hasAnimated ? value.animated : undefined
+    const snapshot = hasGuildId && hasAnimated && identifier(guildId) && typeof animated === "boolean"
+    const allowCloning = snapshot ? value.allowCloning : undefined
+    const metadata = snapshot && typeof allowCloning === "boolean"
+    if (
+        Object.keys(value).some(
+            (key) =>
+                ![
+                    "name",
+                    "id",
+                    "animated",
+                    ...(snapshot ? ["guildId"] : []),
+                    ...(metadata ? ["allowCloning"] : []),
+                ].includes(key),
+        )
+    )
+        return undefined
+    const id = value.id
+    if (animated !== undefined && (typeof animated !== "boolean" || id === undefined)) return undefined
+    const nameValue = value.name
+    if (id === undefined) return name(nameValue) && !/[%/:<>]/.test(nameValue) ? nameValue : undefined
+    return typeof nameValue === "string" && /^[A-Za-z0-9_-]{1,32}$/.test(nameValue) && identifier(id)
+        ? { name: nameValue, id }
+        : undefined
+}
+
+export function encodeReactionEmoji(value: ReactionEmojiInput): string | undefined {
+    const emoji = resolveReactionEmoji(value)
+    return emoji === undefined
+        ? undefined
+        : encodeURIComponent(typeof emoji === "string" ? emoji : `${emoji.name}:${emoji.id}`)
+}
+
+function emoji(value: unknown): ReactionEmoji | undefined {
+    if (!record(value) || !name(value.name)) return undefined
+    if (value.id !== undefined && !identifier(value.id)) return undefined
+    if (value.animated !== undefined && (typeof value.animated !== "boolean" || value.id === undefined))
+        return undefined
+    return Object.freeze({
+        name: value.name,
+        ...(value.id === undefined ? {} : { id: value.id as string }),
+        ...(value.animated === undefined ? {} : { animated: value.animated as boolean }),
+    })
+}
+
+export const reactionEvents = {
+    MESSAGE_REACTION_ADD: "messageReactionAdd",
+    MESSAGE_REACTION_ADD_MANY: "messageReactionAddMany",
+    MESSAGE_REACTION_REMOVE: "messageReactionRemove",
+    MESSAGE_REACTION_REMOVE_ALL: "messageReactionRemoveAll",
+    MESSAGE_REACTION_REMOVE_EMOJI: "messageReactionRemoveEmoji",
+} as const
+
+export function decodeReaction(event: keyof typeof reactionEvents, value: unknown) {
+    if (
+        !record(value) ||
+        !identifier(value.channel_id) ||
+        !identifier(value.message_id) ||
+        (value.guild_id !== undefined && !identifier(value.guild_id))
+    )
+        return undefined
+    const target: ReactionTarget = {
+        id: value.message_id,
+        channelId: value.channel_id,
+        ...(value.guild_id === undefined ? {} : { guildId: value.guild_id as string }),
+    }
+    if (event === "MESSAGE_REACTION_REMOVE_ALL") return Object.freeze(target)
+    if (event === "MESSAGE_REACTION_ADD_MANY") {
+        if (!Array.isArray(value.reactions) || value.reactions.length === 0 || value.reactions.length > 512)
+            return undefined
+        const reactions = []
+        for (const item of value.reactions) {
+            if (!record(item) || !identifier(item.user_id)) return undefined
+            const decoded = emoji(item.emoji)
+            if (!decoded) return undefined
+            reactions.push(Object.freeze({ userId: item.user_id, emoji: decoded }))
+        }
+        return Object.freeze({ ...target, reactions: Object.freeze(reactions) })
+    }
+    const decoded = emoji(value.emoji)
+    if (!decoded) return undefined
+    if (event === "MESSAGE_REACTION_REMOVE_EMOJI") return Object.freeze({ ...target, emoji: decoded })
+    if (!identifier(value.user_id)) return undefined
+    return Object.freeze({ ...target, emoji: decoded, userId: value.user_id })
+}

package/src/internal/rejection-scope.ts

@@ -0,0 +1,119 @@
+/**
+ * Rejection scope: Holds the rest.rejected Warn records of one handler invocation, so a rejected token or permission
+ * that fails the handler within one second is logged once, as the handler's failure record, instead of as a Warn and then an Error.
+ * Invariant: A held record is logged when the invocation ends, after at most holdMs, or never, when the handler's
+ * failure is logged at Error for that rejection's identity, directly or in its cause chain. A handler that fails more
+ * than one second after the rejection also logs its failure, because the Warn has already been flushed. A failure that reaches an onError hook claims
+ * nothing, so the Warn still shows a rejection that the application handles. Native handlers find the scope in their
+ * fiber context. Default-API handler code runs in async context storage, which an operation reads when it starts and
+ * passes on in its fiber context.
+ * Implements [SDK contracts: User-handler failures](/docs/SDK-CONTRACTS.md#user-handler-failures)
+ */
+import { AsyncLocalStorage } from "node:async_hooks"
+import * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import type { ClientLogger, LogInput } from "./logging.js"
+
+/** Longest time a record waits for its handler, so a handler that runs for a long time still shows its rejections */
+const holdMs = 1_000
+
+interface HeldRecord {
+    readonly logger: ClientLogger
+    readonly input: LogInput
+    readonly context: Context.Context<never> | undefined
+    readonly error: object
+}
+
+/** Private identity links keep domain error conversion from changing which rejection a handler reports */
+const rejectionSources = new WeakMap<object, object>()
+
+/** Link a converted failure to its source without changing the public error's cause or retaining either globally */
+export function linkRejectionError<A>(error: A, source: object): A {
+    if (typeof error === "object" && error !== null) rejectionSources.set(error, source)
+    return error
+}
+
+export class RejectionScope {
+    #held: HeldRecord[] = []
+    #timer: ReturnType<typeof setTimeout> | undefined
+    #ended = false
+
+    /** Hold a rejection record for this invocation. False when the invocation already ended, so the caller logs it */
+    hold(logger: ClientLogger, input: LogInput, context: Context.Context<never> | undefined, error: object): boolean {
+        if (this.#ended) return false
+        this.#held.push({ logger, input, context, error })
+        if (this.#timer === undefined) {
+            this.#timer = setTimeout(() => this.flush(), holdMs)
+            this.#timer.unref?.()
+        }
+        return true
+    }
+
+    /** Drop only records for this failure's identity, following a bounded cause chain and domain conversion links */
+    claim(error: unknown) {
+        if (this.#held.length === 0) return
+        const identities = new Set<object>()
+        for (let depth = 0; depth <= 4 && typeof error === "object" && error !== null; depth++) {
+            if (identities.has(error)) break
+            let source: object | undefined = error
+            for (let links = 0; links <= 4 && source !== undefined; links++) {
+                if (identities.has(source)) break
+                identities.add(source)
+                source = rejectionSources.get(source)
+            }
+            try {
+                error = (error as { readonly cause?: unknown }).cause
+            } catch {
+                // allow-silent: A hostile cause getter ends traversal, while already matched identities remain usable
+                break
+            }
+        }
+        this.#held = this.#held.filter(({ error }) => !identities.has(error))
+    }
+
+    /** Log every held record */
+    flush() {
+        if (this.#timer !== undefined) clearTimeout(this.#timer)
+        this.#timer = undefined
+        const held = this.#held
+        this.#held = []
+        for (const { logger, input, context } of held) logger.log(input, context)
+    }
+
+    /** End the invocation: Log what is still held, and log later rejections at once */
+    end() {
+        this.#ended = true
+        this.flush()
+    }
+}
+
+/** The scope of the handler invocation a fiber runs for */
+const CurrentRejectionScope = Context.Reference<RejectionScope | undefined>("@neontechspace/fluxerly/RejectionScope", {
+    defaultValue: () => undefined,
+})
+
+/** The scope of the default-API handler whose code is running, read when an operation starts */
+const storage = new AsyncLocalStorage<RejectionScope>()
+
+/** Run default-API handler code so that the operations it starts hold their rejection records in scope */
+export function inRejectionScope<A>(scope: RejectionScope | undefined, run: () => A): A {
+    return scope === undefined ? run() : storage.run(scope, run)
+}
+
+/** The scope of the running default-API handler code, if any */
+export function currentRejectionScope(): RejectionScope | undefined {
+    return storage.getStore()
+}
+
+/** Provide a scope to an Effect, so its operations and callbacks hold their rejection records in it */
+export function withRejectionScope<A, E, R>(
+    effect: Effect.Effect<A, E, R>,
+    scope: RejectionScope | undefined,
+): Effect.Effect<A, E, R> {
+    return scope === undefined ? effect : Effect.provideService(effect, CurrentRejectionScope, scope)
+}
+
+/** The scope in a fiber context */
+export function fiberRejectionScope(context: Context.Context<never>): RejectionScope | undefined {
+    return Context.get(context, CurrentRejectionScope)
+}

package/src/internal/response-json.ts

@@ -0,0 +1,76 @@
+/**
+ * Bounded JSON response reading.
+ * Invariant: Decoded body bytes are bounded before parsing, and reader cancellation and release are always awaited.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { TransportError } from "./effect-failures.js"
+
+/** Bounded response parsing completed, but releasing its owned reader failed */
+export class ResponseJsonCleanupError extends Error {
+    constructor(
+        readonly cause: unknown,
+        readonly status: number,
+    ) {
+        super("JSON response cleanup failed", { cause })
+        this.name = "ResponseJsonCleanupError"
+    }
+}
+
+/**
+ * Bound decoded HTTP body bytes before parsing JSON, then await reader cancellation and release.
+ * Invalid UTF-8 or JSON returns undefined. A body whose connection fails mid-read throws a TransportError
+ */
+export async function readResponseJson(
+    response: Response,
+    maxBytes = 16_777_216,
+    signal?: AbortSignal,
+): Promise<unknown> {
+    const reader = response.body?.getReader()
+    if (!reader) return undefined
+    const decoder = new TextDecoder("utf-8", { fatal: true })
+    let result = "",
+        bytes = 0,
+        ended = false
+    try {
+        while (true) {
+            const next = await reader.read().catch((error: unknown) => {
+                // A failed read leaves the stream errored, so it needs no cancellation
+                ended = true
+                throw new TransportError(error, "response body read")
+            })
+            if (next.done) {
+                ended = true
+                break
+            }
+            bytes += next.value.byteLength
+            if (bytes > maxBytes) return undefined
+            result += decoder.decode(next.value, { stream: true })
+        }
+        return JSON.parse(result + decoder.decode()) as unknown
+    } catch (error) {
+        if (error instanceof TransportError) throw error
+        // allow-silent: Invalid UTF-8 or JSON returns undefined, which the decoder reports as an unusable response
+        return undefined
+    } finally {
+        const failures: unknown[] = []
+        const actions: (() => Promise<void> | void)[] = [
+            ...(!ended ? [() => reader.cancel()] : []),
+            () => reader.releaseLock(),
+        ]
+        for (const action of actions) {
+            try {
+                await action()
+            } catch (error) {
+                // Re-cancelling a fetch reader after its own request abort can reject with that exact reason
+                if (signal?.aborted && error === signal.reason) continue
+                failures.push(error)
+            }
+        }
+        if (failures.length)
+            // oxlint-disable-next-line no-unsafe-finally -- a reader cleanup failure deliberately replaces the parsed result
+            throw new ResponseJsonCleanupError(
+                failures.length === 1 ? failures[0] : new AggregateError(failures, "JSON response cleanup failed"),
+                response.status,
+            )
+    }
+}