@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/rest/request.ts

@@ -0,0 +1,289 @@
+/**
+ * Caller-described REST requests for client.rest.request: Input validation, path and query encoding, log-safe route
+ * templates and the bounded response reader.
+ * Invariant: A request leaves validation only with a relative API path that cannot change the scheme, host or /v1 base,
+ * reach a parent path or carry a webhook credential. Logs see only the caller route template, and a response body is
+ * read within the JSON limit or not at all.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { RestResponse } from "#sdk/rest"
+import { InputValidationFailure, inputValidationFailure, unsupportedKeyFailure } from "#sdk/input-validation"
+import { encodeAttachments, type EncodedBody } from "../attachments.js"
+import { auditSettings } from "../audit.js"
+import { record } from "../decode/primitives.js"
+import { TransportError } from "../effect-failures.js"
+import { callerRouteTemplate } from "../rate-limits.js"
+import { ResponseJsonCleanupError } from "../response-json.js"
+import { RestFailure } from "./classify.js"
+
+/** Longest accepted path, before the query */
+const pathMaxLength = 2_048
+/** Longest encoded query string, without its leading question mark */
+const queryMaxLength = 8_192
+/** Largest response body read, matching the SDK's JSON response limit */
+const responseMaxBytes = 16_777_216
+/** Longest accepted operation deadline */
+const maximumTimerMs = 2_147_483_647
+
+const methods = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const
+const fields = ["method", "path", "query", "body", "files", "auditReason", "timeoutMs", "signal"]
+/** Resource names whose following numeric segment is the request's major resource for rate-limit grouping */
+const majorResources = new Set(["channels", "guilds", "webhooks", "users"])
+
+/** A validated caller request, ready for the owner's scheduler */
+export interface EncodedRestRequest {
+    readonly method: (typeof methods)[number]
+    /** Path after /v1 with the encoded query appended */
+    readonly path: string
+    /** Log-safe route template */
+    readonly template: string
+    /** The first channel, guild, webhook or user ID in the path, or rest when there is none */
+    readonly major: string
+    readonly body: EncodedBody | undefined
+    readonly auditReason: string | undefined
+    readonly timeoutMs: number | undefined
+}
+
+/** Check a path's shape. Invalid percent escapes and every character outside RFC 3986 path characters are rejected */
+function pathFailure(path: unknown): InputValidationFailure | undefined {
+    if (typeof path !== "string") return inputValidationFailure("path", "type", "REST paths must be strings")
+    if (path.length < 2 || path.length > pathMaxLength)
+        return inputValidationFailure("path", "length", "REST paths must contain 2 through 2,048 characters")
+    if (!path.startsWith("/") || path.startsWith("//"))
+        return inputValidationFailure(
+            "path",
+            "format",
+            "REST paths must be relative API paths that start with one slash, such as /users/@me",
+        )
+    if (!/^[A-Za-z0-9\-._~!$&'()*+,;=:@%/]+$/.test(path) || /%(?![0-9A-Fa-f]{2})/.test(path))
+        return inputValidationFailure(
+            "path",
+            "format",
+            "REST paths may contain only URL path characters and valid percent escapes, with the query in query and no fragment",
+        )
+    const segments = path
+        .slice(1)
+        .split("/")
+        .map((segment) =>
+            segment.replace(/%([0-9A-Fa-f]{2})/g, (encoded, hex: string) => {
+                const character = String.fromCharCode(parseInt(hex, 16))
+                return /^[A-Za-z0-9\-._~]$/.test(character) ? character : encoded
+            }),
+        )
+    if (
+        segments.some((segment) => {
+            const decoded = segment.replace(/%2e/gi, ".")
+            return segment === "" || decoded === "." || decoded === ".." || /%(?:2f|5c)/i.test(segment)
+        })
+    )
+        return inputValidationFailure(
+            "path",
+            "format",
+            "REST paths may not contain empty, dot or dot-dot segments or encoded slashes",
+        )
+    if (segments[0] === "v1")
+        return inputValidationFailure("path", "format", "REST paths are relative to /v1, so omit the version prefix")
+    if (segments[0] === "webhooks" && segments.length > 2)
+        return inputValidationFailure(
+            "path",
+            "format",
+            "Token-authenticated webhook routes carry a credential in the path and are not supported. Use a webhook client",
+        )
+    return undefined
+}
+
+/** Encode query parameters in insertion order, skipping undefined values */
+function encodeQuery(query: unknown): string | InputValidationFailure {
+    if (query === undefined) return ""
+    if (!record(query) || Array.isArray(query))
+        return inputValidationFailure(
+            "query",
+            "type",
+            "REST query must be an object of string, number or boolean values",
+        )
+    const params = new URLSearchParams()
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined) continue
+        if (key === "") return inputValidationFailure("query", "format", "REST query parameter names must not be empty")
+        if (typeof value === "number" && !Number.isFinite(value))
+            return inputValidationFailure("query", "type", "REST query numbers must be finite")
+        if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean")
+            return inputValidationFailure(
+                "query",
+                "type",
+                "REST query must be an object of string, number or boolean values",
+            )
+        params.append(key, String(value))
+    }
+    const encoded = params.toString()
+    if (encoded.length > queryMaxLength)
+        return inputValidationFailure("query", "length", "The encoded REST query must not exceed 8,192 characters")
+    return encoded
+}
+
+/** Serialize the JSON body and any files, which Fluxer's multipart convention describes in body.attachments */
+function encodeBody(
+    method: EncodedRestRequest["method"],
+    body: unknown,
+    files: unknown,
+): EncodedBody | undefined | InputValidationFailure {
+    if (method === "GET" && body !== undefined)
+        return inputValidationFailure("body", "relationship", "GET requests cannot have a body")
+    if (method === "GET" && files !== undefined)
+        return inputValidationFailure("files", "relationship", "GET requests cannot have files")
+    if (files !== undefined && !Array.isArray(files))
+        return inputValidationFailure("files", "type", "REST files must be an array of attachment inputs")
+    const attachments = encodeAttachments(files ?? [], false)
+    if (attachments instanceof InputValidationFailure) {
+        const { path, constraint, explanation } = attachments.detail
+        return inputValidationFailure(path.replace(/^attachments/, "files"), constraint, explanation)
+    }
+    if (
+        attachments.files.length &&
+        body !== undefined &&
+        (!record(body) || Array.isArray(body) || "attachments" in body)
+    )
+        return inputValidationFailure(
+            "body",
+            "relationship",
+            "With files, the body must be omitted or a JSON object without attachments",
+        )
+    if (body === undefined && !attachments.files.length) return undefined
+    let json: string | undefined
+    try {
+        json = JSON.stringify(
+            attachments.files.length ? { ...(body as object | undefined), attachments: attachments.metadata } : body,
+        )
+    } catch {
+        // allow-silent: An unserializable body becomes the typed input failure returned below
+        json = undefined
+    }
+    if (json === undefined) return inputValidationFailure("body", "type", "REST bodies must be JSON-serializable")
+    return { json, files: attachments.files }
+}
+
+/** The first channel, guild, webhook or user ID, which groups provisional rate-limit state like SDK operations */
+function majorResource(segments: readonly string[]): string {
+    for (let index = 0; index < segments.length - 1; index++)
+        if (majorResources.has(segments[index]!) && /^\d+$/.test(segments[index + 1]!)) return segments[index + 1]!
+    return "rest"
+}
+
+/** Validate one caller request. Failures carry SDK-authored paths and explanations, never the rejected values */
+export function encodeRestRequest(input: unknown): EncodedRestRequest | InputValidationFailure {
+    if (!record(input) || Array.isArray(input))
+        return inputValidationFailure("input", "type", "REST requests must be objects")
+    const unsupported = unsupportedKeyFailure(input, fields, "input", "the REST request")
+    if (unsupported) return unsupported
+    const method = input.method
+    if (!methods.includes(method as EncodedRestRequest["method"]))
+        return inputValidationFailure("method", "allowedValue", "REST methods must be GET, POST, PUT, PATCH or DELETE")
+    const path = input.path
+    const invalidPath = pathFailure(path)
+    if (invalidPath) return invalidPath
+    const query = encodeQuery(input.query)
+    if (query instanceof InputValidationFailure) return query
+    const body = encodeBody(method as EncodedRestRequest["method"], input.body, input.files)
+    if (body instanceof InputValidationFailure) return body
+    const audit = auditSettings({ auditReason: input.auditReason })
+    if (audit instanceof InputValidationFailure) {
+        const { constraint, explanation } = audit.detail
+        return inputValidationFailure("auditReason", constraint, explanation)
+    }
+    const timeoutMs = input.timeoutMs
+    if (
+        timeoutMs !== undefined &&
+        (typeof timeoutMs !== "number" ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs <= 0 ||
+            timeoutMs > maximumTimerMs)
+    )
+        return inputValidationFailure(
+            "timeoutMs",
+            "range",
+            "REST timeoutMs must be an integer from 1 through 2,147,483,647 ms",
+        )
+    const pathname = path as string
+    return {
+        method: method as EncodedRestRequest["method"],
+        path: query ? `${pathname}?${query}` : pathname,
+        template: callerRouteTemplate(pathname),
+        major: majorResource(pathname.slice(1).split("/")),
+        body,
+        auditReason: audit.auditReason,
+        timeoutMs: timeoutMs as number | undefined,
+    }
+}
+
+/**
+ * Read a body within the JSON limit. The result is undefined when empty and a failure when oversized or not JSON.
+ * A body whose connection fails mid-read throws a TransportError
+ */
+async function readBody(response: Response, signal: AbortSignal): Promise<unknown> {
+    const invalid = () => new RestFailure({ reason: "response", outcome: "unknown", status: response.status })
+    const reader = response.body?.getReader()
+    if (!reader) return undefined
+    const decoder = new TextDecoder("utf-8", { fatal: true })
+    let text = ""
+    let bytes = 0
+    let ended = false
+    let failure: RestFailure | TransportError | undefined
+    let value: unknown
+    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 > responseMaxBytes) {
+                failure = invalid()
+                break
+            }
+            text += decoder.decode(next.value, { stream: true })
+        }
+        if (!failure) {
+            text += decoder.decode()
+            if (bytes > 0) value = JSON.parse(text) as unknown
+        }
+    } catch (error) {
+        // allow-silent: A body that is not UTF-8 JSON becomes the typed response failure thrown below. A read failure is
+        // thrown as it is
+        failure = error instanceof TransportError ? error : invalid()
+    }
+    const cleanup: 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)) cleanup.push(error)
+        }
+    }
+    if (cleanup.length)
+        throw new ResponseJsonCleanupError(
+            cleanup.length === 1 ? cleanup[0] : new AggregateError(cleanup, "REST response cleanup failed"),
+            response.status,
+        )
+    if (failure) throw failure
+    return value
+}
+
+/** Project an accepted response: Its status, lower-case headers and parsed body */
+export async function readRestResponse<T>(response: Response, signal: AbortSignal): Promise<RestResponse<T>> {
+    const headers: Record<string, string> = {}
+    response.headers.forEach((value, name) => {
+        headers[name] = value
+    })
+    const body = (await readBody(response, signal)) as T
+    return Object.freeze({ status: response.status, headers: Object.freeze(headers), body })
+}

