chronos-ruby 0.1.0.pre.2 → 0.3.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 203d12bad0a790efdb2bb89bcbc9127f067fc096507c6345aefbbdc7ed13966c
-  data.tar.gz: 2fb4eb956405f099b10b3e6f9429800446faf24127bc35b3e092dce316c1edb2
+  metadata.gz: db591fb9c6019444d079a5a5c683be8776b68010e3665e4a09656c2bdf568b46
+  data.tar.gz: 601f34cdaa1f9e06e2748a820b4228bad3c354a8c7feb562473d4268dc217117
 SHA512:
-  metadata.gz: 30be78abcf064b43e2f395c7493f5e7b037c8f1b8ac8dd5a4fc507ea86eae7c89fe0104f094551e3e92d68b4dded9010949fc9a79e43c01880217266bcebaa9c
-  data.tar.gz: 907ba0c16f873d533714b1a06448e857e7a4c8bfcf2b524a150bf0906244d507cf5e6b961d3db219bf63da6d3bf6933474e25360f3715d3e93b0e7d07929db21
+  metadata.gz: 1c4adaeb1222449ba2b7a736f1e28e701d00a1faf3733f42ffa753759854c3deed7a4c9e4c33f2ea997aa9445f057b51641b3829fb49b2012e6668687a1df4b0
+  data.tar.gz: 3809e42fbaed2f3290464cdc7a1e962a70e39fd8c3f7071b6016ee53c53406fca84a250f375e0a46506560c9bdc603f4ceb13721b79b4c6225b28a1e94abdf49

data/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes are documented here. The project follows Semantic Versioning
 
 ## [Unreleased]
 
+### Fixed
+
+- release publishing now updates RubyGems to a Ruby 2.6-compatible version that supports `GEM_HOST_API_KEY`.
+- Updated the legacy development toolchain to non-vulnerable Rake and RuboCop versions.
+- legacy CI now resolves Bundler 1.17.3 through `Gem.bin_path` on RubyGems versions that do not support the `_version_` executable selector.
+- documentation verification now reads source and Markdown files explicitly as UTF-8 on legacy container locales.
+
+## [0.3.0.pre.1] - 2026-07-20
+
+### Added
+
+- explicit delivery-state counters for accepted, queued, serialized, sent, retried, dropped, and rejected events;
+- finite exponential retry with bounded jitter and `Retry-After` support;
+- retry classification for network errors, HTTP 408, 429, and 5xx responses;
+- closed, open, and half-open circuit breaker states;
+- fixed-capacity in-memory backlog restricted to sanitized serialized events;
+- bounded remote configuration for sampling, event types, payload limits, exact fingerprint ignores, send interval, and kill switch;
+- resilience contracts, unit tests, module documentation, ADR, executable example, and outage benchmark.
+
+### Changed
+
+- asynchronous and synchronous delivery now pass through `DeliveryPipeline`;
+- `WorkerPool` delegates delivery policy instead of sending directly through a transport;
+- version advanced to `0.3.0.pre.1`.
+
+### Known limitations
+
+- backlog is not persisted and is lost when the process exits;
+- backlog draining requires later delivery activity;
+- no dedicated remote-configuration polling endpoint;
+- no automatic Rack, Rails, or job integration.
+
+## [0.2.0.pre.1] - 2026-07-19
+
+### Added
+
+- recursive sensitive-key sanitization with String, Symbol, and Regexp matchers;
+- content detection for Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and payment cards;
+- configurable identifier hashing and IPv4 anonymization;
+- bounded safe serialization with cycle and node-budget protection;
+- custom privacy filters with contained failures;
+- privacy contract tests, audit example, module documentation, and filtering benchmark.
+
+### Changed
+
+- all exception fields are sanitized before JSON serialization and transport;
+- configuration snapshots now recursively freeze privacy settings;
+- ADR-005 is accepted for the sanitization boundary.
+
+### Known limitations
+
+- sensitive-data detection is defensive and cannot replace an application privacy review;
+- IPv6 anonymization is not implemented;
+- no retry or backlog;
+- no automatic Rack, Rails, or job integration.
+
 ## [0.1.0.pre.2] - 2026-07-19
 
 ### Changed

data/README.md

@@ -1,10 +1,10 @@
 # Chronos Ruby
 
-Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.1 is the legacy foundation: it captures exceptions manually, builds a bounded JSON event, and delivers it synchronously or through a fixed-size asynchronous queue.
+Chronos Ruby is the framework-independent client for sending Ruby application errors to Chronos. Version 0.3 adds bounded resilience to the privacy-focused legacy foundation: manual exceptions are sanitized before queueing, retried under a finite policy, retained in a fixed-size memory backlog during outages, and controlled by a restricted remote policy.
 
 ## What the gem collects
 
-For each exception, version 0.1 can collect:
+For each exception, version 0.3 can collect:
 
 - exception class, message, structured backtrace, and chained causes;
 - timestamp, severity, tags, and an optional fingerprint;
@@ -16,11 +16,11 @@ See [Data collected](docs/data-collected.md) for the complete field table.
 
 ## What is not collected by default
 
-Chronos Ruby does not inspect environment variables, request bodies, cookies, HTTP headers, source code, database contents, or installed gems. Version 0.1 does not automatically sanitize application-supplied context. Do not pass passwords, tokens, cookies, personal documents, or payment data. Advanced redaction belongs to version 0.2.
+Chronos Ruby does not inspect environment variables, request bodies, cookies, HTTP headers, source code, database contents, or installed gems. Application-supplied fields are recursively sanitized, but applications should still avoid sending unnecessary personal, health, financial, or authentication data.
 
 ## Supported Ruby and Rails versions
 
-Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.1 is independent of Rails and does not yet declare support for any Rails integration. All supported combinations must pass dedicated CI before being listed as supported.
+Version 0.x targets Ruby 2.2.10 through Ruby 2.6. Version 0.3 is independent of Rails and does not yet declare support for any Rails integration. All supported combinations must pass dedicated CI before being listed as supported.
 
 See [Compatibility](docs/compatibility.md).
 
@@ -29,7 +29,7 @@ See [Compatibility](docs/compatibility.md).
 The current public build is a pre-release. Add its exact version to the application's `Gemfile`:
 
 ```ruby
-gem "chronos-ruby", "0.1.0.pre.2"
+gem "chronos-ruby", "0.3.0.pre.1"
 ```
 
 Install with a Bundler version compatible with the application. For the oldest supported runtime:
@@ -47,7 +47,7 @@ gem install chronos-ruby --pre
 
 ## Rails installation
 
-Rails automatic integration is not part of version 0.1. A Rails application may use the plain Ruby API, but this does not constitute declared Rails support. Rack and Rails adapters are planned for later legacy releases.
+Rails automatic integration is not part of version 0.3. A Rails application may use the plain Ruby API, but this does not constitute declared Rails support. Rack and Rails adapters are planned for later legacy releases.
 
 ## Minimum configuration
 
@@ -70,7 +70,7 @@ HTTPS verification is enabled by default. HTTP requires explicitly setting `ssl_
 
 ## Automatic capture
 
-Automatic exception capture is not implemented in version 0.1. Applications must call `Chronos.notify` or `Chronos.notify_sync`. Rack, Rails, and worker hooks will be introduced only after their compatibility suites exist.
+Automatic exception capture is not implemented in version 0.3. Applications must call `Chronos.notify` or `Chronos.notify_sync`. Rack, Rails, and worker hooks will be introduced only after their compatibility suites exist.
 
 ## Manual capture
 
@@ -101,15 +101,26 @@ User data is opt-in and must contain only values your application is allowed to
 Chronos.notify(error, :user => {"id" => "customer-42", "role" => "operator"})
 ```
 
-Avoid names, e-mail addresses, documents, tokens, and other personal or secret fields in version 0.1.
+Version 0.3 sanitizes this context before delivery and before it can enter retry storage. Data minimization remains the application's responsibility.
 
 ## Breadcrumbs
 
-Breadcrumbs are not implemented in version 0.1.
+Breadcrumbs are not implemented in version 0.3.
 
 ## Filters and LGPD
 
-Version 0.1 limits depth, collection length, string length, backtrace length, and total payload size. It does not provide the recursive sensitive-data filter planned for version 0.2. Review all supplied context before production use. See [Privacy and LGPD](docs/privacy-lgpd.md).
+Version 0.3 recursively redacts sensitive keys and detects Bearer tokens, JWTs, e-mail addresses, CPF, CNPJ, and valid payment-card candidates in free text. IPv4 addresses are anonymized by default. Applications can add blocklist matchers, hash selected identifiers, or install custom filters:
+
+```ruby
+Chronos.configure do |config|
+  # required options omitted
+  config.blocklist_keys += [:medical_record, /bank_account/i]
+  config.hash_keys += [:customer_id]
+  config.filters << proc { |key, value| key.to_s == "internal_reference" ? "[REMOVED]" : value }
+end
+```
+
+Sanitization runs before queueing and transport. See [Privacy and LGPD](docs/privacy-lgpd.md) for behavior, limitations, health and financial examples, and a payload audit procedure.
 
 ## Ignore rules
 
