chronos-ruby 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77021c8f603c5908e1e31bb85824a1dcadb6b73917492f51e617128a81170157
-  data.tar.gz: af6c9e930a0c6ea86154c9cfb89b60e2dd6920d934d2afca611a2d129496fa3e
+  metadata.gz: 87b640aa42cc30a22ed1a78e5b581e3e91ad06da354f88d4c64f15c6b93e6c81
+  data.tar.gz: b7e918cf87fb4bed7c0e412bd330a060d94c00133be11f35b3ca40155e681d82
 SHA512:
-  metadata.gz: f2b69c2ef1d1acaaf1e6ded9182e2daeb78549b71ae48e06b0e982fe79d41655f6c4d5c44a0736f683cdb476a90558d5df2561e2f090013e235d4a3ccc1eeddd
-  data.tar.gz: 4989786700879e83e42fb70b9bdfec2e025271d0f97edf294d75e1c2138f40fb1e80e8a7477cadb4cd634fa3fb1c2e80295b7b47858444fad4903df2e831d918
+  metadata.gz: 547197df76b0353e60da6888b3acbdf256dcca6af2983cc5b0318f5445b80f505c223ddc37ed549a4563b632856e125f11dcf026a9a27e0247a7be29d0d6fd89
+  data.tar.gz: 003c1dc2cba82ec998dafadb3e788eb716a9c2fa692ac04a6ab343879cf12b70105882ae507497ff01697d9bfd50e7c5c667cebffb83dddbb0820da824b1e260

data/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-10-31
+
+### Added
+
+- Packaged deploy CLI and safe provider installers ported from legacy 1.1.4, with equivalent explicit configuration, receipt verification, offline diagnostics and exit codes.
+- Transitional core/package gates on Ruby 2.7–3.4, real Rails 7.0/7.1/7.2 fixtures, Sidekiq 7 middleware-chain smokes and an isolated Docker helper.
+
+### Security
+
+- Port SQL literal masking and full original-query inspection guards, sensitive symbol filtering, bounded diagnostic copies/context merging, and descriptor-anchored POSIX installation with regression coverage.
+
+### Changed
+
+- Preserve the existing Ruby >= 2.7 and < 3.5 requirement, protocol v1 and main-line integrations, including fiber-aware context and Rails Error Reporter.
+- Correct legacy references introduced by conflict resolution; prepare 1.2.2 release metadata, English documentation and dedicated readiness evidence.
+- Wire standalone deploy and installed-package tests into PR and release gates. Framework smokes remain focused evidence and do not automatically promote Best effort combinations.
+
+
+## [1.2.1] - 2026-08-13
+
+### Changed
+
+- expanded the gem summary and description to clarify its exception, metrics, and telemetry monitoring purpose;
+- highlighted the official Chronos Monitor endpoint at https://chronosmonitor.com.br so RubyGems users can identify the platform that receives and displays the collected observability data;
+- updated stable-release references and installation examples to `1.2.1`.
+
 ## [1.2.0] - 2026-08-12
 
 ### Added

data/README.md

@@ -1,74 +1,77 @@
 # Chronos Ruby
 
-Chronos Ruby 1.2.0 é o agente para enviar exceções, métricas e telemetria limitada de aplicações Ruby e Rails ao Chronos. Esta é a linha estável atual para Ruby 2.7–3.4, compatível com o protocolo v1.
+Chronos Ruby 1.2.2 sends exceptions, metrics, and bounded telemetry from Ruby and Rails applications to Chronos. This is the transitional line for Ruby >= 2.7 and < 3.5, using protocol v1. Release preparation does not imply publication or promotion of unverified framework combinations.
 
-## O que a gem coleta
+## What the gem collects
 
-A versão 1.1 pode coletar:
+The transitional line can collect:
 
-- classe, mensagem, backtrace estruturado e causas encadeadas da exceção;
-- timestamp, severidade, tags e fingerprint opcional;
-- contexto, parâmetros, sessão e usuário fornecidos pela aplicação;
-- versão, engine e plataforma Ruby, PID, thread opaca e hostname;
-- ambiente, serviço, versão da aplicação, release, revision, deploy ID, região e instância;
-- método, rota normalizada, status, duração e breakdown de requests Rack/Rails;
-- SQL normalizado sem literais/binds e sinais heurísticos de desempenho;
-- jobs Sidekiq/Active Job, cache, HTTP externo explicitamente instrumentado e dependências carregadas;
-- breadcrumbs limitados fornecidos pela aplicação ou por integrações.
+- exception class, message, structured backtrace, and chained causes;
+- timestamp, severity, tags, and an optional fingerprint;
+- context, parameters, session, and user information supplied by the application;
+- Ruby version, engine, platform, PID, opaque thread identifier, and hostname;
+- environment, service, application version, release, revision, deploy ID, region, and instance;
+- Rack/Rails request method, normalized route, status, duration, and timing breakdown;
+- normalized SQL without literals or bind values, plus heuristic performance signals;
+- Sidekiq/Active Job activity, cache operations, explicitly instrumented outbound HTTP, and loaded dependencies;
+- bounded breadcrumbs supplied by the application or integrations.
 