package/src/internal/rest.ts

@@ -0,0 +1,9 @@
+/**
+ * REST module entry: One client's request scheduler, split into [owner](/projects/sdk/src/internal/rest/owner.ts),
+ * [admission](/projects/sdk/src/internal/rest/admission.ts), [attempt](/projects/sdk/src/internal/rest/attempt.ts),
+ * [classify](/projects/sdk/src/internal/rest/classify.ts) and [download](/projects/sdk/src/internal/rest/download.ts).
+ * Invariant: Code outside REST reaches it only through this entry. Implements
+ * [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+export { RestOwner } from "./rest/owner.js"
+export type { AttachmentDownloadSource } from "./rest/download.js"

package/src/internal/retention-age.ts

@@ -0,0 +1,33 @@
+/**
+ * Cache retention ages: One snapshot's age limit from a fixed maxAgeMs setting or an application duration callback.
+ * Invariant: A callback that throws or returns an invalid value never decides retention. Its invalid return is discarded without
+ * being awaited, and the failure is returned for the owning cache to remove the older copy and report.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { validAge } from "./configuration.js"
+import { discardInvalidCallbackReturn } from "./invalid-callback-return.js"
+
+/** A validated maxAgeMs setting: A fixed age, null for no age limit, or a synchronous callback */
+export type AgeSetting<T> = number | null | ((value: T) => number | null)
+
+/** The age to apply, or the failure to report when the callback threw or returned an invalid value */
+export type RetentionAge = { readonly age: number | null } | { readonly error: unknown }
+
+/** Resolve one snapshot's age. The subject names the cache and the noun names what was not cached, for the failure text */
+export function retentionAge<T>(setting: AgeSetting<T>, value: T, subject: string, noun: string): RetentionAge {
+    if (typeof setting !== "function") return { age: setting }
+    let age: unknown
+    try {
+        age = setting(value)
+    } catch (error) {
+        return { error }
+    }
+    if (validAge(age)) return { age }
+    discardInvalidCallbackReturn(age)
+    return {
+        error: new TypeError(
+            // oxlint-disable-next-line typescript/no-base-to-string -- object and function values take the preceding branch
+            `The ${subject} maxAgeMs callback returned ${age === undefined ? "undefined" : typeof age === "object" || typeof age === "function" ? "a non-number value" : String(age)}, but it must return null or a nonnegative safe integer, so the ${noun} was not cached`,
+        ),
+    }
+}