@@ -122,19 +133,19 @@ Chronos.configure do |config|
 end
 ```
 
-Exception-specific ignore rules are not available in version 0.1.
+Local exception-specific ignore callbacks are not available in version 0.3. The server may provide a bounded list of exact fingerprints to ignore; it cannot provide regular expressions or executable rules.
 
 ## Performance monitoring
 
-Request, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.1. The local capture pipeline is bounded and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
+Request, SQL, cache, job, and external HTTP monitoring are not implemented in version 0.3. The local capture pipeline is bounded and HTTP delivery runs outside the caller thread when `Chronos.notify` is used.
 
 ## Sidekiq and Active Job
 
-Sidekiq and Active Job integrations are not implemented in version 0.1. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
+Sidekiq and Active Job integrations are not implemented in version 0.3. Calling the manual API from a job is possible, but automatic capture and deduplication are not yet guaranteed.
 
 ## Deploy tracking
 
-Deploy notifications are not implemented in version 0.1. `app_version` may be included in exception events for release correlation.
+Deploy notifications are not implemented in version 0.3. `app_version` may be included in exception events for release correlation.
 
 ## Asynchronous queue
 
@@ -143,24 +154,33 @@ The queue has a fixed capacity and drops the newest event when full. Worker thre
 ```mermaid
 flowchart LR
   E[Exception] --> N[Notice builder]
-  N --> S[Bounded serializer]
-  S --> Q[Bounded queue]
+  N --> P[Privacy sanitizer]
+  P --> S[Safe bounded serializer]
+  S --> D[Delivery pipeline]
+  D --> Q[Bounded queue]
   Q --> W[Fixed worker pool]
-  W --> H[Net::HTTP transport]
+  W --> R[Retry and circuit breaker]
+  R --> H[Net::HTTP transport]
+  R --> B[Bounded memory backlog]
 ```
 
 Use `Chronos.flush(timeout)` to wait for accepted events and `Chronos.close(timeout)` during shutdown. Workers are recreated after a process fork.
 
 ## Retry and backlog
 
-Version 0.1 classifies network failures, `429`, `4xx`, and `5xx`, but does not retry or persist events. Failed deliveries are dropped after the attempt. Bounded retry and backlog are planned for version 0.3.
+Version 0.3 retries network errors, HTTP `408`, `429`, and `5xx` responses with exponential backoff, bounded jitter, and a finite attempt count. Other `4xx` responses are permanent and are not retried. A circuit breaker pauses requests after repeated failures, preventing retry storms.
+
+After retries are exhausted, the already sanitized `SerializedEvent` may enter a fixed-capacity memory backlog. The backlog drops new items when full, is lost when the process exits, and never writes to disk. A later successful half-open probe drains backlog items as new events arrive.
+
+The SaaS may return a JSON policy in the bounded `X-Chronos-Remote-Configuration` response header. Only sampling rate, enabled event types, a lower payload limit, exact ignored fingerprints, send interval, and kill switch are accepted. Remote values cannot change the host, project credentials, TLS, local maximums, code, or regular expressions. See [Retry and backlog](docs/modules/retry-backlog.md) and [Remote configuration](docs/modules/remote-configuration.md).
 
 ## How it works internally
 
 The code follows hexagonal boundaries:
 
-- `Chronos::Core` contains immutable notices and normalization;
+- `Chronos::Core` contains immutable notices, sanitization, and safe normalization;
 - `Chronos::Application` coordinates capture;
+- `Chronos::Application::DeliveryPipeline` owns bounded retry and remote policy;
 - `Chronos::Ports` defines delivery behavior;
 - `Chronos::Adapters` implements Net::HTTP delivery;
 - `Chronos::Internal` owns bounded queueing, workers, and defensive logging.
@@ -182,6 +202,14 @@ Chronos.configure do |config|
   config.workers = 1
   config.timeout = 5.0
   config.open_timeout = 2.0
+  config.max_retries = 3
+  config.retry_base_interval = 0.5
+  config.retry_max_interval = 30.0
+  config.retry_jitter = 0.25
+  config.backlog_size = 100
+  config.circuit_failure_threshold = 5
+  config.circuit_reset_timeout = 30.0
+  config.remote_configuration = true
 end
 ```
 
