@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/client/backoff.ts

@@ -0,0 +1,69 @@
+/**
+ * Connection retry timing for shard startup and established-session recovery.
+ * Invariant: Startup and recovery use separate backoff steps with full jitter under a capped exponential ceiling, a
+ * server-required wait always wins over a shorter jittered delay, and only a connection that stayed healthy resets the
+ * recovery sequence. Socket-cleanup time never counts as healthy connected time. Recovery timing comes from the
+ * validated connection.recovery settings, while startup keeps fixed timing bounded by the startup deadline.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import type * as Schedule from "effect/Schedule"
+import type { ConnectionFailure } from "#sdk/errors"
+
+/** Validated recovery timing for established sessions */
+export interface RecoveryConfiguration {
+    /** Ceiling for the first recovery retry, doubled for each later step */
+    readonly minDelayMs: number
+    /** Largest backoff ceiling */
+    readonly maxDelayMs: number
+    /** Budget for one recovery attempt, covering discovery and the handshake */
+    readonly attemptTimeoutMs: number
+    /** Connected time after which the next loss restarts the recovery sequence */
+    readonly healthyResetMs: number
+    /** Native schedule that replaces the backoff delays, when configured */
+    readonly schedule: Schedule.Schedule<unknown, ConnectionFailure> | undefined
+}
+
+/** Documented connection.recovery defaults */
+export const defaultRecovery: RecoveryConfiguration = Object.freeze({
+    minDelayMs: 1_000,
+    maxDelayMs: 30_000,
+    attemptTimeoutMs: 30_000,
+    healthyResetMs: 60_000,
+    schedule: undefined,
+})
+
+/** Fixed startup backoff: 1 s doubling to 30 s, always bounded by the startup deadline */
+const startupBackoff = Object.freeze({ minDelayMs: 1_000, maxDelayMs: 30_000 })
+
+/** Doublings after which the ceiling stops growing, far past any configurable maximum */
+const maximumBackoffDoublings = 31
+/** Minimum spacing between Identify sends across this client's shards, unless an identify coordinator paces them */
+export const identifySpacingMs = 1_000
+/** Longest delay host timers accept */
+const maximumTimerMs = 2_147_483_647
+
+/**
+ * Startup budget for one shard group: The configured deadline plus the Identify spacing the SDK itself adds between
+ * the group's shards, so the SDK's own pacing never fails a larger plan. Spacing is added only for spaced shards
+ */
+export function startupBudgetMs(configuredMs: number, spacedShards: number): number {
+    return Math.min(maximumTimerMs, configuredMs + Math.max(0, spacedShards - 1) * identifySpacingMs)
+}
+
+/** Capped exponential ceiling for a zero-based backoff step */
+export function backoffCeiling(
+    step: number,
+    timing: { readonly minDelayMs: number; readonly maxDelayMs: number } = startupBackoff,
+): number {
+    return Math.min(timing.maxDelayMs, timing.minDelayMs * 2 ** Math.min(step, maximumBackoffDoublings))
+}
+
+/** Full-jitter delay under the ceiling, never shorter than a server-required wait */
+export function retryDelay(ceiling: number, random: number, requiredWaitMs: number): number {
+    return Math.max(random * ceiling, requiredWaitMs)
+}
+
+/** Whether a connection that ended at endedAt had been healthy long enough to restart the recovery sequence */
+export function stayedHealthy(connectedAt: number, endedAt: number, healthyResetMs: number): boolean {
+    return endedAt - connectedAt >= healthyResetMs
+}

package/src/internal/client/configuration-fields.ts

@@ -0,0 +1,18 @@
+/**
+ * ConfigurationError construction for the connection, gateway and sharding settings added in stage 5b.
+ * Invariant: Every field name used here is a documented option name, so ConfigurationError.field names the setting the
+ * caller passed. Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { ConfigurationError } from "#sdk/errors"
+
+/** Option names these settings report */
+export type ConnectionSettingField = ConfigurationError["field"]
+
+/** Build a ConfigurationError for one of these settings */
+export function settingError(
+    field: ConnectionSettingField,
+    message: string,
+    options?: { readonly hint?: string | undefined; readonly cause?: unknown },
+): ConfigurationError {
+    return new ConfigurationError(field, message, options)
+}