-Veja a tabela completa em [Dados coletados](docs/data-collected.md).
+See the full inventory in [Collected data](docs/data-collected.md).
 
-## O que não é coletado por padrão
+## What is not collected by default
 
-A gem não varre variáveis de ambiente, sistema de arquivos ou lockfiles e não coleta bodies HTTP, cookies, headers de autorização, conteúdo de e-mail, SQL bruto, binds, valores de cache ou código-fonte. A inspeção de plano, desativada por padrão, usa o SQL original somente na conexão local para `EXPLAIN` sem `ANALYZE` e o descarta. O inventário de dependências contém somente nomes e versões já carregados, uma vez por agente. A aplicação continua responsável por minimização e base legal dos dados enviados.
+The agent does not scan environment variables, the filesystem, or lockfiles. It does not collect HTTP bodies, cookies, authorization headers, email contents, raw SQL, bind values, cache values, or source code. Query plan inspection is disabled by default; when enabled, it uses the original SQL only on the local connection for `EXPLAIN` without `ANALYZE`, then discards it. Dependency inventory includes only names and versions of loaded dependencies, once per agent. The application remains responsible for data minimization and the legal basis for sending data.
 
-## Versões Ruby e Rails suportadas
+The explicit deploy CLI described below reads its documented environment variables and optional configuration file. It does not change how the Ruby configuration API works.
 
-A versão estável 1.2.0 atende a linha transitional para Ruby 2.7–3.4, Rails 7.x e Sidekiq 7. Ela adiciona contexto por Fiber, Rails Error Reporter, Action Cable, Faraday, Trace Context W3C opcional, integração automática com Sidekiq em Rails e coexistência com um SDK OpenTelemetry já configurado. Combinações ainda classificadas como `Best effort` devem ser validadas pela aplicação antes da adoção em produção; as linhas legadas permanecem disponíveis em releases anteriores.
+## Supported Ruby and framework versions
 
-Rubies e frameworks antigos estão fora do suporte de segurança de seus mantenedores. A Chronos oferece compatibilidade técnica, não manutenção de segurança do runtime. Veja [Compatibilidade](docs/compatibility.md).
+The core matrix covers MRI 2.7, 3.0, 3.1, 3.2, 3.3 and 3.4. Rails 7.0/7.1 and Sidekiq 7 require Ruby 2.7 or newer; Rails 7.2 requires Ruby 3.1 or newer. The exact application smoke pairs and their evidence are documented in [Compatibility](docs/compatibility.md). They remain Best effort until all mandatory promotion gates pass. Rails 8 and Ruby 4 belong to the separate 2.x plan.
 
-## Instalação em Ruby puro
+The transitional integrations include fiber-aware context, Rails Error Reporter, Action Cable, Faraday, optional W3C Trace Context, automatic Rails/Sidekiq installation, and coexistence with an application-managed OpenTelemetry SDK. These integrations are preserved by this deploy CLI port.
 
-Obrigatório: adicione a versão estável ao `Gemfile`.
+Legacy Ruby 2.2–2.6 and Rails 4/5 consumers must use an appropriate 1.1 release. Technical compatibility does not provide security maintenance for end-of-life runtimes or frameworks.
+
+## Installing in plain Ruby
+
+Add the stable version to your `Gemfile`:
 
 ```ruby
-gem "chronos-ruby", "~> 1.2.0"
+gem "chronos-ruby", "~> 1.2.2"
 ```
 
-Use Bundler 2 em um runtime suportado:
+Use Bundler 2 on a compatible runtime (CI pins 2.4.22):
 
 ```bash
-gem install bundler -v "~> 2.4"
+gem install bundler -v 2.4.22
 bundle install
 ```
 
-Sem Bundler:
+Without Bundler:
 
 ```bash
-gem install chronos-ruby -v 1.1.0
+gem install chronos-ruby -v 1.2.2
 ```
 
-## Instalação em Rails
+## Installing in Rails
 
-Obrigatório: carregue a integração Rails explicitamente para manter Rails/ActiveSupport fora de aplicações Ruby puras.
+Load the Rails integration explicitly to keep Rails/ActiveSupport out of plain Ruby applications:
 
 ```ruby
-gem "chronos-ruby", "~> 1.1.0", :require => "chronos/rails"
+gem "chronos-ruby", "~> 1.2.2", :require => "chronos/rails"
 ```
 
-Gere o initializer:
+Generate the initializer:
 
 ```bash
 rails generate chronos:install
 ```
 
