auditea 0.1.0.beta.1 → 0.1.0.beta.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 308c6d6709fed09f200bcfc60829af1b7bd470a018691f456576818ccadc87ee
-  data.tar.gz: 27a669b879d0d864d427359bae7c01daf27e2a2d492e45ed73b492136d659196
+  metadata.gz: 587d3b57a35018f55c5e82c15a485715913e911a714971797a47fde50d788251
+  data.tar.gz: beae506f6609e933baa4d4513e9015cc7b11c919a75ed83ba912eeb546aae0e5
 SHA512:
-  metadata.gz: 18517d6f3b825b1f1c97daab0bce3d6da97f68b157d87fb6c6aa302d0b6d79e1e202a682d4c427824df2ae71e7a7f51004124b8cc5ee7246d4d898e0e78cdc06
-  data.tar.gz: c8faa401027af8fadaa8f565994a875c047bed3840722ef101673c7a4565e554965e13e7f1d9b313bd9245499ffb02110145650ade188891278ec06e5aa87d6d
+  metadata.gz: 16e6ebde275b1f03f12028ca1c746fdedd9efb907706560ecae52b1fed188e90944f0e827c40e7a1cb909742d381fe37d26deb385ee66d82965c8185444ac99f
+  data.tar.gz: e0c7097c1f146d724befdaf2df850e30a556c670a06406f459003b46a2b52fc77687b36d3fa366d3db4662e13718ddf70ea12698480555858bf51650ee9781c8

data/CHANGELOG.md

@@ -1,6 +1,65 @@
 # Changelog
 
-## 0.1.0.beta.1 (unreleased)
+## 0.1.0.beta.3 (unreleased)
+
+### Exception capture parity (AUD-ERROR-PARITY01)
+
+- Public `Auditea.capture_exception(error, handled:, mechanism:, context:, metadata:)` → `exception.raised`
+- Rails `ErrorReporter` subscriber via public `subscribe` API (Rails 7.2 / 8.1); graceful no-op when absent
+- Identity-safe WeakMap dedupe of exception objects (no integer `object_id` reuse false negatives); cleared at request/job boundaries
+- When `CurrentContext` is already cleared (post-unwind `application.action_dispatch`), derive method/path/request_id/controller/action from the ErrorReporter controller/request via public APIs only
+- `process_action.action_controller` remains as fallback when ErrorReporter is not installed
+- Structured evidence: type, message, bounded frames (≤40) with deterministic `in_app` when knowable, `handled`, `mechanism`, HTTP path/method (no query secrets), controller/action when available
+- ActiveJob: ErrorReporter sources matching `active_job` are skipped when `capture_active_job` is enabled (dedicated `job.failed` path unchanged)
+- Real Rails 7.2 / 8.1 integration coverage for unhandled/handled controller exceptions and ActiveJob no-duplicate behavior
+- Provenance unchanged: sdk/ruby/rails versions + configured `release`
+
+## 0.1.0.beta.2
+
+### Runtime / dependency inventory (opt-in, default OFF)
+
+- Emit `runtime.inventory` (category `security`) when enabled
+- Ruby engine/version/platform, gem platform, Rails when present, Bundler, RubyGems
+- Ruby-linked OpenSSL constants only (`OpenSSL::VERSION` / build library) — **not** system OpenSSL
+- Locked Bundler gems when available (`completeness: bundle_locked`), else loaded gems (`loaded_only`); may be `truncated`
+- Deterministic package order + SHA-256 digest; package count/string bounds; valid UTF-8
+- Privacy: no filesystem paths, Gemfile/lockfile raw contents, registry/Git URLs, credentials, tokens, env dumps
+- Config: `AUDITEA_CAPTURE_RUNTIME_INVENTORY` / `config.capture_runtime_inventory` **default false**
+- Rails `after_initialize` may emit once when enabled; ~daily process-local refresh thereafter
+- Rack path only **schedules** single-flight background refresh (never inline collection/delivery)
+- Sanitizer allows larger `evidence.inventory.packages` arrays (bounded)
+
+### Host inventory (opt-in, default OFF)
+
+- Emit `host.inventory` with opaque `host_key`, OS/arch/kernel facts, optional display label
+- Multi-host-per-Source / container replica differentiation; no raw machine-id or hostname in payload
+- Linux `os_version` from `/etc/os-release` (not `uname.version` kernel build string)
+- Architecture, kernel name/release, container hint boolean only
+- No OS package/CVE collection (server-side / future)
+- Config: `AUDITEA_CAPTURE_HOST_INVENTORY` **default false**
+- Rack path only schedules single-flight background refresh
+
+### Release provenance
+
+- Configured application release is sent as `provenance.release` (server canonical evidence)
+- Precedence when building configuration: explicit `config.release=` (configure block) overrides env;
+  at initialize: `AUDITEA_RELEASE` → `RELEASE` → `HEROKU_RELEASE_VERSION`
+- No `.git` inspection, no `git rev-parse`, no cloud deployment APIs
+
+### Safety / transport (carried forward + hardened)
+
+- Fail-open by default (`raise_errors` default false)
+- HTTPS required except loopback HTTP
+- Process-aware async queue; single worker; flush waits for in-flight work
+- Request/exception/ActiveJob capture behavior unchanged in intent from beta.1 defaults
+  (`capture_requests` default false; `capture_exceptions` / `capture_active_job` default true)
+
+### Packaging / support
+
+- MIT license; `rubygems_mfa_required`; push host RubyGems.org
+- Supported CI matrix: Ruby 3.2/3.3 + Rails 7.2; Ruby 3.4/4.0.6 + Rails 8.1
+
+## 0.1.0.beta.1
 
 - Initial SDK: capture, structured logs, Rails request/exception observation, ActiveJob failures
 - EVENT_CONTRACT_V1 transport with HTTPS/loopback policy, status classification, byte limits, batch index results