@@ -193,19 +221,21 @@ Configuration errors are raised during `Chronos.configure`. Capture and delivery
 
 ## Benchmark
 
-Run the version 0.1 benchmarks with:
+Run the version 0.3 benchmarks with:
 
 ```bash
 bundle _1.17.3_ exec ruby benchmarks/capture_exception.rb
 bundle _1.17.3_ exec ruby benchmarks/serialization.rb
+bundle _1.17.3_ exec ruby benchmarks/filtering.rb
 bundle _1.17.3_ exec ruby benchmarks/queue.rb
+bundle _1.17.3_ exec ruby benchmarks/retry_backlog.rb
 ```
 
 Results depend on runtime, hardware, and payload. No performance comparison is claimed until repeatable measurements are published.
 
 ## Migration from Airbrake
 
-An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.1 does not claim API compatibility or automatic replacement.
+An Airbrake migration guide will be added before the legacy 1.0 release. Version 0.3 does not claim API compatibility or automatic replacement.
 
 ## Local development
 

data/docs/adr/ADR-005-sanitize-before-backlog.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Proposed for versions 0.2 and 0.3; no backlog exists in 0.1.
+Accepted and implemented in version 0.3.
 
 ## Context
 
@@ -10,7 +10,7 @@ Persisting unsanitized events would increase privacy and credential exposure ris
 
 ## Decision
 
-Any future retry or persistent backlog must receive only data that has already passed sanitization and structural limits.
+`PayloadSerializer` must run `Sanitizer` before `SafeSerializer`, queueing, transport, retry, or backlog. `MemoryBacklog` accepts only `SerializedEvent`. Raw notices remain transient in process memory and never enter delivery storage.
 
 ## Alternatives
 

data/docs/adr/ADR-011-bounded-resilience-and-remote-control.md

@@ -0,0 +1,27 @@
+# ADR-011 — Bounded resilience and restricted remote control
+
+## Status
+
+Accepted for version 0.3.
+
+## Context
+
+Chronos must tolerate prolonged SaaS outages in legacy applications without unbounded memory, unlimited retries, extra per-event threads, unsanitized storage, or a remote-control channel capable of changing security boundaries.
+
+## Decision
+
+Place retry orchestration in `DeliveryPipeline`. Use finite exponential backoff with bounded positive jitter, a simple closed/open/half-open circuit breaker, and a fixed-capacity in-memory backlog that accepts only sanitized `SerializedEvent` values. Do not persist events to disk in version 0.3.
+
+Accept remote policy only from a size-limited JSON response header after successful authenticated event delivery. Apply a fixed scalar allowlist and local upper bounds. Reject executable content, remote regular expressions, host, credentials, TLS, and capacity changes.
+
+## Alternatives
+
+Retry inside `NetHttpTransport` was rejected because transport classification and delivery policy would become coupled. An unbounded queue was rejected because endpoint availability would control host memory. Immediate disk persistence was rejected because permissions, rotation, expiry, checksums, corruption, and privacy need an independent design. Arbitrary remote JSON or code callbacks were rejected as an unsafe control plane.
+
+## Positive consequences
+
+Outage memory remains bounded, retry storms are contained, transport stays replaceable, privacy precedes backlog, and remote operators can reduce or stop later collection without changing endpoint security.
+
+## Negative consequences
+
+Memory backlog is lost on restart and drains only when later delivery activity occurs. Synchronous notification may wait through retry delays. Process-local sampling is approximate. A response header limits policy size and complexity.

data/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Chronos Ruby 0.1 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
+Chronos Ruby 0.3 uses hexagonal boundaries so the legacy core remains independent of frameworks and delivery infrastructure.
 
 ```mermaid
 flowchart TB
@@ -8,7 +8,8 @@ flowchart TB
   Application --> Core[Core / Notice and serialization]
   Application --> Ports[Ports / Transport contract]
   Ports --> Adapter[Adapters / NetHttpTransport]
-  Application --> Internal[Internal / BoundedQueue and WorkerPool]
+  Application --> Delivery[Application / DeliveryPipeline]
+  Delivery --> Internal[Internal / BoundedQueue, WorkerPool, and MemoryBacklog]
   Internal --> Ports
 ```
 
@@ -24,8 +25,8 @@ The `Chronos` module is a thin facade. Rails, Rack, ActiveSupport, Sidekiq, and
 
 ## Capture flow
 