-A Versão 0.5 introduziu Railtie, middleware e subscribers idempotentes por APIs públicas e feature detection. A coleta automática fica desativada em test e console por padrão. Veja [Rails legado](docs/modules/rails-legacy.md).
+Version 0.5 introduced the Railtie, middleware, and idempotent subscribers through public APIs and feature detection. Automatic collection is disabled in tests and the console by default. See [Legacy Rails](docs/modules/rails-legacy.md).
 
-## Configuração mínima
+## Minimal configuration
 
-Obrigatório quando o agente está habilitado: `project_id` e `project_key`. O `host` usa
-`https://chronosmonitor.com.br` por padrão. Recomendado: definir ambiente e serviço explicitamente.
+An enabled agent requires `project_id` and `project_key`. The default `host` is `https://chronosmonitor.com.br`. Set the environment and service explicitly whenever possible.
 
 ```ruby
 require "chronos"
@@ -83,28 +86,28 @@ Chronos.configure do |config|
 end
 ```
 
-TLS é verificado por padrão. HTTP exige `ssl_verify = false` explicitamente e deve ser limitado a endpoints locais de teste. Depois de configurar, valide credenciais e ingestão:
+TLS verification is enabled by default. The Ruby API requires an explicit `ssl_verify = false` to use HTTP, which should be restricted to local test endpoints. After configuration, verify credentials and ingestion:
 
 ```bash
 bundle exec rake chronos:verify_integration
 ```
 
-O task envia uma exceção sintética identificada e só retorna código `0` após uma resposta v1 correlacionada. Em Ruby puro, instale o task com `require "chronos/rake_tasks"` e `Chronos::RakeTasks.install`; por código, use `Chronos.verify_integration`. Veja [Verificação da integração](docs/modules/integration-verification.md).
+The task sends an identified synthetic exception and returns exit code `0` only after a correlated v1 response. In plain Ruby, register the task with `require "chronos/rake_tasks"` and `Chronos::RakeTasks.install`; from Ruby code, use `Chronos.verify_integration`. See [Integration verification](docs/modules/integration-verification.md).
 
-## Captura automática
+## Automatic capture
 
-Opcional em Rack: instale o middleware. Ele notifica exceções não tratadas, preserva a mesma exceção para a aplicação e não consome bodies.
+For Rack applications, optionally install the middleware. It reports unhandled exceptions, preserves the original exception for the application, and does not consume request bodies.
 
 ```ruby
 use Chronos::Integrations::Rack::Middleware,
     :include_user_agent => false
 ```
 
-Em Rails, o Railtie instala middleware e subscribers uma única vez. Veja [Monitoramento de requests](docs/modules/request-monitoring.md).
+In Rails, the Railtie installs middleware and subscribers once. See [Request monitoring](docs/modules/request-monitoring.md).
 
-## Captura manual
+## Manual capture
 
-Recomendado no fluxo da aplicação: captura assíncrona.
+Use asynchronous capture in application flows:
 
 ```ruby
 begin
@@ -115,27 +118,27 @@ rescue StandardError => error
 end
 ```
 
-Opcional para scripts e shutdown controlado: captura síncrona.
+Synchronous capture is available for scripts and controlled shutdown:
 
 ```ruby
 delivered = Chronos.notify_sync(RuntimeError.new("import failed"))
 ```
 
-Falhas internas retornam `false` e não escapam para o fluxo principal.
+Internal capture failures return `false` without escaping into the application's main flow.
 
-## Contexto de usuário
+## User context
 
-Contexto de usuário é opt-in. Envie somente campos necessários e autorizados:
+User context is opt-in. Send only necessary, authorized fields:
 
 ```ruby
 Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
 ```
 
-O valor é limitado e sanitizado, mas a minimização continua sendo responsabilidade da aplicação. Veja [Contexto de execução](docs/modules/context.md).
+Values are bounded and sanitized, but data minimization remains the application's responsibility. See [Execution context](docs/modules/context.md).
 
 ## Breadcrumbs
 
-Breadcrumbs formam um buffer circular delimitado no escopo atual:
+Breadcrumbs use a bounded ring buffer in the current scope:
 
 ```ruby
 Chronos.add_breadcrumb(
@@ -145,11 +148,11 @@ Chronos.add_breadcrumb(
 )
 ```
 
-A gem não transforma logs, SQL ou bodies em breadcrumbs brutos. Veja [Breadcrumbs](docs/modules/breadcrumbs.md).
+The gem does not turn logs, SQL, or bodies into raw breadcrumbs. See [Breadcrumbs](docs/modules/breadcrumbs.md).
 
-## Filtros e LGPD
+## Filters and LGPD
 