data/DESIGN.md

@@ -38,11 +38,24 @@ PR: https://github.com/reznis/auditea-ruby/pull/2
 | Privacy filter | KEEP CONCEPT + REFACTOR (all egress + redacted_fields) |
 | Exception capture | REFACTOR (fixed frames) |
 | Security surface | KEEP CONCEPT (deferred beyond beta.1 core) |
+| Runtime / dependency inventory | REWRITE for vNext (`runtime.inventory`, opt-in, locked bundle) |
 | `Thread.new` per event | REWRITE → bounded queue |
 | `AUDITEA_DEBUG` full payload logs | DROP |
 | Auto Rails.logger forward | DROP for beta.1; adapter boundary reserved |
 
+## AUD-P013 Phase A — runtime inventory
+
+- Action: `runtime.inventory` / category `security`
+- Prefer materialized current-platform `Bundler.definition.specs` (not every lockfile variant; `force_ruby_platform` respected via Bundler) → `bundle_locked`; fallback `Gem.loaded_specs` → `loaded_only` when the locked path cannot be fully materialized; `truncated` when package/size bounds are hit
+- OpenSSL fields are Ruby-linked only (not host `openssl` / OS packages)
+- No paths, URLs, credentials in package sources; git may include revision SHA only
+- Deterministic package ordering + SHA-256 digest (no timestamps/PIDs/hostnames)
+- Default `AUDITEA_CAPTURE_RUNTIME_INVENTORY=false`
+- Measured typical SDK Gemfile inventory ≪ 128 KiB; bound packages (400) + size budget before truncate
+- Sanitizer special-cases `evidence.inventory.packages` array max (400) so ordinary 100-cap does not silently drop gems
+
 ## Compatibility
 
 - Ruby >= 3.2, including current Ruby 4.0.x (CI: 3.2, 3.3, 3.4, 4.0.6)
 - Rails 7.2 and Rails 8.1 gemfiles under `gemfiles/`
+

data/README.md