-An exception becomes an immutable notice, then a bounded JSON envelope. Asynchronous capture inserts the serialized event into a bounded queue. A fixed worker sends it through the transport. Synchronous capture bypasses the queue.
+An exception becomes an immutable notice. `Sanitizer` removes sensitive values before `SafeSerializer` creates a bounded JSON envelope. Asynchronous capture inserts only that sanitized serialized event into the queue. A fixed worker sends it through `DeliveryPipeline`, which applies finite retry, a circuit breaker, and a fixed memory backlog. Synchronous capture bypasses the queue but uses the same privacy and resilience boundaries.
 
 ## Failure policy
 
-Explicit invalid configuration raises `Chronos::ConfigurationError`. Capture, serialization, logger, worker, TLS, network, and HTTP failures do not escape into the host application. They produce `false`, a transport result, or a bounded logger diagnostic.
+Explicit invalid configuration raises `Chronos::ConfigurationError`. Capture, serialization, logger, worker, retry, circuit, TLS, network, HTTP, and remote-policy failures do not escape into the host application. They produce `false`, a classified transport result, a bounded state transition, or a bounded logger diagnostic.

data/docs/compatibility.md

@@ -4,14 +4,14 @@ Chronos Ruby 0.x is the legacy line. Technical compatibility does not make an en
 
 | Ruby | Rails integration | Status | Evidence |
 |---|---|---|---|
-| 2.2.10 | None in 0.1 | Best effort | Local unit, contract, integration, fork, and fake-server suite |
-| 2.3.8 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
-| 2.4.10 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
-| 2.5.9 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
-| 2.6.10 | None in 0.1 | Best effort | Dedicated CI job pending first successful run |
+| 2.2.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 2.3.8 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 2.4.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 2.5.9 | None in 0.3 | Best effort | Dedicated legacy core CI job |
+| 2.6.10 | None in 0.3 | Best effort | Dedicated legacy core CI job |
 | 2.7 and newer | None in 0.x | Unsupported | Belongs to transitional or modern lines |
 
-No Rails version is declared supported by version 0.1. Rails applications may call the plain Ruby API manually. Rails support requires a real example application, framework integration tests, and a successful dedicated matrix job.
+No Rails version is declared supported by version 0.3. Rails applications may call the plain Ruby API manually. Rails support requires a real example application, framework integration tests, and a successful dedicated matrix job.
 
 Status meanings:
 

data/docs/configuration.md

@@ -24,6 +24,23 @@
 | `user_agent` | Optional | Agent version | HTTP user agent |
 | `max_payload_size` | Optional | `1048576` | Maximum serialized payload bytes |
 | `gzip` | Optional | `false` | Compresses request bodies with gzip |
+| `blocklist_keys` | Recommended | Sensitive-key defaults | String, Symbol, or Regexp keys whose values are redacted |
+| `allowlist_keys` | Optional | `[]` | Explicit key-name exceptions; content detection still runs |
+| `hash_keys` | Optional | `[]` | Scalar identifier keys replaced by scoped SHA-256 values |
+| `filters` | Optional | `[]` | Callable application-specific privacy filters |
+| `anonymize_ip` | Recommended | `true` | Replaces the final octet of supplied IPv4 addresses |
+| `max_retries` | Optional | `3` | Maximum retry attempts after the first delivery failure |
+| `retry_base_interval` | Optional | `0.5` | Initial exponential-backoff delay in seconds |
+| `retry_max_interval` | Optional | `30.0` | Maximum local or `Retry-After` delay in seconds |
+| `retry_jitter` | Optional | `0.25` | Random positive jitter fraction between `0.0` and `1.0` |
+| `backlog_size` | Optional | `100` | Maximum sanitized events retained in memory after delivery failure; `0` disables retention |
+| `circuit_failure_threshold` | Optional | `5` | Consecutive retryable failures before opening the circuit |
+| `circuit_reset_timeout` | Optional | `30.0` | Seconds before one half-open delivery probe |
+| `remote_configuration` | Optional | `true` | Accepts only the documented bounded remote policy fields |
+| `remote_config_max_bytes` | Optional | `4096` | Maximum remote policy response-header bytes |
+| `sampling_rate` | Optional | `1.0` | Local upper bound for exception sampling |
+| `enabled_event_types` | Optional | `["exception"]` | Local event-type allowlist; only exception exists in version 0.3 |
+| `max_remote_send_interval` | Optional | `60.0` | Local upper bound for remotely requested send spacing |
 
 ```ruby
 Chronos.configure do |config|
@@ -34,7 +51,16 @@ Chronos.configure do |config|
   config.service_name = "billing"
   config.queue_size = 100
   config.workers = 1
+  config.blocklist_keys += [:medical_record, /bank_account/i]
+  config.hash_keys += [:customer_id]
+  config.max_retries = 3
+  config.backlog_size = 100
+  config.circuit_failure_threshold = 5
 end
 ```
 