package/src/internal/client/drain.ts

@@ -0,0 +1,150 @@
+/**
+ * Draining shutdown: Stop event intake and new scheduled task runs, then let running handlers, waiting handler events,
+ * running scheduled tasks and REST requests finish until a deadline, before shutdown cancels the rest.
+ * Invariant: The drain only waits. It never cancels work itself, so the ordinary shutdown that follows cancels whatever
+ * is left, and a drain that ends early changes nothing but the time shutdown starts. Waiting follows progress signals,
+ * so an idle client ends the drain at once. Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import type * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import { ConfigurationError } from "#sdk/errors"
+import { record } from "../decode/primitives.js"
+import type { EventBus } from "../events.js"
+import type { ClientLogger } from "../logging.js"
+import type { ScheduledTasks } from "../scheduled-tasks.js"
+import { unsupportedKeyHint } from "../suggest.js"
+import { formatDuration } from "./lifetime.js"
+
+/** Longest drain, the longest single timer delay */
+const maximumDrainMs = 2_147_483_647
+
+/**
+ * Read the drain time from shutdown options, 0 when omitted. Misuse returns ConfigurationError without the rejected value.
+ * Reading the options is application input, so the caller runs this under a defect boundary
+ */
+export function shutdownDrainMs(options: unknown): number | ConfigurationError {
+    if (options === undefined) return 0
+    if (!record(options)) return new ConfigurationError("configuration", "Shutdown options must be an object")
+    const unsupported = Object.keys(options).find((key) => key !== "drainMs")
+    if (unsupported !== undefined)
+        return new ConfigurationError("configuration", `Unsupported shutdown option ${JSON.stringify(unsupported)}`, {
+            hint: unsupportedKeyHint(unsupported, ["drainMs"]),
+        })
+    const value = options.drainMs
+    if (value === undefined) return 0
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > maximumDrainMs)
+        return new ConfigurationError(
+            "drainMs",
+            'The option "drainMs" must be an integer from 0 through 2,147,483,647 milliseconds',
+        )
+    return value
+}
+
+/** Work a drain waits for */
+interface DrainWork {
+    readonly running: number
+    readonly waiting: number
+    readonly tasks: number
+    readonly requests: number
+}
+
+function plural(count: number, one: string, many: string) {
+    return `${count} ${count === 1 ? one : many}`
+}
+
+function describeWork(work: DrainWork): string {
+    const parts = [
+        ...(work.running ? [plural(work.running, "running handler", "running handlers")] : []),
+        ...(work.waiting ? [plural(work.waiting, "waiting event", "waiting events")] : []),
+        ...(work.tasks ? [plural(work.tasks, "running scheduled task", "running scheduled tasks")] : []),
+        ...(work.requests ? [plural(work.requests, "REST request", "REST requests")] : []),
+    ]
+    return parts.length < 2 ? (parts[0] ?? "no work") : `${parts.slice(0, -1).join(", ")} and ${parts.at(-1)}`
+}
+
+/**
+ * Seal the event bus and scheduled tasks, then wait until no handler or task is running, no event is waiting and no REST
+ * request is in flight, or until drainMs passes. Logs the start and the result. Runs with the caller's Clock and never fails
+ */
+export function drainWork(options: {
+    readonly events: Pick<EventBus, "seal" | "drainState" | "progress">
+    readonly tasks: Pick<ScheduledTasks, "seal" | "running" | "progress">
+    /** Completion signals of the REST operations in flight now */
+    readonly requests: () => readonly Deferred.Deferred<void>[]
+    readonly logging: ClientLogger
+    readonly drainMs: number
+    readonly context: Context.Context<never>
+}): Effect.Effect<void> {
+    const { events, tasks, requests, logging, drainMs, context } = options
+    return Effect.suspend(() => {
+        events.seal()
+        tasks.seal()
+        const work = (): DrainWork => ({ ...events.drainState(), tasks: tasks.running, requests: requests().length })
+        const initial = work()
+        if (initial.running + initial.waiting + initial.tasks + initial.requests === 0) return Effect.void
+        const startedAt = Date.now()
+        logging.log(
+            {
+                level: "info",
+                category: "lifecycle",
+                code: "lifecycle.draining",
+                message: `Shutting down after the current work: No new events are accepted, and ${describeWork(initial)} get up to ${formatDuration(drainMs)} to finish`,
+                fields: { ...initial, drainMs },
+            },
+            context,
+        )
+        // Handlers and tasks can start REST requests and REST responses can let them finish, so check all of them until
+        // none has work
+        const settled = Effect.gen(function* () {
+            while (true) {
+                const { running, waiting } = events.drainState()
+                if (running + waiting > 0) {
+                    yield* events.progress()
+                    continue
+                }
+                if (tasks.running > 0) {
+                    yield* tasks.progress()
+                    continue
+                }
+                const inFlight = requests()
+                if (inFlight.length === 0) return
+                yield* Effect.forEach(inFlight, (request) => Deferred.await(request), { discard: true })
+            }
+        })
+        return settled.pipe(
+            // Shutdown itself is uninterruptible, and the deadline must still be able to stop this wait
+            Effect.interruptible,
+            Effect.timeoutOption(drainMs),
+            Effect.map((finished) => {
+                const durationMs = Date.now() - startedAt
+                if (Option.isSome(finished)) {
+                    logging.log(
+                        {
+                            level: "info",
+                            category: "lifecycle",
+                            code: "lifecycle.drained",
+                            message: `The current work finished in ${formatDuration(durationMs)}, so shutdown continues without cancelling any`,
+                            durationMs,
+                        },
+                        context,
+                    )
+                    return
+                }
+                const left = work()
+                logging.log(
+                    {
+                        level: "warn",
+                        category: "lifecycle",
+                        code: "lifecycle.drainTimedOut",
+                        message: `The ${formatDuration(drainMs)} drain time (drainMs) ran out, so shutdown cancels ${describeWork(left)}`,
+                        durationMs,
+                        fields: { ...left, drainMs },
+                    },
+                    context,
+                )
+            }),
+        )
+    })
+}