-A gem bloqueia chaves sensíveis e detecta Bearer tokens, JWTs, e-mails, CPF, CNPJ e candidatos válidos a cartão. IPv4 é anonimizado por padrão. Opcionalmente, amplie a blocklist, aplique hash irreversível ou filtros próprios:
+The gem blocks sensitive keys and detects Bearer tokens, JWTs, email addresses, Brazilian CPF/CNPJ identifiers, and valid payment card candidates. IPv4 addresses are anonymized by default. You can extend the blocklist, apply irreversible hashing, or add custom filters:
 
 ```ruby
 Chronos.configure do |config|
@@ -159,11 +162,11 @@ Chronos.configure do |config|
 end
 ```
 
-Sanitização ocorre antes de fila, retry e backlog. Veja [Privacidade e LGPD](docs/privacy-lgpd.md).
+Diagnostic trees are copied with cycle, depth, collection, node, and string limits before immutable event construction. Caller-owned telemetry data is not frozen. Sensitive symbol values are filtered before conversion to JSON text. Sanitization happens before queueing, retries, and backlog storage. See [Privacy and LGPD](docs/privacy-lgpd.md).
 
 ## Ignore rules
 
-Ambientes inteiros podem ser ignorados na configuração. A versão `0.9.0.pre.2` introduziu regras locais limitadas, preservadas na API estável:
+Configuration can exclude entire environments. Version `0.9.0.pre.2` introduced bounded local rules, preserved in the stable API:
 
 ```ruby
 Chronos.ignore_if do |notice|
@@ -171,11 +174,11 @@ Chronos.ignore_if do |notice|
 end
 ```
 
-A regra recebe um notice normalizado e imutável, e somente `true` descarta. Falhas do callback são contidas. Veja [Ignore rules](docs/modules/ignore-rules.md).
+Rules receive a normalized, immutable notice. Only `true` discards it, and callback failures are contained. See [Ignore rules](docs/modules/ignore-rules.md).
 
-## Monitoramento de performance
+## Performance monitoring
 
-A Versão 0.7 introduziu agregação local de requests, queries e jobs em `metric_batch`; a Versão 0.8 adicionou HTTP externo. Grupos possuem contagem, erro, duração, histograma, percentis aproximados, severidades, diagnósticos, status e breakdown limitados.
+Version 0.7 introduced local request, query, and job aggregation into `metric_batch`; Version 0.8 added outbound HTTP. Groups contain bounded counts, errors, durations, histograms, approximate percentiles, severities, diagnostics, statuses, and timing breakdowns.
 
 ```ruby
 Chronos.configure do |config|
@@ -190,7 +193,7 @@ Chronos.configure do |config|
   config.apm_query_analysis_enabled = true
   config.apm_query_analysis_max_queries = 100
 
-  # Opt-in: cada fingerprint elegível pode consultar catálogo/estatística/plano.
+  # Opt-in: each eligible fingerprint may inspect catalogs, statistics, or plans.
   config.apm_query_inspection_enabled = false
   config.apm_query_statistics_enabled = false
   config.apm_query_plan_enabled = false
@@ -201,27 +204,22 @@ Chronos.configure do |config|
 end
 ```
 
-Por padrão, SQL bruto e binds não são lidos pelo pipeline de análise. A inspeção opt-in usa o SQL original apenas localmente para solicitar `EXPLAIN` sem `ANALYZE`; nunca o inclui no evento. A análise estática produz candidatos, não ordens de criação de índice. Erros usam severidade `error`; lentidão e risco usam `warning`; padrões observados usam `info`; correções propostas usam `suggestion`. Veja [APM](docs/modules/apm-aggregation.md), [Requests](docs/modules/request-monitoring.md) e [SQL](docs/modules/sql-monitoring.md).
-
-## Sidekiq e Active Job
+By default, the analysis pipeline does not read raw SQL or bind values. Opt-in inspection uses the original SQL only locally to request `EXPLAIN` without `ANALYZE`; it never includes that SQL in the event. Oversized, incomplete, or lexically ambiguous SQL is omitted instead of emitting partial literals. Plan inspection validates the entire original query and rejects multiple statements independently of normalized metadata. Static analysis produces candidates rather than instructions to create indexes. Errors use `error` severity; slowness and risks use `warning`; observed patterns use `info`; proposed fixes use `suggestion`. See [APM](docs/modules/apm-aggregation.md), [Requests](docs/modules/request-monitoring.md), and [SQL](docs/modules/sql-monitoring.md).
 
-A integração Rails detecta o Sidekiq e instala automaticamente os middlewares de cliente e servidor. O carregamento
-explícito continua disponível para aplicações sem Rails e suporta a API pública de middleware do Sidekiq 7:
+## Sidekiq and Active Job
 
-O suporte histórico começou em `0.6.0.pre.1`; aplicações em Sidekiq 4/5 devem permanecer numa release legada compatível.
+The Rails integration detects Sidekiq and installs its client/server middleware automatically. Explicit loading remains available in plain Ruby applications. Historical middleware support began with `0.6.0.pre.1`; Sidekiq 4/5 users must remain on a matching legacy release.
 
 ```ruby
-gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "~> 1.1.0"
+gem "sidekiq", "~> 7.3"
+gem "chronos-ruby", "~> 1.2.2", :require => "chronos/rails"
 ```
 