-The gem never reads all environment variables automatically. The host application decides which values to pass.
+Privacy matcher collections and filters are copied into the immutable runtime snapshot. Matchers must be String, Symbol, or Regexp values, and every custom filter must respond to `call`.
+
+The gem never reads all environment variables automatically. The host application decides which values to pass. See [Privacy and LGPD](privacy-lgpd.md) before adding application context.
+
+Remote configuration can only reduce collection within local bounds. It cannot increase `max_payload_size` or `sampling_rate`, enable an unsupported or locally disabled event type, change the endpoint, replace credentials, disable TLS verification, or install executable matching rules.

data/docs/data-collected.md

@@ -1,20 +1,23 @@
 # Data collected
 
-Version 0.1 emits only manual exception events.
+Version 0.3 emits only manually submitted exception events. All fields pass through the privacy sanitizer and bounded safe serializer before queueing, retry storage, or delivery.
 
 | Data | Default | Source |
 |---|---|---|
-| Exception class and message | Collected | Ruby exception |
+| Exception class and sanitized message | Collected | Ruby exception |
 | Structured backtrace | Collected when present | Ruby exception |
-| Cause class and message | Collected when present | `Exception#cause` |
+| Sanitized cause class and message | Collected when present | `Exception#cause` |
 | Ruby version, engine, platform | Collected | Ruby constants |
 | PID and opaque thread ID | Collected | Ruby runtime |
 | Hostname | Collected when available | Standard library |
 | Environment and service | Configuration | Host application |
 | Application version | Optional | Host application |
-| Context, parameters, session, user | Optional | Explicit capture arguments |
-| Tags and fingerprint | Optional | Explicit capture arguments |
+| Context, parameters, session, user | Optional and sanitized | Explicit capture arguments |
+| Tags and fingerprint | Optional and sanitized | Explicit capture arguments |
+| IPv4 address in supplied text | Anonymized | Explicit capture arguments |
 
-The gem never collects request bodies, response bodies, cookies, HTTP authorization headers, environment variables in bulk, source code, SQL bind values, database rows, or installed gems in version 0.1.
+The gem never collects request bodies, response bodies, cookies, HTTP authorization headers, environment variables in bulk, source code, SQL bind values, database rows, or installed gems in version 0.3.
 
-The secret `project_key` is an authentication header and is excluded from the JSON payload and logger diagnostics.
+The secret `project_key` is an authentication header and is excluded from the JSON payload and logger diagnostics. The envelope field named `project_key` contains the public `project_id` required by the current v1 server contract.
+
+See [Privacy and LGPD](privacy-lgpd.md) for redaction rules and the payload audit procedure.

data/docs/examples/plain-ruby.md

@@ -10,3 +10,17 @@ bundle _1.17.3_ exec ruby examples/plain-ruby/example.rb
 ```
 
 The example reports one manual exception and closes the agent with a two-second timeout. Use a local fake endpoint when auditing the payload.
+
+For a network-free privacy audit, run:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/privacy_audit.rb
+```
+
+For a network-free outage and bounded-backlog example, run:
+
+```bash
+bundle _1.17.3_ exec ruby examples/plain-ruby/resilient_delivery.rb
+```
+
+The example builds the final event locally and demonstrates key redaction, e-mail and Bearer-token detection, application-specific blocklisting, and identifier hashing.

data/docs/modules/async-queue.md

@@ -10,8 +10,12 @@ stateDiagram-v2
   Accepted --> Queued
   Queued --> Sending
   Sending --> Sent
