@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/cache-changes.ts

@@ -0,0 +1,363 @@
+/**
+ * Cache change notifications: One client-wide hub that every client-owned cache reports set, delete and clear changes to.
+ * Invariant: Notification never changes a cache result, event delivery or REST outcome. Caches only record a change after
+ * applying it and build no record while no observer is registered. Records are delivered in applied order from a microtask
+ * after the synchronous cache work that produced them, so a listener never runs inside a cache operation, and a failing
+ * listener is reported as a cache failure without affecting other listeners. Each listener holds at most its concurrency
+ * of unfinished calls and its maxPendingChanges of waiting changes, and a full queue drops its oldest change with a logged
+ * and counted Warn, so a stuck listener cannot grow memory. Client closure hands the final clears to listeners with a free
+ * call, then closes every observer without waiting for unfinished calls, dropping the changes still waiting with the same
+ * logged and counted Warn. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import * as Cause from "effect/Cause"
+import type * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import type * as Fiber from "effect/Fiber"
+import type * as Scope from "effect/Scope"
+import type { CacheChange, CacheObserverOptions } from "#sdk/cache"
+import type { CacheKind } from "#sdk/client"
+import { ConfigurationError } from "#sdk/errors"
+import type { MessageCore } from "#sdk/messages"
+import type { CacheObserver } from "#sdk/api/default/cache"
+import type { CacheObserver as NativeCacheObserver } from "#sdk/api/effect/cache"
+import { localValue } from "#sdk/internal/binding/execute"
+import type { ClientOwner } from "./client.js"
+import { record as isRecord } from "./decode/primitives.js"
+import { suspendInput } from "./defects.js"
+import { throwIfErr } from "./failures.js"
+import type { ClientLogger } from "./logging.js"
+import { unsupportedKeyHint } from "./suggest.js"
+
+/** One registered listener in either entry point's form */
+interface Observer {
+    /** Emission sequence number at registration. Only later records are delivered */
+    readonly since: number
+    deliver(change: CacheChange): void
+    close(): void
+}
+
+type Queued = { readonly sequence: number; readonly change: CacheChange }
+
+/** Client-wide cache change fan-out. Caches call record after applying a change */
+export class CacheChangeHub {
+    readonly #observers = new Set<Observer>()
+    #queue: Queued[] = []
+    #sequence = 0
+    #ids = 0
+    #scheduled = false
+    #closed = false
+    #watching = false
+
+    /** Whether any listener is registered, so caches can skip building change records */
+    get active(): boolean {
+        return this.#observers.size > 0
+    }
+
+    /** Queue one applied change for the registered listeners. Never runs a listener inline and never throws */
+    record(kind: CacheKind, op: CacheChange["op"], key: string | null): void {
+        if (this.#observers.size === 0) return
+        this.#queue.push({ sequence: ++this.#sequence, change: Object.freeze({ kind, op, key }) })
+        if (this.#scheduled) return
+        this.#scheduled = true
+        queueMicrotask(() => this.#flush())
+    }
+
+    #flush() {
+        this.#scheduled = false
+        // Changes a listener causes are appended to a fresh queue and delivered by this same loop, in applied order
+        while (this.#queue.length) {
+            const batch = this.#queue
+            this.#queue = []
+            for (const { sequence, change } of batch)
+                for (const observer of this.#observers) if (observer.since < sequence) observer.deliver(change)
+        }
+    }
+
+    /** A new observer identifier, also given to registrations after closure */
+    nextId(): string {
+        return `cacheChange#${++this.#ids}`
+    }
+
+    /** Register an observer, or return undefined after client closure, when no further change can occur */
+    add(create: (since: number) => Observer): Observer | undefined {
+        if (this.#closed) return undefined
+        const observer = create(this.#sequence)
+        this.#observers.add(observer)
+        return observer
+    }
+
+    remove(observer: Observer) {
+        this.#observers.delete(observer)
+        if (this.#observers.size === 0) this.#queue = []
+    }
+
+    /** Close every observer once its owner client closes. Watching starts with the first registration */
+    watch(owner: Pick<ClientOwner<MessageCore>, "subscribe">) {
+        if (this.#watching) return
+        this.#watching = true
+        owner.subscribe((state) => {
+            if (state === "Closed") this.close()
+        })
+    }
+
+    /**
+     * Deliver the changes already recorded, including shutdown's final clears, then close every observer. A listener
+     * at its concurrency keeps them waiting, so its observer drops them with a Warn rather than holding shutdown
+     */
+    close() {
+        if (this.#closed) return
+        this.#flush()
+        this.#closed = true
+        for (const observer of this.#observers) observer.close()
+        this.#observers.clear()
+        this.#queue = []
+    }
+}
+
+type Bounds = { readonly concurrency: number; readonly maxPendingChanges: number }
+const boundKeys = ["concurrency", "maxPendingChanges"] as const
+
+/** The validated onChange options, each read once. A throwing read dies as an application fault */
+const observerBounds = (options: unknown): Effect.Effect<Bounds, ConfigurationError> =>
+    suspendInput(() => {
+        if (options === undefined) options = {}
+        if (!isRecord(options))
+            return Effect.fail(
+                new ConfigurationError("cacheObserverOptions", "Cache observer options must be an object"),
+            )
+        const unsupported = Object.keys(options).find((key) => !(boundKeys as readonly string[]).includes(key))
+        if (unsupported !== undefined)
+            return Effect.fail(
+                new ConfigurationError(
+                    "cacheObserverOptions",
+                    `Unsupported option ${JSON.stringify(unsupported)} in the cache observer options`,
+                    { hint: unsupportedKeyHint(unsupported, boundKeys) },
+                ),
+            )
+        const bounds = { concurrency: 256, maxPendingChanges: 256 }
+        for (const key of boundKeys) {
+            const value = options[key]
+            if (value === undefined) continue
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
+                return Effect.fail(
+                    new ConfigurationError(
+                        key,
+                        `The cache observer option ${JSON.stringify(key)} must be a positive safe integer`,
+                    ),
+                )
+            bounds[key] = value
+        }
+        return Effect.succeed(bounds)
+    })
+
+/**
+ * Bounded delivery to one listener: At most concurrency calls are unfinished, later changes wait in applied order, and a
+ * change arriving while maxPendingChanges wait drops the oldest waiting change with a counted Warn
+ */
+class ListenerQueue {
+    #running = 0
+    #waiting: CacheChange[] = []
+    #dropped = 0
+    #draining = false
+    #open = true
+
+    constructor(
+        readonly id: string,
+        private readonly bounds: Bounds,
+        private readonly logger: ClientLogger,
+        /** Start one listener call. It never throws and calls done once that call has finished */
+        private readonly start: (change: CacheChange, done: () => void) => void,
+    ) {}
+
+    deliver(change: CacheChange) {
+        if (!this.#open) return
+        if (this.#running < this.bounds.concurrency && this.#waiting.length === 0) {
+            this.#run(change)
+            return
+        }
+        if (this.#waiting.length >= this.bounds.maxPendingChanges) {
+            this.#waiting.shift()
+            this.#drop()
+        }
+        this.#waiting.push(change)
+    }
+
+    /**
+     * Stop delivery and discard waiting changes. At client shutdown, which never waits for unfinished calls, the
+     * discarded changes are logged and counted as drops
+     */
+    close(shutdown = false) {
+        this.#open = false
+        const discarded = this.#waiting.length
+        this.#waiting = []
+        if (!shutdown || discarded === 0) return
+        this.#dropped += discarded
+        const { concurrency } = this.bounds
+        this.logger.count("cacheChangesDropped", discarded)
+        this.logger.log({
+            level: "warn",
+            category: "cache",
+            code: "cache.changesDropped",
+            message: `The client shut down while ${discarded} ${discarded === 1 ? "change" : "changes"} waited for the cache.onChange listener ${this.id}, which had ${concurrency} unfinished ${concurrency === 1 ? "call" : "calls"} (concurrency), so ${discarded === 1 ? "it was" : "they were"} dropped`,
+            subscriptionId: this.id,
+            fields: { dropped: this.#dropped, concurrency, maxPendingChanges: this.bounds.maxPendingChanges },
+        })
+    }
+
+    #run(change: CacheChange) {
+        this.#running++
+        let finished = false
+        this.start(change, () => {
+            if (finished) return
+            finished = true
+            this.#running--
+            this.#drain()
+        })
+    }
+
+    /** Start waiting changes while calls are free. Calls that finish synchronously continue this loop rather than nest */
+    #drain() {
+        if (this.#draining) return
+        this.#draining = true
+        try {
+            while (this.#open && this.#running < this.bounds.concurrency && this.#waiting.length)
+                this.#run(this.#waiting.shift()!)
+        } finally {
+            this.#draining = false
+        }
+    }
+
+    #drop() {
+        this.#dropped++
+        const { concurrency, maxPendingChanges } = this.bounds
+        // The message stays the same for every drop, so repeats collapse while fields.dropped carries the latest total
+        this.logger.drop("cacheChangesDropped", {
+            level: "warn",
+            category: "cache",
+            code: "cache.changesDropped",
+            message: `The cache.onChange listener ${this.id} has ${concurrency} unfinished ${concurrency === 1 ? "call" : "calls"} (concurrency) and ${maxPendingChanges} waiting ${maxPendingChanges === 1 ? "change" : "changes"} (maxPendingChanges), so the oldest waiting change was dropped`,
+            subscriptionId: this.id,
+            fields: { dropped: this.#dropped, concurrency, maxPendingChanges },
+        })
+    }
+}
+
+/** A listener's failure as a client cache report. Reporting never throws */
+function reportFailure<M extends MessageCore>(
+    owner: ClientOwner<M>,
+    input: { readonly error: unknown } | { readonly cause: Cause.Cause<unknown> },
+) {
+    owner.failures.report({ kind: "cache", ...input })
+}
+
+const closedObserver = (id: string): CacheObserver =>
+    Object.freeze({ id, close: () => undefined, [Symbol.dispose]: () => undefined })
+
+/** Default-API cache.onChange: Listeners run from a microtask, and returned promises are observed but not awaited */
+export const defaultCacheOnChange =
+    <M extends MessageCore>({ owner }: { readonly owner: ClientOwner<M> }) =>
+    (listener: (change: CacheChange) => unknown, options?: CacheObserverOptions): CacheObserver => {
+        if (typeof listener !== "function")
+            throw new ConfigurationError("listener", "Cache change listener must be a function")
+        const bounds = localValue(observerBounds(options), "cache.onChange")
+        const hub = owner.cacheChanges
+        hub.watch(owner)
+        const id = hub.nextId()
+        const report = (error: unknown) => reportFailure(owner, { error })
+        const queue = new ListenerQueue(id, bounds, owner.logging, (change, done) => {
+            let settled: Promise<unknown> | undefined
+            try {
+                const result = listener(change)
+                if (
+                    typeof result === "object" &&
+                    result !== null &&
+                    typeof (result as { then?: unknown }).then === "function"
+                )
+                    settled = Promise.resolve(result).then(throwIfErr)
+                else throwIfErr(result)
+            } catch (error) {
+                report(error)
+            }
+            if (settled === undefined) done()
+            else void settled.catch(report).then(done)
+        })
+        let open = true
+        const observer = hub.add((since) => ({
+            since,
+            deliver: (change) => queue.deliver(change),
+            // The hub closes observers only at client shutdown
+            close: () => {
+                open = false
+                queue.close(true)
+            },
+        }))
+        if (!observer) return closedObserver(id)
+        const close = () => {
+            if (!open) return
+            open = false
+            queue.close()
+            hub.remove(observer)
+        }
+        return Object.freeze({ id, close, [Symbol.dispose]: close })
+    }
+
+/** Native cache.onChange: Each change forks the listener Effect with the registration services, closed with its Scope */
+export const nativeCacheOnChange =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <E = never, R = never>(
+        listener: (change: CacheChange) => Effect.Effect<unknown, E, R>,
+        options?: CacheObserverOptions,
+    ): Effect.Effect<NativeCacheObserver, never, R | Scope.Scope> =>
+        Effect.gen(function* () {
+            if (typeof listener !== "function")
+                return yield* Effect.die(new ConfigurationError("listener", "Cache change listener must be a function"))
+            // Invalid options are misuse, so they become a defect rather than a typed failure
+            const bounds = yield* observerBounds(options).pipe(Effect.orDie)
+            const services = (yield* Effect.context<R>()) as Context.Context<never>
+            const hub = owner.cacheChanges
+            const id = hub.nextId()
+            const close = yield* Effect.acquireRelease(
+                Effect.sync(() => {
+                    hub.watch(owner)
+                    const running = new Set<Fiber.Fiber<unknown, unknown>>()
+                    const queue = new ListenerQueue(id, bounds, owner.logging, (change, done) => {
+                        try {
+                            const fiber = Effect.runForkWith(services)(
+                                Effect.suspend(() => listener(change) as Effect.Effect<unknown, unknown>),
+                            )
+                            running.add(fiber)
+                            fiber.addObserver((exit) => {
+                                running.delete(fiber)
+                                if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause))
+                                    reportFailure(owner, { cause: exit.cause })
+                                done()
+                            })
+                        } catch (error) {
+                            reportFailure(owner, { error })
+                            done()
+                        }
+                    })
+                    let open = true
+                    const stop = (shutdown = false) => {
+                        if (!open) return
+                        open = false
+                        queue.close(shutdown)
+                        for (const fiber of running) fiber.interruptUnsafe()
+                        running.clear()
+                    }
+                    const observer = hub.add((since) => ({
+                        since,
+                        deliver: (change) => queue.deliver(change),
+                        // The hub closes observers only at client shutdown
+                        close: () => stop(true),
+                    }))
+                    return () => {
+                        stop()
+                        if (observer) hub.remove(observer)
+                    }
+                }),
+                (close) => Effect.sync(close),
+            )
+            return Object.freeze({ id, close: () => Effect.sync(close) })
+        })

package/src/internal/cache.ts

@@ -0,0 +1,323 @@
+/**
+ * Optional message cache: Retained message observations, in-flight request guards and connection-gap invalidation.
+ * Invariant: Fluxer is the source of truth. Intake updates stored data from REST responses and gateway events before subscribers
+ * see them, retained data and conflict metadata stay bounded, and pre-gap observations are cleared even after session resumption.
+ * A gap on a guild with a known shard invalidates only that shard's data, private-conversation data belongs to shard zero, and
+ * unknown ownership stays conservative, including channel-only in-flight reads, without an unbounded channel-to-guild index.
+ * A deleted thread parent removes the messages of every channel in its guild that the channel cache cannot place, because
+ * Fluxer deletes the parent's threads without thread deletion events and messages do not record their thread's parent.
+ * Pre-gap requests neither repopulate invalid snapshots nor evict healthy post-gap observations on late completion. A callback
+ * that throws or returns an invalid value is reported with kind cache and the message IDs, and neither retention nor reporting
+ * failure changes a successful REST result or event delivery. Every applied store, removal and whole-cache clear is recorded
+ * to the client's change hub after it is applied, a replacement counting as one store. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { isDeepStrictEqual } from "node:util"
+import type { CacheDiagnostic } from "#sdk/client"
+import type { Message, MessageCore, MessageReference } from "#sdk/messages"
+import type { CacheConfiguration } from "./configuration.js"
+import { retentionAge } from "./retention-age.js"
+import { ExpiryQueue, ExpiryTimer } from "./expiry-queue.js"
+import type { LogicalScheduler } from "./logical-scheduler.js"
+import type { CacheChangeHub } from "./cache-changes.js"
+
+type Entry<M extends MessageCore> = { message: M; bytes: number; expires: number | null }
+export type CacheRequest = {
+    readonly channel: string
+    readonly id: string | undefined
+    readonly mutation: boolean
+    readonly generation: number
+    invalid: boolean
+}
+
+/**
+ * Whether an overlapping response describes the same message state as the retained snapshot.
+ * Fluxer omits guild_id from message HTTP responses while gateway events include it, so a guild ID present on only
+ * one side is unknown context rather than a conflicting change
+ */
+function sameObservation<M extends MessageCore>(retained: M, incoming: M) {
+    if (isDeepStrictEqual(retained, incoming)) return true
+    if ((retained.guildId === undefined) === (incoming.guildId === undefined)) return false
+    const { guildId: _retainedGuild, ...retainedState } = retained
+    const { guildId: _incomingGuild, ...incomingState } = incoming
+    return isDeepStrictEqual(retainedState, incomingState)
+}
+
+/** A message's cache change key: Its channel and message IDs */
+const changeKey = (message: MessageReference) => `${message.channelId}:${message.id}`
+
+/** Running lookup and eviction totals of one cache category, copied into its CacheDiagnostic */
+export type CacheStats = { hits: number; misses: number; evictions: { capacity: number; expiry: number } }
+export const cacheStats = (): CacheStats => ({ hits: 0, misses: 0, evictions: { capacity: 0, expiry: 0 } })
+/** A diagnostic copy of the totals, which keep counting after it is taken */
+export const readStats = (stats: CacheStats): CacheStats => ({ ...stats, evictions: { ...stats.evictions } })
+
+/** One client's retained observations and bounded in-flight guards, never a server-state replica */
+export class MessageCache<M extends MessageCore = Message> {
+    #entries = new Map<string, Entry<M>>()
+    #requests = new Set<CacheRequest>()
+    #bytes = 0
+    #generation = 0
+    #expiry = new ExpiryQueue<Entry<M> & { expires: number }>((entry) => this.#entries.get(entry.message.id) === entry)
+    #timer: ExpiryTimer
+    #closed = false
+    readonly #stats = cacheStats()
+    readonly #limits: { readonly maxEntries: number; readonly maxBytes: number } | undefined
+
+    constructor(
+        private settings: CacheConfiguration<M> | undefined,
+        private report: (error: unknown, message: MessageCore) => void,
+        private readonly now: () => number,
+        logical?: LogicalScheduler,
+        readonly changes?: CacheChangeHub,
+    ) {
+        this.#timer = new ExpiryTimer(
+            "message cache",
+            now,
+            () => {
+                this.#purge()
+                this.#schedule()
+            },
+            logical,
+        )
+        this.#limits = settings && Object.freeze({ maxEntries: settings.maxEntries, maxBytes: settings.maxBytes })
+    }
+
+    get generation() {
+        return this.#generation
+    }
+
+    diagnostics(): CacheDiagnostic {
+        this.#purge()
+        this.#schedule()
+        return {
+            configured: this.#limits !== undefined,
+            retainedEntries: this.#entries.size,
+            accountedBytes: this.#bytes,
+            maxEntries: this.#limits?.maxEntries ?? null,
+            maxBytes: this.#limits?.maxBytes ?? null,
+            ...readStats(this.#stats),
+        }
+    }
+
+    entries(limit: number): readonly M[] {
+        this.#purge()
+        this.#schedule()
+        const entries: M[] = []
+        for (const entry of this.#entries.values()) {
+            entries.push(entry.message)
+            if (entries.length === limit) break
+        }
+        return Object.freeze(entries)
+    }
+
+    /** Release only this client's retained snapshots and block reads that began before this point from refilling them */
+    clear() {
+        if (this.#closed) return
+        this.gap()
+    }
+
+    get(target: MessageReference): M | undefined {
+        const entry = this.#peek(target)
+        if (!entry) {
+            this.#stats.misses++
+            return undefined
+        }
+        this.#stats.hits++
+        this.#entries.delete(target.id)
+        this.#entries.set(target.id, entry)
+        return entry.message
+    }
+
+    #peek(target: MessageReference) {
+        const entry = this.#entries.get(target.id)
+        if (!entry || entry.message.channelId !== target.channelId) return undefined
+        if (entry.expires !== null && entry.expires <= this.now()) {
+            this.#remove(target)
+            this.#stats.evictions.expiry++
+            return undefined
+        }
+        return entry
+    }
+
+    /** Remove one retained message, reporting the deletion unless the caller replaces it. Returns whether one was removed */
+    #remove(target: MessageReference, notify = true): boolean {
+        const entry = this.#entries.get(target.id)
+        if (entry?.message.channelId !== target.channelId) return false
+        this.#entries.delete(target.id)
+        this.#bytes -= entry.bytes
+        if (notify && this.changes?.active) this.changes.record("messages", "delete", changeKey(entry.message))
+        return true
+    }
+
+    #invalidate(target: MessageReference, except?: CacheRequest) {
+        for (const request of this.#requests)
+            if (
+                request !== except &&
+                request.channel === target.channelId &&
+                (request.id === undefined || request.id === target.id)
+            )
+                request.invalid = true
+    }
+
+    begin(channel: string, id: string | undefined, mutation: boolean, generation: number): CacheRequest {
+        const request = { channel, id, mutation, generation, invalid: generation !== this.#generation }
+        for (const other of this.#requests) {
+            if (other.channel !== channel || (id !== undefined && other.id !== undefined && id !== other.id)) continue
+            if (mutation) other.invalid = true
+            if (other.mutation) request.invalid = true
+        }
+        this.#requests.add(request)
+        return request
+    }
+
+    end(request: CacheRequest) {
+        this.#requests.delete(request)
+    }
+
+    complete(request: CacheRequest, messages: readonly M[]) {
+        if (this.#closed || request.generation !== this.#generation) return
+        // Admit a history page oldest first so its newest members survive tight capacity limits
+        for (let index = messages.length - 1; index >= 0; index--) {
+            const message = messages[index]!
+            if (request.invalid) {
+                const entry = this.#peek(message)
+                if (entry && !sameObservation(entry.message, message)) {
+                    this.#remove(message)
+                    this.#invalidate(message, request)
+                }
+            } else this.observe(message, request)
+        }
+        this.#schedule()
+    }
+
+    observe(message: M, request?: CacheRequest) {
+        if (this.#closed || !this.settings) return
+        this.#invalidate(message, request)
+        const resolved = retentionAge(this.settings.maxAgeMs ?? null, message, "message cache", "message")
+        if ("error" in resolved) {
+            this.#remove(message)
+            this.report(resolved.error, message)
+            this.#schedule()
+            return
+        }
+        if (this.#closed || !this.settings) return
+        const age = resolved.age
+        const bytes = age === 0 ? 0 : Buffer.byteLength(JSON.stringify(message))
+        // A replacement reports one set, while an older copy that the new one cannot replace reports a delete
+        const replaced = this.#remove(message, false)
+        if (age !== 0 && bytes <= this.settings.maxBytes) {
+            this.#purge()
+            while (this.#entries.size >= this.settings.maxEntries || this.#bytes > this.settings.maxBytes - bytes) {
+                const oldest = this.#entries.values().next().value!
+                this.#remove(oldest.message)
+                this.#stats.evictions.capacity++
+            }
+            const entry: Entry<M> = { message, bytes, expires: age === null ? null : this.now() + age }
+            this.#entries.set(message.id, entry)
+            this.#bytes += bytes
+            if (entry.expires !== null) this.#expiry.push(entry as Entry<M> & { expires: number })
+            if (this.changes?.active) this.changes.record("messages", "set", changeKey(message))
+        } else if (replaced && this.changes?.active) this.changes.record("messages", "delete", changeKey(message))
+        this.#schedule()
+    }
+
+    delete(target: MessageReference, except?: CacheRequest) {
+        if (this.#closed) return
+        this.#invalidate(target, except)
+        this.#remove(target)
+        this.#schedule()
+    }
+
+    /** Remove one message by ID when its channel is unknown, and block reads already in flight from restoring it */
+    deleteId(id: string) {
+        if (this.#closed) return
+        this.#generation++
+        for (const request of this.#requests) if (request.id === undefined || request.id === id) request.invalid = true
+        const entry = this.#entries.get(id)
+        if (entry) this.#remove(entry.message)
+        this.#schedule()
+    }
+
+    deleteMany(channelId: string, ids: readonly string[]) {
+        if (this.#closed) return
+        // Also block queued reads that have not registered their request guard yet
+        this.#generation++
+        for (const id of ids) this.delete({ channelId, id })
+    }
+
+    deleteAuthor(userId: string) {
+        if (this.#closed) return
+        this.#generation++
+        for (const entry of this.#entries.values()) if (entry.message.author.id === userId) this.delete(entry.message)
+    }
+
+    deleteChannel(channelId: string) {
+        if (this.#closed) return
+        // Queued REST calls have captured this generation but may not have registered a per-request guard yet
+        // Preserve other channel snapshots while conservatively blocking admission of pre-deletion responses
+        this.#generation++
+        for (const request of this.#requests) if (request.channel === channelId) request.invalid = true
+        for (const entry of this.#entries.values())
+            if (entry.message.channelId === channelId) this.#remove(entry.message)
+        this.#schedule()
+    }
+
+    /**
+     * Remove the messages a deleted thread parent can have taken with its threads: Those in this guild, or without guild
+     * context, whose channel held does not place. Reads of such channels already in flight cannot restore them
+     */
+    deleteUnplaced(guildId: string, held: (channelId: string) => boolean) {
+        if (this.#closed) return
+        // Queued REST calls have captured this generation but may not have registered a per-request guard yet
+        this.#generation++
+        for (const request of this.#requests) if (!held(request.channel)) request.invalid = true
+        for (const entry of this.#entries.values()) {
+            const message = entry.message
+            if ((message.guildId === undefined || message.guildId === guildId) && !held(message.channelId))
+                this.#remove(message)
+        }
+        this.#schedule()
+    }
+
+    gap(affects?: (guildId: string | null | undefined) => boolean) {
+        // Channel-only requests capture this generation before admission and retain it across retries
+        if (!affects || affects(undefined)) {
+            this.#generation++
+            for (const request of this.#requests) request.invalid = true
+        }
+        if (!affects) {
+            const held = this.#entries.size > 0
+            this.#entries.clear()
+            this.#bytes = 0
+            this.#expiry.clear()
+            if (held && this.changes?.active) this.changes.record("messages", "clear", null)
+        } else {
+            for (const entry of this.#entries.values()) if (affects(entry.message.guildId)) this.#remove(entry.message)
+        }
+        this.#schedule()
+    }
+
+    #purge() {
+        this.#expiry.purge(this.now(), (entry) => {
+            if (this.#remove(entry.message)) this.#stats.evictions.expiry++
+        })
+    }
+
+    #schedule() {
+        if (this.#closed) {
+            this.#timer.cancel()
+            this.#expiry.clear()
+            return
+        }
+        this.#expiry.compact(this.#entries.size)
+        this.#timer.set(this.#expiry.next())
+    }
+
+    close() {
+        this.#closed = true
+        this.gap()
+        this.#requests.clear()
+        this.settings = undefined
+        this.report = () => {}
+    }
+}