package/src/internal/client/intake.ts

@@ -0,0 +1,228 @@
+/**
+ * Gateway cache intake: How decoded events, raw guild dispatches and skipped malformed dispatches update or invalidate
+ * the client's message, guild, channel and user caches.
+ * Invariant: Fluxer is the source of truth, and intake runs before subscriber delivery, so a subscriber never observes
+ * a cache older than the event it is handling. A skipped dispatch clears every entry it could have changed.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { GuildChannel } from "#sdk/channels"
+import type { EventMap, EventName } from "#sdk/events"
+import type { MessageCore } from "#sdk/messages"
+import type { MessageCache } from "../cache.js"
+import type { ChannelCache } from "../channel-cache.js"
+import { identifier, record } from "../decode/primitives.js"
+import { isMessageEvent } from "../events.js"
+import type { GuildCache } from "../guild-cache.js"
+import type { ClientLogger } from "../logging.js"
+import { threadParentTypes } from "../thread-events.js"
+import type { UserCache } from "../user-cache.js"
+
+/** The caches one client owns. Only the user cache is always present */
+export interface ClientCaches<M extends MessageCore> {
+    readonly cache: MessageCache<M> | undefined
+    readonly resources: GuildCache | undefined
+    readonly channelCache: ChannelCache | undefined
+    readonly userCache: UserCache
+    /** Records threads that a community snapshot carried in a malformed form */
+    readonly logging: ClientLogger
+    /** The bot account ID once READY or a self read supplied it, which tells whether a thread member change is the bot's */
+    readonly botUserId: string | undefined
+}
+
+/** Clear every cache without closing it */
+export function clearCaches<M extends MessageCore>(caches: ClientCaches<M>) {
+    caches.cache?.clear()
+    caches.resources?.clear()
+    caches.channelCache?.clear()
+    caches.userCache.clear()
+}
+
+/** Apply one decoded event to the caches before it is offered to subscribers */
+export function applyEvent<M extends MessageCore, K extends EventName>(
+    caches: ClientCaches<M>,
+    event: K,
+    message: EventMap<M>[K],
+) {
+    const { cache, resources, channelCache, userCache } = caches
+    resources?.event(event, message)
+    channelCache?.event(event, message)
+    if (event === "userUpdate" && "discriminator" in message) {
+        const guard = userCache.begin("users", { id: message.id })
+        userCache.complete(guard, [message])
+        userCache.invalidate("directMessages")
+    }
+    if (event === "guildMemberUpdate") {
+        const member = message as EventMap["guildMemberUpdate"]
+        // Member projections omit complete account fields, so evict rather than fabricate a User snapshot.
+        // A collection fence also covers pending DM reads whose recipients are not known until completion
+        userCache.invalidate("users", member.userId)
+        userCache.invalidate("directMessages")
+    }
+    if ((event === "directMessageCreate" || event === "directMessageUpdate") && "recipients" in message) {
+        const guard = userCache.begin("directMessages", { id: message.id })
+        userCache.complete(guard, [message])
+    }
+    if (
+        event === "directMessageRecipientAdd" ||
+        event === "directMessageRecipientRemove" ||
+        event === "directMessageDelete"
+    ) {
+        const id = "channelId" in message ? message.channelId : "id" in message ? message.id : undefined
+        userCache.invalidate("directMessages", typeof id === "string" ? id : undefined)
+    }
+    if (event === "directMessageDelete" && "id" in message) cache?.deleteChannel(message.id)
+    if (event === "guildChannelDelete" || event === "threadDelete" || event === "threadMembersUpdate")
+        applyThreadEffects(caches, event, message)
+    if (isMessageEvent<typeof event, M>(event, message)) cache?.observe(message)
+    else if ("ids" in message) {
+        for (const id of message.ids) cache?.delete({ id, channelId: message.channelId })
+    } else if (event === "messageDelete" && "id" in message && "channelId" in message) cache?.delete(message)
+}
+
+/** Apply a channel deletion's or thread event's effects on cached messages and on the bot's cached thread memberships */
+function applyThreadEffects<M extends MessageCore>(
+    caches: ClientCaches<M>,
+    event: "guildChannelDelete" | "threadDelete" | "threadMembersUpdate",
+    message: EventMap<M>[EventName],
+) {
+    const { cache, channelCache } = caches
+    if (event === "guildChannelDelete") {
+        const channel = message as GuildChannel
+        cache?.deleteChannel(channel.id)
+        // Fluxer deletes a parent's threads without THREAD_DELETE, and a message does not record its thread's parent.
+        // The channel cache already evicted the parent's threads, so every channel it still holds is placed elsewhere
+        if (threadParentTypes.has(channel.type))
+            cache?.deleteUnplaced(channel.guildId, (channelId) => channelCache?.holds(channelId) === true)
+    } else if (event === "threadDelete") cache?.deleteChannel((message as EventMap["threadDelete"]).id)
+    else {
+        const update = message as EventMap["threadMembersUpdate"]
+        const self = caches.botUserId
+        // The cached thread carries the bot's membership, so a change that may be the bot's makes it stale
+        const named =
+            self === undefined
+                ? update.added.length > 0 || update.removedUserIds.length > 0
+                : update.added.some((member) => member.userId === self) || update.removedUserIds.includes(self)
+        if (named) channelCache?.evictThread(update.threadId, update.guildId)
+    }
+}
+
+/** Raw guild lifecycle, expression and own thread membership intake, or undefined when no cache can use it */
+export function guildIntake<M extends MessageCore>(
+    caches: ClientCaches<M>,
+): ((event: string, value: unknown) => void) | undefined {
+    const { cache, resources, channelCache, logging } = caches
+    if (!resources && !channelCache && !cache) return undefined
+    return (event, value) => {
+        if (event === "THREAD_MEMBER_UPDATE") {
+            // The dispatch table validated the body first. A cached thread carries the bot's membership, now stale
+            if (record(value) && identifier(value.id) && identifier(value.guild_id))
+                channelCache?.evictThread(value.id, value.guild_id)
+            return
+        }
+        resources?.guildEvent(event, value)
+        if (event !== "GUILD_EMOJIS_UPDATE" && event !== "GUILD_STICKERS_UPDATE")
+            for (const field of channelCache?.guildEvent(event, value) ?? [])
+                logging.log({
+                    level: "warn",
+                    category: "gateway",
+                    code: "gateway.threadSkipped",
+                    message: `Skipped a thread in a ${event} dispatch because its data did not match the expected shape at ${field}. The channel cache does not hold it, and handlers still receive the community`,
+                    fields: { dispatch: event, guildId: (value as { id: string }).id, field },
+                })
+        if (event === "GUILD_DELETE")
+            cache?.gap((guildId) => guildId === undefined || (record(value) && value.id === guildId))
+    }
+}
+
+/** Clear cached observations that a skipped malformed dispatch could have changed */
+export function invalidateDispatch<M extends MessageCore>(caches: ClientCaches<M>, type: string, body: unknown) {
+    const { cache, resources, channelCache, userCache } = caches
+    const value = record(body) ? body : undefined
+    if (type.startsWith("MESSAGE_")) {
+        // Reactions never change cached message snapshots
+        if (type.startsWith("MESSAGE_REACTION")) return
+        if (value && identifier(value.channel_id)) {
+            if (identifier(value.id)) cache?.delete({ id: value.id, channelId: value.channel_id })
+            else cache?.deleteChannel(value.channel_id)
+        } else if (value && identifier(value.id)) {
+            // Without a usable channel the message can still be found by its ID, which is the cache key
+            cache?.deleteId(value.id)
+        } else if (value && identifier(value.guild_id)) {
+            const guildId = value.guild_id
+            cache?.gap((candidate) => candidate === undefined || candidate === guildId)
+        } else cache?.gap()
+        return
+    }
+    if (
+        type === "TYPING_START" ||
+        type.startsWith("PRESENCE_UPDATE") ||
+        type.startsWith("INVITE_") ||
+        type === "WEBHOOKS_UPDATE" ||
+        type === "VOICE_STATE_UPDATE" ||
+        type === "GUILD_AUDIT_LOG_ENTRY_CREATE" ||
+        type === "GUILD_HEALTH_UPDATE" ||
+        // Calls and entrance sounds feed no cache category
+        type.startsWith("CALL_") ||
+        type === "ENTRANCE_SOUND_PLAY"
+    )
+        return
+    if (type === "USER_UPDATE") {
+        userCache.invalidate("users")
+        return
+    }
+    if (type.startsWith("THREAD_")) {
+        invalidateThreadDispatch(caches, type, value)
+        return
+    }
+    if (type === "GUILD_MEMBER_UPDATE") {
+        const userId = value && record(value.user) && identifier(value.user.id) ? value.user.id : undefined
+        userCache.invalidate("users", userId)
+        userCache.invalidate("directMessages")
+    }
+    const guildId =
+        value && identifier(value.guild_id)
+            ? value.guild_id
+            : value && type.startsWith("GUILD_") && identifier(value.id)
+              ? value.id
+              : undefined
+    if (guildId !== undefined) {
+        const affects = (candidate: string | null | undefined) => candidate === undefined || candidate === guildId
+        cache?.gap(affects)
+        resources?.gap(affects)
+        channelCache?.gap(affects)
+        return
+    }
+    if (type.startsWith("CHANNEL_")) {
+        userCache.invalidate("directMessages")
+        // Without a usable guild ID the affected guild is unknown, and a category change can reorder its siblings,
+        // so the channel cache is cleared entirely
+        channelCache?.gap()
+        if (value && identifier(value.id)) cache?.deleteChannel(value.id)
+        else cache?.gap()
+        return
+    }
+    clearCaches(caches)
+}
+
+/**
+ * Clear what a skipped thread dispatch could have changed: Only cached threads, and for a deletion also the thread's
+ * messages. THREAD_LIST_SYNC names its guild in guild_id, and each other type also names its thread in id
+ */
+function invalidateThreadDispatch<M extends MessageCore>(
+    caches: ClientCaches<M>,
+    type: string,
+    value: Record<string, unknown> | undefined,
+) {
+    const { cache, channelCache } = caches
+    const guildId = value && identifier(value.guild_id) ? value.guild_id : undefined
+    const threadId = type !== "THREAD_LIST_SYNC" && value && identifier(value.id) ? value.id : undefined
+    const affects =
+        guildId === undefined
+            ? undefined
+            : (candidate: string | null | undefined) => candidate === undefined || candidate === guildId
+    if (threadId !== undefined) channelCache?.evictThread(threadId, guildId)
+    else channelCache?.gap(affects)
+    if (type !== "THREAD_DELETE") return
+    if (threadId !== undefined) cache?.deleteChannel(threadId)
+    else cache?.gap(affects)
+}

