@neontechspace/fluxerly 1000.0.0-nightly.12

package/CHANGELOG.md

@@ -0,0 +1,833 @@
+# @neontechspace/fluxerly
+
+## 1000.0.0-rc.7
+
+### Major Changes
+
+- 66e4f2b: Audit-log reads and `guildAuditLogEntryCreate` events no longer fail on an audit action this SDK version does not name. `AuditLogEntry.actionType` is now a `number` that keeps any action Fluxer records, including ones added later, so compare it with `AuditLogActions` values. Previously one such entry rejected its whole audit-log page and made the gateway event malformed. `AuditLogActions` gains `ThreadCreate` (110), `ThreadUpdate` (111) and `ThreadDelete` (112), which also work as `actionType` filters
+- 07d2b9d: A prefix command parser can now explain why it declined a message. The `commands.parseQuoted` parser now returns a new `PrefixCommandParseRejection` with a fixed `reason` for a quote that never closes or a backslash at the end, where it used to return `undefined` and give no hint, and a custom `parse` function can return the same `{ reason }` shape. The router's `onUnmatched` callback, which already handles unknown names and groups typed without a subcommand, receives the reason on `CommandParserRejected` in both entry points, and the Debug `commands.unmatched` record includes it. The router still sends no reply by itself, so a bot decides whether to turn the reason into one. A rejection with an empty or non-text reason or with other keys is reported like any malformed parser result. The commands guide now explains how to opt in to the quoted parser and how to reply to unmatched messages. A direct caller of `commands.parseQuoted` that tests the result for truthiness or reads `args` must now rule out a rejection first, such as with `"reason" in result`, because only a rejection has `reason` and a parse has `name`, `args` and `rawArgs`
+- c8c87b0: `Embed.provider` and `EmbedChild.provider` now have their own `EmbedProvider` type, with only `name` and `url`, matching what Fluxer sends. They were typed as `EmbedAuthor`, whose `iconUrl` and `proxyIconUrl` never arrived on a provider. `EmbedProvider` is exported from both entry points, and a provider's icon fields are no longer decoded
+- 37612fd: A `runBot` handler set to `overflow: "stop"` whose queue fills now stops the bot in both entry points. The bot previously kept running without that handler, as its API comments said, so the handler's events stopped arriving while the bot looked healthy. The run now fails with `CriticalWorkerStoppedError`, whose `details` hold the `event`, the exceeded `limit`, `messages` or `bytes`, and its `capacity`, and whose `cause` is the subscription's `EventOverflowError`. The overflow itself is still reported to `onError` or logged. A bot that should keep running sets `overflow` to `dropOldest` or `dropNewest`, which are unchanged
+- dd54820: Threads, forum channels and media channels now have their own channel shapes in both entry points, instead of arriving as `GuildUnknownChannel`. `ChannelType` gains `AnnouncementThread` (10), `PublicThread` (11), `PrivateThread` (12), `Forum` (15) and `Media` (16), and `GuildChannel` gains `GuildAnnouncementThreadChannel`, `GuildPublicThreadChannel`, `GuildPrivateThreadChannel`, `GuildForumChannel` and `GuildMediaChannel`. A thread flattens Fluxer's thread metadata, such as `archived`, `locked` and `autoArchiveMinutes`, and carries the bot's own `membership` when Fluxer reports it. The `isThreadChannel` function selects every thread type. A forum or media channel carries its tags and post settings, each optional because Fluxer leaves them out of some payloads, such as `guildChannelDelete`. Text and announcement channels gain `defaultAutoArchiveMinutes` and `defaultThreadRateLimitPerUser`. The new constants are `ChannelFlags`, `ThreadAutoArchiveMinutes`, `ForumSortOrder` and `ForumLayout`. The `channels.get` and `channels.fetch` methods can return any of these shapes, and `channels.fetchAll` never lists threads
+
+    `Permissions` gains `ManageThreads`, `CreatePublicThreads`, `CreatePrivateThreads` and `SendMessagesInThreads`, so `permissionBits` and `guards.requirePermissions` accept their names. `MessageType` gains `ThreadCreated` (18) and `ThreadStarterMessage` (21). `MessageFlags` gains the server-managed bits `HasThread` (32) and `FailedToMentionSomeRolesInThread` (256), which message and webhook send and edit operations reject before dispatch. `Message.thread` holds the thread a message started, and `GuildListSummary.threadsActive` reports whether the bot can use threads in a community. The testing fixtures gain `thread()` and `forumChannel()` with the `WireThread` and `WireForumChannel` types, and `guildCreate()` now includes an empty `threads` list
+
+    The new `client.threads` namespace creates, changes, lists and searches threads and manages their members. Its `create` method starts a thread in a text or announcement channel, `createFromMessage` starts one on an existing message, and `createPost` creates a forum or media post with its first message, sending its files in the same multipart request. The `edit` method archives, locks, renames or pins a thread and replaces a post's tags. For reading, `fetchActive` lists a community's active threads, `fetchArchived` reads one page of a channel's archived threads, and `search` reads one page of matching threads, with the first message of each post in a forum or media channel. Every list carries the bot's own `membership` on each thread it joined. A search that Fluxer answers with HTTP 202 while it builds the community's search index returns `{ indexing: true }` without a retry
+
+    Thread membership changes through `join`, `leave`, `addMember` and `removeMember`, and thread members are read with `fetchMember`, `fetchMembers` and `iterateMembers`. With `withMember`, each member also carries the user's community membership, decoded with the thread's community from the channel cache or from one extra channel read. Failures are `ChannelOperationError` values whose operation names the `threads` method, and a missing-permission rejection of `create`, `createFromMessage`, `createPost`, `edit`, `fetchArchived`, `search`, `addMember` or `removeMember` lists the permissions that method needs
+
+    Forum and media channels can be created and managed through `channels`. Creating a channel accepts `ChannelType.Forum` and `ChannelType.Media` with `availableTags`, `defaultReactionEmoji`, `defaultSortOrder`, `defaultTagSetting`, `flags`, a `topic` of up to 4,096 characters and, on forum channels, `defaultForumLayout`. Text and announcement channels accept `defaultAutoArchiveMinutes` and `defaultThreadRateLimitPerUser` on creation, and `channels.edit` accepts those two settings and every forum setting, including a complete `availableTags` list. On creation, a setting that the chosen channel type cannot have fails with reason `input` before any request. An edit cannot tell the channel's type, so `channels.edit` accepts every setting and leaves that check to Fluxer. Both methods fail with reason `input` before any request when a value has the wrong format or range, such as more than 20 tags, while checks that need the channel or community, such as whether a tag emoji exists, stay with Fluxer. The new `channels.createForumTag`, `channels.editForumTag` and `channels.deleteForumTag` change one tag and return the updated forum or media channel. The `editForumTag` method replaces the tag, so an omitted `moderated` value or emoji resets. A permission rejection of any of the three lists `ViewChannel` and `ManageChannels` in `details.requiredPermissions`
+
+    Webhook clients can now reach threads. `WebhookMessageInput` gains `threadId`, sent as the `thread_id` query parameter, and, on new messages, `threadName` to start a forum or media post with up to five `appliedTagIds`. The SDK rejects `threadName` together with `threadId`, `appliedTagIds` without `threadName`, and `threadName` on a reply or forward before any request. The `fetchMessage`, `editMessage` and `deleteMessage` methods take `WebhookMessageOperationOptions` with a `threadId` to reach a message in a thread, and the default API names it `DefaultWebhookMessageOperationOptions`
+
+    Thread gateway events now have their own typed events. The `threadCreate` event delivers a `ThreadCreateEvent`, the thread plus `isNewlyCreated`, which is false when the bot joined or was added to an existing thread. The `threadUpdate` event delivers the changed thread, `threadDelete` a `ThreadDeletion` with the thread's ID, community, parent and type, `threadListSync` a `ThreadListSync` with the bot's active threads in a community or in some of its channels, and `threadMembersUpdate` a `ThreadMembersUpdate` with the members who joined and the IDs of those who left. The `"channel"` handler partition keys thread events by their thread. Automatic event filtering suppresses unused thread dispatches, keeps every thread dispatch while the channel cache is enabled and keeps `THREAD_DELETE` while the message cache is enabled
+
+    The channel cache now holds threads. A community snapshot fills it with the active threads the bot can view, leaving out a malformed thread with a `gateway.threadSkipped` Warn record instead of failing the snapshot. Thread create and update events store the thread, a thread deletion removes it, and a thread list replaces the cached threads it covers. The `threads.fetchActive` list also enters the cache, while archived pages, search results, forum posts and member reads do not. A change to the bot's own membership of a thread removes that thread, and a completed Resume removes the resumed shard's threads, because Fluxer never replays thread lists. A `channels.fetchAll` result keeps cached threads, and an operation confined to one thread clears only that thread
+
+    Deleting a text, announcement, forum or media channel deletes its threads without thread deletion events. The channel cache removes the threads whose parent is the deleted channel, and the message cache removes the messages of every channel in that community, or without community context, that the channel cache does not hold. Without the channel cache that is every such message, because a message does not record its thread's parent. A thread deletion removes the thread's messages
+
+    Permission checks now handle threads. A thread has no permission overwrites of its own, because Fluxer calculates its permissions in its parent channel and then grants `SendMessages` in the thread exactly when `SendMessagesInThreads` is granted. The new `PermissionInput.parentChannel` supplies that parent to `permissions.calculate`, which applies the same rule. A thread without its parent, a thread with a different channel as `parentChannel`, and a `parentChannel` beside a channel that is not a thread fail with reason `input`. For a thread, `permissions.fetch` also reads the parent channel under the same deadline. The `guards.requirePermissions` guard now reads the thread and then its parent channel, each from an enabled channel cache before a request, and decides by the same rule, where it previously used only the member's role permissions and ignored the parent channel's overwrites. None of these checks covers whether the member can see a private thread or whether the thread is archived or locked. The guard also denies a command, with the reason "This command cannot check permissions in this kind of channel", when the channel has a type this SDK version does not know and Fluxer reads it without permission overwrites, because such a channel can take its permissions from elsewhere
+
+    Message search no longer fails when a result comes from a thread. Fluxer lists the channel of such a result in a separate thread list, which previously made `messages.search` reject the whole page and stopped `messages.iterateSearch`. `MessageSearchResultsPage.threads` now holds those threads as typed thread shapes, each with the bot's `membership` when the bot has joined it, and `channels` keeps the other channels. Each message's channel appears exactly once across `channels` and `threads`. Audit-log pages and `guildAuditLogEntryCreate` events also no longer fail on a forum or media channel change, because its `available_tags` and `default_reaction_emoji` values now decode as `ForumTag` lists and `ForumDefaultReaction` objects, which `AuditLogChangeValue` gains, and `AuditLogPage.threads` lists the threads that the page's thread actions target
+
+    Rejections of thread, forum tag and webhook post operations carry a reviewed `apiError`. The new `ApiErrorCode` categories are `threadArchived`, `threadLocked`, `threadAlreadyCreated`, `channelHasThreads`, `invalidChannelType`, `forumTagNamesNotUnique`, `forumTagRequired`, `noTagsAvailable`, `mediaChannelRequired`, `webhookForumTargetRequired` and `webhookThreadNameRequiresForum`, each with a hint that names the fix. The active thread, forum tag, pinned post and thread member limits join `resourceLimit`, and a missing forum tag or thread member joins `unknownResource`. `ApiProviderCode` gains the matching Fluxer codes
+
+    Migration: Code that matched `type === "unknown"` for a thread, forum channel or media channel now receives the typed shape, and an exhaustive `switch` over `GuildChannel`, `ChannelType`, `ChannelCreate` or `ApiErrorCode` needs the new cases. A `permissions.calculate` call for a thread passes the parent channel as `parentChannel`. A `gateway.ignoredEvents` list that names a thread dispatch an enabled cache needs, which is any thread dispatch for the channel cache and `THREAD_DELETE` for the message cache, now fails client creation with `ConfigurationError`, so remove the name or turn off that cache. With only the message cache enabled, deleting a text, announcement, forum or media channel now evicts every cached message of its community and every cached message without community context
+
+### Minor Changes
+
+- 3d68f4d: The `client.cache.onChange` method now bounds the work each listener can hold, in both APIs. A listener whose calls never finished, such as one returning a promise that never settles or an Effect that never ends, kept one unfinished call per cache change without limit. A listener now has at most `concurrency` unfinished calls, 256 by default, and up to `maxPendingChanges` later changes, also 256 by default, wait in the order they were applied. A change arriving beyond that drops the oldest waiting change, logs a `cache.changesDropped` Warn with the observer's new `id` and how many changes it has dropped, and counts the drop in `diagnostics().counters.cacheChangesDropped`. Both limits go in the new optional second argument, `CacheObserverOptions`, and `{ concurrency: 1 }` handles changes one at a time in order. A limit that is not a positive safe integer, or an unknown key, throws `ConfigurationError` in the default API and dies with it in the Effect API. A synchronous listener finishes each call before the next change, so the limits never delay or drop its changes. Shutdown does not wait for unfinished listener calls, so changes still waiting at shutdown, including its final clears, are dropped and recorded the same way
+- 3d68f4d: Each category in `client.diagnostics().caches` now keeps running totals since the client was created, in both APIs. The `hits` and `misses` values count local lookups such as `client.messages.get`, including lookups the SDK makes itself, and the `evictions` value counts entries the cache removed on its own, with `capacity` for room within `maxEntries` or `maxBytes` and `expiry` for entries older than `maxAgeMs`. Removal by events, writes, `cache.delete`, clears, connection gaps or shutdown is not counted, and a disabled category reports zero
+- cae766a: The new `client.schedule` method runs a task once after `delayMs` or repeatedly with `intervalMs` between runs, owned by the client's lifetime in both APIs, so a `runBot` command, handler or `setup` can start delayed or repeating work without keeping a command slot busy or leaving a timer behind. It returns a `ScheduledTask` whose `close()` cancels later runs. The `delayMs` value is 0 through 2,147,483,647 and `intervalMs` 1 through 2,147,483,647, and a repeating task first runs after `intervalMs` unless `delayMs` is set. Invalid options throw `ConfigurationError` in the default API and die with it in the Effect API. The default API takes a function that receives a cancellation signal, and the Effect API takes an Effect that keeps the caller's services and gets a Scope of its own for each run. Each failed run is reported to the client-level `onError`, or logged at Error with the new code `lifecycle.taskFailed` under the new failure kind `task`, and a repeating task keeps its schedule after a failure. A draining shutdown, including a requested `runBot` stop, lets running tasks finish within `drainMs` and counts them in the drain records' new `tasks` field, and every shutdown cancels the rest, counting the tasks it cut short in one `lifecycle.tasksCancelled` Info record. The test kit's `idle()` and `say` in both APIs also wait for scheduled task runs in progress, while a task still waiting for its time does not hold them up. Scheduling after shutdown began throws `ClientClosedError` in the default API and dies with it in the Effect API. The test clients treat a failed task run without an `onError` hook as an unhandled failure. Tasks are kept in memory only. The commands guide's reminder example now schedules its reply instead of waiting inside the command, and the bot lifetime guide explains scheduled tasks
+- ce65b67: The `client.logging.configure` method now accepts `debug` in both APIs, so Debug output can be changed while the client runs, including output turned on by `FLUXERLY_DEBUG`. A `debug` value replaces the current Debug categories: `true` for every category, a list for those categories, and `false` or an empty list for none. An omitted `debug` keeps the current categories, while an omitted `level` or `categories` still returns to its default. `LogLevelSettings` gains the `debug` setting
+- 7ec55f6: `PresenceUpdate`, and so each entry of `PresenceUpdateBulk` and of the presences in a member chunk, now carries `customStatus` in both entry points, instead of dropping the custom status Fluxer sends. The value is `null` when the account has none, which includes an offline or invisible account because Fluxer hides the status of one, and otherwise an `ObservedCustomStatus` with `text`, `emoji` and `expiresAt`. The `emoji` field is `null` or an `ObservedCustomStatusEmoji` with `id`, `name` and `animated`, so a custom emoji keeps its ID and animation flag and a Unicode emoji has a name and no ID and always reads as `animated: false`. Fluxer stores custom statuses without validating them, so a field of the wrong type reads as `null` and the presence is still delivered
+- 37612fd: The `runBot` `commands` option now accepts the delivery settings of the router's `attach` in both entry points: `concurrency`, `partition`, `overflow`, `maxPendingMessages` and `maxPendingBytes`. They reach the router unchanged and are checked before any client exists, so an invalid value throws `ConfigurationError` in the default API and dies with it in the Effect API. Previously `runBot` passed only `onError`, so its commands always ran eight at a time and dropped the oldest waiting message when 256 were waiting. A command router set to `overflow: "stop"` stops the bot when its queue fills, like a handler. The commands guide shows the settings
+- ce65b67: Events that shutdown or a closed subscription discards are now logged instead of disappearing without a trace. When the client closes, each subscription that still had waiting events logs one `events.discarded` Info record with the count in `fields.discarded`. Closing a subscription with waiting events logs the same record at Debug. A draining shutdown that received events for open subscriptions or collectors logs one `events.refused` Info record with the count in `fields.refused`. All of these events are also counted in the new `diagnostics().counters.eventsDropped.closed` counter. A subscription stopped by `overflow: "stop"` keeps its existing `events.overflow` record
+- 1eeb268: A client created without `sharding` settings now keeps running when the bot outgrows one shard. Fluxer refuses a new session with close code 4011 (sharding required) once one shard would hold more than 2,500 communities, and such a client previously ended with a `ConnectionError`, so a restart or a lost session took the bot down until its configuration changed. The client now counts the bot's communities and moves to a larger plan as `sharding: "auto"` does, with the same limit of 3 moves within an hour, and logs `lifecycle.resharded` at Warn with the old and new totals. Every shard starts a new session for the move, so events sent during it are missed. While the bot stays above the limit, each start first opens a session that Fluxer refuses, which `sharding: "auto"` avoids. An explicit `totalShards`, including 1, still ends the client on 4011, and supervised children are unchanged because the supervisor always assigns an explicit plan
+- 2b86017: `MessageFlags` gains `VoiceMessage` (8192), which marks a voice message in Fluxer. Message and webhook send and edit operations still reject this bit before dispatch, because only `SuppressEmbeds` and `SuppressNotifications` are writable in this SDK
+- a4c3572: `VoiceState`, which `voiceStateUpdate` and `voiceStateSnapshot` deliver, now reports `isSelfVideoOn`, `isSelfStreaming`, `viewerStreamKeys` and `member`. The first three also appear on `CallVoiceState`, while `member` does not, because Fluxer attaches no community member in a private call. The `member` field is the same `GuildMember` shape that member events use and is omitted when Fluxer sends none. An omitted video or stream flag reads as false and omitted watched streams read as an empty list, so events from servers that do not send them still arrive. A voice state whose member data is present but malformed is rejected whole, like any other malformed field
+
+### Patch Changes
+
+- d19d3c7: Prefix commands now run only for messages a person typed, meaning the `Default` and `Reply` message types, and skip every other type. When a thread is created, Fluxer posts a notice of type 18 into the parent channel, with the thread's name as its content and the thread's creator as its author, so a thread named `!ping` ran the `!ping` command as its creator. The message `type` is now part of `MessageCore`, so every client keeps it, even with a `messageFields` selection that leaves it out. A message without a `type`, such as a hand-built test message, still counts as typed
+- ce65b67: Reading the bot's community list page by page no longer repeats one page when Fluxer returns a page that does not move past the previous one. Automatic sharding now fails at once with a discovery `ConnectionError` that says so, and the supervisor's count for `totalShards: "auto"` reports that error as the cause of its `shardCount` failure. The count previously requested the same full page again until `connection.startupTimeoutMs` passed and then failed with a `ConnectionTimeoutError`. The cache refill after restored sessions now stops at such a page and logs `lifecycle.cacheRefill` at Warn, where it previously requested the same page until the client closed without logging the refill
+- ce65b67: Log deduplication now keeps records about different shards or subscriptions apart. The same malformed dispatch on two shards previously collapsed into one record within the dedupe window, so the second shard's fault appeared only as a repeat count with the first shard's ID
+- 3c685e3: The deploying guide and the agent guide now say which `runBot` handles SIGINT and SIGTERM by default. The default API does unless `processSignals` is `false`, while the native Effect `runBot` handles them only with `processSignals: true`, because an Effect launcher such as `NodeRuntime.runMain` already interrupts the program on both signals and an interrupted program skips the drain. Runtime behavior is unchanged
+- 37612fd: The comment on the Effect API's `BotOptions` no longer calls a missing or blank token misuse that dies with `ConfigurationError`. As `runBot` already behaved and documented, the bot fails with a typed `ConfigurationError` once the other options are valid
+- 3c685e3: The `fluxerly init` command no longer refuses a folder that already has a `.gitignore`, such as the one the Create a bot guide has readers write before the quick start. It keeps that file and appends `node_modules` and `.env` only when a line is missing, leaving the rest and its line endings as they were, and a failed run still leaves the file untouched. Its next steps now link the guide that explains how to get the token and invite the bot to a community, and the quick start presents `init` before saving the token by hand. The missing-token hint no longer tells projects created by `init` to copy `.env.example`, because init already writes the `.env` file, and now says to set `FLUXER_BOT_TOKEN` in it
+- 3c685e3: The TypeScript and Effect starters from `fluxerly init` now typecheck. Node.js runs a `.ts` file by removing its types without checking them, so a type error in a generated project went unnoticed. Init now installs TypeScript 7, the version the SDK documents as required, together with the Node.js types, adds a `check` script that runs the compiler and prints the command to run it in its next steps, such as `npm run check`, `pnpm run check` or `bun run check`. The JavaScript starter is unchanged
+- 25125b0: Log records, unsafe payload records and `describeError` output now hide the user information of a URL, such as `user:password` in `https://user:password@host/path`, in both APIs. A user name without a password is hidden too, because it can be a credential on its own. The scheme, host and path stay readable, and an `@` in a path, query or fragment is left as it was
+- c927087: A `members.iterateChunks` request that would be the client's 13th member request in 11 seconds now fails at once with `MemberChunkError` reason `rateLimit` and a `retryAfterMs` wait, without being sent. Fluxer accepts 12 member requests per account in 10 seconds and drops the rest without an answer, so such a request previously waited out its whole timeout and failed with reason `timeout`. The count covers one client, or the children of one supervisor together, and other processes with the same token are not counted. Member requests sent with `gateway.send` count toward the same window from the moment the socket takes them, but are never refused
+- ae161e3: A page read whose items arrive out of ID order now fails with `details.responseField` set to `order`, as message history already did. This covers `members.fetchPage`, `guilds.fetchPage`, `messages.fetchReactionUsers` and `auditLogs.fetchPage`. Previously the error named the last field read from a valid item, such as `1.deaf`, which pointed at the wrong cause
+- 6563bf3: API comments now warn where Fluxer applies one operation as several separate writes. A failed `roles.delete` can leave the role in place after some members already lost it, and a failed `channels.delete` can leave a channel that already lost its invites, webhooks, attachments and messages. A failed overwrite change on a category, through `channels.edit`, `channels.setPermissionOverwrite` or `channels.removePermissionOverwrite`, can leave some of its channels with the old overwrites, and a retry may not reach them. The `channels.reorder` comment now says its error does not list the moves that finished, and the communities guide shows how to keep the failure while reading the actual order and parents. The announcement guide's publish helpers log the sent message's ID when publishing fails, and the guide notes that a failed publish can still leave the message published
+- ce65b67: A REST request that would wait behind a known rate-limit pause past its deadline now fails at once with reason `rateLimit` and the remaining wait in `retryAfterMs`, and logs `ratelimit.deadline`, at Warn for the first such request on a route each minute when the wait is a second or longer, and at Debug for every other such request. Previously it waited until its timeout and failed with reason `timeout`, so a long global 429 held every later request on the client for its whole deadline without saying why. The pause itself still lasts as long as Fluxer asked and ends on time, so requests sent after it go out normally
+- ce65b67: A connection lost while a REST response body arrives now fails with reason `network`, keeping the sanitized transport code as the error's cause, and a read such as `messages.fetch` or a GET through `rest.request` retries it at most twice like any other network error. Previously the operation failed with reason `response`, as if Fluxer had sent malformed data, logged a misleading `rest.responseRejected` Warn and reported the raw transport error as an SDK defect, so the read was never retried. A write whose response is cut off still fails with outcome `unknown` and is never sent again
+- 95ca9f2: The children of a supervisor now share the Fluxer limits that apply to the whole bot account, in both APIs. When one child is rate-limited globally, the parent holds the other children's REST requests until the same time, so they no longer keep sending into the pause and collect more 429 responses. Member requests from all children share the member request limit through the parent. A child that gets no answer from its parent within one second counts only its own member requests and logs `supervisor.memberRequestsLocal` at Warn once. Per-route rate limits stay with each child. A client's first REST request also no longer waits out a global pause while it discovers the Fluxer instance, so it fails at once when the pause outlasts its deadline
+- ce65b67: The supervisor now logs why before it acts. A child that misses `startupTimeoutMs` logs `supervisor.startupTimeout` at Error before the supervisor shuts down. A child force-terminated after ignoring a stop request logs `supervisor.terminated` at Warn, and one that lost its message channel and kept running logs it at Error before the supervisor shuts down. A child that does not confirm sending Identify within 5 seconds of its permission logs `supervisor.identifyUnacknowledged` at Warn before it is stopped. A failed read of a child's output, which ends forwarding of that stream while the child keeps running, logs `supervisor.outputFailed` at Warn with the error. A failed message send to a child now keeps its error in the `supervisor.spawnFailed` record
+- 0b7c49f: A supervisor with `totalShards: "auto"` now completes its move to a larger plan when a child's shard asks to start a session, or reports one it just started, while every child stops for the move. Either message previously failed the whole supervisor with reason `protocol` instead of moving. A request during the move stays unanswered until its stopping child withdraws it, and an Identify that a child sent after its permission still counts, so the larger plan's first Identify waits `identify.minimumSpacingMs` after it
+- 37612fd: The test clients of both testing entry points now see every unhandled failure, whatever their logging settings. Previously `failures()` and the shutdown check read failures from the captured log records, so a test client with a logging level above `error` or a silent `events` or `commands` category hid a broken handler, and shutdown passed. A failure repeated within the log deduplication window also appeared in `failures()` only once, and shutdown then rejected for the summary of the suppressed repeats. Each failure now appears in `failures()` once and counts for shutdown, while `logs()` still follows the logging settings
+- 0bca1c9: The `idle()` and `say` waits of both testing entry points now also wait for received events whose handler has not started yet. Previously they counted only handlers that were running, so a wait could settle between two invocations while emitted events still waited in a handler's queue, and a test then asserted before its handler ran. This happened mostly with Effect API handlers, which run on the registering caller's scheduler
+
+## 1000.0.0-rc.6
+
+### Major Changes
+
+- dd52acd: The `runBot` function now skips `messageCreate` and `messageUpdate` events written by bots, including the bot's own messages, before they reach its `events` handlers or its `commands` router, in both entry points. A reply can no longer trigger the handler that sent it, and handlers no longer need a `message.author.isBot` check.
+  The new `ignoreBots` option controls this in one place and defaults to `true`. Setting it to `false` lets both the handlers and the prefix commands see bot-authored messages. A `commands.ignoreBots` setting, when present, still decides for the prefix commands alone. A value other than a boolean is misuse. The `createTestBot` functions of both testing entry points accept the same option
+
+    Migration: A bridge, logging or moderation bot that handles messages from other bots passes `ignoreBots: false` to `runBot`. Bots built with `createClient` and `client.on` are not affected
+
+- 944c7bf: A missing or empty token no longer makes `runBot` throw in the default API or die in the Effect API. Once the other options are valid, `runBot` reports it like any failed run before creating a client: It logs the `ConfigurationError` once without a stack trace, sets `process.exitCode` to 1 unless `reportFailure` is `false`, and returns it as an Err in the default API or fails with it in the Effect API. Both `runBot` failure types now include `ConfigurationError`. Other invalid options still throw in the default API and die in the Effect API, and `createClient` still rejects a missing token as misuse
+
+    The missing-token hint now also covers projects created by `fluxerly init`: Copy `.env.example` to `.env` and set `FLUXER_BOT_TOKEN`
+
+    Migration: Code that caught the thrown `ConfigurationError` for a missing token around a default `runBot` call reads it from the returned Err instead. Effect code that handled the defect handles the typed `ConfigurationError` failure
+
+- dd52acd: The default API's `runBot` now handles SIGINT and SIGTERM unless `processSignals` is `false`. Ctrl+C or a stop from a process manager such as Docker, systemd or PM2 requests a normal stop that drains running work for `drainMs`, then the listeners are removed and the process can exit. The runner still never exits the process itself, and `processSignals: true` is no longer needed
+
+    The Effect API's `runBot` keeps process signals opt-in. A launcher such as `NodeRuntime.runMain` already interrupts the program on these signals, and a second handler would race its interruption. Set `processSignals: true` there only when nothing else handles the signals
+
+    Migration: An application that handles SIGINT or SIGTERM itself, or runs several bots in one process with its own shutdown, passes `processSignals: false` to the default `runBot`
+
+- 314ac29: Test clients in both testing entry points now answer message sends (`POST /channels/:id/messages`) and edits (`PATCH /channels/:id/messages/:id`) that no `rest.respond` registration matches. The reply is a message by the bot account that echoes the request's content, embeds, flags and tts, so a first test needs no response fixture. A registered response still wins, and other unmatched requests still receive a 404 with a `testing.unmatchedRequest` Warn
+
+    Migration: A test that relied on the 404 for an unmatched message send or edit registers that failure with `rest.respond`
+
+- 314ac29: Test waits in both testing entry points, such as `TestRoute.next` and `idle`, no longer fail after a default 2,000 ms. Without `timeoutMs` they wait until their condition holds, the test client shuts down or, in the Effect API, the wait is interrupted, so the test runner's own timeout ends a test that hangs. An explicit `timeoutMs` still fails the wait with `TestTimeoutError`
+
+    Migration: A test that expects `TestTimeoutError` from a wait without options passes `timeoutMs`
+
+### Minor Changes
+
+- c4f4f49: Add `ownerId` to the result of `client.application.fetch()` in both entry points, the decimal user ID of the account that owns the bot's application. The result keeps no other owner details, and a response without a valid owner ID now fails with `BotApplicationOperationError` and reason `"response"`.
+  `guards.ownerOnly()` called without IDs now allows only that owner. The first invocation reads the owner with `application.fetch`, and the guard keeps the ID for the client's lifetime. A failed read keeps nothing and fails the command, and the next invocation reads again. Explicit owner IDs work as before, and an `undefined` argument still throws `ConfigurationError`
+- 7755411: The `client.cache.clear(kind)` method now releases a single cache kind, and the new `client.cache.delete(kind, key)` removes one entry by the key format that `cache.onChange` reports, such as `guildId:userId` for members or `channelId:messageId` for messages. Both work in the default and Effect APIs, run synchronously and report a `clear` or `delete` change to `cache.onChange` listeners. Reads already in flight cannot restore what was removed. An invalid kind or key throws `ConfigurationError`, whose `field` is `kind` or the new value `key`
+- c4f4f49: Add `fluxerly init`, which writes a JavaScript, TypeScript or Effect starter bot into the current folder. In a terminal it asks which starter to write, with JavaScript as the default. The `--template js|ts|effect` option chooses without asking, and without a terminal or the option it writes the JavaScript starter. An unknown template prints the usage, writes nothing and exits with status 1.
+  Each starter writes a `package.json` with `start` and `test` scripts that run without a build step, the bot with the starter's `!ping` handler, a test that talks to the bot through `say` from `@neontechspace/fluxerly/testing` or, for Effect, `@neontechspace/fluxerly/effect/testing`, `.env.example` and its copy `.env`, a `.gitignore` for `.env` and `node_modules`, and the `AGENTS.md` that `fluxerly agents` creates. The TypeScript and Effect starters write `bot.ts` and `bot.test.ts`, which Node.js runs directly, and a strict `tsconfig.json` for editors.
+  It replaces no file. When any of these files exists, it lists them and writes nothing. An existing `.env` is kept and does not stop it.
+  It then installs the SDK, Effect for the Effect starter and the Node.js types for the TypeScript starters with the package manager that ran it, npm, pnpm or Bun, and prints the next steps with that manager's test and start commands. The `--no-install` option skips the install and prints the install commands instead, for offline or CI use. A failed install keeps the written files, prints the install commands and exits with status 1
+- 314ac29: Add `fileSessionStore(directory)` to both entry points, a built-in `SessionStore` for `sharding.sessions` that keeps one JSON file per shard. Saves write a temporary file with mode 0600, flush it and rename it over the shard's file, so a crash never leaves a partial snapshot. A missing file loads as no snapshot, and a corrupt file rejects without quoting its contents, so the session ID never appears in logs
+- 314ac29: Add `client.logging.configure({ level, categories })`, which changes a running client's log level and per-category levels with the same validation as the creation settings. Omitted settings return to their defaults, and the `debug` setting and `FLUXERLY_DEBUG` still apply. The Effect API has the same member, because its clients apply these levels before records reach the Effect logger and the two clients keep the same members. The new `LogLevelSettings` type describes the accepted settings
+- d3a22bc: A missing-permission rejection now names the permissions the failed operation needs, in both entry points. When Fluxer answers HTTP 403 with `MISSING_PERMISSIONS`, guild, channel, message, send and webhook operation errors list them in `details.requiredPermissions` as `Permissions` keys, such as `["ViewChannel", "ManageChannels"]`, and the hint names them, as in "The bot needs View Channel and Manage Channels for this operation". The hint also says where to grant them and adds other checks behind the same rejection, such as role hierarchy for moderation or Manage Roles when a channel edit changes permission overwrites. Fluxer does not report which permission is missing, so the bot may already have some of the listed ones.
+  The change covers 72 operations, including channel, webhook, invite, role, member moderation, message, pin and reaction operations. Operations whose checks depend on data the SDK does not have, such as editing or deleting an emoji or sticker, and `rest.request` keep a general hint without `details.requiredPermissions`. Operations without an entry that previously received the generic message-sending or moderation hint now receive the general hint instead
+- 34b3ab0: Reaction pages show several pages in one message that people flip with ◀ and ▶ reactions, because Fluxer has no buttons. Call `ctx.paginate(pages)` in a prefix command, where only the command's author can flip by default, or `client.messages.paginate(channelId, pages, { users })` elsewhere, in both the default and Effect APIs. Pages are strings or `{ content, embeds }` objects. Adding or removing an arrow both count as a click, so the bot needs only Add Reactions and Read Message History, and `removeClicks: true` instead removes each click, which needs Manage Messages. Listening stops after `idleMs` (default 60,000) without a click and at most after `timeoutMs` (default 300,000), then the bot removes its own arrows and the current page stays. The result reports `idle`, `timeout` or `singlePage`, and failures and cancellation use the usual failure channel. The new `ctx.sendHelp()` sends the router's help as one message, or as reaction pages when it needs more than one page. So that pages started after connecting receive clicks, `gateway.ignoredEvents: "auto"` now always keeps `MESSAGE_REACTION_ADD` and `MESSAGE_REACTION_REMOVE`
+- 7755411: Every resource cache kind now accepts a `maxAgeMs` callback, as the `messages` cache already did, so an application can choose per community, channel or other snapshot what gets cached. The callback receives the frozen snapshot and returns a duration in milliseconds, `null` for no age limit or `0` to skip retention, for example `channels: { maxAgeMs: (channel) => (watched.has(channel.guildId) ? null : 0) }`. A callback that throws or returns an invalid value removes the older copy and is reported as a `cache` failure to the client-level `onError`, or logged at Error, without changing the event or REST result. `ResourceCacheSettings` now takes the snapshot type as a type parameter, and `ClientOptions.cache` passes the matching type for each kind
+- dd52acd: The default API's `runBot` passes its `setup` callback a second argument, `{ signal }`. The `AbortSignal` aborts when the bot begins stopping for any reason, including a requested stop before its drain, a failure and a stop while setup is still running. Pass it to SDK operations, or clear timers and end other background work started in `setup` when it aborts, so that work ends with the bot. The runner does not track or await such work.
+  In the default `createTestBot`, the signal aborts when the test bot's shutdown starts
+
+    The Effect API's `setup` is unchanged. It already runs in the bot's Scope, so its finalizers run and fibers it forks into that Scope are interrupted when the bot stops
+
+- 314ac29: Add `say(content, options?)` to the test bot of both testing entry points. It delivers a message from a human user, waits until the bot settles as `idle` does, and returns the messages the bot sent in response in wire shape, or an empty list when it sent nothing. The default `createTestBot` now returns the new `TestBot` type, and the new `TestSayOptions` type adds message overrides to the wait options
+- dd52acd: Add `client.users.getSelf()` to both entry points, a local lookup of the bot's own public account as the gateway's READY reported it, without a request. It returns the `User` directly in the default API and a never-failing Effect in the Effect API, like `users.get`.
+  The result is undefined until the client's first READY, and also while no READY has carried a complete account. A later READY replaces it only when it carries a complete account, and the value remains available after the client stops. Other user updates do not change it, so use `users.fetchSelf` for a current remote snapshot
+
+### Patch Changes
+
+- c3bbcf9: Cache kinds with a `maxAgeMs` expiry now release a replaced or removed snapshot as soon as the cache drops it. Previously the expiry schedule kept such snapshots in memory until their original deadline came up or enough replacements accumulated to rebuild the schedule, so frequently updated entries of every cache kind, from `messages` to `emojis` and `stickers`, could hold more memory than the cache limits suggested
+
+## 1000.0.0-rc.5
+
+### Patch Changes
+
+- f1aebe9: The coding agent guide's list of APIs that Fluxerly does not have, such as `client.login` and message methods, now stands on its own without naming another library. Its rules section, which `fluxerly agents` copies into an application's `AGENTS.md`, keeps the instruction to use only declared methods. Run the command again to refresh an existing section
+- 6655b27: The `AGENTS.md` section that `fluxerly agents` writes now records `npx --no fluxerly agents` or `bunx --no-install fluxerly agents` as its refresh command, and pnpm projects keep `pnpm exec fluxerly agents`. These forms never install a package automatically, because the unscoped `fluxerly` name on npm is not this SDK, so the SDK must already be installed in the project. Run the command again to update an existing section
+- f0e7941: The `CacheChange` example now tracks cached keys, so replaced entries and cleared kinds stay accurate. The `ResourceCacheSettings` description now names the one preload, the refill after a shard resumes a stored session, which `sharding.refillCaches` controls
+- 2b9efdf: Cancelling a connect while a failed discovery response is being cleaned up again keeps the discovery `ConnectionError` alongside the interruption and the cleanup defect. The native Cause holds all three, and the default API's `SdkDefect` lists them as reasons. With Effect 4.0.1, the discovery failure had been dropped
+- 06be6c0: The hosted `links.installation` URL now starts at Fluxer's API authorization route, `https://api.fluxer.app/v1/oauth2/authorize`, which redirects to the hosted installation page. The previous `https://fluxer.app/oauth2/authorize` URL showed a page-not-found error. Installation links for a discovered instance still open that instance's web app directly
+- 9df8363: Update the WebSocket gateway transport dependency from ws 8.21.3 to 8.22.0
+
+## 1000.0.0-rc.4
+
+### Major Changes
+
+- abb5d3f: The coding agent guide moved from `consumer/AGENTS.md` to `agents/AGENTS.md` in the installed package. An application's `AGENTS.md` section from an earlier `fluxerly agents` run points at the old path, so run `npx fluxerly agents`, `pnpm exec fluxerly agents` or `bunx fluxerly agents` again after updating
+
+    The README now links the documentation's `llms.txt` for agents that read web pages, and its Effect section describes the accepted Effect 4 range instead of an exact version
+
+- abb5d3f: Add `ChannelType.Announcement` (5), `GuildAnnouncementChannel`, `GuildTextChannelBase` and `AnnouncementChannelCreate` to both APIs. Announcement channels now decode into their own shape instead of `GuildUnknownChannel`, so exhaustive channel-type switches need an announcement case
+
+    Allow `ChannelEdit.type` to convert between text (0) and announcement (5), including a type-only patch. A text channel that follows an announcement channel cannot become one. Delete its follower webhooks first. Conversion to text queues asynchronous follower webhook removal, and a `channelUpdate` event replaces the cached channel with its new type
+
+- abb5d3f: Require Effect `^4.0.0` instead of exactly `4.0.0-rc.117`. The SDK is tested against `4.0.0`, the first stable release. Effect is a required peer, so applications that use only the default API must update it too. Update the application's Effect dependency and lockfile together with the SDK
+- abb5d3f: Received `message.messageReference` now has its own type, `MessageContextReference`, separate from the `MessageReference` that message operations take in both APIs. Its `channelId` is required and `id` is optional. Channel-follow notices, which have no message ID, now decode in events and REST reads, including minimal message field selections. A present but malformed ID still fails
+
+    This is a breaking type change: Check that the received context has an ID and build a `MessageReference` from both fields before passing it to fetch, reply or another message operation
+
+    Add `MessageType.ChannelFollowAdd` and the received-only flags `MessageFlags.Crossposted`, `MessageFlags.IsCrosspost` and `MessageFlags.SourceMessageDeleted`. Fluxer sets these publishing flags itself. Sending and editing continue to accept only `SuppressEmbeds` and `SuppressNotifications`, with other flags rejected before sending the request
+
+- abb5d3f: Remove the retired phone-verification level. The `GuildVerificationLevels.VeryHigh` constant is gone and guild edits reject level 4 before the request. Level 4 received from older instances decodes as `High` (3), matching Fluxer. Other out-of-range levels still fail decoding. The `ApiProviderCode` type drops `GUILD_PHONE_VERIFICATION_REQUIRED`, and an unrecognized code stays in `details.providerCode`
+- abb5d3f: Message search no longer fails when a result comes from an unnamed group DM, in both entry points. Fluxer now sends `name: null` for such channels, so `MessageSearchChannel.name` is now `string | null` when present, and code that reads it must handle null
+- abb5d3f: Add `WebhookType` and the `IncomingWebhook`, `ChannelFollowerWebhook` and `UnknownWebhook` shapes to both APIs. Received metadata now requires a kind and preserves future numeric kinds as `type: "unknown"` with `rawType`
+
+    Bot clients can rename, move or delete follower webhooks but cannot change their avatars. Deleting a follower webhook stops its channel following the source. Optional frozen `sourceGuild` and `sourceChannel` snapshots reflect source visibility to the original creator, and their absence does not prove deletion
+
+    Webhook metadata no longer carries tokens. The `CreatedWebhook.webhook` field and webhook-client `fetch` and `edit` results now use `IncomingWebhook`, and creation requires a valid incoming token before returning credentials
+
+### Minor Changes
+
+- abb5d3f: Add `channels.follow`, `channels.fetchFollowerStats`, `messages.publish` and `messages.fetchCrosspostSource` to both APIs for announcement-channel follows, follower counts, message publishing and public source-community lookups. Follow results identify the source channel and the created follower webhook, which can be deleted to stop following. After publishing, the cached source is updated and copies enter the cache only when they arrive. After an unknown outcome, the SDK drops the source from the cache and does not publish again
+
+    The `errors.apiCode` helper now names announcement, follow, conversion, publishing and published-message editing rejections, such as `invalidFollowTargetChannel`
+
+- abb5d3f: Add the `guildHealthUpdate` event with a frozen `GuildHealthUpdate` payload, `{ guildId, degraded }`, in both entry points. Fluxer sends it when the server hosting a community starts or stops lagging. It does not mean that the bot is disconnected or that the community is unavailable, and the SDK neither reconnects nor clears caches because of it
+- abb5d3f: `messages.delete`, `messages.deleteMany`, `messages.pin` and `messages.unpin` accept an `auditReason` option in both entry points, which Fluxer now records in the community's audit log
+- abb5d3f: Webhook message sends, replies and forwards accept an optional `nonce` in both entry points. For five minutes, Fluxer then tries to suppress another send from the same webhook with the same nonce, which helps after a lost response but does not guarantee exactly-once delivery. Webhook sends without a nonce send none, and a forward that sets a nonce both on the message and on its source fails before the request
+
+### Patch Changes
+
+- abb5d3f: API comments now explain recent Fluxer behavior. Member search can fail with `twoFactorRequired` in a community that requires two-factor authentication for moderators, even without filters. The older `nsfw: false` channel field restores inheritance on create and edit, and `nsfwOverride: false` marks a channel as not adult-only. Message search in an age-restricted community can include adult content even when `includeNsfw` is false. Member queries over the gateway match the start of a nickname, global name or username. A rejected bot token or OAuth grant can come from the owning account's standing, which a new token does not fix
+- abb5d3f: Embed media can reference any image or video attachment through `attachment://`, following Fluxer's file-type detection, instead of only PNG, JPEG, WebP and GIF files, in both entry points
+- abb5d3f: A successful emoji or sticker metadata or source lookup no longer pauses unrelated requests such as message sends. Fluxer limits these lookups in one bucket per bot across all emojis or stickers, and the SDK now tracks them that way, so running out of that bucket still delays the next lookup of any emoji or sticker
+- abb5d3f: Gateway member requests, presence member selection and member count requests now reject IDs above 9223372036854775807 before sending, in both entry points. Fluxer ignores such IDs, so a request could wait until its timeout, and an explicit member list made only of such IDs could turn into a request for all members
+- abb5d3f: When the SDK plans to resume a gateway session, it now closes the connection with code 4000 instead of 1000, in both entry points. Fluxer ends a session when the client closes with 1000 or 1001, so a reconnect after a missed heartbeat or a restart from a `SessionStore` had to identify again and lost the events sent in between. A final shutdown without a `SessionStore` still closes with 1000
+- abb5d3f: With the users or direct-message cache enabled, a member update now removes that member's cached user and clears cached direct-message channels before handlers run, in both entry points. Fluxer reports username and other account changes to bots through member updates, so cached users and DM recipients could show the old identity. Automatic gateway event selection keeps member updates for these caches even without a `guildMemberUpdate` handler. Later reads fetch fresh snapshots, and snapshots already returned stay unchanged
+
+## 1000.0.0-rc.3
+
+### Patch Changes
+
+- 4ce40a1: Release event handler slots and partition keys after a synchronous handler or middleware throw, including when middleware calls next. The failure is reported once and the invocation emits its failure observation without blocking later events
+
+    Keep guards returning false silent under automatic rejection feedback, including the runBot reply default. Rejection counters, Debug records and custom onReject callbacks still receive the denial, while guards returning an explicit deny reason retain their reply
+
+    Include the matched command's canonical name and reported failure in each command router observation, with one observation spanning event and command middleware. Interrupted commands report cancelled, and messages with no command match remain unnamed observations. Command failure metrics use the same name and command spans cover middleware, guards and execution
+
+- 4ce40a1: Retain the gateway command pacing history across Resume within a running client, so reconnecting cannot restart a full send budget while Fluxer still counts the previous session's commands. A fresh Identify starts a new budget
+
+    Withdraw unsent community-count, channel-member-count and member-chunk requests when cancelled or timed out, preventing stale requests from being sent later. Bound internal waiting commands and report queue pressure through the existing busy failures
+
+    Release a cancelled, unsent `gateway.send` command's local queue capacity immediately, so replacement work can wait instead of failing as busy until the pacing window opens. Queued commands are still abandoned on disconnect rather than replayed
+
+    Coalesce outgoing status changes to one unsent update per shard, keeping only the latest intent while the gateway send budget is full. Measure the four-second interval from actual transmission, and avoid retaining timers that already fired during scheduling
+
+    Replace queued member-presence selections with the latest IDs and withdraw an unsent selection when cleared. Start member-selection spacing at actual transmission, so pacing delays cannot flush obsolete selections or clears together
+
+- 4ce40a1: Match a handler's failed HTTP 401 or 403 request by error identity, including wrapped causes, rather than status and Fluxer code. Unknown codes no longer cause duplicate rejection logs, and a handled request keeps its Warn when a different request with the same code fails the handler. A rejection is logged once unless the handler fails more than one second later, after its Warn has already appeared
+
+    Keep credential-key values masked in unsafe REST payload logging when a response exceeds the 65,536-byte read limit, including passwords and cookies in truncated JSON text. Invite-shaped objects in truncated lists also keep their access codes masked, while unrelated diagnostic and provider codes stay readable
+
+    Mask credential patterns in application error names and string codes in log records, failure descriptions, describeError and native Effect log causes and annotations. SDK error JSON also masks names in summarized causes, without changing the original error or its cause
+
+    List Debug for handled failure reports in the error and log code catalogue, alongside the existing unhandled failure levels
+
+- 4ce40a1: Classify failures from OAuth identity, community and connection reads and token introspection as reads in their messages, hints and details, so `errors.isRetryable` can identify eligible transient failures. Code exchange, refresh and revoke calls with unknown outcomes remain unsafe to repeat, and OAuth requests are not retried automatically
+
+    Preserve sanitized transport causes, including safe codes such as `ECONNRESET`, when discovery failures become resource errors and during OAuth calls and buffered or streamed attachment downloads. Raw transport errors and their private text are not retained
+
+    Retain unknown uppercase Fluxer error codes in `details.providerCode` for HTTP 429 failures, including when the required wait exceeds the operation deadline
+
+    Reject raw REST paths whose reserved `/v1` prefix or token-authenticated webhook route names use percent-encoded unreserved characters. Keep route checks case-sensitive and do not decode reserved characters
+
+    Compare pin page ordering and pagination progress at full fractional timestamp precision, with timezone offsets normalized by instant. Equal timestamps still remain equal
+
+    Reject audit message-deletion durations whose milliseconds fall outside the safe integer range, rather than projecting an overflowed value such as `Infinity`, and round other durations to whole milliseconds. The same validation applies to REST audit pages and gateway audit events
+
+- 4ce40a1: Clear a shard's cached communities and dependent resources when partial replay of a saved session falls back to Identify. Clear reads cached during the outage again at `READY`, while retaining replayed observations after a successful Resume
+
+    Make the in-memory test gateway enforce the session's Identify event filtering, including message mention exceptions and filtering retained across Resume. Emitting a dispatch Fluxer would suppress now fails with `ConfigurationError` instead of making an unrealistic test pass
+
+    Keep `MESSAGE_REACTION_ADD` available under automatic filtering when a `messageReactionAddMany` handler is registered, because Fluxer generates reaction batches only from unsuppressed additions. Test reaction batches use the same source filter, including when an explicit list ignores only the generated batch name
+
+- 4ce40a1: Effect supervised children let running handlers, queued handler events and REST requests finish within the parent's drain allowance before closing when the parent stops them, including a move to a larger automatic shard plan. Failure still stops running work without draining
+
+    Supervisor child-run options and default readiness-wait options reject unsupported keys before waiting for the parent or observing readiness. Misspelled keys include a suggested supported name, as do assignment and Identify options
+
+    Both `runBot` entry points mask the normalized token in failure reports before a client exists, including tokens surrounded by whitespace and matching quotes
+
+    Effect `runBot` retains readable token, logging and `reportFailure` settings when an option getter throws. A throwing getter no longer discards a configured log sink, token masking or `reportFailure: false`
+
+## 1000.0.0-rc.2
+
+### Major Changes
+
+- 2d263aa: Fluxerly needs Node.js 24.15 or newer, up from 24.11, because that is the oldest Node 24 release npm 12 supports
+
+### Minor Changes
+
+- a47b104: The package installs a `fluxerly` command. Running `npx fluxerly agents`, `pnpm exec fluxerly agents` or `bunx fluxerly agents` in an application's folder copies the SDK's rules for coding agents into its `AGENTS.md`, which coding agents read automatically, and records the installed SDK version. Running it again replaces only that section, and a broken section marker stops the command without changing the file
+
+    The consumer guide at `consumer/AGENTS.md` starts with those rules, includes the starter bot and a Result check, and lists the differences from discord.js. The package's entry points name the guide in their overview
+
+## 1000.0.0-rc.1
+
+### Major Changes
+
+- 7733b23: Make request errors say what to change. Rejections carry a `hint` for missing permissions or access, naming what a message send or a moderation action needs, unknown IDs, rejected tokens, invalid form fields, refused direct messages, two-factor requirements, slowmode, resource limits and temporary Fluxer failures, with a fallback by HTTP status for 401, 403 and 404.
+  A rejected credential gets a hint for the credential the request sent: The webhook ID and token for a webhook client, the OAuth client ID and secret for an `invalid_client` error or a 401 from a code exchange, refresh, revocation or introspection, and the user's access token for a 401 from `fetchIdentity`, `fetchGuilds` or `fetchConnections`.
+  Operation error messages lead with the failed operation and Fluxer's answer, for example `Message send failed: Fluxer reports that the bot lacks a required permission (MISSING_PERMISSIONS, HTTP 403)`, and explanations name Fluxer instead of "the provider"
+
+    Keep Fluxer error codes that this SDK version does not describe yet. An uppercase code of up to 64 characters is recorded as `details.providerCode` and named in the message while `apiError` stays `null`, and an unrecognized validation code stays in `apiError.validationErrors` with its field path and a generic explanation. `OAuthOperationError` and `MessageCleanupError` keep unrecognized codes the same way.
+    A response that does not match the expected shape names the failing field or check, such as `type` or `channelMismatch`, in `details.responseField` and logs a `rest.responseRejected` Warn. A message cleanup that fails in a history read or batch request copies that step's `details.responseField`. A `client.rest.request` route has no expected shape, so its unusable response is only returned in the Result.
+    The `members.fetchCanManage` and `permissions.fetch` checks keep these facts and the failed step's error as `cause` when they report a failure under their own operation name.
+    `OperationErrorOptions` and the `MessageError` and `MessageCleanupError` constructors accept `providerCode` and `responseField`, and the `OAuthOperationError` constructor accepts `providerCode`
+
+    Log HTTP 401 and 403 rejections as a `rest.rejected` Warn with the Fluxer code and hint, even when the application handles the Result. When an event handler or command fails with the rejection and no `onError` hook receives the failure, the handler's failure record reports it instead, so one failed reply is logged once. Webhook clients and OAuth clients accept the same `logging` option as a client, so their rejected webhook tokens and OAuth client credentials are logged the same way. A rejected OAuth user access token concerns one user and is only returned. Like other Warn records, identical repeats within one minute are printed once by default, so a rejection that keeps happening shows about once a minute with a repeat count. Other client rejections are logged at Debug, and `rest.request` Debug records carry the Fluxer code in `fields.apiError`
+
+    A `ConfigurationError` thrown by the default `createClient` or `runBot` points at the caller's line
+
+    Migration: `ApiValidationErrorDetail.providerCode` is now `ApiValidationCode | (string & {})`, so code that assigns it to an `ApiValidationCode` must narrow it first.
+    Operation error message text changed, so match on `code`, `reason` and `apiError` rather than on messages
+
+- 7733b23: Ban durations are milliseconds, like member timeouts, command cooldowns and the `duration` command argument. The `BanInput` fields are now `durationMs`, 0 for a permanent ban or 60,000 through 63,072,000,000 for a temporary one, and `deleteMessagesMs`, 0 through 604,800,000. Both must be whole seconds and are sent to Fluxer in seconds. A rejected ban input names the failing field, such as `input.durationMs`, and states its whole-second range
+
+    Audit-log entries report the message deletion of a member ban in milliseconds too, so the `AuditLogOptions` field `deleteMessageSeconds` is now `deleteMessagesMs`, in both API styles and in `guildAuditLogEntryCreate` events
+
+    A `duration` command argument accepts `wholeSeconds: true`, which rejects a value with a millisecond part such as `1m500ms` and adds "in whole seconds" to the rejection reply. With `wholeSeconds: true`, `min: 60_000` and `max: 63_072_000_000`, the argument's value can be passed to `durationMs` unchanged, and a moderator's out-of-range value gets the usage reply instead of a failed ban
+
+    Migration:
+
+    - Replace `durationSeconds: n` with `durationMs: n * 1000` and `deleteMessageSeconds: n` with `deleteMessagesMs: n * 1000` in ban input
+    - Replace `options.deleteMessageSeconds` with `options.deleteMessagesMs` on audit-log entries, and divide by 1000 where seconds are still needed
+
+- 7733b23: The command argument types that pick from a fixed list are renamed to `userChoice`, `channelChoice` and `roleChoice`, next to `choice`, so the names `user`, `channel` and `role` no longer suggest a lookup in the message's community. They still select one of up to 100 `candidates` given at registration.
+  The old names now fail registration with `ConfigurationError`, whose hint names `{ type: "id", mention }` for any ID or mention, `{ type: "member" }` for a member of the message's community when the old type was `user`, and the new list form
+
+    Migration: Replace `type: "user"`, `"channel"` and `"role"` with `"userChoice"`, `"channelChoice"` and `"roleChoice"` in argument schemas, and in code that reads `CommandArgumentMetadata.type`
+
+- 7733b23: Rename client members so each name states what it does and each concept uses one word across both entry points.
+  Deleting a bot's own history now requires an explicit `{ confirm: true }` option, checked by TypeScript and again at runtime, and a missing confirmation fails with reason `input` before any request.
+  Subscriptions, collectors and state observers all end with `close()`, and a collector's `result()` returns its final collection.
+  `MessageError` reports `outcome` with the same `notDispatched`, `rejected` and `unknown` values as other operation errors, so an API rejection is now distinguishable from a send that never started
+
+    Migration:
+
+    - Replace `guilds.deleteMine(guildId)` with `guilds.deleteOwnMessages(guildId, { confirm: true })`, and `messages.deleteMine(channelId)` with `messages.deleteOwnMessages(channelId, { confirm: true })`. The required `confirm` option joins the existing timeout and signal options. The operation IDs change from `guilds.deleteMine` and `deleteMine` to `guilds.deleteOwnMessages` and `deleteOwnMessages`
+    - Call `members.ban`, `members.unban` and `members.fetchBans` instead of `guilds.ban`, `guilds.unban` and `guilds.fetchBans`, with the same parameter order. Their operation IDs change from `guilds.ban`, `guilds.unban` and `guilds.fetchBans` to `members.ban`, `members.unban` and `members.fetchBans`
+    - Rename `invites.fetchChannel` and `invites.fetchGuild` to `invites.fetchForChannel` and `invites.fetchForGuild`, and `webhooks.fetchChannel` and `webhooks.fetchGuild` to `webhooks.fetchForChannel` and `webhooks.fetchForGuild`. Their operation IDs change to the same new names, so code matching `error.operation` on `invites.fetchChannel`, `invites.fetchGuild`, `webhooks.fetchChannel` or `webhooks.fetchGuild` needs updating
+    - Replace `application.fetchCurrent()` with `application.fetch()`. The operation ID changes from `application.fetchCurrent` to `application.fetch`
+    - Replace `members.fetchHierarchyCheck(target)` with `members.fetchCanManage(target)`. The operation ID changes from `members.fetchHierarchyCheck` to `members.fetchCanManage`
+    - Replace `members.setMute(target, true)` with `members.setMute(target, { muted: true })`, and `members.setDeaf(target, true)` with `members.setDeaf(target, { deafened: true })`. The exported `VoiceMuteInput` and `VoiceDeafenInput` types describe these inputs
+    - Call `close()` instead of `subscription.unsubscribe()` on subscriptions, and instead of `collector.stop()` on message and reaction collectors, in both entry points
+    - Call a collector's `result()` instead of its `waitForClose()`. The operation IDs change from `collector.waitForClose` and `reactionCollector.waitForClose` to `collector.result` and `reactionCollector.result`
+    - The default `client.observeState(listener)` returns a `StateObserver` instead of a function. Call `observer.close()` where the returned function was called
+    - A malformed target passed to `client.messages.get` throws `MessageOperationError` with operation `messages.get` instead of `get`, matching `users.get` and `channels.get`, and an `SdkDefect` from that lookup also names `messages.get`. Code that compared a lookup failure's `operation` with `"get"` compares it with `"messages.get"` instead
+    - Replace `client.events(event)` with `client.subscribe(event)`, which no longer shares a name with the `runBot` events option. The operation ID changes from `events` to `subscribe`
+    - Read `MessageError.outcome` instead of `MessageError.delivery`. Replace `"notSent"` checks with `outcome !== "unknown"`, or distinguish `"notDispatched"` from `"rejected"`, and pass `outcome` instead of `delivery` when constructing the error
+
+- 7733b23: The `EmbedBuilder.field` method takes its display setting as a named option, following the rule that settings are option objects rather than boolean positionals. The new `EmbedFieldOptions` type describes it
+
+    Migration: Replace `field(name, value, true)` with `field(name, value, { inline: true })`, and drop a `false` third argument. A leftover boolean or other non-object third argument throws `ConfigurationError` with a hint naming `{ inline: true }`
+
+- 7733b23: Base every SDK error on the exported `FluxerlyError` with a stable `code`, an optional fix `hint`, frozen `details`, a standard `cause` and `toJSON()`.
+  Errors now keep the application or transport failure that caused them. A network failure is kept as a cause that records only the transport error code, such as `ECONNRESET`, never the transport message. API validation failures include the sanitized field path with each error code.
+  Messages and `toJSON()` output mask credential patterns, including application text quoted by `ApplicationError` and `SdkDefect`, while `cause` keeps the original value.
+  Masking applies to error text, `describeError` output and log records. It covers bare Fluxer bot tokens of the form `<application_id>.<secret>`, keeping the application ID. It also covers the value after an assignment to a key ending in `token` or `secret`, such as `FLUXER_BOT_TOKEN=`, the value after a quoted key such as `"botToken":`, and a credential-shaped value after an unquoted key and a colon, so prose such as `Missing token: check the configuration` stays readable
+
+    Add `describeError(error)` for readable output with the code, hint, safe details and cause chain. It collapses stack frames inside the SDK and Effect into one line and prints no frames for expected SDK errors other than `ConfigurationError` and `SdkDefect`. It also accepts an Effect Cause and describes each failure, defect and interruption, so native programs can pass `exit.cause` directly. A thrown value that is not an Error is named `Non-Error value (string)` and similar.
+    Add `errors` with `apiCode`, `isRetryable` and `match`. The `errors.apiCode(error)` helper returns the recognized Fluxer rejection category of an operation error, such as `"missingPermissions"` or `"twoFactorRequired"`, and undefined for every other value, so `errors.apiCode(result.error) === "missingPermissions"` works on any error of an operation's Result without checking its `_tag` first.
+    A read that failed after it was sent records `details.read`, so `errors.isRetryable` treats it as safe to repeat, unlike a write with an unknown outcome.
+    Add `ApplicationError` for failures raised by application callbacks such as a `runBot` `setup` or `commands` callback or a `keepTyping` task
+
+    Migration: `MessageOperationError`, `ChannelOperationError`, `GuildOperationError`, `UserOperationError`, `WebhookOperationError`, `BotApplicationOperationError`, `AttachmentRefreshError`, `MessageCleanupError`, `MessageError` and `OAuthOperationError` now take one options object, described by `OperationErrorOptions` for the resource operation errors.
+    Replace `new AttachmentDownloadError(reason, status, inputValidation)` with `new AttachmentDownloadError({ reason, status, inputValidation, cause })`. `CountOperationError`, `MemberChunkError`, `PaginationError` and `PresenceError` change the same way, taking `{ operation, reason, inputValidation, cause }`, `{ reason, retryAfterMs, inputValidation, cause }`, `{ operation, reason, inputValidation, cause }` and `{ reason, inputValidation, cause }`. `PresenceError` no longer defaults its reason to `input`, and omitted status, retry and input detail values still default to null.
+    `ConfigurationError`, `ConnectionError`, `HelperError`, `AssetUrlError`, `CollectorError`, `EventWaitError`, `SupervisorError` and `SupervisorChildError` accept a trailing options object with `cause`. `ConfigurationError` also accepts `hint` there, and `ConnectionError` accepts `hint` and `details`
+
+- 7733b23: Report every failure that has no returned result, including throwing event handlers, failed commands, collector callbacks and filters, cleanup progress callbacks, message cache callbacks, state observers and overflowing subscriptions.
+  Each failure goes to the subscription's `onError`, then the client's new `onError` option, or is logged at Error with its full message, stack and cause chain.
+  A `FailureReport` carries the original thrown value unchanged, its kind, and the event, command, subscription and message IDs involved, and `describe()` returns readable text. Native reports also keep the Effect cause
+
+    A failure only queues its report. Each client, subscription and command router hook receives reports one at a time in order through its own bounded queue, so a slow hook never holds up handlers.
+    Later reports are logged and counted instead, and a failing hook is logged together with the original failure without being retried.
+    Shutdown interrupts running hooks without waiting for one that never finishes, and logs the interrupted and queued reports.
+    Command routers now report failures with the command name, including failed `onUnmatched` callbacks and parsers, and rejected or unmatched commands are logged at Debug and counted
+
+    Migration: `HandlerErrorReport` is replaced by `FailureReport`, and the message cache `onError` option and `CachePolicyErrorReport` are removed in favour of the client's `onError`.
+    A message cleanup `onProgress` callback that throws, rejects or returns an Err is now reported to `onError` with kind `progress` instead of being ignored, and cleanup continues. The callback stays synchronous, so a returned Effect is not run and is reported as a `TypeError`.
+    `SdkDefect` now keeps each fault's original value in `reasons` and its first fault as `cause`. A fault from an application callback, or a throw while the SDK reads caller-supplied options or input, such as a property getter or a caller AbortSignal's `aborted` getter or listener methods, has origin `application` and code `application.defect`. Other faults, including faults in SDK work around those reads, have code `sdk.defect`
+
+- 7733b23: Invalid data from the Fluxer gateway, such as a frame that is not JSON, a second HELLO or READY, or a sequence that goes backwards, no longer ends the client at once. The shard logs the failure with `fields.reason` set to `protocol` and reconnects with a new session. Three such failures in a row without a healthy connection between them end the shard with a protocol `ConnectionError` as before. Oversized frames, invalid UTF-8, binary frames and `gateway: { onMalformedDispatch: "terminate" }` still end the shard without retrying
+
+    Migration: A single invalid gateway message no longer ends `client.run`, because the shard reconnects. The protocol `ConnectionError` now arrives only after three such failures in a row
+
+- 7733b23: The `runBot` function lets running work finish before it stops, in both entry points.
+  When its `signal` aborts, or SIGINT or SIGTERM arrives with `processSignals: true`, the bot stops accepting new events and gives running handlers and commands, events already waiting for them and their REST requests up to 5,000 ms to finish. Then it shuts down as before and cancels whatever is left. The new `drainMs` option changes that time. A stop caused by a failure still shuts down at once. Sending the same process signal again ends the process at once with the default Node.js behavior
+
+    Add `ShutdownOptions` with `drainMs` to `client.shutdown(options)` in both entry points for the same drain outside `runBot`. Without options, `shutdown()` still cancels running handlers at once.
+    During a drain the connection state stays as it was, new subscriptions and event waits start closed, and handlers can still send requests. The drain ends as soon as no work is left, logging `lifecycle.drained`. When the time runs out, a `lifecycle.drainTimedOut` Warn record names how many handlers, events and requests were cut off. A `lifecycle.draining` Info record marks the start.
+    An invalid `drainMs` throws `ConfigurationError` in the default API and dies with it in the Effect API
+
+    Supervised children drain the same way when the supervisor stops them, for up to the supervisor's `shutdownTimeoutMs` minus one second, which keeps that second for closing the connection. A child whose client stopped on its own is not drained
+
+    Migration: To keep cancelling running handlers as soon as the bot is asked to stop, pass `drainMs: 0` to `runBot`
+
+- 7733b23: Cache entries for communities, which Fluxer calls guilds, and for members, roles, emojis, stickers and channels now survive a successful Resume, because Fluxer replays every missed event on Resume or refuses the session. They are cleared when a shard has to start a new session. Users, direct messages and messages are still cleared on every lost connection
+
+    A `guildCreate` event now fills the enabled role, emoji, sticker and channel caches from its snapshot and replaces that community's earlier entries, so a new session rebuilds them without REST requests. Members are not filled, because the snapshot lists only a few
+
+    Migration: Code that relied on community caches being empty after a reconnect should call `guilds.fetch` and the other fetch methods when it needs current state, since a cached entry now stays across a Resume
+
+- 7733b23: Skip a known gateway event that fails validation instead of ending the client. The SDK logs `gateway.dispatchRejected` with the event type and failing field path, clears cache entries the event could have changed and counts it.
+  Set `gateway: { onMalformedDispatch: "terminate" }` to end the shard with a protocol `ConnectionError` instead
+
+    Add an `overflow` handler option with `stop`, `dropOldest` and `dropNewest` policies. Every dropped event is logged at Warn and counted in `diagnostics().counters.eventsDropped`.
+    Handlers registered with `client.on` drop the oldest waiting event by default when their queue is full, as `runBot` handlers and command routers do, and the handler keeps running.
+    An unknown event name fails with `ConfigurationError` whose hint suggests the closest valid name when one is similar
+
+    Migration: A full `client.on` queue no longer ends the subscription. To keep that behavior, where `waitForClose` returns `EventOverflowError`, pass `{ overflow: "stop" }` to `client.on`. The `subscribe` streams, event waits and collectors still end on overflow.
+    Event handlers passed to `runBot` now run `messageCreate` up to eight at a time and drop the oldest waiting event when their queue is full instead of stopping the bot.
+    Pass `{ handler, concurrency, overflow, maxPendingMessages, maxPendingBytes, onError }` instead of a function to change this per event. Command routers attached without options, or with undefined settings, also run up to eight commands at a time and drop the oldest waiting message
+
+- 7733b23: Each helper has one public name, and the role hierarchy helpers join the other pure helpers in a namespace:
+
+    - The top-level `createPkce` export is removed. Use `oauth.createPkce`, which is unchanged
+    - The `hierarchy` namespace replaces `canManageHierarchy`, `compareHierarchy` and `isAboveInHierarchy` with `hierarchy.canManage`, `hierarchy.compare` and `hierarchy.isAbove`. The `HierarchyHelpers` type describes it
+
+    Migration: Replace `createPkce()` with `oauth.createPkce()`, and each loose hierarchy function with its `hierarchy` method
+
+- 7733b23: Reject misspelled and unsupported top-level option keys in `createClient`, `runBot` and `supervisor.create` in both entry points with `ConfigurationError`, whose hint names the closest supported key, such as `events` for `event`.
+  The `clientOptions` of `supervisor.child.run` are checked the same way, where an unknown key was silently dropped before, so the child client ran without it.
+  Unsupported keys in the nested `logging`, `cache`, `cache.messages`, `cache.<kind>`, `connection`, `connection.recovery`, `uploads`, `gateway`, `sharding`, `instance` and supervisor `restart` settings are named in the message with the same suggestion, and a removed logging setting names its replacement
+
+    Normalize the configured token: Surrounding whitespace and one pair of matching quotes, which `.env` files often add, are removed.
+    A token that starts with a `Bot` or `Bearer` scheme is rejected with `ConfigurationError`, since the SDK adds the `Bot` scheme itself.
+    The `auth.rejected` hint suggests checking the configured value before regenerating the token
+
+    Migration: Remove option keys that `createClient`, `runBot`, `supervisor.create` or the `clientOptions` of `supervisor.child.run` do not support, including unknown nested keys such as a `connection` key other than `startupTimeoutMs`, `maxStartupAttempts` and `recovery`, and pass the bare token without a `Bot ` or `Bearer ` prefix
+
+- 7733b23: Return plain values from the local helpers in both entry points, and throw their existing error for invalid input, which indicates a programming mistake.
+  This covers `format`, `snowflakes`, `permissionBits`, `colors`, `text.split`, `links`, `assets`, the role hierarchy helpers in `hierarchy` and the `assets` and `links` helpers returned by `client.instance.resolve()`.
+  Invalid input throws the same `HelperError`, `AssetUrlError` or `GuildOperationError` with the same `operation` and `reason` that the Result or Effect previously carried.
+  In the native API such a throw inside Effect code becomes a defect rather than a typed failure
+
+    Add `format.tryParseMention`, `format.tryParseTimestamp`, `format.tryParseCustomEmoji`, `snowflakes.tryParse` and `colors.tryParse` for text received from users.
+    They apply the same rules as their plain counterparts without throwing, returning a Result in the default API and an Effect that fails with `HelperError` in the native API
+
+    Migration:
+
+    - In the default API, helpers such as `format.userMention(id)` now return plain values directly, so drop `isOk()`, `value` and `_unsafeUnwrap()` handling from helper calls, and catch `HelperError` only where invalid input is possible
+    - In the native API, helpers are no longer Effects, so drop `yield*` and `Effect.runPromise` around calls such as `format.userMention(id)`, `links.installation(id)`, `assets.displayAvatar(user)`, `hierarchy.canManage(input)` and `resolved.links.channel(target)`
+    - Parse untrusted text with `format.tryParseMention(text)`, `format.tryParseTimestamp(text)`, `format.tryParseCustomEmoji(text)`, `snowflakes.tryParse(text)` or `colors.tryParse(input)` instead of `parseMention`, `parseTimestamp`, `parseCustomEmoji`, `snowflakes.parse` or `colors.parse`, which now throw
+    - Native code that deferred validation by building a helper Effect before its input changed now reads the input when the helper is called
+
+- 7733b23: Make public types describe what Fluxer actually sends and what builders accept.
+  `GuildChannel` is a union of `GuildTextChannel`, `GuildVoiceChannel`, `GuildCategoryChannel`, `GuildLinkChannel` and `GuildUnknownChannel`. Comparing `channel.type` with a `ChannelType` constant narrows it to exactly that shape, so `if (channel.type === ChannelType.Voice)` yields a `GuildVoiceChannel`. A channel type this SDK version does not know arrives as a `GuildUnknownChannel` whose `type` is `"unknown"` and whose `rawType` holds the number Fluxer sent, so a `switch` on `type` that also handles `"unknown"` is exhaustive.
+  `PresenceUpdate.status` is an `ObservedPresenceStatus`, and an unrecognized status from Fluxer becomes `"unknown"` instead of an arbitrary string.
+  `EmbedBuilder.color` accepts any `ColorInput`, such as `"#ff8800"` or an RGB tuple, and `EmbedBuilder.timestamp` accepts a `Date`, epoch milliseconds or an ISO string. An invalid color, or an invalid `Date` or number, throws `HelperError` with operation `embed.color` or `embed.timestamp`.
+  The type error from calling `build()` on an empty `MessageBuilder` now names the missing body, through the exported `MissingMessageBody` type.
+  Default clients, OAuth clients, webhook clients, subscriptions and collectors support `await using`, which shuts a client down or closes a subscription or collector and waits for its cleanup
+
+    Migration:
+
+    - Narrow a `GuildChannel` on `type`, for example with `ChannelType.Voice`, before reading `bitrate`, `userLimit` or other fields that belong to one channel type
+    - Handle channel types outside `ChannelType` by checking `channel.type === "unknown"` and reading the Fluxer number from `channel.rawType`. A numeric `type` no longer carries an unknown type
+    - Compare `PresenceUpdate.status` against the listed values and handle `"unknown"` instead of Fluxer strings outside that list
+    - `EmbedBuilder.color(value)` converts its input, so pass the color directly rather than converting it first. A number outside the 24-bit range now throws
+    - `EmbedBuilder.timestamp(value)` converts a `Date` or number with `toISOString()`. An invalid `Date` or number now throws instead of producing an invalid embed
+
+- 7733b23: Public types now use one name per concept, and API rejection details are readable in the reference, in both entry points
+
+    - `MemberSearchHit.globalName` and `OAuthIdentity.globalName` are now `displayName`, the name `User` and `MessageUser` already use for the account-wide display name. The `display.name` helper therefore reads it from member-search hits and OAuth identities too
+    - The deprecated `MessageMention` alias is removed. `MessageUser` is the only name for the partial-user shape in mentions and references
+    - `ApiErrorDetail` and `ApiValidationErrorDetail` are plain interfaces. The new `ApiErrorCode`, `ApiProviderCode` and `ApiValidationCode` unions list every recognized category and server code to branch on. The `explanation` fields are typed `string`, and `validationErrors` is present only when `code` is `invalidFormBody`
+    - The `@neontechspace/fluxerly/effect` entry point no longer exports the ten default-API option types `DefaultMemberChunkOptions`, `DefaultCountOperationOptions`, `DefaultBotApplicationOperationOptions`, `DefaultExpressionDeleteOptions`, `DefaultUserOperationOptions`, `DefaultWebhookOperationOptions`, `DefaultAttachmentDownloadOptions`, `DefaultAttachmentRefreshOptions`, `DefaultAttachmentStreamOptions` and `DefaultMessageCleanupOptions`. No Effect member accepts them
+
+    Migration:
+
+    - Read `displayName` instead of `globalName` on `MemberSearchHit` and `OAuthIdentity`
+    - Replace `MessageMention` with `MessageUser`
+    - Use `ApiErrorCode`, `ApiProviderCode` or `ApiValidationCode` to branch on codes. Code that compared `explanation` against literal types compares strings instead
+    - Effect code that imported a `Default*` option type imports it from `@neontechspace/fluxerly`, or uses the Effect option type of the same operation
+
+- 7733b23: Return a Result or a failing Effect only where a failure can happen at runtime, such as a request, a gateway command, an event wait or a collector's outcome.
+  Local setup returns its value directly: Creating clients, registering handlers, creating command routers and reading caches.
+  Misuse of that setup, such as invalid options, a missing token or an unknown event name, throws `ConfigurationError` in the default API and is a defect in the native API, so a misconfigured bot fails at startup instead of returning an easily ignored Err.
+  An Err returned or resolved by an application callback, including event and command handlers, guards, middleware, collector callbacks, `onError` hooks, state observers and supervisor configuration, is now reported like a throw of its error
+
+    The default API exports `orThrow`, which returns a Result's value or throws its error and also accepts a Promise of a Result, and re-exports the `Result` and `ResultAsync` types.
+    Callback return types accept `unknown`, and handler, collector and supervisor signals are typed as `AbortSignal`.
+    A missing or blank `token` is accepted by the types as `string | undefined` and throws `ConfigurationError` with a hint that the environment variable holding it is probably unset
+
+    Migration:
+
+    - Default `createClient(options)`, `createWebhookClient(options)`, `oauth.create(config)` and `supervisor.create(options)` return the client or supervisor directly. Drop `isErr()`, `value` and `_unsafeUnwrap()` handling and catch `ConfigurationError` only where options come from untrusted input
+    - Native `createClient`, `createWebhookClient`, `oauth.create` and `supervisor.create` no longer fail with `ConfigurationError`. Invalid options become a defect, so handlers for that typed failure can be removed
+    - Default `client.on(event, handler)` returns the `Subscription`, `client.subscribe(event)` returns the `EventSubscription`, and `messages.collect(...)` and `messages.collectReactions(...)` return the collector directly. A gateway that is not ready or an aborted signal now appears in the collector's `result()` instead of the creation result. Native `on`, `collect` and `collectReactions` no longer fail, and a native `subscribe` stream fails only with `EventOverflowError`
+    - Cache lookups such as `client.messages.get(reference)` return the cached value or `undefined` directly, and return `undefined` after shutdown instead of `ClientClosedError`. A malformed ID throws the namespace's operation error with reason `input` in the default API and is a defect in the native API. Native lookups otherwise return an Effect that never fails
+    - The default `client.cache.entries(kind)` returns the array directly, and native `cache.entries` never fails
+    - The `client.permissions.calculate(input)` method returns the `bigint` directly in both entry points and throws `GuildOperationError` with reason `input` for inconsistent data
+    - Command routers return values directly in both entry points. The `commands.create`, `register`, `registerMany`, `registerGroup`, `help` and `commands.memoryCooldowns()` calls throw `ConfigurationError` for invalid definitions, and the default `attach` returns the `Subscription`. Drop `yield*` in front of those calls in native code, where `attach` remains an Effect
+    - A default cooldown store's `claim` returns the claim or a Promise of it rather than a Result
+    - Callbacks that returned an Err to signal an ignored outcome now report a failure. Return nothing, or handle the Result inside the callback, when the failure is expected
+    - The `RegistrationError` and `CollectorRegistrationError` exports are removed, because registration misuse now throws `ConfigurationError` and a registration during shutdown returns a closed handle
+    - TypeScript consumers that read handler signals or use `await using` need `AbortSignal` and `AsyncDisposable` from the Node.js types, for example `"types": ["node"]`
+
+- 7733b23: Command `id` arguments now accept only IDs in the 64-bit ID range, in both entry points. A valid ID is a nonzero decimal without leading zeroes, up to `9223372036854775807`.
+  The same limit applies to IDs inside the accepted mention forms.
+  The value `0` and longer or larger values are now rejected as `Invalid` before the command runs.
+  Commands that relied on `0` or out-of-range tokens reaching the handler need a `custom` argument instead
+- 7733b23: Command cooldowns no longer turn users away because a memory store is full, and commands can be hidden from help and suggestions, in both entry points
+
+    - A memory cooldown store never refuses a new key. When it is full, it removes expired keys first, then the reservation that expires soonest, which lets that key run again early. This applies to `commands.memoryCooldowns()` and to each router's own store
+    - The default limit rises from 1,024 to 10,000 keys, and the router option `cooldowns: { maxEntries }` sizes a router's own store, for example `commands.create({ prefix: "!", cooldowns: { maxEntries: 50_000 } })`
+    - Commands and groups accept `hidden: true`. Generated help leaves them out, along with everything inside a hidden group, and selecting a hidden group in `help` throws `ConfigurationError` as for a missing one. Hidden commands still run when invoked, so guard the ones that need it
+
+    Migration:
+
+    - The `CooldownCapacity` claim and the `CommandCooldownCapacity` rejection are removed, because a built-in store no longer refuses a key. A custom store returns only `CooldownAcquired` or `CooldownActive`, and any other claim fails the command with `ConfigurationError`. Code that handled either removed tag can drop that branch
+    - Code that relied on the old limit of 1,024 keys, for example to cap memory, passes `maxEntries` to `commands.memoryCooldowns` or the router's `cooldowns` option
+    - Owner-only and other private commands that must not appear in help set `hidden: true` instead of filtering them in every `help` call's `include`
+
+- 7733b23: Registering a subscription or collector after client shutdown has begun no longer fails with `ClientClosedError` at registration, in both entry points. A handler that is still running when shutdown starts can register, which is a runtime race rather than misuse
+
+    - A `client.on` or `client.subscribe` registration, including a command router's `attach`, returns an already-closed subscription. Its handler never runs, `waitForClose` succeeds and the default `next` returns `Ok(null)`. The native `subscribe` Stream ends without events. Each such registration writes a Warn log record with code `events.registeredAfterShutdown`
+    - A `messages.collect` or `messages.collectReactions` registration returns a collector whose `result` fails with `ClientClosedError`, as it does for a collector already running when shutdown starts
+    - Invalid arguments are misuse and throw or die with `ConfigurationError`, whatever the client state. Registering middleware with `client.use` on a closing client throws or dies with `ClientClosedError`
+
+    Migration:
+
+    - Code that handled `ClientClosedError` from these registrations reads the handle instead. Check `client.state`, or read the collector's `result` for `ClientClosedError`
+
+- 7733b23: Configure a whole bot with one `runBot` options object in both entry points.
+  A `commands` option routes prefix commands, `setup` runs after every handler is registered and before the connection starts, and `onError` and `processSignals` sit beside them.
+  The `runBot` function checks every option, including event names, event delivery settings and client settings, before any client, process signal listener or request exists, even when the `signal` is already aborted. Invalid configuration throws `ConfigurationError` at the call, or is a defect in the native API.
+  It then creates the client and registers every event and command synchronously. An aborted `signal` with valid options returns success without creating a client.
+  A failed `setup` or an application error thrown by a `commands` register callback is an application failure, reported as `ApplicationError` with the original value as `cause`. In the default API, a `setup` callback that throws, rejects or returns an Err gives `source` `"runBot setup"`, and in the native API a failed `setup` Effect gives the same. A register callback that throws gives `source` `"runBot commands"` in both APIs. A failed `setup` stops the bot before connecting and shuts down its client, and a failed register callback stops it before any client exists. Misuse inside the register callback is `ConfigurationError`, and an `SdkDefect` or a native defect keeps its original cause
+
+    Commands gain features for common bot needs:
+
+    - The `guard` option accepts one guard or an array, and a guard can return `{ deny: "reason" }`. The exported `guards` provide `guildOnly()`, `dmOnly()`, `ownerOnly(ids)` and `requirePermissions(names)`
+    - The `guildOnly()` guard allows a message sent in a community, which Fluxer calls a guild, and denies every other message without a request. The `dmOnly()` guard allows only a confirmed one-to-one or group conversation: It checks the direct-message cache, then the channel cache, and otherwise reads the channel once with `directMessages.fetch`, which also fills an enabled direct-message cache. A community channel is denied, and any other failed read fails the command and is reported with the command name. In the Effect API, its error type is `UserOperationFailure`
+    - The `requirePermissions(names)` guard reads cached community, member, role and channel data first. It reads a cached channel that lacks its overwrite list again, and evaluates a channel that Fluxer returns without one from the member's role permissions
+    - The `cooldown` option accepts `{ durationMs, per }` with `per` set to `"user"`, `"channel"` or `"guild"`, and uses a memory store owned by the router when `store` is omitted
+    - The router's `use` option adds middleware that wraps every command and can stop it by not calling `next`. In both APIs, `next` fails with the command's own error, and each middleware stage and the command run at most once per message, even when `next` is called again or evaluated concurrently. A command failure is reported once with its command name, whatever the middleware does with it. Middleware that fails with a different error adds its own report after the command's failure
+    - Setting `onReject: "reply"` sends a short explanation, such as `Missing name. Usage: !greet <name>`, the guard's reason or the cooldown's remaining time. The commands of `runBot` use it by default, while a router from `commands.create` gives no feedback unless `onReject` is set. Setting `onReject: "silent"`, on a router or on one command, sends nothing, and the rejection is still counted and logged at Debug as `commands.rejected`. An active cooldown key is answered once until its retry time, and a guard denial once per user and command every 5 seconds, while argument rejections are answered each time. A skipped reply still counts as a rejection and is logged at Debug with `feedbackSuppressed`. An `onReject` function receives every rejection. Native replies measure the remaining time with the handler's Effect Clock
+    - Setting `mentionPrefix: true` accepts a mention of the bot, `<@id>` or `<@!id>`, as a prefix, and the `prefix` option can be resolved asynchronously. The bot's ID comes from the user in the gateway's READY. When READY lacks it, one shared `users.fetchSelf` read supplies it, and a failed read is logged at Warn and retried after a backoff that starts at 5 seconds and doubles up to 5 minutes
+    - An unknown command name passed to `onUnmatched` and its Debug `commands.unmatched` log record carry `suggestion`, the closest registered command or group name when one is similar. Two swapped adjacent characters count as one edit, so `pnig` suggests `ping`. Hidden commands and everything inside a hidden group are never suggested
+    - The bound `reply` accepts a plain string
+    - Argument descriptors add `min`, `max` and `default` for integers and numbers, and new `duration`, `member` and `custom` types. A `member` argument accepts only IDs in the 64-bit ID range, as `id` does. A `custom` parse function is synchronous: A returned Err fails the command like a throw, and a returned Promise or Effect is not run as the value but fails the command with `ConfigurationError` for field `command`, without an unhandled rejection
+
+    Migration:
+
+    - The `runBot(options, install, runOptions)` form is removed. Move event handlers into `events`, commands into `commands`, other startup work into `setup(client)`, and `runOptions` settings such as `signal` and `processSignals` into the options object
+    - Code that checked `runBot`'s Result for configuration failures catches the thrown `ConfigurationError` instead. The Result reports connection failures, cancellation and stopped workers as before, and a failed `setup` or `commands` callback as `ApplicationError`. A handler set to `overflow: "stop"` that overflows is reported and the bot keeps running without it, so `EventOverflowError` is no longer part of the `runBot` error type in either API. Remove its case from code that matches on `runBot` failures
+    - `CriticalWorkerStoppedError.workerIndex` counts event subscriptions in configuration order, followed by the command router
+    - A cooldown without `store` no longer requires one. Pass `per` instead of building the key from the message when the default key fits
+    - Keyed `registerMany` entries may omit `arguments` for unrestricted raw args. TypeScript projects with `exactOptionalPropertyTypes` omit it rather than pass `arguments: undefined`
+    - The commands of `runBot` now answer a rejected command. Set `onReject: "silent"` in the `commands` option of `runBot` to keep rejected commands unanswered. Unmatched commands, and rejected commands of a router from `commands.create`, still get no reply unless `onUnmatched` or `onReject` asks for one
+
+- 7733b23: The `runBot` function reports a failed run for the process by default, in both entry points.
+  When the bot stops because of a failure, it logs that failure once as an Error record with code `lifecycle.botFailed` and sets `process.exitCode` to 1. It skips the record when the client already logged the same error, such as the `lifecycle.connectionEnded` record of a rejected token, so the failure appears once. The failure is still returned, and a normal stop or an interruption reports nothing. The native API also reports a defect this way, including misuse found before any client exists, such as a missing token or a misspelled option key. In the default API, misuse throws `ConfigurationError` and a defect rejects with `SdkDefect`, which Node.js prints before it exits with a failing code.
+  A bot entry point therefore needs no try/catch: `await runBot({ ... })` is complete in the default API, and so is `await Effect.runPromiseExit(runBot({ ... }))` in the native API
+
+    Migration: Code that already logs the returned failure and sets the exit code can drop that handling. To keep full control of the failure output and exit status, pass `reportFailure: false`
+
+- 7733b23: Forward each supervised child's output in the supervisor's console format by default, and add the `childOutput` supervisor option with `prefix`, `inherit` and `ignore`.
+  Readable output labels each line with its shard or child ID. JSON output stays valid JSON Lines: A child's SDK record gains `fields.child`, another JSON object passes through unchanged and other text becomes a `supervisor.childOutput` record.
+  With `prefix`, children receive the supervisor's format and color through `FLUXERLY_LOG_FORMAT` and `FLUXERLY_LOG_COLOR` unless those variables are already set. Very long lines are truncated with a marker, forwarding respects output backpressure, and exit handling waits briefly for a child's final output, such as a crash stack trace.
+  The supervisor now logs child start, exit, crash, restart and spawn failures, and spawn errors keep their original cause. The new `logging` supervisor option accepts the client logging settings for these records
+
+    Migration: Supervised child output was previously discarded. Set `childOutput: "ignore"` to keep discarding it
+
+- 7733b23: Supervisors now restart a crashed child by default, with the documented defaults of `SupervisorRestartOptions`: Up to 3 restarts in a row, delays from 1,000 ms doubling up to 30,000 ms, and a fresh budget after 60,000 ms of healthy running. Previously an omitted `restart` option meant that one crashed child stopped the whole supervisor and took every shard offline. The `restart` option now also accepts `false`, and the `supervisor.crash` record names that setting when it stops the supervisor
+
+    Restart budgets now count consecutive crashes instead of every crash over a child's lifetime. A child that runs for the new `restart.healthyResetMs` (default 60,000 ms) after finishing configuration gets its full budget and the first delay back at its next exit. When that restores used restarts, the `supervisor.restart` record has `fields.budgetReset` set to true. A crash loop still exhausts `maxAttempts` and stops the supervisor
+
+    Migration:
+
+    - To keep the previous behavior, where one unexpected child exit stops the supervisor, set `restart: false`
+    - To keep a lifetime-wide budget in practice, set `restart.healthyResetMs` to a period longer than the expected process lifetime, up to 2,147,483,647 ms. The `restarts` count in `status()` child snapshots also starts again after such a reset
+
+- 7733b23: Check every validated timestamp, whether received from Fluxer or supplied as a pin cursor, community history cutoff or embed time, with one ISO 8601 grammar: A date, `T`, hours, minutes and seconds, an optional fraction of any length and a `Z` or `±hh:mm` offset, on a real calendar day.
+  Accepted values stay exactly as received or supplied. Custom status expiry inputs keep their own rules, which also allow omitting seconds, and attachment expiry times remain unchecked text.
+  `GuildEdit.messageHistoryCutoff` now accepts an offset instead of only UTC, discovery times and community history cutoffs from Fluxer accept offsets, and pin cursors and message, pin and community times accept fractions longer than nine digits
+
+    Migration: Member join and timeout times, invite times, ban times and channel last-pin times received in any other form, such as without seconds or a zone, are now rejected. Before, only the date was checked and `Date.parse` had to accept the value
+
+- 7733b23: Every operation that takes an input, query or options object rejects a key it does not support before sending anything, in both API styles. The failure is the operation's own error with reason `input` and an `inputValidation` constraint of `allowedFields`. Its explanation names the key, suggests the closest supported key and lists the supported keys, for example `Unsupported option "timeout" in the operation options. Did you mean "timeoutMs"? Supported options are timeoutMs, signal`
+
+    Operations that sent the request and ignored an unknown key before now reject it: The options of message sends, replies, forwards, edits, deletions, fetches, searches, pins and reactions, the OAuth `authorizationUrl`, `exchangeCode` and `revoke` inputs, and the default API `gateway.send` options. Channel position entries and permission overwrites report an unsupported key separately instead of as a general format failure. The `instance.resolve` and `cache.entries` options name an unsupported key and suggest the closest one in their `ConfigurationError`
+
+    Migration: Remove keys that an operation does not support from its input, query and options objects. Each failure names the first unsupported key it finds
+
+- 7733b23: Log startup, readiness, lost connections with the close-code meaning and the real next step, session resets, long rate-limit waits, event drops, shutdown and every application failure by default.
+  Records share one shape with a level, category, stable code, message and safe fields, and never contain the token, authorization values, client secrets, webhook tokens or invite codes
+
+    Configure output through `logging` with `level`, per-category `categories`, `debug`, `format`, `sink`, `dedupe` and `unsafe` settings, or set `FLUXERLY_DEBUG=1` or a list of categories for Debug records.
+    The default API prints readable lines in a terminal and JSON lines otherwise, deciding separately for standard output and standard error. Readable lines show the record code after the category, print safe details for every error in the cause chain and collapse stack frames inside the SDK and Effect into one line. The `FLUXERLY_LOG_FORMAT` and `FLUXERLY_LOG_COLOR` environment variables choose the format and color for a client without `format`. The color variable accepts `1`, `true`, `yes` or `on` to force color and `0`, `false`, `no` or `off` to disable it, and an unrecognized value of either variable logs one `sdk.unknownEnvironmentValue` Warn.
+    Without `sink` or `format`, the native Effect API logs through the caller's Effect logger with `fluxerly.*` annotations, including `fluxerly.error.code`, `fluxerly.error.hint` and `fluxerly.error.*` details for a failure. Each error in the cause chain adds its own annotations under `fluxerly.error.cause.`, then `fluxerly.error.cause.cause.` and so on. Its records carry masked copies of failures that show their code, so Effect's cause printer never shows credentials or extra error properties.
+    Repeated Warn and Error records are collapsed with a repeat count, and `diagnostics().counters` counts failures, drops, retries, rate-limit waits, reconnects and resumes.
+    A rate limit whose wait would pass the request deadline fails the request at once, logs `ratelimit.deadline` and is not counted as a wait.
+    Failure reports logged instead of reaching an `onError` hook carry `fields.reportOutcome` (`queueFull`, `interrupted`, `clientClosed` or `subscriptionClosed`), and collapsed records carry the suppressed count in `fields.repeated`.
+    The `lifecycle.retry` and `lifecycle.connectionLost` records carry `fields.next`, which is `resume` or `identify` and names the next handshake
+
+    Unsafe payload logging prints its Warn banner once before the first payload record at any level, prints nothing for a `silent` category and reads at most the first 64 KiB of each received REST body
+
+    The native API also records `fluxerly.*` tracing spans for gateway connection, REST requests, event handling and command execution, plus REST duration, rate-limit wait, reconnect, drop and handler-failure metrics
+
+    Migration: The `development`, `measurements`, `minimumLevel` and `logger` logging settings, `fromStructuredLogger` and `fromEffectLogger` are removed.
+    Use `level` and `categories` for levels, `debug` or `FLUXERLY_DEBUG` for Debug records, and `sink` to forward records to another logger.
+    The types `DefaultLogger`, `DefaultLoggingOptions`, `StructuredLogger`, `SdkLifecycleEvent`, `SdkLifecycleLogRecord`, `SdkOperationalLogRecord`, `SdkMeasurementLogRecord`, `SdkMeasurementOperation` and `SdkMeasurementStage` are removed. `SdkLogLevel` is renamed to `LogLevel` and its values are now lowercase, such as `"info"`. The `All` and `None` values are removed, and `level: "silent"` replaces `None`. `SdkLogRecord` is renamed to `LogRecord`, which has a new shape.
+    Clients now print startup, readiness, connection loss and shutdown at Info by default. Set `level: "warn"` to print only problems.
+    The Effect API's `MessageCacheOptions<E, R, M>` is now `MessageCacheOptions<M>`, because cache callback failures go to the client's `onError` rather than a cache-specific hook
+
+### Minor Changes
+
+- 7733b23: A client logs one `lifecycle.connected` record once every shard it owns is connected, such as `Connected to Fluxer as MyBot in 3 communities`. When the bot owns every shard and is in no community, the record is a Warn that includes the bot's installation link
+
+    Loading any entry point on a Node.js version older than 24.11 throws an error that names the required and the found version, instead of failing later with an unrelated error
+
+    Several configuration errors explain the likely fix:
+
+    - An event named `ready`, `clientReady`, `onReady` or `connected` points to the connected record, the `setup` option of `runBot` and `client.connect()`
+    - An unsupported command argument type suggests the supported type it most likely meant, such as `text` for `string`, and lists every supported type
+    - A missing bot token mentions `node --env-file=.env bot.js`, the current folder and a `.env` file saved as `.env.txt`
+    - A command definition placed next to `prefix` in the `commands` option of `runBot` is explained as belonging in the inner `commands` object, an unknown key there lists `commands` and `onError` among the supported keys, and a missing `prefix` is reported as required
+
+- 7733b23: Add `client.cache.onChange(listener)` to observe changes to the client's local caches as `{ kind, op, key }` records, where `op` is `set`, `delete` or `clear`.
+  Every cache kind reports stored and replaced entries, removals including expiry and capacity eviction, and whole-kind clears from `cache.clear()`, connection gaps of unknown scope and shutdown.
+  Keys use decimal IDs, such as `channelId:messageId` for messages and `guildId:userId` for members.
+  Changes are delivered in applied order after the cache work that produced them, a failing listener is reported as a cache failure, and no change is recorded while no listener is registered
+- 7733b23: Add the `callCreate`, `callUpdate`, `callDelete` and `entranceSoundPlay` events for Fluxer's CALL_CREATE, CALL_UPDATE, CALL_DELETE and ENTRANCE_SOUND_PLAY dispatches, with frozen `CallCreate`, `CallUpdate`, `CallDelete` and `EntranceSoundPlay` payloads.
+  Call participants use `CallVoiceState`, which omits Fluxer's internal voice routing fields.
+  A malformed dispatch of these types is skipped and counted like other malformed events, without clearing any cache
+- 7733b23: Add the `observe` client option to export metrics and traces from either entry point to any monitoring system.
+  The observer receives one frozen `Observation` for each finished REST request attempt, with its method, route template, status, duration and attempt number, each rate-limit wait, each reconnection attempt, each resumed session, and each finished handler or command invocation, with its duration, outcome and the error name and code of a failure.
+  Observations never contain tokens, payloads or message content, and route templates replace IDs with placeholders.
+  The observer runs synchronously and independently of the logging settings. An observer that throws is counted in `diagnostics().counters.sinkFailures` without changing SDK work. The Effect API keeps its Effect metrics and spans and calls the same observer
+- 7733b23: Command contexts in both entry points gain `help(options?)`, which builds help pages from the router that matched the command, so a `help` command works in the keyed `commands` object of `runBot` without a reference to the router.
+  The prefix defaults to the one the invoking message used and the page length to 2,000 UTF-16 code units. The other settings match `router.help`, and the new `CommandContextHelpOptions` type describes them. For example: `help: { execute: ({ help, reply }) => reply(help()[0] ?? "No commands") }`
+- 7733b23: Make errors and log records say what went wrong and what is accepted. `HelperError` and `AssetUrlError` messages name the helper and the accepted form, for example `Helper operation format.userMention failed: IDs must be decimal strings from 0 through 9,223,372,036,854,775,807`, instead of `Invalid input for format.userMention`.
+  `PaginationError` messages include the input explanation or what stopped the iteration, and the error carries a `hint`: The rejected path for invalid settings, raising `maxPages` for `pageLimit`, and retrying later for `cursorStalled` and `indexing`
+
+    Input validation explanations name the field in words and state the accepted range with its unit, such as `ms`, `bytes` or `seconds`. Presence explanations name the field they describe, unsupported-field explanations list the accepted fields or the type that defines them, timeouts state their `ms` unit, and ban and timeout durations state their range in `ms` with the matching days or years.
+    Connection, startup and shutdown records use full sentences, such as `Shard 1 lost its connection. Close code 4000 (UNKNOWN_ERROR): The gateway reported an unspecified error. Reconnecting and resuming the session in 486 ms`, and configuration errors name the full option path, such as `connection.startupTimeoutMs`. `SupervisorError` and `SupervisorChildError` messages describe the failure and carry a hint. An instance discovery failure keeps its transport error code and says what was wrong with the response.
+    `CancelledError` accepts an optional operation, which is recorded as `details.operation` and named in the message, and its hint explains that signals the SDK passes to handlers abort when the client shuts down
+
+    The `inputValidation.path` and `constraint` values are unchanged. Messages remain changeable text, so match on `code`, `reason`, `field` and `inputValidation` and on log record codes instead
+
+- 7733b23: Provide a native client as an Effect service with `FluxerClient` from the Effect entry point.
+  `FluxerClient.layer(options)` creates the client in the layer's scope and shuts it down when that scope closes.
+  `FluxerClient.layerConfig({ token: Config.Redacted("FLUXER_BOT_TOKEN") })` reads the token, and optionally any other top-level setting, from Effect `Config`. The token stays redacted until the client receives it.
+  A missing Config value fails the layer with `ConfigError`, while a blank token or another invalid setting dies with `ConfigurationError`.
+  Building either layer does not connect. Register handlers, then call `client.connect()` or `client.run()`
+- 7733b23: Add `FluxerTestClient` to `@neontechspace/fluxerly/effect/testing` for applications that read their client from the `FluxerClient` service.
+  `FluxerTestClient.layer(options)` creates a test client with `createTestClient` and provides its client as `FluxerClient` and the whole test client, with its controls, as `FluxerTestClient`. Application code then runs against the in-memory Fluxer unchanged.
+  Closing the layer's Scope shuts the client down and dies with `UnhandledTestFailuresError` for a handler failure the test did not read
+- 7733b23: Read the community that owns a custom emoji or sticker with `emojis.fetchSource(id)` and `stickers.fetchSource(id)` in both entry points. Fluxer calls a community a guild.
+  The result is a frozen `ExpressionSourceGuild` with the community's `id`, `name`, `icon` hash and badge `features`.
+  Fluxer answers when the source community is discoverable or the bot is a member of it. A private or unavailable source community fails with `GuildOperationError` whose `apiError.code` is `unknownResource`.
+  Badge names added by Fluxer later are kept rather than failing the read, and a response missing any documented field fails with reason `response`
+- 7733b23: The `members.fetchCanManage` method accepts `actorUserId` to check whether another member, such as the moderator who ran a command, outranks the target instead of the bot. It reads that member in place of the bot's own membership, and an invalid ID fails with reason `input` before any request. The option types are `CanManageOptions` and `DefaultCanManageOptions`
+- 7733b23: Recognize Fluxer's `TWO_FACTOR_REQUIRED` rejection in both entry points. A kick, ban, timeout or other action that needs a moderation permission in a community that requires two-factor authentication now fails with `apiError.code` set to `twoFactorRequired` and `apiError.providerCode` set to `TWO_FACTOR_REQUIRED`, instead of `apiError` set to `null`. Fluxer returns it when the account that owns the bot's application has no two-factor authentication enabled and the bot does not own the community.
+  Communities, which Fluxer calls guilds, gain an optional `mfaLevel` field with the new `GuildMfaLevels` constants `None` and `Elevated`, so a bot can see this requirement before it sends a moderation request. The field appears on fetched communities, community list entries and `guildCreate` and `guildUpdate` events. A community whose `mfa_level` is present but not 0 or 1 is treated as malformed, like other malformed community fields
+
+    The moderation and message deletion references describe this requirement, and the `messages.deleteMany` reference states that it requires `ManageMessages` even for the bot's own messages
+
+- 7733b23: Add `snowflakes.shardFor(guildId, totalShards)`, which returns the shard Fluxer routes a community's events to, and `client.shardIdForGuild(guildId)`, which returns this client's shard for a community or `undefined` when another process owns it. Fluxer calls a community a guild. Both APIs provide them
+
+    For an invalid ID, the helper throws `HelperError` with reason `id`, and for a total outside 1 through 16,384 with the new reason `shardCount`. The client method throws `ConfigurationError` for an invalid ID
+
+- 7733b23: Pass an `EventContext` with `shardId` and `receivedBytes` to every `client.on` handler, as the third argument in the default API and the second in the Effect API.
+  The context names the local shard that received the event and the byte length of the gateway frame that carried it
+
+    Add `client.use(middleware)` to run event middleware around every later `on` handler invocation, including those of existing subscriptions, command routers and `runBot` handlers.
+    Middleware runs in registration order, receives the event name, payload, context and subscription ID, and can skip the handler by not calling `next`.
+    Failures of middleware and of the handler inside it are reported like handler failures, so middleware cannot hide a handler failure.
+    Both APIs return a `MiddlewareRegistration` with `close()`. The default registration also works with `using`, and the Effect API ends the registration when the executing Scope closes and runs middleware with the services available at registration
+
+- 7733b23: Add the `partition` handler option to `client.on` and `runBot` events, in both entry points, to keep related events in order while unrelated events run side by side.
+  Events with the same key run one at a time in receive order, and events with different keys run in parallel up to `concurrency`, which defaults to 8 when a partition is set.
+  The value `"guild"` keys each event by its community, which the API calls a guild, and a direct message by its channel. The value `"channel"` keys each event by its channel, or by its community when it has no channel. A function receives the event and returns its own key.
+  Waiting events still count toward the queue limits. A partition function that throws or returns a value other than a string or undefined is reported as a failure of that event's handler, which then does not run
+- 7733b23: Add `gateway.ignoredEvents`, `gateway.flags` and `gateway.presence`, sent in each new session's Identify.
+  The `ignoredEvents` option lists dispatch names Fluxer should not send, or `"auto"` to suppress every type no registered event, enabled cache category or SDK feature needs, computed at each new session. A handler registered after a session started receives suppressed types only from that shard's next new session, and a `raw` subscriber disables automatic suppression.
+  Setting `flags: { debounceMessageReactions: true }` turns on Fluxer's `DEBOUNCE_MESSAGE_REACTIONS` flag, merging direct-message reaction runs into `messageReactionAddMany`.
+  The `presence` option sets the initial presence, which Identify carries and the SDK publishes after READY as if `presence.set` had been called before connecting.
+  An explicit `ignoredEvents` list that names a type the SDK or an enabled cache needs fails client creation with `ConfigurationError`. `GatewayOptions` is a new public type
+- 7733b23: Expose the instance's advertised web domain migration as `domainMigration` on `ResolvedInstance`, typed as the new `InstanceDomainMigration`, and log an Info record when a migration is enabled
+- 7733b23: Message operations accept a plain string as the whole message and an `EmbedBuilder` wherever they accept embeds, in both entry points.
+  A string such as `client.messages.send(channelId, "Hello")` is shorthand for `{ content: "Hello" }` in `messages.send`, `messages.reply`, `messages.edit`, `directMessages.send` and a webhook client's `send` and `editMessage`.
+  An `EmbedBuilder` in `embeds` is built once when the operation reads its input, so `client.messages.reply(message, { embeds: [builders.embed().title("Status")] })` needs no `build()` call and later changes to the builder do not affect that operation
+- 7733b23: Send text-to-speech messages with `tts: true` on `messages.send`, `messages.reply`, `directMessages.send` and the `runBot` reply helpers.
+  A non-boolean value fails with reason `input` before any request. In a community, Fluxer sends a normal message without an error when the bot lacks the Send TTS Messages permission.
+  Webhook messages do not accept `tts`, because Fluxer never sends a webhook message as text-to-speech. Webhook sends, replies and forwards with `tts` fail with reason `input` before any request.
+  Messages gain an optional `tts` field, selectable through `messageFields`. Fluxer does not store the value, so it is meaningful only on the message returned by a send and on `messageCreate` events. Fetches, history pages and other later reads always report `false`. A message whose `tts` is present but not a boolean is treated as malformed, like other malformed message fields
+- 7733b23: Add `MessageType` constants to both entry points, naming the values of `Message.type`, for example `message.type === MessageType.UserJoin`. They cover every message type in Fluxer's message schema: Default, RecipientAdd, RecipientRemove, Call, ChannelNameChange, ChannelIconChange, ChannelPinnedMessage, UserJoin and Reply.
+  `Message` stays one shape rather than a union by type, because Fluxer returns the same message fields for every type. A value Fluxer adds later is still kept in `Message.type`
+- 7733b23: Add the `raw` event, which delivers every gateway dispatch a shard accepts as `{ shardId, t, s, d }`, including `READY`, `RESUMED` and types this SDK version does not decode. The body is Fluxer's unvalidated wire data and is not part of the SDK's compatibility contract. Delivery is logged at Trace with code `events.raw`, and nothing is built while no `raw` subscriber exists. Types listed in `gateway.ignoredEvents` never arrive
+
+    Add `client.gateway.send(shardId, op, d)` for gateway commands without an SDK method. It fails with `GatewaySendError` whose `reason` is `input` for invalid arguments or frames above Fluxer's 4,096-byte limit, `reserved` for heartbeat, Identify, Resume and server-only opcodes, `notOwned`, `notReady` or `busy`, and with `ClientClosedError` after shutdown. A throw from a getter or `toJSON` in the command data rejects with `SdkDefect` code `application.defect`, and cycles, BigInt values and overly deep data fail with reason `input`. Completion means the frame was handed to the connection. Each sent command is logged at Debug with code `gateway.commandSent`
+
+- 7733b23: Export the types that public signatures already referenced, so they can be named in application code and appear in the reference.
+  Both entry points now export `FormatHelpers`, `SnowflakeHelpers`, `DisplayHelpers`, `PermissionBitHelpers`, `ColorHelpers`, `TextHelpers`, `LinkHelpers` and `AssetHelpers` for the helper objects, whose `tryParse` methods return a Result in the default entry point and an Effect in the Effect entry point, and `Operation`, `MessageContent`, `EditMessageOptions`, `WebhookMessageOptions`, `AuditLogFilter`, `AuditLogQueryBase`, `AuditLogIterationQueryBase`, `CommandArgumentOptionalValue` and `ErrorMatchHandlers`.
+  The default entry point adds `DefaultCommands` and `DefaultPrefixCommandBatch`, and the Effect entry point adds `NativeCommands`, `NativePrefixCommandBatch`, `NativeBatchRequirements`, `NativeCommandRequirements`, `NativeEffectRequirements`, `BotEventServices` and `HandlerServices`
+
+    Every public export now has a reference category, and each client method has one description shared by both entry points, with the differences between them stated separately
+
+- 7733b23: Add `client.rest.request({ method, path, query?, body?, files?, auditReason?, timeoutMs? })` for Fluxer API routes without an SDK method.
+  Default calls return a `ResultAsync` and accept `signal`, and Effect calls return an Effect. Both resolve with `{ status, headers, body }`, where header names are lower case and `body` is the parsed JSON body or `undefined` for an empty response.
+  Requests use the client's credential, queue, learned rate-limit buckets, 429 waits, deadline, logging and bounded GET retries. Other methods are sent again only after a confirmed 429, never after an uncertain outcome.
+  Paths must be relative API paths such as `/users/@me`, without a scheme, host, query, fragment, dot segments or the `/v1` prefix. Token-authenticated webhook routes are rejected because their credential is part of the path.
+  Invalid input fails with `RestRequestError` reason `input` before any request, a non-2xx status fails with `RestRequestError` carrying the status and sanitized `apiError`, and a request after shutdown fails with `ClientClosedError`. Logs, metrics and spans show only a route template in which IDs, codes and other non-word segments are placeholders.
+  The `files` field accepts the message attachment inputs and sends them inline as multipart form data with their metadata in `payload_json`
+- 7733b23: Add the `rest` client option to tune REST scheduling: The `concurrency` setting for Fluxer API requests that run at once (1 through 64), `mediaConcurrency` for attachment downloads (1 through 64, default 4), `maxQueued` (1 through 65,536, default 256), `queuedJsonMaxBytes` (64 KiB through 256 MiB, default 4 MiB) and `defaultTimeoutMs` (default 30,000).
+  By default a client runs 4 API requests at once for each of its shards, up to 64, instead of 4 in total, and the limit follows the shard plan when `sharding: "auto"` sizes or enlarges it. An explicit `concurrency` is used as given.
+  The `defaultTimeoutMs` setting replaces the fixed 30,000 ms deadline of REST operations and attachment downloads that omit `timeoutMs`.
+  Invalid values throw `ConfigurationError` naming the field in the default API and are defects in the Effect API, and `client.diagnostics().rest` reports the configured capacities
+
+    A request that fails with reason `busy` because the REST queue or the upload byte budget is full now logs `rest.busy` at Warn, at most once a minute, naming the full limit. Every such failure is counted in the new `diagnostics().counters.restBusy` counter
+
+- 7733b23: A shard that resumes a session from the `sharding.sessions` store now refills the enabled community, role and channel caches through REST, because a resumed session receives no community data. Fluxer calls a community a guild. Once every shard is ready, the SDK lists the bot's communities and fetches each one on a resumed shard, one request at a time, so application requests keep the other REST slots and rate limits apply as usual. The refill is logged with code `lifecycle.cacheRefill`, at Info when it succeeds and at Warn when some communities fail or it stops after 10 failures
+
+    Set `sharding.refillCaches` to `false` to skip the refill
+
+- 7733b23: Add scaling options for large bots.
+  The setting `sharding: "auto"`, or `totalShards: "auto"`, counts the bot's communities at the first connect and uses one shard per 2,000 communities. Fluxer calls a community a guild. Fluxer rejects a new session with close code 4011 (sharding required) when one shard holds more than 2,500 communities, and community IDs do not split evenly across shards, so the lower target keeps every shard below that ceiling and leaves room to grow. Counting the communities has its own `connection.startupTimeoutMs` deadline, so a slow count does not shorten the time the shards get to connect. Until the count completes, `client.shards` is empty. Automatic sizing assigns every shard to the client, so processes that split the shards need an explicit total.
+  When the bot outgrows its plan while the client runs and Fluxer closes a shard with close code 4011, the client keeps running. The SDK counts the communities again and moves every shard to the plan for the new count, or to one more shard when the count still fits the old total. Every shard then starts a new session under the new total, so events sent during the move are missed, and the community caches refill from the new sessions. The move is logged once at Warn with code `lifecycle.resharded` and the old and new totals. After 3 moves within an hour, or at 16,384 shards, a further 4011 closure ends the client with a `ConnectionError`, and the `lifecycle.connectionEnded` record says why. An explicit `totalShards` still ends the client on the first 4011 closure.
+  An application can pass `sharding.identify.permit(shardId, totalShards, signal)` to coordinate new-session Identify commands across processes, and a refused permit is logged at Error and retried like a connection failure. The coordinator owns Identify pacing, so the SDK adds no spacing of its own before a permit. A coordinator should space its permits, for example by one second, to stay within Fluxer's budget of 300 Identify commands per source IP address in each 60-second window.
+  A `sharding.sessions` store loads a saved `{ sessionId, sequence, resumeUrl, savedAt, totalShards }` snapshot at startup and saves one at shutdown, so a restart within Fluxer's 60-second window resumes instead of starting a new session. Stale, malformed or foreign snapshots, snapshots saved under a different shard total and store failures are logged and never fail startup.
+  The `connection.recovery` option sets `minDelayMs`, `maxDelayMs`, `attemptTimeoutMs` and `healthyResetMs` for established-session recovery, with the previous 1,000, 30,000, 30,000 and 60,000 ms as defaults, and the Effect API also accepts a `schedule` that decides recovery delays and ends recovery when it completes.
+  `ConnectionRecoveryOptions`, `IdentifyCoordinator`, `SessionStore` and `SessionSnapshot` are new public types
+- 7733b23: The `token` option of `supervisor.child.run` accepts `string | undefined` in both entry points, as `createClient` and `runBot` do, so `process.env.FLUXER_BOT_TOKEN` can be passed directly. A missing or blank token still fails `child.run` with `ConfigurationError` once the assignment arrives, and the parent then sees that child fail during configuration
+- 7733b23: Add scaling options to the supervisor in both APIs.
+  As an alternative to hand-written `assignments`, the new `processes` and `shardsPerProcess` options split every shard into contiguous blocks, one per child, named `process-0`, `process-1` and so on. With `totalShards: "auto"` the supervisor counts the communities the bot is in, which the API calls guilds, when it starts and uses one shard per 2,000 communities, as a client with `sharding: "auto"` does. The count needs the new `token` supervisor option and accepts `instance` and `transport` for a self-hosted instance or a proxy. It logs `supervisor.automaticSharding`, and a failed count fails `start` with the new `SupervisorError` reason `shardCount`, whose cause is the count's error. When Fluxer later closes a child's shard with close code 4011 because the bot outgrew the plan, the supervisor stops every child, counts again and starts children for a larger plan, logging a `supervisor.resharded` Warn. After 3 such moves within an hour, or at 16,384 shards, it fails with reason `closed` instead.
+  The `identify.coordinator` supervisor option accepts the same `IdentifyCoordinator` a client accepts in `sharding.identify`, so supervisors on several hosts can share Fluxer's Identify budget. The parent asks it before every grant and adds no spacing of its own, and a refused permit is logged at Error with code `supervisor.identifyPermitFailed` while the child retries like after a network failure.
+  Supervised children can keep resumable sessions across a deploy with `clientOptions.sharding.sessions` in `supervisor.child.run`. A shard plan or identify coordinator in that `sharding` object is rejected with `ConfigurationError`, because the parent assigns shards and paces Identify.
+  Each child now sends its client diagnostics (gateway latency, shard states, REST queue, cache use and counters) to the parent when it finishes configuration and then every `diagnosticsIntervalMs`, 5,000 ms by default. The `status()` method shows the latest snapshot in the new `diagnostics` field of each child.
+  `SupervisorChildDiagnostics` and `SupervisorChildSharding` are new public types. `ConfigurationError` can name the new fields `processes`, `shardsPerProcess` and `diagnosticsIntervalMs`, and code that switches over every `SupervisorError` reason needs a case for `shardCount`
+- 7733b23: Add `@neontechspace/fluxerly/testing` and `@neontechspace/fluxerly/effect/testing` for application tests that need no network, token or Fluxer account.
+  The `createTestClient` function returns a real client wired through the `transport` option to an in-memory Fluxer, together with controls: The `ready()` control connects through a protocol-v1 fake gateway, `emit(type, payload, { shardId })` delivers a wire dispatch such as `MESSAGE_CREATE` through the SDK's own decoders, caches and handlers, and `disconnect({ shardId, code })` closes a shard's connection so the client resumes, or stops for a fatal close code.
+  The `user` and `heartbeatIntervalMs` settings choose the bot account reported in READY and the HELLO heartbeat interval.
+  The `rest.respond(matcher, response | handler)` control answers HTTP requests matched by a `"METHOD /path/:param"` pattern, a RegExp or a `{ method, path }` object, `requests()` and `commands()` record what the client sent without its token or Authorization header, `logs()` captures log records at the configured level while still calling application sinks, and `counters()` reads the diagnostics counters.
+  Unmatched requests receive a Fluxer-shaped 404 and a `testing.unmatchedRequest` Warn record.
+  The native `createTestClient` is scoped: Closing its Scope shuts the client down and closes the transport, while the default client uses `shutdown()` or `await using`.
+  Both entry points share `fixtures`, `createFixtures` and `fixtureToken`: Deterministic snake_case wire builders for users, the bot user, communities, GUILD_CREATE bodies, channels, roles, members and messages whose defaults refer to one community, channel and author
+
+    The `createTestBot` function tests a bot written for `runBot` as written. It takes the bot's own options object, registers its `events` and `commands` with the same handler contexts, delivery defaults and command router as `runBot`, and runs `setup` once in `ready` before connecting. The `signal`, `processSignals`, `reportFailure` and `drainMs` settings are accepted and ignored, and an undefined `token` uses the fixture token.
+    A misspelled or unsupported option key throws `ConfigurationError` with a hint naming the closest key that `createTestClient` or `createTestBot` accepts, as `createClient` does. A failed setup rejects `ready` with `ApplicationError`. The result is the usual test client, typed `TestBot` in the Effect entry point
+
+    Tests wait without building their own promises or sleeping.
+    The `TestRoute.next()` control returns the next request a registered response answered, in order, including one that arrived before the call.
+    The `idle()` control waits until no handler or command is running and no request is pending, which confirms that the bot did nothing after an emitted event.
+    Both fail with `TestTimeoutError` after `timeoutMs`, default 2,000 ms, and the native entry point returns them as Effects.
+    Their timers stay real when a test fakes timers, for example with `vi.useFakeTimers()`. The SDK runs on `setImmediate`, so fake timers must leave it real, and `idle()` rejects with `ConfigurationError`, or dies with it in the native entry point, instead of settling while no handler can run
+
+    A test client fails the test when application code failed without a handler, such as an event handler or command that threw, or returned a failed Result such as a rejected reply, while no `onError` hook was registered.
+    The default `shutdown()` and `await using` disposal reject with `UnhandledTestFailuresError`, which lists the Error records of those failures.
+    The native `shutdown()` fails with it, and closing the scope that created the test client dies with it.
+    Each failure is reported once, so a later shutdown succeeds.
+    A test that makes application code fail on purpose reads the failure from the `failures()` control, which marks it as expected, or handles it with `onError`
+
+- 7733b23: Add the advanced `transport` client option. Its `fetch` and `webSocket` settings replace the HTTP and WebSocket implementations, for example for proxies, instrumentation or tests, and `userAgent` replaces the User-Agent header.
+  Replacements receive every client request, including instance discovery, REST, signed upload parts, attachment downloads and gateway connections. Invalid values throw `ConfigurationError` naming the field in the default API and are defects in the Effect API.
+  Bot, webhook and OAuth clients now send `User-Agent: Fluxerly.js/<version> (+https://fluxerly.neontechspace.com)` with every HTTP request and gateway handshake. A configured `transport.userAgent` replaces it for a bot client.
+  Custom WebSocket factories receive the handshake headers, including the User-Agent, in `WebSocketOptions.headers`
+
+### Patch Changes
+
+- 7733b23: TypeScript now reports a mistake in one argument descriptor of `registerMany` or the keyed `commands` object of `runBot`, such as `{ type: "int" }`, on that descriptor with the list of valid types, and the other commands keep their inferred `values`. Previously the error named the whole schema and every command lost its value types
+- 7733b23: Expire entries in every cache category through an expiry heap and reschedule the expiry timer only when the next deadline changes, so timed cache writes no longer scan every retained entry
+- 7733b23: A caller AbortSignal whose `addEventListener` throws no longer leaves the `runBot` SIGINT and SIGTERM listeners installed. The `runBot` function now registers the caller signal listener before its process signal listeners and removes it after them
+- 7733b23: The `display.name` helper accepts a message author directly. Its user parameter now allows an absent `displayName`, as on received message authors, and falls back to the username
+- 7733b23: Start faster by importing each Effect module the SDK uses from its own `effect/<Module>` subpath instead of the `effect` package index, which loads every Effect module.
+  Importing `@neontechspace/fluxerly` now loads 87 Effect modules instead of 203, and `@neontechspace/fluxerly/effect` loads 133
+- 7733b23: Loading the package with `require()` now fails with an error explaining that the SDK is ESM-only and how to switch the project to `import`
+- 7733b23: Pace presence, member-subscription, member-chunk, count and `gateway.send` commands on each gateway connection to at most 500 in any 60-second window, sent in order, so they stay within Fluxer's budget of 600 payloads per connection instead of closing it with 4008. Heartbeats, Identify and Resume are never delayed behind them
+- 7733b23: Event handlers use much less CPU while a backlog waits for a free handler slot
+- 7733b23: Keep a sent message in the message cache when its gateway echo arrives before the HTTP response.
+  Fluxer omits the community ID, `guild_id`, from message HTTP responses, and the cache previously treated that difference as a conflict and dropped the message.
+  Other differences between overlapping observations still remove the cached message
+- 7733b23: Read each message input field once when sending, replying, editing, forwarding, sending direct messages or executing webhooks, so the validated value is the one sent.
+  A getter on `content`, `flags`, `embeds`, `stickerIds`, `messageReference`, an `allowedMentions` switch or an attachment field can no longer pass validation with one value and send another.
+  Other operations read caller arrays and options once too. The `messages.deleteMany`, `guilds.fetchCounts`, `channels.fetchMemberCounts` and `presence.setMembers` methods copy their IDs once and use the validated copy.
+  Cache entry limits, event wait options, presence input, pagination, search, member chunk, message cleanup, permission, instance resolution and attachment download options, webhook client options, supervisor options and client cache and upload settings read each field once
+- 7733b23: Keep the original OAuth response cleanup failure when reader cancellation or release fails, as REST and discovery cleanup already do. The native Cause holds it as the defect, the default API's `SdkDefect` holds it as its cause, and several failures arrive as one `AggregateError`. Response bodies never become part of it
+- 7733b23: Return the received failure at once when a GET retry after a network error or HTTP 500, 502, 503 or 504 could not start before the operation deadline, such as a long `Retry-After`. Such a read previously waited for the whole deadline and failed with reason `timeout`
+- 7733b23: Ship JavaScript source maps that point to the package's `src/` files instead of embedding a second copy of every source file, which reduces the installed size.
+  Stack traces with `--enable-source-maps`, debuggers and go-to-source still resolve to the original TypeScript
+- 7733b23: Large sharded bots now start within the default startup deadline. When a client owns several shards and has no `sharding.identify` coordinator, the SDK spaces new-session Identify commands by one second, as before, and now adds one second to the startup deadline for each shard after the first, so this spacing alone never fails startup. An Info record with code `lifecycle.startupDeadline` states the extended deadline
+- 7733b23: Keep the original thrown value of an attachment stream cleanup failure that no caller observed. Client shutdown reports up to 64 retained failures with their values, and later ones are counted without their values
+- 7733b23: In the default API, a `configure` callback of `supervisor.child.run` that throws or rejects makes `child.run` reject with `SdkDefect` code `application.defect`. Its cause is an `ApplicationError` with source `supervisor child configure`, whose own cause is the original value
+
+## 1000.0.0-rc.0
+
+### Major Changes
+
+- 6eaecbf: Require the exact Effect peer `4.0.0-rc.117` instead of `4.0.0-rc.115`. Update the application's Effect dependency and lockfile together with the SDK, including applications using only the default API
+
+    Expand received message context with immutable partial-user metadata, non-notifying referenced users, explicit-emoji classifications and one resolved reply level without hidden requests. The `referencedMessage` type is now `ReferencedMessage`, not an address-only `MessageReference`. Hand-authored message fixtures must supply the resolved message shape or omit the optional field. Address-only operations can continue to use `MessageReference`. Additional retained context counts toward configured cache and collector byte budgets
+
+    Add explicit attachment URL refresh and endpoint-specific audit reasons through both APIs. Refresh preserves exact signed strings and does not download attachments. OAuth preflight now rejects overlong or noncanonical opaque values rather than changing them and bounds supplied scope arrays to 256 entries before deduplication. Member-role replacement enforces provider signed-identifier bounds
+
+    Add a plain JavaScript structured logger adapter, opt-in bounded stage measurements and aggregate event-work diagnostics. Measurements remain off by default, native Effect retains caller logging context, and applications retain responsibility for asynchronous sink delivery and aggregate admission policy
+
+    Improve resource-aware refill pacing, unrelated user and DM cache reads, incremental cache byte accounting and concurrent member-search preflight without replaying ambiguous writes. Scope logical scheduling to the owning Effect clock while retaining separate host-safety watchdogs
+
+    Native owner-backed gateway, REST, collector, member-stream, cache and presence timing now follows the Clock supplied when the client is created. Applications overriding logical time must create the client under that Clock rather than replacing it only around a later operation. Ownerless utilities retain their documented executing-clock behavior
+
+### Minor Changes
+
+- 139f4dc: Add atomic keyed command batches with per-command argument inference, plus command-context reply helpers that bind the incoming message and handler cancellation
+- ada1d09: Add an optional `runBot` runner to both SDK entry points for critical subscriptions, graceful shutdown and opt-in process signal handling
+
+    Configure event handlers in one object, with automatic subscription registration, access to the full client and a message reply helper. Keep the explicit installer and low-level APIs for custom lifetime and subscription control
+
+    Keep native Effect context and Cause information while the default API returns expected failures as ResultAsync and sanitizes defects
+
+### Patch Changes
+
+- 139f4dc: Include standalone JavaScript, TypeScript and native Effect bot starters using the public SDK runner for critical subscriptions and awaited cleanup
+
+    Clarify ordinary handler Promise ownership and add checked-JavaScript consumer coverage and symptom-based troubleshooting using existing diagnostics
+
+- 5f6b6dd: Refresh the package README with matching JavaScript, TypeScript and Effect-native starter setup, explicit lifecycle ownership and installed Effect version guidance
+- 01caebf: Contain accidentally returned Promise and thenable rejections in the default API's Effect logger adapter, matching the structured adapter and documented synchronous logging contract without adding asynchronous delivery or flushing guarantees
+- 139f4dc: Contain accidentally returned rejected promises and thenables from structured logging callbacks without changing SDK operation outcomes
+- 01caebf: Preserve inherited and non-enumerable command fields during batch registration in both APIs, so supplied guards, argument schemas, cooldowns and rejection callbacks cannot silently disappear
+
+    Snapshot recognized command and cooldown fields before validation and retain those same values, preserving atomic registration and preventing changing getters from replacing validated policies
+
+- 6eaecbf: Align request text validation with Fluxer's field-specific normalization and UTF-16 limits without rewriting accepted input
+
+    Preserve global rate-limit pauses when error bodies are unavailable and learn server rate-limit buckets with bounded, resource-aware tracking
+
+    Bound complete gateway messages before decoding, including fragmented frames, and reject invalid UTF-8 through the transport
+
+    Keep attachment reads responsive to cancellation and deadlines when sources repeatedly yield empty chunks
+
+    Use ordinary JavaScript and TypeScript extensions inside ESM package scopes while retaining the existing public package entry points
+
+- 01caebf: Treat runner-initiated client closure as normal when stopping a bot, while preserving run and cleanup failures
+
+    Preserve combined native failures and sanitized default-API failure reasons when an operation and cleanup both fail
+
+## 1000.0.0-canary.1
+
+### Minor Changes
+
+- 1afd073: Preserve provider-supplied guild context as optional `guildId` on `messageDelete`, `messageDeleteBulk` and `channelPinsUpdate` payloads through both APIs. No channel lookup or cache inference is added, and omission does not establish that the event came from a private channel
+- 1afd073: Add `GuildCreate.isNewJoin` to distinguish provider-reported joins from startup and recovery availability snapshots through both APIs. Existing `guildCreate` delivery and `connect()` readiness remain unchanged
+
+    Classification requires a bot gateway that supplies Fluxer's availability marker. Legacy instances that omit it for startup snapshots cannot be classified reliably, and a join dispatch may replay during Resume
+
+### Patch Changes
+
+- 1afd073: Reject malformed array entries using their indexed values while preserving documented local bounds
+
+    Reject impossible calendar dates in embed timestamps, pin cursors, guild history cutoffs and status expiry before dispatch or retention. Apply the same calendar validation to received message, pin, channel, guild, member, invite, ban and discovery timestamps while preserving each field's existing timezone and precision rules
+
+- 1afd073: Expose Fluxer's recorded positive member-ban message-deletion duration through audit-log REST reads and gateway events
+- 1afd073: Honor inherited and non-enumerable audit-log iterator bounds, preserving requested cursors and enforcing page limits through both APIs
+- 1afd073: Keep malformed nested allowed-mention selections and embed values intact when building message inputs so message-operation validation rejects them before a request starts
+- 1afd073: Preserve inherited and non-enumerable supported structural properties when builders snapshot embeds, attachments, message references and allowed mentions. Builders retain unknown own enumerable fields for message-operation validation and attachment source references
+- 1afd073: Accept voice-channel bitrate requests through 384,000 bits per second and return the value applied by Fluxer
+- 1afd073: Identify affected generic event subscriptions in safe fallback diagnostics
+- 1afd073: Remove unsupported message-search cursor inputs and result cursors. Traverse numbered pages with a fixed page size, report the provider's page ceiling explicitly and reject results with missing or unrelated channel context
+- 1afd073: Reject array-valued OAuth operation options before discovery or request dispatch
+- 1afd073: Preserve unexpected OAuth construction failures as defects attributed to oauth.create, with configuration details kept private
+- 1afd073: Keep OAuth consent, code exchange and revocation requests aligned with the values that passed local validation
+- 1afd073: Reject role and channel permission writes above Fluxer's signed 64-bit maximum while preserving unsigned 64-bit response values
+- 1afd073: Prevent stale private-conversation snapshots from surviving overlapping direct-message mutations
+- 1afd073: Accept static and animated custom-emoji markup in reaction requests and collectors. Parsed custom emoji, guild emoji snapshots and received reaction emoji now share the same input normalization across both APIs, including Unicode event values. Custom collectors continue matching by emoji ID after a rename
+- 1afd073: Validate bounded resource input arrays from one indexed snapshot before encoding or dispatching requests
+- 1afd073: Preserve HTTP rejection status and cleanup defects when releasing an error-response reader fails, instead of reporting an ordinary network error
+- 1afd073: Preserve native shutdown interruption and cleanup-defect reasons without exposing a connection failure through shutdown. Keep both classifications in sanitized default-API defects
+- 1afd073: Preserve inherited and non-enumerable client settings in both supervisor child APIs, so an explicitly selected instance is not silently replaced by hosted Fluxer. Reject inherited token and sharding overrides as well as own-property overrides
+- 1afd073: Capture message targets, search scopes and traversal bounds, pin and reaction-user cursors, and reaction emoji identities once before validation and dispatch, preventing later caller-controlled property reads from changing an accepted request
+- 1afd073: Keep webhook create and edit requests aligned with the settings that passed local validation
+
+## 1000.0.0-canary.0
+
+### Patch Changes
+
+- Initial canary release of Fluxerly.js for testing and feedback