-Em uma aplicação Ruby sem Rails, use `require "chronos/sidekiq"`.
-
-O envelope de contexto não altera argumentos públicos e contém somente IDs limitados de trace/span/request e flags. Active Job usa um campo serializado com namespace (`chronos_context`) e hooks públicos. Erros aninhados são deduplicados e reerguidos. Veja [Sidekiq legado](docs/modules/sidekiq-legacy.md), [Active Job](docs/modules/active-job.md) e [Jobs](docs/modules/job-monitoring.md).
+Without Rails, load `chronos/sidekiq` after Sidekiq. The context envelope preserves public arguments and contains only bounded trace/span/request IDs and flags. Active Job uses its namespaced `chronos_context` field and public serialization hooks. Nested errors are deduplicated and re-raised. See [Sidekiq](docs/modules/sidekiq-legacy.md), [Active Job](docs/modules/active-job.md), and [Jobs](docs/modules/job-monitoring.md).
 
 ## Deploy tracking
 
-A Versão 0.9 introduziu deploy síncrono e correlação fixa em todos os eventos:
+Version 0.9 introduced synchronous deploy reporting and fixed correlation across events:
 
 ```ruby
 Chronos.notify_deploy(
@@ -233,35 +231,45 @@ Chronos.notify_deploy(
 )
 ```
 
-Configure release/revision/deploy na inicialização de cada novo processo. A gem não lê Git ou variáveis automaticamente. Capistrano é opcional; Kamal e GitHub Actions usam exemplos em `examples/deploy/`. Veja [Deploys](docs/modules/deploys.md).
+Configure release/revision/deploy metadata when each new process starts. The Ruby API does not read Git or environment variables automatically. Capistrano is optional; Kamal and GitHub Actions recipes are available in `examples/deploy/`. See [Deploys](docs/modules/deploys.md).
+
+Version 1.2.2 ports a packaged deploy command without a copied Ruby notification script:
+
+```bash
+bundle exec chronos deploy notify
+```
+
+Supply `CHRONOS_PROJECT_ID`, `CHRONOS_PROJECT_KEY`, `CHRONOS_ENVIRONMENT`, a stable `CHRONOS_DEPLOY_ID`, and `CHRONOS_DEPLOY_REVISION` or `CHRONOS_DEPLOY_VERSION` for the artifact actually published. The CLI reads explicit ENV and optional public YAML without booting Rails. It requires HTTPS and never accepts the project key as a process argument. Optional integration installers cover Kamal, Capistrano, GitHub Actions, GitLab CI, Jenkins, and Azure DevOps. Integration file installation requires POSIX filesystem support (Linux/macOS) and anchors operations to opened directories to prevent symlink redirection.
 
-## Fila assíncrona
+This branch prepares 1.2.2; publication remains subject to the [release gates](docs/release-1.2.2-readiness.md). See the [CLI guide](docs/deploy-cli.md) for configuration, receipt verification, exit codes, and integration fragments.
 
-A fila tem capacidade fixa, descarta o evento mais novo quando cheia e cria workers somente após a primeira captura aceita.
+## Asynchronous queue
+
+The queue has a fixed capacity, drops the newest event when full, and starts workers only after the first accepted capture.
 
 ```mermaid
 flowchart LR
-  E[Exceção ou telemetria] --> N[Normalização]
-  N --> P[Sanitização]
-  P --> S[Serialização limitada]
-  S --> D[Pipeline de entrega]
-  D --> Q[Fila limitada]
-  Q --> W[Workers fixos]
+  E[Exception or telemetry] --> N[Normalization]
+  N --> P[Sanitization]
+  P --> S[Bounded serialization]
+  S --> D[Delivery pipeline]
+  D --> Q[Bounded queue]
+  Q --> W[Fixed workers]
   W --> H[Net::HTTP]
-  W --> B[Backlog em memória]
+  W --> B[In-memory backlog]
 ```
 
-Use `Chronos.flush(timeout)` antes de encerrar e `Chronos.close(timeout)` no shutdown. Workers são recriados após fork. Veja [Fila assíncrona](docs/modules/async-queue.md).
+Use `Chronos.flush(timeout)` before termination and `Chronos.close(timeout)` during shutdown. Workers are recreated after a fork. See [Asynchronous queue](docs/modules/async-queue.md).
 
-## Retry e backlog
+## Retry and backlog
 
-Retry cobre erros de rede, HTTP `408`, `429` e `5xx`, com backoff exponencial, jitter e tentativas limitadas. Outros `4xx` são permanentes. Circuit breaker reduz tempestades de retry.
+Retries cover network errors and HTTP `408`, `429`, and `5xx`, with exponential backoff, jitter, and bounded attempts. Other `4xx` responses are permanent failures. A circuit breaker reduces retry storms.
 