package/src/internal/client/lifetime.ts

@@ -0,0 +1,165 @@
+/**
+ * Client lifetime helpers: The shard group under one startup deadline, service cleanup that keeps every defect, and
+ * shutdown records.
+ * Invariant: The group awaits every assigned shard for initial readiness under one deadline, a healthy shard's work
+ * stays independent of another shard's transient gap, and terminal supervision preserves sibling cleanup failures.
+ * Shutdown shares cleanup across callers and reports completion only after owned resources are released.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import * as Cause from "effect/Cause"
+import * as Clock from "effect/Clock"
+import type * as Context from "effect/Context"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import { ConnectionTimeoutError, ShardConnectionError, type ConnectError, type ConnectionFailure } from "#sdk/errors"
+import { nowMs } from "../clock.js"
+import { mapFailureCause, withDeadline } from "../effect-failures.js"
+import type { ClientLogger } from "../logging.js"
+
+/** Short readable duration for log messages */
+export function formatDuration(milliseconds: number): string {
+    if (milliseconds < 1_000) return `${Math.max(0, Math.round(milliseconds))} ms`
+    if (milliseconds < 60_000) return `${(milliseconds / 1_000).toFixed(1)} s`
+    return `${Math.floor(milliseconds / 60_000)} min ${Math.round((milliseconds % 60_000) / 1_000)} s`
+}
+
+/** Run every shard loop until one fails permanently, bounded by the group startup deadline until startup completes.
+ * Defects from losing loops, such as socket cleanup failures, are kept in the group's cause
+ */
+export function superviseShards<Shard extends { readonly shardId: number }>(options: {
+    readonly shards: readonly Shard[]
+    readonly startupTimeoutMs: number
+    /** Wrap each shard failure with its shard ID, as configured sharding requires */
+    readonly attributeShards: boolean
+    /** Completed once every shard is ready */
+    readonly startup: Deferred.Deferred<void, ConnectError>
+    readonly runShard: (shard: Shard, deadline: number) => Effect.Effect<unknown, ConnectionFailure>
+}) {
+    const { shards, startupTimeoutMs, attributeShards, startup, runShard } = options
+    return Effect.suspend(() => {
+        const exits: Exit.Exit<unknown, ConnectionFailure>[] = []
+        const sessions = Effect.gen(function* () {
+            const clock = yield* Clock.Clock
+            const deadline = nowMs(clock) + startupTimeoutMs
+            return yield* Effect.forEach(
+                shards,
+                (shard) =>
+                    runShard(shard, deadline).pipe(
+                        mapFailureCause((failure) =>
+                            attributeShards && !(failure instanceof ShardConnectionError)
+                                ? new ShardConnectionError(shard.shardId, failure)
+                                : failure,
+                        ),
+                        Effect.onExit((exit) =>
+                            Effect.sync(() => {
+                                exits.push(exit)
+                            }),
+                        ),
+                    ),
+                { concurrency: "unbounded", discard: true },
+            )
+        })
+        const startupGuard = Deferred.await(startup).pipe(
+            // allow-silent: The startup outcome itself is observed through the startup deferred
+            Effect.ignore,
+            withDeadline(startupTimeoutMs, () => new ConnectionTimeoutError(startupTimeoutMs)),
+            Effect.andThen(Effect.never),
+        )
+        return Effect.raceFirst(sessions, startupGuard).pipe(
+            // A losing session may defect during socket cleanup. Keep those causes across the race boundary
+            Effect.onExit((outcome) => {
+                const missing = exits.flatMap((exit) =>
+                    Exit.isFailure(exit)
+                        ? exit.cause.reasons.filter(
+                              (reason) =>
+                                  reason._tag !== "Interrupt" &&
+                                  (!Exit.isFailure(outcome) || !outcome.cause.reasons.includes(reason)),
+                          )
+                        : [],
+                )
+                return missing.length ? Effect.failCause(Cause.fromReasons(missing)) : Effect.void
+            }),
+        )
+    })
+}
+
+/** Keep only defects from a set of cleanup exits, as one cause */
+export function defectsOnly(exits: readonly Exit.Exit<unknown, unknown>[]): Exit.Exit<void> {
+    const reasons = exits.flatMap((exit) =>
+        Exit.isFailure(exit) ? exit.cause.reasons.filter((reason) => reason._tag === "Die") : [],
+    )
+    return reasons.length ? Exit.failCause(Cause.fromReasons<never>(reasons)) : Exit.void
+}
+
+/** Run service cleanups concurrently and fail with every reason any of them produced */
+export function closeAll(services: readonly Effect.Effect<Exit.Exit<unknown, never>>[]): Effect.Effect<void> {
+    return Effect.all(services, { concurrency: "unbounded" }).pipe(
+        Effect.flatMap((exits) => {
+            const reasons = exits.flatMap((exit) => (Exit.isFailure(exit) ? exit.cause.reasons : []))
+            return reasons.length ? Effect.failCause(Cause.fromReasons<never>(reasons)) : Effect.void
+        }),
+    )
+}
+
+/** Log the start of shutdown for a client that connected or ran */
+export function logShutdownStart(
+    logging: ClientLogger,
+    context: Context.Context<never>,
+    everStarted: boolean,
+    reason: string | undefined,
+) {
+    if (!everStarted) return
+    logging.log(
+        {
+            level: "info",
+            category: "lifecycle",
+            code: "lifecycle.shutdown",
+            message: reason === undefined ? "Shutting down" : `Shutting down because ${reason}`,
+        },
+        context,
+    )
+}
+
+/** Log each cleanup failure, flush deduplicated records and log completion for a client that connected or ran */
+export function logShutdownEnd(
+    logging: ClientLogger,
+    context: Context.Context<never>,
+    options: { readonly everStarted: boolean; readonly startedAt: number; readonly services: Exit.Exit<void, unknown> },
+) {
+    const { everStarted, startedAt, services } = options
+    const durationMs = Date.now() - startedAt
+    let failedSteps = 0
+    if (Exit.isFailure(services)) {
+        const faults = services.cause.reasons.filter((reason) => reason._tag !== "Interrupt")
+        failedSteps = Math.max(1, faults.length)
+        logging.count("cleanupFailures", failedSteps)
+        faults.forEach((reason, index) =>
+            logging.log(
+                {
+                    level: "error",
+                    category: "lifecycle",
+                    code: "lifecycle.cleanupFailed",
+                    message: `Cleanup step ${index + 1} of ${faults.length} failed during shutdown`,
+                    error: reason._tag === "Fail" ? reason.error : reason._tag === "Die" ? reason.defect : undefined,
+                    cause: Cause.fromReasons([reason]),
+                },
+                context,
+            ),
+        )
+    }
+    logging.flush(context)
+    if (!everStarted) return
+    logging.log(
+        {
+            level: "info",
+            category: "lifecycle",
+            code: "lifecycle.shutdownComplete",
+            message: Exit.isFailure(services)
+                ? `Shutdown finished in ${formatDuration(durationMs)}, but ${failedSteps} cleanup step${failedSteps === 1 ? "" : "s"} failed`
+                : `Shutdown complete in ${formatDuration(durationMs)}`,
+            durationMs,
+        },
+        context,
+    )
+}