-  Sending --> Dropped: delivery failure in 0.1
+  Sending --> Retried: retryable failure
+  Retried --> Sending: policy permits
+  Retried --> Backlog: attempts exhausted
+  Backlog --> Sending: later recovery probe
+  Sending --> Rejected: permanent 4xx
   Accepted --> Dropped: queue full
 ```
 
-Version 0.1 has no disk persistence and no retry. Queue statistics expose current size, capacity, accepted events, and dropped events. Tests cover full queues, waiter wakeup, lazy startup, contained failures, timed shutdown, double close, flush, and fork behavior.
+Version 0.3 adds retry and a separate fixed-size memory backlog, but no disk persistence. Only sanitized serialized events enter either structure. Queue statistics expose current size, capacity, accepted events, and dropped events. Delivery diagnostics additionally expose state counters, backlog statistics, and circuit state. Tests cover full queues, waiter wakeup, lazy startup, contained failures, timed shutdown, double close, flush, fork behavior, and prolonged endpoint failure.

data/docs/modules/notice-pipeline.md

@@ -9,12 +9,15 @@ flowchart LR
   NoticeBuilder --> CauseCollector
   NoticeBuilder --> RuntimeInfo
   NoticeBuilder --> Notice
-  Notice --> PayloadSerializer
+  Notice --> Sanitizer
+  Sanitizer --> SafeSerializer
+  SafeSerializer --> PayloadSerializer
   PayloadSerializer --> SerializedEvent
+  SerializedEvent --> DeliveryPipeline
 ```
 
-`Notice` is immutable. Parsers are stateless. The serializer accepts only JSON primitives, bounds nested structures, tolerates invalid encoding, and represents unknown objects without arbitrary `to_json` calls.
+`Notice` is immutable. Parsers are stateless. Raw notice values exist only in process memory. The sanitizer removes sensitive keys and recognized personal data before the safe serializer accepts JSON primitives, bounds nested structures, tolerates invalid encoding, and represents unknown objects without arbitrary application serialization.
 
-Version 0.1 deliberately excludes the advanced sanitizer, sampler, and fingerprint policy. These can be inserted before serialization without changing transport or queue code.
+Version 0.3 passes the serialized event to `DeliveryPipeline`. The pipeline applies remote sampling and exact fingerprint policy before serialization where possible, then manages queueing, retry, circuit state, and bounded memory backlog without changing transport or queue code.
 
 Unit and contract tests verify missing backtraces, cyclic causes, invalid encoding, unsafe objects, payload limits, and the v1 envelope.

data/docs/modules/remote-configuration.md