-O backlog guarda somente eventos já sanitizados/serializados, possui capacidade fixa, vive em memória e é perdido no encerramento. Configuração remota aceita apenas sampling, tipos habilitados, limite menor de payload, fingerprints exatas, intervalo e kill switch; nunca altera host, credenciais, TLS ou executa código. Veja [Retry e backlog](docs/modules/retry-backlog.md), [Sampling](docs/modules/sampling.md) e [Configuração remota](docs/modules/remote-configuration.md).
+The backlog stores only sanitized, serialized events. It has a fixed capacity, lives in memory, and is lost on shutdown. Remote configuration accepts only sampling, enabled event types, a smaller payload limit, exact fingerprints, send interval, and a kill switch; it never changes the host, credentials, or TLS settings, or executes code. See [Retry and backlog](docs/modules/retry-backlog.md), [Sampling](docs/modules/sampling.md), and [Remote configuration](docs/modules/remote-configuration.md).
 
-## Configuração por ambiente
+## Environment-based configuration
 
-A gem não varre o ambiente. Leia somente variáveis escolhidas pela aplicação:
+The Ruby API does not scan the environment. Read only variables chosen by your application:
 
 ```ruby
 Chronos.configure do |config|
@@ -285,55 +293,99 @@ Chronos.configure do |config|
 end
 ```
 
-Todas as opções, defaults e limites estão em [Configuração](docs/configuration.md).
+See [Configuration](docs/configuration.md) for all options, defaults, and limits.
 
 ## Troubleshooting
 
-Erros de configuração são levantados durante `Chronos.configure`; falhas de captura/entrega são contidas e podem ir ao logger seguro. Confirme TLS, credenciais, timeouts e retorno de `flush`. Consulte [Troubleshooting](docs/troubleshooting.md).
+Configuration errors are raised during `Chronos.configure`; capture and delivery failures are contained and may be reported to the safe logger. Check TLS, credentials, timeouts, and the return value of `flush`. See [Troubleshooting](docs/troubleshooting.md).
+
+## Benchmarks
+
+The stable release gate runs a repeatable Rack comparison and load against a fake endpoint:
 
-## Benchmark
+```bash
+ITERATIONS=50000 WARMUP=5000 SAMPLES=7 bundle _2.4.22_ exec ruby benchmarks/comparative.rb
+ITERATIONS=500 bundle _2.4.22_ exec ruby benchmarks/fake_endpoint_load.rb
+```
+
+Results depend on the runtime and hardware. There is no general claim of superiority: record CPU, OS, Ruby, commit, warmup, samples, median, and dispersion. Additional benchmarks are in `benchmarks/` and documented in [Performance](docs/performance.md).
+
+## Migrating from Airbrake
+
+Migrate in stages. Run both agents together only during validation to avoid prolonged duplicate reporting. Callbacks and notices are not API-compatible and must be translated and tested explicitly. See the [Airbrake migration guide](docs/migration-from-airbrake.md).
+
+## Local development
 
-O gate estável executa comparação Rack repetível e carga contra endpoint fake:
+On a compatible Ruby, install Bundler 2.4.22 and run `bundle _2.4.22_ install`. Use `bin/console` for inspection. See [Architecture](docs/architecture.md).
+
+## Tests
+
+The transitional CI entry point runs RSpec/security regressions, RuboCop 1.57, standalone CLI/adapters, documentation and built-gem smoke tests:
 
 ```bash
-ITERATIONS=50000 WARMUP=5000 SAMPLES=7 bundle _1.17.3_ exec ruby benchmarks/comparative.rb
-ITERATIONS=500 bundle _1.17.3_ exec ruby benchmarks/fake_endpoint_load.rb
+sh script/ci_transitional
 ```
 
-Resultados dependem de runtime e hardware. Não há alegação genérica de superioridade; registre CPU, SO, Ruby, commit, warmup, amostras, mediana e dispersão. Outros benchmarks ficam em `benchmarks/` e estão descritos em [Performance](docs/performance.md).
+For a focused suite/lint check with dependencies installed, use `bundle _2.4.22_ exec rake`. The additional tests and installed-package gates are required before release as well.
+
+### Prepare Docker
 
-## Migração do Airbrake
+Start Docker Desktop on macOS and verify both client and server:
 
-Migre por etapas e mantenha os dois agentes juntos somente durante a validação, evitando duplicidade prolongada. Callbacks e notices não são API-compatíveis e devem ser traduzidos/testados explicitamente. Consulte o [guia de migração do Airbrake](docs/migration-from-airbrake.md).
+```bash
+open -a Docker
+docker version
+docker info
+```
 
