yuzuha 0.0.0-stage → 0.1.5

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+O Yuzuha segue [Semantic Versioning](https://semver.org/) e
+[Keep a Changelog](https://keepachangelog.com/). Biblioteca, SDK reexportado e CLI
+são entregues no mesmo pacote npm.
+
+<details>
+<summary>Para saber mais sobre o versionamento, expanda aqui.</summary>
+
+As versões do pacote usam SemVer simples, como `0.1.0`. Os títulos do histórico
+e eventuais tags Git incluem `v`, como `v0.1.0`.
+
+O Yuzuha é uma biblioteca com CLI incluída. Não há sufixo `m`, divisão por
+superfícies ou canais `-alpha`, `-beta` e `-stable` no histórico. A série `0.x`
+continua em desenvolvimento inicial; ausência de sufixo não significa validação
+de operação no Fluxer real.
+
+Cada entrada usa `## vX.Y.Z · DD/MM/YYYY`, um resumo humano e a lista de mudanças.
+Publicar um pacote ou criar uma tag é uma operação separada da atualização destes
+documentos. Veja a [política completa](VERSIONING.md).
+
+</details>
+
+## v0.1.5 · 22/10/2026
+
+Subcomandos e flags tipadas, ajuda derivada das definições e testes nativos com relógio controlável, com projetos gerados prontos para compartilhar. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.5).
+
+- Comandos aceitam árvores de subcomandos e flags com inferência de tipos, aliases, valores entre aspas e separador `--`. As restrições dos grupos são preservadas na execução dos filhos.
+- Ajuda detalha argumentos, flags, escolhas, valores padrão, exemplos e subcomandos. Erros de entrada incluem o uso esperado; metadados também ficam disponíveis no JSON de `check`.
+- `createTestBot`, em `yuzuha/testing`, reúne transporte, recursos simulados, estado isolado, mensagens, erros e resultados. O relógio controlável permite verificar cooldown, TTL e tarefas sem aguardar tempo real; o descarte aguarda o encerramento.
+- `init` usa dependência npm por padrão; `--local` seleciona a instalação local explicitamente. Projetos JS/TS incluem teste offline de exemplo e `npm test`.
+- SDK permanece em 3.3.0 e o catálogo mantém 288 funções. Os contratos e exemplos novos são compartilhados com a documentação e a validação do pacote instalado.
+
+## v0.1.4 · 22/10/2026
+
+Eventos em scripts, cron com fuso, HTTP em streaming e ferramentas de manutenção e testes offline, com autorização compartilhada nos recursos. Esta atualização da biblioteca Yuzuha foi preparada em 22/10/2026 (v0.1.4).
+
+- **19 funções novas**, totalizando **288**: eventos, cron, HTTP multipart, conjuntos de arrays, bytes, percentuais, conversão exata de bases, pré-carga de mensagens e criação de emojis em lote. O SDK permanece em **3.3.0**.
+- Mutações de cargos, canais e webhooks em `ctx.resources` verificam autor e bot, servidor, permissões locais e hierarquia aplicável, tanto em scripts quanto em comandos nativos. IDs autorizados são usados na operação final; tokens de webhook não dispensam os guards.
+- `bot.scriptEvent` e `plugin.scriptEvents` atendem seis eventos do SDK com dados próprios e imutáveis. Payloads parciais mantêm campos ausentes como `null`; reply exige mensagem disponível. Cancelamento, erros, logs e encerramento seguem o ciclo de vida do bot.
+- Scheduler aceita cron de cinco campos, fusos IANA, políticas de execuções atrasadas, concorrência limitada e jitter de retry. Mantém claims, heartbeat e proteção de efeitos parciais; trata transições de horário de verão e expressões sem ocorrência válida.
+- `HttpService.stream` entrega o corpo incrementalmente, mantendo timeout, limite e cancelamento durante a leitura. Multipart aceita texto e bytes; políticas por comando só restringem hosts e limites existentes. `$try` continua sem capturar guards e cancelamento.
+- Transações reduzem cópias redundantes mantendo isolamento e rollback. `StateMaintenance` oferece estatísticas, limpeza paginada por cursor e backup versionado; restore valida conflitos e claims antes de aplicar, com simulação por padrão.
+- CLI acrescenta `lint --json`, exportação de catálogo de plugins, `test` com cenários JSON offline e `data` para manutenção. Lint e cenários não importam código do usuário; exportar funções de uma config exige indicar o arquivo confiável explicitamente.
+- Ports próprios precisam implementar os novos métodos e o campo `RoleInfo.managed`; o SDK fixado não expõe esse metadado. As mudanças de autorização e migração estão em [VERSIONING.md](VERSIONING.md).
+- Correções de integração preservam IDs reais em eventos sem cache, recusam autor ausente antes de consultas ou dados de usuário, rejeitam arrays esparsos antes de persistir e descartam corpos HTTP também em falhas de redirecionamento.
+- Catálogo do editor, referência gerada, documentação e testes do pacote instalado atualizados. Instruções de instalação pelo npm e de uso local incluídas; a validação funcional é offline, sem login no Fluxer.
+- Manifest usa o caminho normalizado da CLI para evitar avisos no publish; o teste do pacote instalado também verifica `npm exec --offline -- yuzuha --version`.
+
+## v0.1.3 · 21/10/2026
+
+Histórico de tarefas, diagnósticos no editor, variáveis com expiração e mais recursos do Fluxer, com cancelamento e logs integrados. Esta atualização da biblioteca Yuzuha foi preparada em 21/10/2026 (v0.1.3).
+
+- **24 funções novas**, totalizando **269**: moderação de voz, threads ativas/arquivadas, canais de link, avisos de conteúdo, perfis, contagens ao vivo, TTL, transações declarativas e histórico/reexecução de tarefas.
+- `ctx.mod.move`, `mute` e `deafen` compartilham guards de autor/bot, hierarquia, proteção de alvos e casos; falhas parciais continuam escapando de `$try` e impedem retry.
+- Threads arquivadas preservam membros, paginação e cursores; perfis normalizados e contagens de gateway incluem timeout e cancelamento. O SDK permanece em **3.3.0**.
+- Scheduler persiste histórico limitado, oferece consulta de falhas e reexecução manual segura, renova a claim por heartbeat e encaminha falhas de manutenção aos hooks. Encerramento cancela e aguarda a finalização das execuções rastreadas.
+- Variáveis recebem TTL consistente em memória, JSON e SQLite; `userFor` escolhe outro usuário explicitamente. `$dataTransaction` executa até 100 operações entre escopos com rollback, validação e limite de saída antes do commit.
+- Editor aponta sintaxe, nomes desconhecidos e aridade em arquivos e strings JS/TS, com posições UTF-16. Catálogos JSON de plugins atualizam sugestões e diagnósticos sem importar código do workspace.
+- HTTP e collectors recebem automaticamente `ctx.signal`; cancelamento encerra esperas, remove listeners e não é capturado por `$try`. Respostas HTTP que chegam após o cancelamento têm o corpo descartado.
+- `onLog` fornece eventos estruturados com correlação, resultado e duração, sem incluir entrada de comandos, mensagens de erro ou tokens automaticamente. Não há serviço de telemetria.
+- Contextos criam os adaptadores de HTTP/collectors sob demanda. Benchmarks acrescentam catálogo grande, payload maior, séries de memória e comparação com baseline compatível, com limiar opcional de regressão.
+- Documentação, exemplos de migração e verificações do pacote/editor atualizados. Validação continua offline, sem login ou publicação.
+
+## v0.1.2 · 21/10/2026
+
+Busca e envio de mensagens, gestão de membros e threads, tarefas editáveis, transações entre chaves e ferramentas de desenvolvimento. Esta atualização da biblioteca Yuzuha foi preparada em 21/10/2026 (v0.1.2).
+
+- **21 funções novas**, totalizando **245**: mensagens diretas, encaminhamento, buscas, apelidos, servidor, threads, convites/vanity, clonagem, anexos e controles de agendamento.
+- Histórico com cursores `before`, `after` ou `around`; buscas preservam paginação e o estado de indexação do Fluxer.
+- `ctx.members.setNickname` e `$nickname` compartilham motivo, permissões do autor/bot, hierarquia e proteção do dono. `ctx.members.search` acrescenta busca por nome.
+- Edição de servidor e threads, entrada/saída do bot em threads, convites/vanity e clonagem de expressões sobre **@fluxerjs/core 3.3.0**.
+- `$fileBase64`, `$sendFileBase64`, `$sendAttachments` e `sendBytes`/`sendAttachments` nativos: até dez anexos URL/binários na mesma mensagem, com descrições e menções desabilitadas.
+- Scheduler com edição, pausa, retomada e política persistente de retry/backoff por tarefa. Alterações recusam tarefas em execução; scripts só alteram tarefas do mesmo autor e servidor.
+- Falhas de dispatch agora chegam ao scheduler. Guards e moderação aplicada ou parcialmente concluída encerram a tarefa sem retry automático; claims impedem que uma conclusão antiga apague uma tarefa reivindicada novamente.
+- `ctx.data.transaction` oferece operações síncronas entre várias chaves e escopos, com rollback, validação antes do commit e isolamento em memória, JSON e SQLite.
+- `yuzuha doctor [config] [--json]` verifica Node, SDK, configuração, comandos, permissões declaradas, presença de token e acesso ao caminho do store, sem login ou exposição de segredos.
+- Extensão VS Code incluída no pacote e instalador VSIX local: autocomplete, argumentos em snippets, hover e assinatura ativa para `.yz`/`.yuzuha` e strings JS/TS. Catálogo gerado do registro; `yuzuha/tooling` expõe os auxiliares de linguagem.
+- Benchmarks reproduzíveis de dispatch, compilação, avaliação, memória e transações concorrentes, com aquecimento, amostras e JSON. Resultados locais não representam desempenho em rede.
+- Guias de migração, editor, benchmarks e cobertura atualizados; validação offline dos contratos novos e do tarball instalado.
+
+## v0.1.1 · 21/10/2026
+
+Mais recursos do Fluxer.js nos modos nativo e script, operações de arrays e correções de execução, JSON e HTTP. Esta atualização da biblioteca Yuzuha foi preparada em 21/10/2026 (v0.1.1).
+
+- **26 funções novas**, totalizando **224**: reações de mensagens, membros de threads, edição de emojis, criação/edição/exclusão de stickers, posição de canais/cargos e categorias.
+- `$arrayMap`, `$arrayFilter`, `$arraySome`, `$arrayEvery`, `$arrayFind`, `$arrayReduce` e `$arraySortBy`, com expressões reavaliadas por item, curto-circuito, restauração de variáveis e os mesmos orçamentos do runtime. `$loopAccumulator` expõe o acumulador da redução.
+- `$arrayConcat`, `$arrayFlat`, `$arrayChunk`, `$jsonValues` e `$jsonEntries` para compor e consultar dados sem alterar os valores originais.
+- Os recursos de `ctx.resources` compartilham as novas operações com scripts. Listas de usuários de reações e membros de threads aceitam limite e cursor de paginação.
+- `$createEmoji[nome;url]` baixa bytes respeitando a política HTTP e envia base64 ao SDK; corrige o envio da URL como se fosse uma imagem codificada. `ctx.http.requestBytes` permite downloads binários sem conversão UTF-8.
+- HTTP remove credenciais ao seguir redirecionamentos para outra origem, cancela streams que excedem o tamanho permitido e identifica timeout durante a leitura do corpo.
+- Caminhos JSON deixam de seguir propriedades herdadas; `$object` e `$jsonMerge` preservam `__proto__` como dado. Escritas em arrays por caminho aceitam índices de **0 a 9999**, evitando alocações descontroladas.
+- `$range` termina corretamente nos extremos de inteiros seguros; loops verificam a saída entre iterações, e `$loopValue` preserva itens `null`.
+- Deduplicação de valores primitivos em `$arrayUnique` usa um conjunto, mantendo igualdade profunda para objetos. Arquivar e bloquear uma thread usa uma única chamada ao SDK.
+- Resolução de emojis, stickers e cargos preserva erros de transporte; buscas por ID deixam de disparar listagens extras após falha.
+- `mockResources` aceita implementações parciais por método, mantém `this` para campos privados e informa recursos ausentes com `NATIVE_UNAVAILABLE`.
+- Referência gerada, inventário de lacunas, exemplos e testes offline atualizados. O SDK continua fixado em **@fluxerjs/core 3.3.0**; os wrappers ampliam a cobertura sem prometer uma função para cada método do SDK.
+
+## v0.1.0 · 20/10/2026
+
+Primeira versão do Yuzuha como framework para Fluxer.js com function mode opcional. Um bot nativo ganha comandos tipados, guards, estado, moderação, recursos, agendamentos e HTTP sem carregar o runtime de scripts; quem quiser a sintaxe curta ativa `yuzuha/functions`.
+
+- Entrypoint `yuzuha` focado em JS/TS: `Yuzuha`, `defineCommand`, `arg`, eventos, contexto, plugins, middleware, recursos, stores, scheduler, HTTP e `yuzuha/sdk`.
+- Function mode isolado em `yuzuha/functions`: parser, AST, evaluator, `Runtime`, `registerBuiltins`, `script()` e **198 funções**.
+- Builtins registrados sob demanda: comandos nativos não pagam o custo nem expõem a linguagem; `code` ativa o modo automaticamente e `bot.enableFunctions()` permite pré-carregar.
+- Comandos com prefixos, aliases, argumentos tipados, cooldowns, permissões, checks, middleware e recarga atômica de diretórios.
+- Eventos tipados, plugins com comandos/eventos/funções e encerramento idempotente.
+- Moderação compartilhada entre JS/TS e scripts, com permissões efetivas, hierarquia, proteção do alvo e casos por servidor.
+- Recursos de usuários, membros, servidor, banimentos, auditoria, presença, cargos, canais, mensagens, fixados, anexos, convites, webhooks, emojis, stickers, threads e fóruns.
+- Coletores com timeout e filtro por autor, `$confirm`, JSON, arrays, texto, números, datas, loops e caminhos persistentes.
+- Agendamentos persistentes com retry e recuperação de tarefas órfãs; HTTP com timeout, limite de bytes, allowlist e bloqueio de hosts privados.
+- Estado em memória, JSON e SQLite com schema 2, transações, snapshots isolados e migração automática do schema 1.
+- CLI `init`, `check`, `functions`, `run` e `dev`; scaffolds JS/TS com `--functions` opcional.
+- `MockTransport`, `mockResources` e `MemoryStore` para validação offline, sem login ou ações reais.
+- **168 testes** offline, **198 funções** na referência gerada e documentação de linguagem, framework, API, arquitetura, estado, paridade, CLI e validação.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# Yuzuha
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework para bots do Fluxer: a ergonomia que falta no Fluxer.js, com comandos
+tipados, guards, estado, moderação, agendamentos e testes offline. Function mode
+(scripts no estilo ForgeScript) é opcional. Versão **0.1.5**.
+
+```ts
+import { arg, defineCommand, Yuzuha } from 'yuzuha';
+
+const bot = new Yuzuha({ name: 'meu-bot', prefix: '!' });
+
+bot.command(defineCommand({
+  name: 'ban',
+  description: 'Bane um membro e registra um caso.',
+  args: {
+    membro: arg.user().required(),
+    motivo: arg.text().rest(),
+  },
+  async run(ctx) {
+    const caso = await ctx.mod.ban(ctx.args.get('membro'), {
+      reason: ctx.args.get('motivo') ?? '',
+    });
+    await ctx.reply(`Membro banido. Caso #${caso.id}.`);
+  },
+}));
+
+await bot.login();
+```
+
+Uso: `!ban @membro spam no chat`. `ctx.mod.ban` verifica permissões e hierarquia,
+executa o banimento e registra o caso. O token vem de `FLUXER_BOT_TOKEN`.
+`bot.client` continua sendo o client real do Fluxer.js.
+
+## O que o Yuzuha adiciona ao Fluxer.js
+
+- Comandos com prefixos, subcomandos, flags e argumentos tipados, cooldowns e permissões.
+- Ajuda com uso, escolhas e exemplos a partir das definições dos comandos.
+- Guards, middleware, plugins, eventos tipados e recarga de comandos sem reiniciar.
+- Moderação compartilhada (ban, kick, timeout, unban) com casos por servidor.
+- Recursos prontos: usuários, cargos, canais, mensagens, convites, webhooks,
+  emojis, stickers, threads e fóruns, incluindo reações, membros de threads,
+  posição de cargos/canais e categorias.
+- Estado em memória, JSON ou SQLite, com transações e variáveis por escopo.
+- Agendamentos persistentes com cron, fuso IANA, concorrência e retry com jitter.
+- HTTP textual/binário, streaming e multipart, com limites e políticas por comando.
+- `createTestBot`, relógio controlável, `MockTransport` e stores isolados para testar sem token.
+- Transações entre chaves, agendamentos editáveis com pausa/retry e apelidos com autorização compartilhada.
+- Limpeza de expirados, estatísticas e backup/restauração versionados com simulação.
+- `doctor`, lint JSON, cenários offline, catálogos de plugins e extensão VS Code.
+- SDK `@fluxerjs/core` **3.3.0** reexportado em `yuzuha/sdk`, sem esconder o original.
+
+Não é um fork do Fluxer.js nem um wrapper de todos os métodos do SDK. O que não
+estiver no framework continua acessível por `bot.client` e pelos tipos originais.
+
+## Function mode (opcional)
+
+Quem preferir a sintaxe curta do ForgeScript pode usar `yuzuha/functions`. O
+runtime é ativado quando um comando com `code` ou um evento de script é registrado.
+
+```ts
+import { script } from 'yuzuha/functions';
+import { Yuzuha } from 'yuzuha';
+
+const bot = new Yuzuha({ prefix: '!' });
+
+bot.command(script({
+  name: 'ban',
+  code: '$modBan[$mentioned[1];$messageSlice[1]]$reply[Membro banido. Caso #$caseID.]',
+}));
+```
+
+Os dois modos compartilham guards, estado, moderação e recursos. São
+**288 funções** com referência gerada, ou use `bot.enableFunctions()` para
+pré-carregar o runtime.
+
+`bot.scriptEvent()` registra scripts para entrada/saída de membros, edição/exclusão
+de mensagens e reações. O contexto preserva os dados disponíveis do evento e exige
+um canal real para enviar respostas. Veja [eventos](docs/EVENTS.md).
+
+## Instalar pelo npm
+
+Requer Node **22.13 ou mais recente**. O pacote é ESM; use `"type": "module"`
+no `package.json` do seu projeto.
+
+```sh
+npm install yuzuha@0.1.5
+```
+
+Para gerar um bot novo:
+
+```sh
+npx yuzuha@0.1.5 init ./meu-bot --ts
+cd meu-bot
+npm install
+npm run check
+npm run typecheck
+npm test
+cp .env.example .env
+```
+
+`init` declara a dependência npm e gera um teste offline. O projeto pode ser
+movido e compartilhado sem depender do caminho da instalação que o criou.
+Para JavaScript, use `--js` e omita `typecheck`.
+Para acrescentar um exemplo de script, use `--functions`.
+
+Preencha `FLUXER_BOT_TOKEN` no `.env` e execute `npm run dev`.
+
+## Desenvolver a biblioteca localmente
+
+```sh
+cd ~/Projects/yuzuha
+npm ci
+npm run build
+node dist/cli.js init ~/Projects/meu-bot --ts --local
+cd ~/Projects/meu-bot
+npm install
+npm run check
+npm run typecheck
+cp .env.example .env
+```
+
+O scaffold desse fluxo usa a biblioteca local. O
+[guia inicial](docs/QUICKSTART.md) explica instalação e configuração.
+
+## Experimentar sem token
+
+```sh
+npx tsx examples/offline.ts
+npx tsx examples/function-mode.ts
+node dist/cli.js check examples/yuzuha.config.js --json
+node dist/cli.js functions --category moderation
+```
+
+Os exemplos usam `MockTransport`; nenhuma ação chega ao Fluxer. `check` importa
+config e comandos JS/TS de confiança, valida os scripts e não chama `login`.
+Ele não substitui o typecheck do TypeScript.
+
+## Documentação
+
+Comece pelo [índice da documentação](docs/README.md).
+
+| Preciso de… | Documento |
+|---|---|
+| Criar meu primeiro bot JS ou TS | [Guia inicial](docs/QUICKSTART.md) |
+| Programar comandos, eventos e plugins | [Guia nativo JS/TS](docs/NATIVE.md) |
+| Escrever scripts `$...` | [Function mode](docs/LANGUAGE.md) e [referência](docs/FUNCTIONS.md) |
+| Saber quais funções de script existem | [Lacunas auditadas](docs/FUNCTION-GAPS.md) |
+| Usar comandos, contexto e extensões | [Framework](docs/FRAMEWORK.md) e [API](docs/API.md) |
+| Copiar exemplos completos | [Receitas](docs/COOKBOOK.md) |
+| Usar a linha de comando | [CLI](docs/CLI.md) |
+| Entender módulos e dependências | [Arquitetura](docs/ARCHITECTURE.md) |
+| Escolher persistência e tratar falhas | [Estado e execução](docs/STORAGE.md) |
+| Diagnosticar ou testar | [Problemas comuns](docs/TROUBLESHOOTING.md) e [testes](docs/TESTING.md) |
+| Usar autocomplete e diagnóstico offline | [Editor e doctor](docs/EDITOR.md) |
+| Medir dispatch, runtime e memória | [Benchmarks](docs/BENCHMARKS.md) |
+| Ver evidência local | [Validação](docs/VALIDATION.md) |
+
+As mudanças estão no [changelog](CHANGELOG.md); a política de versões está em
+[VERSIONING.md](VERSIONING.md). Leia [CONTRIBUTING.md](CONTRIBUTING.md) para contribuir.

package/VERSIONING.md

@@ -0,0 +1,147 @@
+# Versionamento
+
+O Yuzuha aplica o formato Hory ao histórico e usa **SemVer simples** no pacote.
+A versão desta atualização é **0.1.5**.
+
+## Pacote e histórico
+
+| Lugar | Formato nesta versão |
+|---|---|
+| `package.json` e raiz do `package-lock.json` | `0.1.5` |
+| Pacote npm e saída de `yuzuha --version` | `0.1.5` |
+| Título do changelog | `## v0.1.5 · 22/10/2026` |
+| Eventual tag Git | `v0.1.5` |
+
+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.
+
+As datas dos títulos usam `DD/MM/YYYY`. Cada entrada começa com uma frase sobre
+o resultado da versão, menciona o produto, a data e a tag, e lista mudanças
+de uso ou manutenção. O histórico preserva as datas e os fatos anteriores.
+
+## Compatibilidade
+
+A série `0.x` ainda evolui. Mesmo assim, correções patch preservam os imports
+públicos e os comandos documentados; mudanças incompatíveis recebem uma nota
+explícita no changelog.
+
+Mudanças incompatíveis planejadas devem entrar numa versão minor enquanto
+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` e `yuzuha/tooling`. 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.
+
+A versão do SDK é fixada separadamente. Atualizá-la exige revisar
+[PARITY.md](docs/PARITY.md), o adaptador e o teste de consumidor. A versão do bot
+gerado por `init` pertence ao consumidor e não precisa acompanhar a biblioteca.
+
+## Preparar uma atualização
+
+### Migrar para 0.1.5
+
+Imports, argumentos posicionais e comandos existentes continuam disponíveis.
+Flags são interpretadas somente em comandos que as declaram. Grupos de
+subcomandos não declaram argumentos ou flags próprios; a folha define sua entrada.
+Permissões, checks, middleware e demais restrições dos grupos continuam valendo
+nos filhos. Veja o contrato em [NATIVE.md](docs/NATIVE.md).
+
+O scaffold agora declara a versão npm do Yuzuha. Para desenvolver contra a
+instalação que executa a CLI, use `init --local`. Projetos já gerados conservam
+suas dependências; a atualização não reescreve projetos consumidores.
+O schema de persistência permanece em 2 e o SDK em 3.3.0.
+
+### Migrar para 0.1.4
+
+O schema persistido continua em 2. Cron, timezone, missedRun e retryJitter são
+campos opcionais das tarefas; stores próprios devem preservá-los. Backup usa um
+envelope separado `yuzuha-state` versão 1, validado antes de qualquer gravação.
+`StateMaintenance.restore` exige política `replace` ou `merge` e simula por
+padrão; passe `dryRun: false` ou `data restore --apply` para confirmar a alteração.
+Pare e drene o scheduler antes de backup/restore de tarefas em execução.
+
+Implementações próprias de `Resources` precisam acrescentar `messages.preload`,
+`expressions.createEmojisBulk` e `webhooks.fetch`, além de `RoleInfo.managed`.
+`transport.member(guildID, userID, channelID)` precisa resolver permissões locais
+em qualquer canal do servidor, inclusive categorias. O adaptador do SDK 3.3.0
+usa `false` quando o campo `managed` não está disponível no SDK; essa limitação
+não permite afirmar proteção completa de cargos gerenciados remotamente.
+
+Mutações de cargos/canais e operações de webhooks pelo contexto agora exigem as
+permissões do autor e do bot, com hierarquia e escopo aplicáveis. Comandos que antes
+usavam apenas a autoridade do bot podem receber `GuardError`. Use `ctx.resources`
+para a autorização compartilhada. `bot.resources` e `bot.client` permanecem APIs
+de código nativo confiável com a autoridade do bot.
+
+`ScriptEventDefinition` é separado de comandos. Em eventos, `ctx.event` contém
+os dados disponíveis; eventos parciais ou de exclusão não oferecem uma mensagem
+para reply. Defina um canal de saída quando necessário e um `actorID` explícito
+somente quando o código confiável precisar escolher outro autor. Não há promoção
+automática para a identidade do bot. Veja [EVENTS.md](docs/EVENTS.md).
+
+Políticas `command.http` só restringem a política global; configurações inválidas
+são recusadas no registro. O timeout do streaming permanece ativo até o corpo
+terminar ou ser cancelado. Código nativo deve consumir ou cancelar o corpo de
+`stream`. Consulte [HTTP.md](docs/HTTP.md), [SCHEDULER.md](docs/SCHEDULER.md) e
+[CLI.md](docs/CLI.md) para limites e formatos novos.
+
+### Migrar para 0.1.3
+
+Schema 2 anterior continua legível. Os campos opcionais `variableExpirations` e
+`scheduleHistory` guardam TTL e histórico; não remova esses campos ao escrever um
+store próprio. `set` sem TTL mantém o comportamento persistente; `update` preserva
+o prazo de valores vivos. `userFor` é explícito e exige contexto de servidor.
+
+Implementações próprias de `Resources` precisam acrescentar `users.profile`,
+`users.guildCounts`, `users.channelCounts`, `threads.active` e `threads.archived`.
+Collectors aceitam `AbortSignal` opcional; o transporte passa a receber as ações
+`move`, `mute` e `deafen`, as opções de voz no sexto argumento de `moderate` e
+um canal opcional em `member` para verificar permissões efetivas. Adapte esses
+contratos antes de habilitar os novos comandos. `mockResources` continua
+permitindo mocks parciais. Os ports brutos mantêm a autoridade do bot; prefira
+`ctx.mod` para autorização do autor e casos.
+
+`destroy` agora cancela HTTP/collectors do contexto e aguarda também o scheduler.
+Callbacks próprios do scheduler recebem `signal` como segundo argumento;
+callbacks antigos que ignoram esse argumento continuam válidos. Use `stop()`
+seguido de `await drain()` ao gerenciar uma instância fora do bot. Cancelamento
+é cooperativo e não desfaz efeitos já confirmados.
+
+O histórico retém 1000 execuções por padrão. Reexecução manual usa o ID da
+execução com falha, cria uma tarefa nova e recusa guards/efeitos de moderação.
+Os catálogos do editor são JSON declarativo configurado em
+`yuzuha.functionCatalogs`; não são imports de plugins. Veja
+[STORAGE.md](docs/STORAGE.md), [NATIVE.md](docs/NATIVE.md) e
+[EDITOR.md](docs/EDITOR.md).
+
+### Migrar para 0.1.2
+
+Os imports existentes e o schema 2 continuam válidos. Implementações próprias
+de `Resources` precisam fornecer os novos métodos das áreas de mensagens,
+usuários, threads, convites e expressões. Mocks podem usar implementações parciais
+com `mockResources`. A extensão tem a mesma versão numérica da biblioteca e
+continua sendo uma ferramenta incluída, sem criar uma superfície Hory separada.
+
+Operações de agendamento em script agora respeitam autor e servidor; um ID de
+outro escopo retorna `false`. Tarefas em execução recusam edição/pausa/retomada.
+Falhas de comandos passam a receber retry conforme a política; guards e
+moderação já aplicada são terminais. Revise comandos agendados com efeitos
+externos para idempotência. Veja [NATIVE.md](docs/NATIVE.md) e
+[EDITOR.md](docs/EDITOR.md).
+
+### Procedimento
+
+1. Atualize manifest e lockfile para a mesma versão.
+2. Acrescente a entrada no [CHANGELOG.md](CHANGELOG.md), com data real e mudanças verificáveis.
+3. Atualize migração, cobertura e documentação quando o contrato mudar.
+4. Rode `npm run check` e `npm run smoke:package` e registre a evidência.
+5. Inspecione `npm pack --dry-run` para conferir a distribuição.
+
+A CLI lê a versão do manifest; não mantenha um número paralelo no código.
+`npm run check:docs` verifica links locais e a correspondência entre manifest,
+lockfile e título do changelog.
+
+Atualizar estes arquivos prepara a versão local. Publicação npm, criação de tag
+e release remota são operações separadas e exigem instrução explícita.

package/benchmarks/compare.mjs

@@ -0,0 +1,21 @@
+export function compareReports(current, baseline) {
+  for (const field of ['platform', 'arch', 'cpu']) {
+    if (current[field] !== baseline[field]) throw new Error(`Baseline incompatível: ${field}.`);
+  }
+  if (current.node.split('.')[0] !== baseline.node?.split('.')[0]) throw new Error('Baseline incompatível: versão principal do Node.');
+  for (const field of ['iterations', 'samples', 'concurrency']) {
+    if (current.config[field] !== baseline.config?.[field]) throw new Error(`Baseline incompatível: ${field}.`);
+  }
+  for (const field of ['catalogSize', 'payloadSize', 'soakRounds']) {
+    if (baseline.config?.[field] !== undefined && current.config[field] !== baseline.config[field]) throw new Error(`Baseline incompatível: ${field}.`);
+  }
+  if (!Array.isArray(baseline.results)) throw new Error('Baseline sem resultados.');
+  return current.results.map(row => {
+    const previous = baseline.results.find(item => item.name === row.name);
+    if (!previous) return { name: row.name, status: 'new' };
+    if (!(previous.operationsPerSecond > 0) || !Number.isFinite(previous.operationsPerSecond)) throw new Error(`Baseline inválida: ${row.name}.`);
+    const throughputChangePercent = (row.operationsPerSecond / previous.operationsPerSecond - 1) * 100;
+    return { name: row.name, status: 'compared', throughputChangePercent,
+      regressionPercent: Math.max(0, -throughputChangePercent), heapChangeBytes: row.heapDeltaBytes - previous.heapDeltaBytes };
+  });
+}

package/benchmarks/run.mjs

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import { performance } from 'node:perf_hooks';
+import { arch, cpus, platform } from 'node:os';
+import { readFile } from 'node:fs/promises';
+import { CommandContext, MemoryStore, Yuzuha } from '../dist/index.js';
+import { registerBuiltins, Runtime } from '../dist/functions.js';
+import { MockTransport, mockMessage } from '../dist/testing.js';
+import { compareReports } from './compare.mjs';
+
+const config = { iterations: 1000, samples: 7, concurrency: 16, catalogSize: 1000, payloadSize: 4096, soakRounds: 5, json: false };
+let baselinePath, maxRegression;
+for (let index = 2; index < process.argv.length; index++) {
+  const key = process.argv[index];
+  if (key === '--json') { config.json = true; continue; }
+  if (key === '--baseline') {
+    baselinePath = process.argv[++index];
+    if (!baselinePath || baselinePath.startsWith('--')) throw new Error('Informe --baseline <arquivo.json>.');
+    continue;
+  }
+  if (key === '--max-regression') {
+    maxRegression = Number(process.argv[++index]);
+    if (!Number.isFinite(maxRegression) || maxRegression < 0 || maxRegression > 100) throw new Error('--max-regression deve estar entre 0 e 100.');
+    continue;
+  }
+  const name = { '--catalog-size': 'catalogSize', '--payload-size': 'payloadSize', '--soak-rounds': 'soakRounds' }[key] ?? key?.slice(2);
+  if (!['iterations', 'samples', 'concurrency', 'catalogSize', 'payloadSize', 'soakRounds'].includes(name)) throw new Error(`Opção desconhecida: ${key}`);
+  const value = Number(process.argv[++index]);
+  const max = { iterations: 1_000_000, samples: 50, concurrency: 128, catalogSize: 10_000, payloadSize: 99_000, soakRounds: 1000 }[name];
+  if (!Number.isSafeInteger(value) || value < 1 || value > max) throw new Error(`${key} deve estar entre 1 e ${max}.`);
+  config[name] = value;
+}
+if (maxRegression !== undefined && !baselinePath) throw new Error('--max-regression precisa de --baseline.');
+const percentile = (values, fraction) => [...values].sort((a, b) => a - b)[Math.ceil(values.length * fraction) - 1];
+const results = [];
+async function measure(name, operation, concurrency = 1) {
+  const run = async count => {
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, count) }, async () => {
+      while (next++ < count) await operation();
+    }));
+  };
+  await run(Math.min(config.iterations, 200));
+  global.gc?.();
+  const before = process.memoryUsage(), samples = [];
+  for (let sample = 0; sample < config.samples; sample++) {
+    const start = performance.now();
+    await run(config.iterations);
+    samples.push(performance.now() - start);
+  }
+  global.gc?.();
+  const after = process.memoryUsage();
+  results.push({ name, operations: config.iterations * config.samples, concurrency,
+    medianMs: percentile(samples, 0.5), p95Ms: percentile(samples, 0.95),
+    operationsPerSecond: config.iterations * config.samples / (samples.reduce((sum, value) => sum + value, 0) / 1000),
+    heapDeltaBytes: after.heapUsed - before.heapUsed, rssDeltaBytes: after.rss - before.rss, samplesMs: samples });
+}
+const bots = [];
+try {
+  for (const scripted of [false, true]) {
+    for (const concurrency of new Set([1, config.concurrency])) {
+    const bot = new Yuzuha({ transport: new MockTransport(), store: new MemoryStore(), scheduler: false, http: false });
+    bots.push(bot);
+    bot.command(scripted ? { name: 'bench', code: '$let[x;$math[2;*;3]]' } : { name: 'bench', run() {} });
+    const name = scripted ? 'dispatch/functions' : 'dispatch/native';
+    await measure(concurrency > 1 ? `${name}-concurrent` : name, async () => {
+      assert.equal(await bot.handle(mockMessage('!bench')), 'success');
+    }, concurrency);
+    }
+  }
+  const runtime = registerBuiltins(new Runtime());
+  const source = '$arrayReduce[$range[1;10];0;$math[$loopAccumulator;+;$loopValue]]';
+  const program = runtime.compile(source);
+  const ctx = new CommandContext({ message: mockMessage('!bench'), command: { name: 'bench', code: '' },
+    transport: new MockTransport(), store: new MemoryStore(), cooldown: () => 0 });
+  await measure('runtime/compile', () => { runtime.compile(source); });
+  await measure('runtime/evaluate', async () => { assert.equal(await runtime.execute(program, ctx), 55); });
+  await measure('store/transaction-concurrent', async () => {
+    await ctx.data.transaction(tx => {
+      tx.guild.update('a', value => Number(value) + 1, 0);
+      tx.guild.update('b', value => Number(value) + 1, 0);
+    });
+  }, config.concurrency);
+  const expected = Math.min(config.iterations, 200) + config.iterations * config.samples;
+  assert.equal(await ctx.data.guild.get('a'), expected);
+  assert.equal(await ctx.data.guild.get('b'), expected);
+  const catalog = new Yuzuha({ transport: new MockTransport(), store: new MemoryStore(), scheduler: false, http: false });
+  bots.push(catalog);
+  for (let index = 0; index < config.catalogSize; index++) catalog.command({ name: `item${index}`, run() {} });
+  await measure('dispatch/large-catalog', async () => {
+    assert.equal(await catalog.handle(mockMessage(`!item${config.catalogSize - 1}`)), 'success');
+  });
+  const payload = 'x'.repeat(config.payloadSize);
+  const payloadProgram = runtime.compile(`$let[payload;${payload}]`);
+  await measure('runtime/large-payload', async () => {
+    assert.equal(await runtime.execute(payloadProgram, ctx), '');
+    assert.equal(ctx.vars.get('payload').length, config.payloadSize);
+  });
+  const memory = [];
+  for (let round = 0; round <= config.soakRounds; round++) {
+    if (round > 0) for (let index = 0; index < config.iterations; index++) {
+      assert.equal(await catalog.handle(mockMessage(`!item${config.catalogSize - 1} ${payload}`)), 'success');
+    }
+    global.gc?.();
+    const usage = process.memoryUsage();
+    memory.push({ round, operations: round * config.iterations, heapUsed: usage.heapUsed, rss: usage.rss });
+  }
+  const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+  const report = { version: manifest.version, date: new Date().toISOString(), node: process.versions.node,
+    platform: platform(), arch: arch(), cpu: cpus()[0]?.model, gc: typeof global.gc === 'function', config, results,
+    memory: { samples: memory, heapGrowthBytes: memory.at(-1).heapUsed - memory[0].heapUsed,
+      rssGrowthBytes: memory.at(-1).rss - memory[0].rss } };
+  if (baselinePath) {
+    report.comparison = compareReports(report, JSON.parse(await readFile(baselinePath, 'utf8')));
+    if (maxRegression !== undefined && report.comparison.some(row => row.regressionPercent > maxRegression)) process.exitCode = 1;
+  }
+  console.log(config.json ? JSON.stringify(report, null, 2) : [
+    `Yuzuha ${report.version} · Node ${report.node} · ${report.platform}/${report.arch}`,
+    `${config.iterations} operações/amostra, ${config.samples} amostras; GC explícito: ${report.gc}`,
+    ...results.map(row => `${row.name}: ${row.operationsPerSecond.toFixed(0)} ops/s; mediana ${row.medianMs.toFixed(2)}ms; p95 ${row.p95Ms.toFixed(2)}ms; heap ${row.heapDeltaBytes} bytes`),
+    `Memória após ${config.soakRounds * config.iterations} operações: heap ${report.memory.heapGrowthBytes} bytes; RSS ${report.memory.rssGrowthBytes} bytes`,
+    ...(report.comparison ?? []).map(row => `${row.name}: ${row.status === 'new' ? 'novo cenário' : `${row.throughputChangePercent.toFixed(1)}% ops/s ante baseline`}`),
+  ].join('\n'));
+} finally { await Promise.all(bots.map(bot => bot.destroy())); }

package/dist/adapter.d.ts

@@ -0,0 +1,3 @@
+export { FluxerTransport } from './infrastructure/fluxer/transport.js';
+export { incoming } from './infrastructure/fluxer/messages.js';
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC"}

package/dist/adapter.js

@@ -0,0 +1,3 @@
+export { FluxerTransport } from './infrastructure/fluxer/transport.js';
+export { incoming } from './infrastructure/fluxer/messages.js';
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC","sourcesContent":["export { FluxerTransport } from './infrastructure/fluxer/transport.js';\nexport { incoming } from './infrastructure/fluxer/messages.js';\n"]}

package/dist/bot.d.ts

@@ -0,0 +1,3 @@
+export { Yuzuha, Bot } from './framework/bot.js';
+export type { YuzuhaOptions, YuzuhaPlugin, Middleware, DispatchResult } from './framework/options.js';
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/bot.js

@@ -0,0 +1,2 @@
+export { Yuzuha, Bot } from './framework/bot.js';
+//# sourceMappingURL=bot.js.map

package/dist/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC","sourcesContent":["export { Yuzuha, Bot } from './framework/bot.js';\nexport type { YuzuhaOptions, YuzuhaPlugin, Middleware, DispatchResult } from './framework/options.js';\n"]}