package/src/internal/role-hierarchy-workflow.ts

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

package/src/internal/role-hierarchy.ts

@@ -0,0 +1,93 @@
+/**
+ * Pure role hierarchy comparison.
+ * Invariant: Comparisons use position and then ID, and invalid or cross-guild roles compare as unknown.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { GuildMember, GuildRole } from "#sdk/guilds"
+import type { RoleHierarchyInput } from "#sdk/role-hierarchy"
+import { identifier } from "./decode/primitives.js"
+
+const validRole = (value: unknown): value is GuildRole =>
+    typeof value === "object" &&
+    value !== null &&
+    identifier((value as GuildRole).guildId) &&
+    identifier((value as GuildRole).id) &&
+    typeof (value as GuildRole).position === "number" &&
+    Number.isInteger((value as GuildRole).position) &&
+    (value as GuildRole).position >= 0 &&
+    (value as GuildRole).position <= 2_147_483_647
+
+export function compareRoleHierarchy(left: GuildRole, right: GuildRole): -1 | 0 | 1 | undefined {
+    if (!validRole(left) || !validRole(right) || left.guildId !== right.guildId) return undefined
+    if (left.id === right.id) return 0
+    if (left.position !== right.position) return left.position > right.position ? 1 : -1
+    return BigInt(left.id) < BigInt(right.id) ? 1 : -1
+}
+
+export function isRoleAboveInHierarchy(left: GuildRole, right: GuildRole): boolean | undefined {
+    const comparison = compareRoleHierarchy(left, right)
+    return comparison === undefined ? undefined : comparison === 1
+}
+
+export function evaluateMemberHierarchy(input: RoleHierarchyInput): boolean | undefined {
+    if (!validInput(input)) return undefined
+    const { guild, actor, target, roles } = input
+    if (actor.userId === target.userId) return true
+    if (actor.userId === guild.ownerId) return true
+    if (target.userId === guild.ownerId) return false
+
+    const roleById = new Map(roles.filter((role) => role.id !== guild.id).map((role) => [role.id, role]))
+    const actorRole = highestExplicitRole(actor.roleIds, roleById)
+    const targetRole = highestExplicitRole(target.roleIds, roleById)
+    if (!actorRole) return false
+    if (!targetRole) return true
+    return isRoleAboveInHierarchy(actorRole, targetRole)
+}
+
+function validMember(value: unknown, guildId: string): value is GuildMember {
+    if (
+        typeof value !== "object" ||
+        value === null ||
+        (value as GuildMember).guildId !== guildId ||
+        !identifier((value as GuildMember).userId) ||
+        !Array.isArray((value as GuildMember).roleIds)
+    )
+        return false
+    const ids = new Set<string>()
+    for (const roleId of (value as GuildMember).roleIds) {
+        if (!identifier(roleId) || roleId === guildId || ids.has(roleId)) return false
+        ids.add(roleId)
+    }
+    return true
+}
+
+function validInput(value: unknown): value is RoleHierarchyInput {
+    if (typeof value !== "object" || value === null) return false
+    const input = value as RoleHierarchyInput
+    if (
+        !input.guild ||
+        !identifier(input.guild.id) ||
+        !identifier(input.guild.ownerId) ||
+        !validMember(input.actor, input.guild.id) ||
+        !validMember(input.target, input.guild.id) ||
+        !Array.isArray(input.roles)
+    )
+        return false
+
+    const roleIds = new Set<string>()
+    for (const role of input.roles) {
+        if (!validRole(role) || role.guildId !== input.guild.id || roleIds.has(role.id)) return false
+        roleIds.add(role.id)
+    }
+    return [...input.actor.roleIds, ...input.target.roleIds].every((roleId) => roleIds.has(roleId))
+}
+
+function highestExplicitRole(roleIds: readonly string[], roles: ReadonlyMap<string, GuildRole>): GuildRole | undefined {
+    let highest: GuildRole | undefined
+    for (const roleId of roleIds) {
+        const role = roles.get(roleId)
+        if (!role) return undefined
+        if (!highest || isRoleAboveInHierarchy(role, highest)) highest = role
+    }
+    return highest
+}