-## Desenvolvimento local
+The helper uses Linux/amd64 (emulated on Apple Silicon), mounts the repository read-only, and runs a temporary copy without local Bundler configuration, credentials directories, `.env` files or lockfiles. Host gems and lockfiles are unchanged. Images and dependencies require registry access; no SaaS credentials are needed.
 
-Instale as dependências:
+### Run individual core or framework checks
 
 ```bash
-bin/setup
+sh script/test_transitional_docker 2.7
+sh script/test_transitional_docker 3.4
+sh script/test_transitional_docker 2.7 examples/rails-7.0
+sh script/test_transitional_docker 3.2 examples/rails-7.1
+sh script/test_transitional_docker 3.4 examples/rails-7.2
+sh script/test_transitional_docker 3.4 examples/sidekiq-7
 ```
 
-Use `bin/console` para inspeção e `bundle exec rake install` para instalar a fonte localmente. A arquitetura hexagonal está descrita em [Arquitetura](docs/architecture.md).
+Core checks accept Ruby 2.7, 3.0, 3.1, 3.2, 3.3 and 3.4. Rails fixtures pin 7.0.10, 7.1.6 and 7.2.4; Sidekiq pins 7.3.10. The Rails application checks controller/SQL telemetry, Active Job, Error Reporter deduplication, initialization and deploy generation. Sidekiq checks its real middleware chains without starting Redis or a worker process.
 
-## Testes
+### Run the complete configured matrix
 
-Execute suíte e lint no runtime atual:
+This block stops at the first failure and returns a nonzero status:
 
 ```bash
-bundle exec rake
+(
+  set -e
+  for version in 2.7 3.0 3.1 3.2 3.3 3.4; do
+    sh script/test_transitional_docker "$version"
+    sh script/test_transitional_docker "$version" examples/sidekiq-7
+  done
+  for version in 2.7 3.0; do
+    sh script/test_transitional_docker "$version" examples/rails-7.0
+  done
+  for version in 2.7 3.1 3.2; do
+    sh script/test_transitional_docker "$version" examples/rails-7.1
+  done
+  for version in 3.1 3.3 3.4; do
+    sh script/test_transitional_docker "$version" examples/rails-7.2
+  done
+)
 ```
 
-A matriz CI cobre a linha transitional e os checks de pacote/documentação; workflows legados preservam evidência das releases anteriores.
+Keep per-runtime logs and resolved versions. A stopped matrix does not approve unexecuted combinations. These checks do not replace dependency audit, benchmarks/load, Redis-backed worker lifecycle, authorized provider execution or SaaS receipt/ledger/projection gates. See [1.2.2 readiness](docs/release-1.2.2-readiness.md). Legacy Docker helpers remain historical tools and do not validate this gem's Ruby requirement.
 
-## Contribuição
+## Contributing
 
-Abra uma issue antes de adicionar API pública ou dependência. Classes públicas precisam de YARD, testes, documentação de módulo e evidência de compatibilidade. Veja [CONTRIBUTING.md](CONTRIBUTING.md).
+Open an issue before adding a public API or dependency. Public classes require YARD documentation, tests, module documentation, and compatibility evidence. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Segurança
+## Security
 
-Nunca inclua credenciais no contexto. Releases usam Trusted Publishing, checksum SHA-256 e SBOM; dependências passam por auditoria. Reporte vulnerabilidades pelo canal privado de [SECURITY.md](SECURITY.md).
+Never include credentials in context. Releases use Trusted Publishing, SHA-256 checksums, and an SBOM; dependencies are audited. Report vulnerabilities through the private channel in [SECURITY.md](SECURITY.md).
 
-## Licença
+## License
 
-Chronos Ruby é distribuída sob a licença MIT. Veja [LICENSE.txt](LICENSE.txt).
+Chronos Ruby is distributed under the MIT license. See [LICENSE.txt](LICENSE.txt).

data/docs/adr/legacy-deploy-cli.md