@@ -2,15 +2,17 @@
 
 Ruby / Rails SDK for [AudiTea](https://github.com/reznis/AudiTea) event collection.
 
-Version: **0.1.0.beta.1**
+Version: **0.1.0.beta.3** (not published yet)
 
-Captures durable technical and business evidence. AudiTea **server** owns taxonomy, dictionary, human labels, and reinterpretation.
+Captures durable technical and business evidence. AudiTea **server** owns taxonomy, dictionary, human labels, vulnerability matching, correlation, and reinterpretation.
+
+The SDK does **not** perform vulnerability scanning, OS package/CVE inventory, deployment detection, root-cause analysis, AI, or APM/metrics.
 
 ## Install (after RubyGems beta publication)
 
 ```ruby
 # Gemfile
-gem "auditea", "0.1.0.beta.1"
+gem "auditea", "0.1.0.beta.3"
 ```
 
 ```bash
@@ -27,18 +29,80 @@ Prefer the RubyGems artifact for ordinary TEST deployments once published.
 
 ## Configure
 
+### Required
+
+| Setting | Purpose |
+|---|---|
+| `endpoint` / `AUDITEA_ENDPOINT` | AudiTea server base URL (HTTPS, or HTTP only to loopback) |
+| `source_token` / `AUDITEA_SOURCE_TOKEN` | Source credential (`at_src_…`) |
+
+Without a Source token (and with the SDK enabled), capture is skipped (`not_configured`) — the host app keeps running. Note: there is a **default endpoint**, so clearing `AUDITEA_ENDPOINT` alone is not a reliable disable.
+
+### Recommended for first controlled TEST pilot
+
+| Setting | Recommendation | Why |
+|---|---|---|
+| `release` / `RELEASE` | Set an opaque app release id | Server Observed Releases use `provenance.release` |
+| `capture_exceptions` | `true` (default) | Useful error evidence with restrained volume |
+| `capture_runtime_inventory` | `true` for pilot | Dependency evidence; default is OFF — enable deliberately |
+| `capture_host_inventory` | `true` only if multi-host/container identity matters | Default OFF; enable per environment decision |
+| `capture_requests` | `false` initially | Avoid high-volume request spam on first connect |
+
+### Optional
+
+Async tuning (`AUDITEA_ASYNC`, batch/flush/queue/timeouts), `AUDITEA_INVENTORY_REFRESH_INTERVAL`, `AUDITEA_HOST_KEY` / `AUDITEA_HOST_LABEL`, `capture_request_params`, `raise_errors` (debug only).
+
+### First TEST initializer (example)
+
 ```ruby
 # config/initializers/auditea.rb
 Auditea.configure do |config|
-  config.endpoint = ENV.fetch("AUDITEA_ENDPOINT", "https://app.auditea.com")
-  config.source_token = ENV.fetch("AUDITEA_SOURCE_TOKEN") # at_src_<public_id>_<secret>
-  config.capture_requests = true   # opt-in Rails request observation
+  config.endpoint = ENV.fetch("AUDITEA_ENDPOINT")
+  config.source_token = ENV.fetch("AUDITEA_SOURCE_TOKEN")
+
+  # Opaque release id. Prefer AUDITEA_RELEASE (matches Configuration initialize
+  # precedence). Explicit config.release always wins over env.
+  config.release = ENV["AUDITEA_RELEASE"] || ENV["RELEASE"]
+
   config.capture_exceptions = true
-  config.release = ENV["RELEASE"]
+  config.capture_runtime_inventory = true
+
+  # First pilot: keep request volume low unless you need path evidence immediately.
+  config.capture_requests = false
+
+  # Enable only when you want opaque host/node identity in this environment.
+  config.capture_host_inventory = ENV["AUDITEA_CAPTURE_HOST_INVENTORY"] == "true"
+
+  # Never leave raise_errors on in shared TEST/prod hosts.
+  config.raise_errors = false
 end
 ```
 
-Environment variables: `AUDITEA_ENDPOINT`, `AUDITEA_SOURCE_TOKEN` (or `AUDITEA_API_KEY`), `AUDITEA_CAPTURE_REQUESTS`, `AUDITEA_CAPTURE_EXCEPTIONS`, `AUDITEA_ASYNC`, `AUDITEA_RELEASE`.
+### Release precedence
+
+1. Explicit `config.release = …` in the configure block (wins)
+2. Else at `Configuration` initialize: `AUDITEA_RELEASE` → `RELEASE` → `HEROKU_RELEASE_VERSION`
+
+No git inspection. No cloud metadata calls.
+
+### Pilot rollback / disable (safe)
+
+Preferred immediate disable:
+
+```bash
+AUDITEA_ENABLED=false
+```
+
+(or `config.enabled = false` and redeploy)
+
+Other valid paths:
+
+1. Remove / revoke the Source token (`AUDITEA_SOURCE_TOKEN`) — without a token, capture is `not_configured`
+2. Revoke the Source credential server-side (SDK fail-opens on auth failure)
+3. Disable individual capture flags (`capture_exceptions`, inventories, requests)
+4. Remove the initializer and/or gem from the Gemfile and redeploy
+
+Do **not** treat “remove endpoint” as a reliable kill switch while a valid Source token remains: Configuration has a default endpoint.
 
 ## Capture APIs
 
@@ -50,9 +114,17 @@ Auditea.capture(
   evidence: { business: { from_status: "draft", to_status: "approved" } }
 )
 
+Auditea.capture_exception(
+  error,
+  handled: true,
+  mechanism: "application_rescue"
+)
+
 Auditea.log(:info, "Export finished", context: { export_id: export.id })
 ```
 
+Automatic Rails exception observation uses `Rails.error` (ErrorReporter) when available, with `process_action.action_controller` as fallback. Same-exception dedupe is request/thread-local by object id so ErrorReporter and controller notifications do not double-count.
+
 Wire format follows AudiTea **EVENT_CONTRACT_V1**:
 
 - Bearer Source credential authentication
@@ -60,6 +132,52 @@ Wire format follows AudiTea **EVENT_CONTRACT_V1**:
 - No client tenancy/scope fields (`workspace_id`, `environment`, …)
 - Extensible `evidence` / `context` / `provenance` / `metadata` bags
 
+## Runtime inventory (opt-in, default off)
+
+When enabled, the SDK can emit a `runtime.inventory` security event describing:
+
+- Ruby engine / version / platform / gem platform
+- Rails version (when Rails is present)
+- Bundler + RubyGems versions
+- OpenSSL **linked to Ruby** — not host/system OpenSSL
+- AudiTea SDK version and configured release
+- Locked Bundler gems when available (`completeness: bundle_locked`), otherwise loaded gems (`loaded_only`)
+
+**Not collected:** filesystem paths, Gemfile/lockfile raw contents, Git remote URLs, private registry URLs, credentials, tokens, environment variables, usernames, hostnames.
+
+```ruby
+Auditea.capture_runtime_inventory!
+Auditea.maybe_capture_runtime_inventory!
+```
+
+```bash
+AUDITEA_CAPTURE_RUNTIME_INVENTORY=true
+# optional: AUDITEA_INVENTORY_REFRESH_INTERVAL=86400
+```
+
+With Rails, when capture is enabled, the Railtie may emit once after `after_initialize`. Opportunistic Rack refresh only **schedules** a single-flight background job when due — collection/delivery are never inline on the request path.
+
+Enabling inventory reveals internal gem names to AudiTea. Keep it off unless that is intentional.
+
+## Host inventory (opt-in)
+
+Emits `host.inventory` with an opaque host/node key and platform/OS facts.
+
+**Collected (bounded):** opaque `host_key`, optional display `label`, OS family/name/version, architecture, kernel name/release, logical CPU count, container hint boolean, SDK name/version.
+
+**Not collected:** raw hostname, machine-id plaintext, filesystem paths, env vars, credentials, CPU/memory/disk utilization, processes, ports, packages/CVEs, cloud metadata dumps.
+
+```ruby
+Auditea.capture_host_inventory!
+Auditea.maybe_capture_host_inventory!
+```
+
+```bash
+AUDITEA_CAPTURE_HOST_INVENTORY=true
+# optional: AUDITEA_HOST_KEY=...
+# optional: AUDITEA_HOST_LABEL=...
+```
+
 ## Rails
 
 The Railtie installs:
@@ -67,21 +185,18 @@ The Railtie installs:
 - request context middleware (path **without** query string, request_id, method)
 - optional `process_action` observation → `network.request.completed`
 - optional exception observation → `exception.raised`
-
-Structural evidence is preserved so the server can later distinguish routes such as `/researchers/projects/18` vs `/bcer/1/projects/18` without SDK redeploy.
+- optional inventory emit after initialize when enabled
 
 ### Structured logs
 
-Use `Auditea.log` explicitly.
-
-**Automatic `Rails.logger` forwarding is intentionally disabled in beta.1** (`Auditea::Instrumentation::LoggerAdapter`).
+Use `Auditea.log` explicitly. **Automatic `Rails.logger` forwarding is intentionally disabled.**
 
 ## Transport
 
 - Sync or single-worker async queue (not one thread per event)
 - HTTPS required (HTTP allowed only for localhost / 127.0.0.1 / ::1)
 - Single events → `POST /api/v1/events`
-- Batches → `POST /api/v1/event_batches` with per-index result handling
+- Batches → `POST /api/v1/event_batches`
 - Client-side 128 KiB / 1 MiB / 100-event limits
 - Retries with injectable exponential backoff+jitter on 5xx / 429 / network
 - Process-aware queue for pre-fork servers
@@ -95,7 +210,11 @@ AUDITEA_SOURCE_TOKEN=at_src_... \
 bundle exec ruby examples/manual_capture.rb
 ```
 
-Never commit a real token. The script prints a minimal safe result only.
+Never commit a real token.
+
+## Release process
+
+See [RELEASE.md](RELEASE.md). Do not `gem push` without explicit human approval after server readiness.
 
 ## License
 
@@ -108,10 +227,11 @@ bundle install
 bundle exec rspec
 bundle exec rubocop
 gem build auditea.gemspec
+bash script/release_artifact_smoke.sh
 
 # Rails compatibility (optional local)
 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rspec
 BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle install
 BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rspec
-```
+```

data/RELEASE.md

@@ -1,43 +1,205 @@
-# Release: auditea 0.1.0.beta.1
+# Release: auditea 0.1.0.beta.3
 
-## Preconditions (blockers)
+Authoritative runbook for controlled beta publication of the Ruby SDK.
 
-1. Independent human review of the PR
-2. Merge to `main`
-3. Exact-head CI green on merge commit
-4. License approved: **MIT**
-5. RubyGems MFA / owner account for `reznis` with push rights
-6. OTP / API key for `gem push` stored outside the repository (never commit secrets)
+**Do not publish until every gate below is green and a human explicitly says GO.**
 
-## Build
+This document does **not** authorize:
+
+- `gem push`
+- GitHub Release / publication tags
+- Nagano or any real TEST installation
+- production rollout
+
+---
+
+## Publication requires all of
+
+1. SDK **exact candidate SHA** reviewed (not a GitHub merge ref labeled as exact-head)
+2. Built `.gem` artifact audited (filename, SHA-256, size, file count, candidate source SHA, `Auditea::VERSION`)
+3. **Artifact-generated** payload gate PASS (payloads from the installed candidate gem, not checkout `lib/`)
+4. SDK matrix PASS (Ruby 3.2/3.3 + Rails 7.2; Ruby 3.4/4.0.6 + Rails 8.1)
+5. **Current AudiTea server strict interop PASS** — recorded live server SHA (Gate B)
+6. **AUD-BETA01** reviewed and merged
+7. Beta server operational (deployed separately under human approval; health verified)
+8. Explicit human **GO**
+9. RubyGems MFA / credentials available **outside** the repository
+
+If AudiTea `main` advances after strict interop and before publication in a way that touches ingestion / runtime inventory / host inventory / observed-release boundaries, **rerun Gate B** against the then-current main and record the new SHA.
+
+---
+
+## Two interoperability gates (do not conflate)
+
+### Gate A — pinned AudiTea envelope compatibility
+
+Lightweight SDK CI check against the **vendored** `Ingestion::ContractV1` snapshot.
+
+- Pin SHA: `script/support/INGESTION_CONTRACT_PIN.txt`
+- Labels accurately: **pinned envelope compatibility**
+- Does **not** prove runtime/host/release projector success
+- May become stale relative to current AudiTea
+- Must **not** be described as complete current-server interoperability
+
+```bash
+AUDITEA_INTEROP_MODE=envelope bash script/release_candidate_gate.sh
+```
+
+### Gate B — live current-server strict interoperability (mandatory release gate)
+
+Runs against an **actual local checkout** of current AudiTea. No silent fallback to the vendored pin.
+
+Gate B is **fail-closed test-only**:
+
+- forces `RAILS_ENV=test`
+- unsets inherited `DATABASE_URL` (so an operator export cannot redirect to development/production)
+- refuses to continue unless `Rails.env.test?` and the resolved DB name ends in `_test`
+- prepares the AudiTea test DB via `rails db:prepare`
+- wraps all fixture/ingest/projection work in an outer transaction that is always rolled back
+- clears ActiveJob test-adapter enqueues so no durable queue/projection work remains
+
+```bash
+export AUDITEA_SERVER_ROOT=/actual/path/to/AudiTea
+export AUDITEA_INTEROP_MODE=strict
+EXPECTED_CANDIDATE_SHA="$(git rev-parse HEAD)" bash script/release_candidate_gate.sh
+```
+
+Required behavior when live/current mode is requested:
+
+- missing checkout → **FAIL**
+- wrong/incomplete checkout → **FAIL**
+- missing expected server components → **FAIL**
+- non-test Rails env / unsafe DB → **FAIL**
+
+Exercises real domain paths (from the installed candidate `.gem` payloads):
+
+| Payload | Server path |
+|---|---|
+| ordinary event | `EventIngestor` → accepted/persisted |
+| exception | ingest → `Errors::Classifier` / `IssueReconciler` |
+| `runtime.inventory` | ingest → `Runtime::InventoryProjector` |
+| `host.inventory` | ingest → `Hosts::InventoryProjector` |
+| `provenance.release` | ingest → `Releases::ObservedReleaseProjector` |
+
+Private-repo CI cannot clone AudiTea automatically. For beta.2 it is acceptable that Gate A is automated in SDK CI while Gate B is an explicit local/human release gate — **but Gate B must PASS before publication**, and its AudiTea SHA must be recorded.
+
+**After AUD-BETA01 merges**, repeat Gate B against the then-current AudiTea `main` immediately before publication.
+
+---
+
+## Code gates (SDK)
+
+1. Exact SDK head reviewed on the release-readiness PR (`github.event.pull_request.head.sha` for PR jobs)
+2. Full CI matrix green on that exact head
+3. Local quality: `bundle exec rspec`, `bundle exec rubocop`, `bundle exec bundle-audit check --update`
+4. Unified release-candidate artifact gate:
+
+```bash
+EXPECTED_CANDIDATE_SHA="$(git rev-parse HEAD)" \
+  AUDITEA_INTEROP_MODE=envelope \
+  bash script/release_candidate_gate.sh
+```
+
+Conceptually:
+
+```text
+build .gem from candidate SHA
+→ install into isolated GEM_HOME
+→ prove loaded files come from installed gem
+→ generate interoperability payloads from that installed gem
+→ Gate A pinned envelope compatibility
+→ Gate B live strict (when AUDITEA_INTEROP_MODE=strict)
+```
+
+5. License remains **MIT**; `rubygems_mfa_required` + `allowed_push_host=https://rubygems.org` intact
+6. Fail-open defaults verified; runtime/host inventory and request capture default **OFF**
+
+Terminology:
+
+```text
+exact-head  !=  merge-ref
+```
+
+Do not call one the other. Merge-ref testing may be useful separately; it is not exact-head evidence.
+
+---
+
+## Server gate (AudiTea)
+
+Publication and first TEST install remain blocked until:
+
+1. **AUD-BETA01** independently reviewed and merged
+2. Beta server deployed separately under human approval
+3. Health verified (`/up`, auth, jobs, migrations, backups as applicable)
+4. Gate B live strict interop recorded against current AudiTea (see above)
+
+BETA02 must not depend on unmerged BETA01 implementation details for SDK correctness, but **actual gem publication and first TEST installation require the operational server**.
+
+---
+
+## Publication gate (human)
+
+1. Explicit human **GO** after SDK + server gates
+2. RubyGems owner/authentication for `reznis` verified
+3. MFA / OTP / API key available **outside the repository** (never commit)
+4. No automatic publish-on-tag workflow for this beta
+
+PR status may say `READY FOR HUMAN PUBLICATION REVIEW` while still listing external operator gates (BETA01, server deploy). It must **not** claim `current server strict interop PASS` unless Gate B actually ran against the recorded real checkout.
+
+---
+
+## Publication (only after explicit human approval)
 
 ```bash
 git checkout main
 git pull
-bundle install
-bundle exec rspec
+# confirm VERSION and CHANGELOG still say 0.1.0.beta.3
 gem build auditea.gemspec
-# => auditea-0.1.0.beta.1.gem
+# inspect package once more
+gem push auditea-0.1.0.beta.3.gem
 ```
 
-## Publish
+Then mark CHANGELOG released with the publication date in a follow-up commit.
 
-Publish only from reviewed `main` after its exact-head CI is green:
+---
+
+## Post-publication verification
 
 ```bash
-gem push auditea-0.1.0.beta.1.gem
+gem install auditea -v 0.1.0.beta.3 --pre
+ruby -rauditea -e 'puts Auditea::VERSION'
+# expect: 0.1.0.beta.3
 ```
 
-Optional GitHub Actions: use `rubygems/configure-rubygems-credentials` with a repository secret `RUBYGEMS_API_KEY` — never commit the secret.
+Prefer installing the RubyGems artifact (not a git branch) into the controlled TEST app.
+
+---
 
-## Verify
+## Pilot gate
+
+- Start with **1** controlled Rails TEST client (optionally a second later)
+- Do **not** broaden to production or multi-app fleets in this beta
+- Use the first-pilot configuration in `README.md`
+- Keep a documented rollback/disable path ready (`AUDITEA_ENABLED=false` preferred)
+
+---
+
+## Build checklist (local, pre-approval)
 
 ```bash
-gem install auditea -v 0.1.0.beta.1 --pre
-```
+bundle install
+bundle exec rspec
+bundle exec rubocop
+bundle exec bundle-audit check --update
+
+EXPECTED_CANDIDATE_SHA="$(git rev-parse HEAD)" \
+  AUDITEA_INTEROP_MODE=envelope \
+  bash script/release_candidate_gate.sh
 
-Then install in Semiweb TEST via:
+EXPECTED_CANDIDATE_SHA="$(git rev-parse HEAD)" \
+  AUDITEA_INTEROP_MODE=strict \
+  AUDITEA_SERVER_ROOT=/actual/path/to/AudiTea \
+  bash script/release_candidate_gate.sh
 
-```ruby
-gem "auditea", "0.1.0.beta.1"
+bash script/volume_baseline.sh
 ```

data/auditea.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Ruby/Rails SDK for AudiTea event collection"
   spec.description =
-    "Capture business events, Rails request evidence, exceptions, and structured logs " \
-    "for AudiTea /api/v1."
+    "Capture business events, Rails request evidence, exceptions, structured logs, " \
+    "and optional runtime/host inventory for AudiTea /api/v1."
   spec.homepage = "https://github.com/reznis/auditea-ruby"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.2.0"

data/lib/auditea/configuration.rb

@@ -12,13 +12,16 @@ module Auditea
     DEFAULT_MAX_RETRIES = 3
     DEFAULT_MESSAGE_MAX = 8_192
     DEFAULT_NESTING_MAX = 16
+    DEFAULT_INVENTORY_REFRESH = 86_400
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
 
     attr_accessor :endpoint, :source_token, :enabled, :async, :raise_errors,
                   :batch_size, :flush_interval, :queue_capacity, :timeout,
                   :open_timeout, :write_timeout, :max_retries, :logger, :release, :sdk_name,
                   :capture_requests, :capture_exceptions, :capture_request_params,
-                  :capture_active_job, :message_max_bytes, :nesting_max_depth
+                  :capture_active_job, :capture_runtime_inventory, :capture_host_inventory,
+                  :inventory_refresh_interval, :host_key, :host_label,
+                  :message_max_bytes, :nesting_max_depth
 
     def initialize
       @endpoint = ENV.fetch("AUDITEA_ENDPOINT", DEFAULT_ENDPOINT)
@@ -40,10 +43,28 @@ module Auditea
       @capture_exceptions = truthy?(ENV.fetch("AUDITEA_CAPTURE_EXCEPTIONS", "true"))
       @capture_request_params = truthy?(ENV.fetch("AUDITEA_CAPTURE_REQUEST_PARAMS", "false"))
       @capture_active_job = truthy?(ENV.fetch("AUDITEA_CAPTURE_ACTIVE_JOB", "true"))
+      # Opt-in: dependency inventories reveal internal gem names.
+      @capture_runtime_inventory = truthy?(ENV.fetch("AUDITEA_CAPTURE_RUNTIME_INVENTORY", "false"))
+      # Opt-in: host/platform inventory (opaque node id + OS facts).
+      @capture_host_inventory = truthy?(ENV.fetch("AUDITEA_CAPTURE_HOST_INVENTORY", "false"))
+      @host_key = ENV.fetch("AUDITEA_HOST_KEY", nil)
+      @host_label = ENV.fetch("AUDITEA_HOST_LABEL", nil)
+      @inventory_refresh_interval = float_env(
+        "AUDITEA_INVENTORY_REFRESH_INTERVAL",
+        DEFAULT_INVENTORY_REFRESH
+      )
       @message_max_bytes = integer_env("AUDITEA_MESSAGE_MAX_BYTES", DEFAULT_MESSAGE_MAX)
       @nesting_max_depth = integer_env("AUDITEA_NESTING_MAX_DEPTH", DEFAULT_NESTING_MAX)
     end
 
+    def capture_runtime_inventory?
+      !!@capture_runtime_inventory
+    end
+
+    def capture_host_inventory?
+      !!@capture_host_inventory
+    end
+
     def enabled?
       !!@enabled
     end