@@ -0,0 +1,54 @@
+# Remote configuration module
+
+## Problem
+
+Operators may need to reduce event volume or stop collection during an incident without redeploying a legacy application. Accepting unrestricted server instructions would create remote-code, SSRF, credential, privacy, and memory risks.
+
+## Boundary
+
+`NetHttpTransport` only parses a bounded JSON object from the `X-Chronos-Remote-Configuration` success-response header. `Chronos::Application::RemoteConfiguration` owns the allowlist and local upper bounds. `DeliveryPipeline` applies accepted policy to later capture and delivery work.
+
+## Allowed fields
+
+| Field | Accepted value | Local restriction |
+|---|---|---|
+| `sampling_rate` | Number from `0.0` to `1.0` | Cannot exceed local `sampling_rate` |
+| `enabled_event_types` | Array of strings | Intersected with local and implemented event types |
+| `max_payload_size` | Integer | Cannot exceed local maximum or fall below 256 bytes |
+| `ignored_fingerprints` | Up to 100 strings | Exact matching only; 256 bytes per value |
+| `send_interval` | Non-negative seconds | Cannot exceed `max_remote_send_interval` |
+| `kill_switch` | Boolean | Stops later capture while active |
+
+Unknown keys are ignored. If a recognized value is invalid, the document is rejected atomically and the previous policy remains active.
+
+## Explicitly forbidden
+
+Remote configuration cannot change host, proxy, project ID, project key, TLS verification, logger, queue or backlog capacity, retry limits, local upper bounds, Ruby code, object serialization, regular expressions, or arbitrary headers. No `eval`, `send`, `Marshal`, YAML, or application callback is used.
+
+## Example server response
+
+```text
+HTTP/1.1 202 Accepted
+X-Chronos-Remote-Configuration: {"sampling_rate":0.25,"send_interval":1.0,"kill_switch":false}
+```
+
+Disable this channel locally when it is not required:
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.remote_configuration = false
+end
+```
+
+## Risks and limits
+
+- The policy is process-local and is not persisted across restarts.
+- A stale policy remains until another accepted response changes it.
+- The header size is bounded before JSON parsing, but upstream proxies may impose a lower header limit.
+- Sampling uses process-local randomness and is not a globally exact rate.
+- Version 0.3 does not poll a separate configuration endpoint.
+
+## Tests
+
+Tests cover the field allowlist, local caps, unsupported event types, invalid types, regex rejection, forbidden endpoint and credential keys, response-header byte limits, kill switch, sampling, and atomic preservation of previous state.

data/docs/modules/retry-backlog.md

@@ -0,0 +1,60 @@
+# Retry and backlog module
+
+## Problem
+
+Transient endpoint failures must not discard every event immediately, block application threads indefinitely, or grow memory without a limit.
+
+## Boundary
+
+Retry belongs to `Chronos::Application::DeliveryPipeline`, not `NetHttpTransport`, because HTTP classifies an outcome while application policy decides whether another attempt is acceptable. `Chronos::Internal::MemoryBacklog` is separate from the asynchronous queue because it stores failed deliveries, not newly accepted work.
+
+## Data flow
+
+```mermaid
+stateDiagram-v2
+  [*] --> accepted
+  accepted --> serialized
+  serialized --> queued: asynchronous capture
+  queued --> sent: successful delivery
+  serialized --> sent: synchronous delivery
+  queued --> retried: network, 408, 429, or 5xx
+  retried --> sent: later attempt succeeds
+  retried --> backlog: attempts exhausted or circuit open
+  backlog --> sent: later half-open recovery
+  backlog --> dropped: backlog full
+  queued --> rejected: permanent 4xx
+```
+
+`RetryPolicy` calculates exponential backoff with positive bounded jitter. `Retry-After` is respected only within `retry_max_interval`. `CircuitBreaker` opens after the configured consecutive failure count, rejects concurrent probes, and permits one half-open probe after `circuit_reset_timeout`.
+
+The memory backlog accepts only `SerializedEvent`. Sanitization and safe serialization therefore happen before an event can enter retry storage. Its capacity is `backlog_size`; zero disables retention. The oldest stored event is attempted as new delivery activity arrives. No background timer or additional thread exists for backlog draining.
+
+## Configuration and extension
+
+```ruby
+Chronos.configure do |config|
+  # connection settings omitted
+  config.max_retries = 3
+  config.retry_base_interval = 0.5
+  config.retry_max_interval = 30.0
+  config.retry_jitter = 0.25
+  config.backlog_size = 100
+  config.circuit_failure_threshold = 5
+  config.circuit_reset_timeout = 30.0
+end
+```
+
+Tests may inject a clock, sleeper, random source, backlog, or retry policy into `DeliveryPipeline`. These are internal composition points rather than stable public configuration APIs.
+
+## Risks and limits
+
+- Events in memory are lost on process exit.
+- A quiet process does not drain backlog until another event triggers delivery.
+- Backlog order is best effort when multiple workers are active.
+- Retry sleeps occupy a fixed worker, never the application caller for asynchronous capture.
+- Synchronous capture waits for configured retries and should be used only when that latency is acceptable.
+- Disk persistence is deliberately excluded from version 0.3.
+
+## Tests
+
+Unit tests cover bounded exponential delay, retry limits, `Retry-After`, permanent `4xx`, circuit opening and half-open recovery, fixed backlog capacity, raw-object rejection, prolonged outage, state counters, and recovery draining. The privacy contract proves that fixture secrets do not enter backlog storage.

data/docs/modules/sanitization.md

@@ -0,0 +1,19 @@
+# Sanitization module
+
+`Chronos::Core::Sanitizer` prevents raw secrets and common personal identifiers from crossing the serialization boundary. It is separate from `SafeSerializer`: privacy policy decides what may remain, while serialization decides which Ruby values can safely become JSON.
+
+```mermaid
+flowchart LR
+  Notice --> Envelope
+  Envelope --> Sanitizer
+  Sanitizer --> SafeSerializer
+  SafeSerializer --> JSON
+  JSON --> Queue
+  JSON --> Transport
+```
+
+`Sanitizer` recursively processes hashes and arrays, supports String, Symbol, and Regexp key matchers, anonymizes IPv4 addresses, and optionally hashes selected scalar identifiers. `SensitiveValueFilter` validates and redacts common sensitive patterns in free text. Depth, visited nodes, hash keys, and array items are bounded before safe serialization. Custom filters can remove application-specific fields. A failing filter redacts its field and cannot interrupt the application.
+
+The module deliberately does not inspect global variables, environment variables, request bodies, database records, or arbitrary object methods. Pattern detection can produce false positives or miss domain-specific formats, so applications must extend the blocklist and audit representative payloads.
+
+Tests in `spec/unit/core/sanitizer_spec.rb` cover recursive keys, allowlisting, content detection, hashing, IP anonymization, and filter failure. `spec/contract/privacy_spec.rb` ensures sensitive fixtures never occur in the final JSON payload.