@@ -0,0 +1,21 @@
+# CLI de deploy legada — implementação para revisão
+
+Em 31/10/2026, a branch de trabalho é `legacy/1`, baseline `a8ab679`, versão 1.1.3, Ruby >= 2.2.10 e < 2.7. A autorização para executar o plano permite desenvolver esta exceção limitada ao congelamento. A versão de lançamento foi definida como 1.1.4; sua publicação continua condicionada aos gates e ao aceite. O artefato local 1.1.3 anterior serviu somente para validação, nunca para substituir uma versão publicada.
+
+A CLI usa OptionParser, configuração explícita e a API existente, sem boot Rails. ENV pertence à CLI. O alias Rake também não inicializa Rails. O generator Rails é somente um adaptador do instalador. Não há descoberta de revisão ou identidade por variáveis do fornecedor.
+
+`legacy/1.2` aponta para código anterior (b2a1347), portanto não foi adotada como ref transitória. O backport deve partir de uma ref de manutenção confirmada baseada em 1.2.1; nenhuma branch foi trocada automaticamente.
+
+A implementação atual fornece JSON em todas as respostas operacionais. O contrato desta entrega mantém a CLI leve: não oferece boot Rails; credenciais de initializer continuam atendidas pela API existente. Conflitos exibem o template proposto com o conteúdo anterior omitido por privacidade; faça merge manual ou use force explicitamente. Não gera configuração pública automaticamente. Templates de CI são fragmentos para merge manual e exigem os outputs reais exportados pelo cliente.
+
+Gates pendentes: instalação e execução em cada Ruby legado, Rails 4.2/5.2 nos pares documentados, receipt/ledger/projeção no SaaS local, execução nos fornecedores, backport transitório e aceite de manutenção/release. A suíte standalone e o smoke do pacote foram adicionados à matriz existente; testes locais no Ruby 3.4 não comprovam suporte legado.
+
+Revisão do contrato: diagnose exige a configuração completa de notificação, mas não autentica; host HTTPS obrigatório; metadados acima do limite do protocolo são rejeitados. Opções fora do comando correto são erros. Verify preserva verification_status do receipt, desliga dependências e nunca envia deploy. A CLI desativa retries e backlog; notify ainda pode enviar eventos de dependências. Falha no close após notify impede sucesso confirmado. Escrita usa arquivo temporário, criação exclusiva ou substituição explícita, com rechecagem de symlinks.
+
+Preparação da matriz: [procedimento e helper Docker](../legacy-test-environment.md). Sintaxe validada com gramática Ruby 2.2 é evidência estática apenas.
+
+Evidência local desta revisão: 201 exemplos RSpec passaram com Gemfile temporário e ferramentas locais no Ruby 3.4; 17 testes de CLI/configuração/fechamento (84 assertions), 2 testes de adaptadores (7 assertions) e 6 testes HTTPS (36 assertions) passaram. O pacote foi construído e o executável extraído respondeu help. Isso não equivale à instalação em Ruby suportado. A gramática Ruby 2.2 foi verificada estaticamente. RuboCop local 1.57 é suplementar; o gate oficial continua sendo 0.49 nas imagens legadas.
+
+Correções da revisão de segurança: lexer SQL conservador com rejeição de entrada truncada/ambígua e validação completa antes de inspeção; sanitização de Symbol; cópia estrutural limitada antes da construção e merge de eventos; instalador POSIX baseado em descritores, usando Fiddle da biblioteca padrão para openat/mkdirat/linkat/renameat/unlinkat. Não há shell ou biblioteca nativa escolhida pelo usuário. A raiz é aberta uma vez por instalação e os descendentes são abertos sem seguir symlinks; a escrita fica ancorada aos diretórios abertos. Os testes de corrida simulam substituições entre as operações e verificam ausência de alteração em diretório externo.
+
+Evidência após as correções de segurança: gates de core/segurança/pacote passaram em Docker Linux/amd64 nos cinco Rubies 2.2.10–2.6.10, com 221 exemplos RSpec, RuboCop 0.49.1 sem ocorrências em 225 arquivos, 25 testes adicionais de fonte (127 assertions) e 6 testes HTTPS da gem instalada (36 assertions) por runtime. Os gates Rails/Sidekiq, fornecedores, SaaS e promoção continuam separados.

data/docs/adr/transitional-deploy-cli.md

@@ -0,0 +1,11 @@
+# Transitional deploy automation port
+
+Base: main 1.2.1 (`b31d703`), branch feat/transitional-deploy-automation-1.2.2. The cherry-picked CLI and security behavior is retained; the gemspec remains Ruby >= 2.7 and < 3.5. Version 1.2.2 is a limited port, not the planned 2.x migration.
+
+Review against main confirmed the existing Rails Error Reporter, fiber-aware context, Action Cable, Faraday, W3C/OpenTelemetry integration paths remain in place. Agent context changes are limited to bounded copies/merge and breadcrumb preservation. Tests exercise ordinary modern behavior and the five security regressions.
+
+Unlike the legacy release, this line uses Bundler 2.4.22/RuboCop 1.57, a transitional core matrix, real Rails 7 fixtures and Sidekiq 7 middleware-chain fixtures. PR and release share a reusable validation workflow; framework dependency locks are uploaded as evidence. The old legacy scripts remain historical and cannot validate this gem's Ruby requirement.
+
+The CLI remains lightweight and never boots Rails implicitly. Generator integration uses the same installer. Optional Rails credential boot is deferred to the distinct modern plan. No protocol/schema change, hard-mode activation or SaaS rollout is included. See [readiness](../release-1.2.2-readiness.md) for observed results and pending gates.
+
+Local verification passed the six core runtimes, eight combined Rails/Sidekiq application pairs and six standalone Sidekiq middleware pairs, plus the audit and release-readiness execution gates. Remaining external/approval gates and evidence limitations are recorded in readiness; no compatibility status or published capability is promoted implicitly.