yuzuha 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -21,6 +21,50 @@ documentos. Veja a [política completa](VERSIONING.md).
 
 </details>
 
+## v0.2.0 · 02/11/2026
+
+Embeds completos em uma API só, nos modos nativo e function mode, com uma matriz automática de paridade com o SDK. Esta atualização da biblioteca Yuzuha foi preparada em 02/11/2026 (v0.2.0); a tag Git `v0.2.0` aponta para esta versão.
+
+- `Embed` aceita `url`, `timestamp`, `author` com ícone e link, `footer.iconURL`, texto alternativo em imagem e miniatura, e `fields[].inline` opcional. Na função `$color` e em `$embedFromObject`, a cor aceita `#RRGGBB`, tupla `r,g,b` ou nome simples; o tipo `Embed` nativo continua recebendo número. `embed()` valida um embed tipado na API nativa e `yuzuha/sdk` continua expondo o `EmbedBuilder` do SDK.
+- Mensagens aceitam até 10 embeds, `tts`, `stickerIds`, `flags`, `allowedMentions` e `reply` na API nativa. O padrão continua sem menções e sem ping ao autor respondido. Relaxar menções exige `MentionEveryone` do autor, e TTS exige `SendTtsMessages`.
+- Catorze funções novas: `$url`, `$embedTimestamp`, `$author`, `$footerIcon`, `$imageAlt`, `$thumbnailAlt`, `$fields`, `$addField`, `$removeField`, `$editField`, `$embedFromObject`, `$embeds`, `$addEmbed` e `$messageOptions`. `$field` aceita valor vazio quando é inline.
+- `$fetchMessage` e `$messages` devolvem `embeds` normalizados, com `type`, `provider`, `video`, `audio`, `nsfw` e `children` somente leitura.
+- Mudança incompatível: `MessageInfo.embeds` é obrigatório para implementações próprias de `MessagesResources`. Objetos de mensagem em script rejeitam chaves desconhecidas, que antes viravam embed sem validação. Veja [VERSIONING.md](VERSIONING.md#migrar-para-020).
+- `npm run docs:generate` gera [PARITY-MATRIX.md](docs/PARITY-MATRIX.md), que classifica cada export do SDK como coberto por script, coberto pelo código nativo, só-SDK ou lacuna. Um teste falha quando o SDK ganha export sem área.
+- Catálogo do function mode: de 322 para **336** funções. [FUNCTION-GAPS.md](docs/FUNCTION-GAPS.md) foi atualizado com a contagem real.
+
+## v0.1.9 · 29/10/2026
+
+Composição opcional de cartões para comandos, eventos e function mode, com fontes locais e renderização isolada. Esta atualização da biblioteca Yuzuha foi preparada em 29/10/2026 (v0.1.9).
+
+- `yuzuha/canvas` oferece builder tipado para texto, imagens, avatares, formas, gradientes, sombras, badges e progresso. A raiz e o function mode continuam importáveis sem instalar `@napi-rs/canvas`; o backend carrega somente no processo filho durante a renderização.
+- `ctx.canvas.send` e `bot.contextEvent` permitem anexar imagens em comandos e eventos sem mensagem. O canal é explícito quando o evento não o fornece.
+- Doze funções `$canvas*` mantêm cenas privadas por execução e elevam o catálogo canônico de 310 para **322**. Quotas, cancelamento e limites atravessam `$try`.
+- Inter 4.1 Regular e Bold acompanham os arquivos originais e a licença OFL. Fontes próprias podem vir de bytes, aliases configurados ou HTTP submetido à política do contexto.
+- Canvas e Sharp compartilham no máximo dois processos simultâneos, sem fila implícita. Canvas não depende de Sharp; `yuzuha/images` preserva seu contrato.
+- Perfil, boas-vindas e ranking têm versões JS, TS e function mode e geram nove PNGs offline. O tarball verifica imports sem os peers e renderização real com Canvas sem Sharp.
+- SDK 3.3.0, Node >=22.13 e schema persistido 2 permanecem compatíveis.
+
+## v0.1.8 · 28/10/2026
+
+Bases de bots, buscas e páginas do Fluxer.js, com autorização compartilhada e correções de limites, streams e cooldowns. Esta atualização da biblioteca Yuzuha foi preparada em 28/10/2026 (v0.1.8).
+
+- A CLI oferece sete bases JS/TS com `templates` e `init --template`: simple, multifunctional, moderation, community, economy, entertainment e utility. A multifuncional reúne 24 comandos raiz; os projetos incluem configuração, exemplos e testes offline. O scaffold padrão e `--functions` continuam disponíveis.
+- A distribuição preserva o modo executável da CLI e testa a instalação, os tipos e o dispatch dos 14 pares de base/linguagem a partir do tarball.
+- Quatro funções novas levam o catálogo de 306 a **310**: `$searchMessagesAdvanced`, `$pinnedMessagesPage`, `$reactionUsersPage` e `$threadMember`. Seus recursos e tipos também estão disponíveis na API nativa.
+- A busca aceita filtros de conteúdo, frases, autores, canais, menções, anexos, IDs e ordenação sem exigir texto. A validação é compartilhada entre scripts e adaptador, copia arrays e limita as opções a 32 KiB; a busca anterior continua disponível, incluindo cursor vazio.
+- Páginas de fixadas preservam ordem de fixação, timestamps, `hasMore` e cursor ISO. Páginas de reações preservam `hasMore`/`nextAfter`, incluindo respostas legadas em array. A consulta individual de membros de threads inclui flags e metadados de mute, com o autor do contexto como padrão nos scripts.
+- Mutações de emojis e stickers pelo contexto exigem `ManageExpressions` de autor e bot no servidor atual. Criar emoji verifica as permissões antes do download e revalida antes de criar o recurso. Guards não são capturados por `$try`.
+- `$jsonEncode` preserva guards, limites, cancelamento, controle de loops e `PartialModerationError`. Incrementos, remoções/inclusões em arrays e atualizações por caminho verificam a saída antes do commit, preservando valor, TTL e ausência quando recusados.
+- O prazo cooperativo do runtime usa relógio monotônico. Esperas externas sobrepostas ou aninhadas descontam seu intervalo uma única vez, sem conceder tempo duplicado.
+- HTTP valida sub-redes IPv4/IPv6, inclusive IPv4 mapeado, link-local e redes especiais. Literais IPv6 públicos funcionam sem consulta DNS; credenciais na URL e corpos em GET/HEAD são recusados.
+- Redirects preservam os métodos conforme o padrão Fetch e removem cabeçalhos de conteúdo quando descartam o corpo. Respostas binárias copiam chunks reutilizados; cancelamento libera readers mesmo quando a fonte não conclui a limpeza.
+- Anexos por stream mantêm os metadados validados durante a leitura e não deixam um timeout agendado quando a fonte já está bloqueada por outro reader.
+- Deduplicação de mensagens e consultas de cooldown ativo deixam de varrer o mapa de cooldowns. A coleta considera vencimentos e pressão de capacidade; renovação e admissão reutilizam entradas expiradas, mantendo o teto de 100 mil. Flags malformadas geram `GuardError` antes do handler.
+- Um benchmark reproduzível compara a implementação anterior e a atual com amostras intercaladas. O ganho é localizado na manutenção removida; cenários comuns tiveram resultados mistos, registrados sem alegação de aceleração geral.
+- Referências, catálogo do editor, guias e consumidores JS/TS acompanham os novos contratos. O SDK continua fixado em 3.3.0, o schema persistido em 2 e os sete entrypoints permanecem disponíveis.
+- **Adaptação de integrações:** implementações completas próprias de `MessagesResources` devem acrescentar `pinnedPage` e `reactionUsersPage`; `ThreadsResources` deve acrescentar `member`. Comandos antes autorizados apenas pelo bot podem receber `GuardError` nas mutações de expressões. Apesar da numeração patch, esta entrega altera esses contratos; veja [VERSIONING.md](VERSIONING.md) antes de atualizar.
+
 ## v0.1.7 · 23/10/2026
 
 Loops controláveis, comparadores de arrays, regex isolada, decimais exatos e busca pela CLI, com o conteúdo preparado na 0.1.6. Esta atualização da biblioteca Yuzuha foi preparada em 23/10/2026 (v0.1.7).

package/README.md

@@ -7,7 +7,7 @@ Os dois modos compartilham permissões, moderação, estado e recursos.
 O Yuzuha usa **Fluxer.js 3.3.0**. Você continua tendo acesso ao client original
 por `bot.client` e aos exports do SDK em `yuzuha/sdk`.
 
-[0.1.7](CHANGELOG.md) · Node **22.13+** · ESM · [MIT](LICENSE)
+[0.2.0](CHANGELOG.md) · Node **22.13+** · ESM · [MIT](LICENSE)
 
 [Começar](#começar) · [Comandos](#escrever-comandos) · [Recursos](#recursos) · [Testes](#testar-sem-token) · [Documentação](#documentação)
 
@@ -16,7 +16,7 @@ por `bot.client` e aos exports do SDK em `yuzuha/sdk`.
 ### Criar um bot
 
 ```sh
-npx yuzuha@0.1.7 init ./meu-bot --ts
+npx yuzuha@0.2.0 init ./meu-bot --ts
 cd meu-bot
 npm install
 npm run check
@@ -42,7 +42,7 @@ para incluir um comando de exemplo com scripts.
 ### Usar em um projeto existente
 
 ```sh
-npm install yuzuha@0.1.7
+npm install yuzuha@0.2.0
 ```
 
 Use `"type": "module"` no `package.json`. O [guia inicial](docs/QUICKSTART.md)
@@ -84,7 +84,7 @@ export default script({
 });
 ```
 
-O function mode tem **306 funções** para mensagens, guards, moderação, variáveis,
+O function mode tem **336 funções** para mensagens, guards, moderação, variáveis,
 JSON, arrays, loops, eventos e agendamentos. O runtime é ativado ao registrar um
 comando com `code` ou um evento de script.
 
@@ -103,6 +103,7 @@ e a [cobertura](docs/PARITY.md).
 | Dados | Memória, JSON e SQLite; TTL, transações, limpeza e backup/restauração com simulação |
 | Agendamentos | Tarefas persistentes, cron, fusos IANA, pausa/retomada, histórico e retry |
 | HTTP | Texto, bytes, streaming e multipart, com limites, cancelamento e políticas por comando |
+| Canvas | Cartões com texto, avatares, imagens, gradientes, badges e progresso; peer nativo opcional |
 | Música | Lavalink v4 com plugin e ponte de áudio para Fluxer, recuperação, filas editáveis, loop, seek, volume e filtros |
 | Desenvolvimento | CLI, autocomplete e diagnósticos no VS Code, mocks e relógio controlável para testes |
 
@@ -157,6 +158,7 @@ O [índice completo](docs/README.md) reúne os guias e as referências.
 | Programar em JS/TS | [Guia nativo](docs/NATIVE.md), [framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
 | Criar um bot de música | [Lavalink, filas e voz Fluxer](docs/MUSIC.md) |
 | Medir performance | [Benchmarks e comparações com a 0.1.5](docs/BENCHMARKS.md) |
+| Compor cartões e imagens | [Canvas](docs/CANVAS.md) e [transformações de imagem](docs/IMAGES.md) |
 | Escrever scripts `$...` | [Linguagem](docs/LANGUAGE.md) e [referência de funções](docs/FUNCTIONS.md) |
 | Copiar exemplos | [Receitas](docs/COOKBOOK.md) e [código de exemplo](examples) |
 | Usar o editor ou diagnosticar um erro | [VS Code](docs/EDITOR.md) e [problemas comuns](docs/TROUBLESHOOTING.md) |
@@ -196,3 +198,18 @@ Transformações opcionais de imagens e entrada de anexos por stream estão em
 [IMAGES.md](docs/IMAGES.md); consultas por prefixo e cursor em
 [STORAGE.md](docs/STORAGE.md), e limites das integrações em
 [INTEGRATIONS.md](docs/INTEGRATIONS.md).
+
+### Bases de bots
+
+Sete opções: `simple`, `multifunctional`, `moderation`, `community`, `economy`,
+`entertainment` e `utility`. Na cópia local compilada:
+
+```sh
+node dist/cli.js templates
+node dist/cli.js init ../bot-comunidade --template community --ts --local
+```
+
+A multifuncional reúne 24 comandos raiz com embeds e subcomandos, incluindo
+moderação com casos, regras, sugestões, enquetes, moedas virtuais, diversão
+e notas pessoais em DM. Todas as bases aceitam JS/TS e `--functions`, com README
+e testes offline próprios. Veja [BOT-BASES.md](docs/BOT-BASES.md).

package/VERSIONING.md

@@ -1,16 +1,16 @@
 # Versionamento
 
 O Yuzuha aplica o formato Hory ao histórico e usa **SemVer simples** no pacote.
-A versão desta atualização é **0.1.7**.
+A versão desta atualização é **0.2.0**.
 
 ## Pacote e histórico
 
 | Lugar | Formato nesta versão |
 |---|---|
-| `package.json` e entrada raiz de `package-lock.json` | `0.1.7` |
-| Pacote npm e saída de `yuzuha --version` | `0.1.7` |
-| Título do changelog | `## v0.1.7 · 23/10/2026` |
-| Eventual tag Git | `v0.1.7` |
+| `package.json` e entrada raiz de `package-lock.json` | `0.2.0` |
+| Pacote npm e saída de `yuzuha --version` | `0.2.0` |
+| Título do changelog | `## v0.2.0 · 02/11/2026` |
+| Tag Git | `v0.2.0` |
 
 O SDK e a CLI pertencem ao mesmo pacote. Para bibliotecas, a convenção Hory mantém
 SemVer sem `m`, sem seções por superfície e sem sufixos de canal.
@@ -30,7 +30,8 @@ estivermos em `0.x`. Ao chegar a `1.0.0`, mudanças incompatíveis exigem major;
 novas funcionalidades compatíveis, minor; correções compatíveis, patch.
 
 Os exports públicos são `yuzuha`, `yuzuha/functions`, `yuzuha/sdk`,
-`yuzuha/testing`, `yuzuha/tooling`, `yuzuha/music` e `yuzuha/images`. A organização interna de `src/` não cria estabilidade de deep
+`yuzuha/testing`, `yuzuha/tooling`, `yuzuha/music`, `yuzuha/images` e
+`yuzuha/canvas`. A organização interna de `src/` não cria estabilidade de deep
 imports. Schema persistido,
 gramática e funções documentadas também fazem parte da compatibilidade.
 
@@ -40,6 +41,77 @@ gerado por `init` pertence ao consumidor e não precisa acompanhar a biblioteca.
 
 ## Preparar uma atualização
 
+### Migrar para 0.2.0
+
+A 0.2.0 acrescenta campos a `Embed` (`url`, `timestamp`, `author`, `footer.iconURL`,
+alt text em imagem e miniatura), `allowedMentions`, `tts`, `stickerIds`, `flags` e
+`reply` em `Payload`, além de 14 funções de script e a leitura normalizada de embeds
+em `$fetchMessage` e `$messages`. Os exports públicos continuam os mesmos.
+
+Há duas mudanças de contrato, por isso a versão é minor na série `0.x`:
+
+- `MessageInfo.embeds` passou a ser obrigatório. Quem implementa `MessagesResources`
+  própria deve devolver `embeds` (use `[]` se não houver embeds).
+- Objetos de mensagem em script (`$reply`, `$sendMessage`, `$editMessage`) aceitam
+  somente as chaves `content`, `embeds`, `tts`, `stickerIds`, `flags` e `allowedMentions`.
+  Antes, qualquer objeto virava embed sem validação; agora campos desconhecidos são erro.
+
+Menções só relaxam com a permissão `MentionEveryone` do autor, e TTS exige
+`SendTtsMessages`. O padrão continua sem menções e sem ping ao autor respondido.
+
+```sh
+npm install yuzuha@0.2.0
+```
+
+### Migrar para 0.1.9
+
+A 0.1.9 acrescenta `yuzuha/canvas`, `ctx.canvas` e `bot.contextEvent`, além de
+12 funções de script da categoria `canvas`. O pacote continua utilizável sem
+Canvas; para renderizar, instale `@napi-rs/canvas@^1.0.13`. Sem o peer, somente
+a chamada de renderização falha com `CANVAS_DEPENDENCY`. Sharp continua sendo
+opcional e independente. O envio usa `resources.messages.sendBytes` e eventos
+sem canal precisam fornecer `channelID` em `ctx.canvas.send`.
+
+`CanvasConfig` pode registrar bytes de assets e fontes TTF/OTF. As respostas
+HTTP continuam sujeitas à política e ao limite configurado no bot. Canvas e
+transformações Sharp compartilham duas vagas de processo. O schema persistido
+permanece em 2 e o SDK em 3.3.0; não há migração de dados.
+
+```sh
+npm install yuzuha@0.1.9 @napi-rs/canvas@^1.0.13
+```
+
+Veja [CANVAS.md](docs/CANVAS.md) para opções, limites, fontes e exemplos. A
+extensão incluída acompanha a versão 0.1.9.
+
+### Migrar para 0.1.8
+
+A 0.1.8 é uma exceção pontual à regra de versões minor para mudanças de
+contrato na série 0.x. Embora use numeração patch, requer adaptação de
+implementações completas próprias de `Resources` e revisão das autorizações
+de comandos. A regra de compatibilidade acima continua valendo para as
+próximas versões.
+
+- Acrescente `messages.pinnedPage`, `messages.reactionUsersPage` e
+  `threads.member` aos adaptadores completos. Os tipos de retorno são
+  `PinnedMessagesPage`, `ReactionUsersPage` e `ThreadMemberDetails`, exportados
+  pela raiz. `mockResources` continua aceitando overrides parciais.
+- Mutações de emojis/stickers por `ctx.resources.expressions` exigem
+  `ManageExpressions` de autor e bot no servidor do contexto. Código confiável
+  que precisa operar diretamente com a autoridade do bot continua usando
+  `bot.resources` ou `bot.client` explicitamente.
+- HTTP recusa credenciais embutidas na URL, corpos GET/HEAD e destinos nas
+  redes locais/especiais bloqueadas, incluindo IPv4 mapeado em IPv6. Use
+  `Authorization` para autenticação; rede privada exige `allowPrivate: true`
+  explícito. Redirects 301/302 preservam PUT/PATCH/DELETE e 303 preserva HEAD;
+  cabeçalhos de conteúdo são removidos quando o corpo é descartado.
+- As opções de busca recebem validação compartilhada de tipos, IDs, cursores
+  e limites. Texto é opcional na API nativa e em `$searchMessagesAdvanced`;
+  `$searchMessages` mantém sua assinatura e aceita cursor vazio.
+- O catálogo passa a 310 funções. Imports, SDK 3.3.0 e schema 2 permanecem;
+  não há migração de dados em disco. As sete bases da CLI são aditivas e não
+  reescrevem projetos existentes. A extensão incluída acompanha a versão 0.1.8.
+
 ### Migrar para 0.1.7
 
 A distribuição 0.1.7 inclui o conteúdo preparado na 0.1.6 e acrescenta

package/assets/canvas/OFL.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/canvas/ORIGIN.md

@@ -0,0 +1,8 @@
+These unmodified font files are from Inter 4.1, distributed by the upstream
+Inter project under the SIL Open Font License 1.1.
+
+- `Inter-Regular.ttf`: Inter 4.1 Regular
+- `Inter-Bold.ttf`: Inter 4.1 Bold
+- License text: `OFL.txt`
+- Upstream release: https://github.com/rsms/inter/releases/tag/v4.1
+- License source: https://github.com/rsms/inter/blob/v4.1/LICENSE.txt

package/benchmarks/rate-limits.mjs

@@ -0,0 +1,138 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { arch, cpus, platform } from 'node:os';
+import { performance } from 'node:perf_hooks';
+import { RateLimits } from '../dist/framework/rate-limits.js';
+import { YuzuhaError } from '../dist/errors.js';
+
+// Baseline: src/framework/rate-limits.ts at a227759f726420471ade044a3cf9600a6359a668, with TypeScript types removed.
+class BaselineRateLimits {
+  now;
+  seen = new Map();
+  seenKeys = [];
+  seenExpirations = [];
+  seenCursor = 0;
+  cooldowns = new Map();
+  nextSweep = 0;
+
+  constructor(now = Date.now) { this.now = now; }
+
+  sweep(time) {
+    if (time < this.nextSweep) return;
+    for (const [key, until] of this.cooldowns) if (until <= time) this.cooldowns.delete(key);
+    this.nextSweep = time + 1000;
+  }
+
+  duplicate(channelID, messageID) {
+    const time = this.now();
+    this.sweep(time);
+    const key = `${channelID.length}:${channelID}${messageID}`;
+    if ((this.seen.get(key) ?? 0) > time) return true;
+    const previous = this.seenKeys[this.seenCursor];
+    if (previous !== undefined && this.seen.get(previous) === this.seenExpirations[this.seenCursor]) this.seen.delete(previous);
+    const until = time + 60_000;
+    this.seen.set(key, until);
+    this.seenKeys[this.seenCursor] = key; this.seenExpirations[this.seenCursor] = until;
+    this.seenCursor = (this.seenCursor + 1) % 10_000;
+    return false;
+  }
+
+  cooldown(key, duration) {
+    const time = this.now();
+    this.sweep(time);
+    const remaining = (this.cooldowns.get(key) ?? 0) - time;
+    if (remaining > 0) return remaining;
+    if (this.cooldowns.size >= 100_000) throw new YuzuhaError('COOLDOWN_CAPACITY', 'Capacidade de cooldown excedida.');
+    this.cooldowns.set(key, time + duration);
+    return 0;
+  }
+}
+
+const config = { samples: 7, normalIterations: 50_000, loadedIterations: 1000, entries: 25_000,
+  warmup: 2000, normalClockStepMs: 0, loadedClockStepMs: 1000, cooldownMs: 1_000_000_000_000 };
+let json = false;
+for (let index = 2; index < process.argv.length; index++) {
+  const option = process.argv[index];
+  if (option === '--json') { json = true; continue; }
+  const name = { '--samples': 'samples', '--normal-iterations': 'normalIterations', '--loaded-iterations': 'loadedIterations', '--entries': 'entries' }[option];
+  const value = Number(process.argv[++index]);
+  const max = { samples: 50, normalIterations: 90_000, loadedIterations: 100_000, entries: 100_000 }[name];
+  if (!max || !Number.isSafeInteger(value) || value < 1 || value > max) throw new Error(`Opção inválida: ${option}.`);
+  config[name] = value;
+}
+
+const scenarios = [
+  { name: 'duplicate/same-tick', operation: 'duplicate', loaded: false },
+  { name: 'cooldown/new-same-tick', operation: 'new', loaded: false },
+  { name: 'cooldown/active-same-tick', operation: 'active', loaded: false },
+  { name: 'duplicate/loaded-clock-steps', operation: 'duplicate', loaded: true },
+  { name: 'cooldown/loaded-clock-steps', operation: 'active', loaded: true },
+];
+
+function fixture(Implementation, scenario, iterations) {
+  let now = 0;
+  const limits = new Implementation(() => now);
+  const step = scenario.loaded ? config.loadedClockStepMs : config.normalClockStepMs;
+  if (scenario.loaded) for (let index = 0; index < config.entries; index++) limits.cooldown(String(index), config.cooldownMs);
+  else if (scenario.operation === 'active') limits.cooldown('0', config.cooldownMs);
+  const outputs = new Array(iterations);
+  return {
+    run() {
+      for (let index = 0; index < iterations; index++) {
+        now += step;
+        outputs[index] = scenario.operation === 'duplicate' ? limits.duplicate('channel', String(index))
+          : limits.cooldown(scenario.operation === 'active' ? '0' : String(index), config.cooldownMs);
+      }
+    },
+    validate() {
+      for (let index = 0; index < iterations; index++) {
+        const expected = scenario.operation === 'duplicate' ? false
+          : scenario.operation === 'active' ? config.cooldownMs - step * (index + 1) : 0;
+        assert.equal(outputs[index], expected);
+      }
+      return outputs;
+    },
+  };
+}
+
+const median = values => [...values].sort((a, b) => a - b)[Math.ceil(values.length / 2) - 1];
+const summarize = (samplesMs, iterations) => ({ samplesMs, medianMs: median(samplesMs),
+  operationsPerSecond: iterations * samplesMs.length / (samplesMs.reduce((sum, value) => sum + value, 0) / 1000) });
+const implementations = [['baseline', BaselineRateLimits], ['current', RateLimits]];
+const results = [];
+for (const scenario of scenarios) {
+  const iterations = scenario.loaded ? config.loadedIterations : config.normalIterations;
+  for (const [, Implementation] of implementations) {
+    const warmup = fixture(Implementation, scenario, Math.min(config.warmup, iterations));
+    warmup.run(); warmup.validate();
+  }
+  const samples = { baseline: [], current: [] };
+  for (let sample = 0; sample < config.samples; sample++) {
+    const outputs = {};
+    for (const [name, Implementation] of sample % 2 ? [...implementations].reverse() : implementations) {
+      const trial = fixture(Implementation, scenario, iterations);
+      global.gc?.();
+      const start = performance.now();
+      trial.run();
+      samples[name].push(performance.now() - start);
+      outputs[name] = trial.validate();
+    }
+    assert.deepEqual(outputs.current, outputs.baseline);
+  }
+  const baseline = summarize(samples.baseline, iterations), current = summarize(samples.current, iterations);
+  results.push({ name: scenario.name, iterations, entries: scenario.loaded ? config.entries : scenario.operation === 'active' ? 1 : 0,
+    clockStepMs: scenario.loaded ? config.loadedClockStepMs : config.normalClockStepMs, baseline, current,
+    medianChangePercent: (current.medianMs / baseline.medianMs - 1) * 100 });
+}
+const hash = input => createHash('sha256').update(input).digest('hex');
+const report = { suite: 'rate-limits', date: new Date().toISOString(), node: process.versions.node, platform: platform(), arch: arch(),
+  cpu: cpus()[0]?.model, gc: typeof global.gc === 'function', baselineCommit: 'a227759f726420471ade044a3cf9600a6359a668',
+  sourceHashes: { baselineImplementation: hash(BaselineRateLimits.toString()), currentDist: hash(await readFile(new URL('../dist/framework/rate-limits.js', import.meta.url))),
+    benchmark: hash(await readFile(new URL(import.meta.url))) }, config,
+  scope: 'Local synthetic workloads; advancing the fake clock simulates sweep boundaries, not wall-clock throughput of a bot.', results };
+console.log(json ? JSON.stringify(report, null, 2) : [
+  `RateLimits · Node ${report.node} · ${report.cpu} · ${report.platform}/${report.arch}`,
+  report.scope,
+  ...results.map(row => `${row.name}: ${row.baseline.medianMs.toFixed(3)} -> ${row.current.medianMs.toFixed(3)} ms; ${row.iterations} operations; clock +${row.clockStepMs} ms/operation`),
+].join('\n'));