foam-otel 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ef766d3509a7ee5daa25c7f53dce352b9c67c8ed22283099c72f3d6f0b8e957
-  data.tar.gz: caca5adca96f4e3dab3d0610ce54000858cb231cbf167e5bb6dd0c6f1dcd6a9b
+  metadata.gz: d27bb6b38712364503503fecd37ea383f9a7e3fb3648da8ef41524c575ef9302
+  data.tar.gz: 0c9fee962999043120904c8ffe85621e32ae04fcb300280ec8af0b2c77291a0d
 SHA512:
-  metadata.gz: 55da8fd55a07d287d81fddf5a65eeb8b7e0f743d1ec8b034362972f5c02a15a84bab18119aacf9e881b4deefc61d6958e062990fe3b205f66f2a88fd11ba514b
-  data.tar.gz: 70e46934c6250308cb8d15c90a160eeab5ce916b294cfc7395e46fc07e0d8d2027ded17f3f21cdcf3125c35773fb899324eb0374c6326c04d73a2908e0e1024d
+  metadata.gz: 8bdcb84ca5d9becc44e9a181512ac19c9c8c24f5035e7da9da09a1ab59a4c09cd96b9cde80a8b5d073001ae6f36d9f4e1b3e1a3e640c4eafa6d30ac34800e47c
+  data.tar.gz: b09d59343870e8d16ef9e4c0794e7ec78486d5ab9c3eea339d99c4f8b4fa46f58ca5246ca3df70ed8a82c795fd4108c296c3bb19e720640c5acce080f0e90a98

data/GOTCHAS.md

@@ -866,6 +866,132 @@ exfiltratable — the value-pattern secret layer is the required second control
   "REAL OTLP encode", "aggregates hook faults", "arity", "in-place value
   mutation never bleeds"); `spec/before_send_champ_scenario_spec.rb` (the
   export-thread / stamped-context proof).
+## F17: There is no unwrapped Net::HTTP instance — foam's export must own its transport (export isolation, 2026-07-29)
+
+- **Trap**: Ruby APM agents instrument by PREPENDING modules onto `Net::HTTP`
+  itself, so every instance in the process — including the one inside the
+  upstream OTLP exporter — dispatches through the foreign prepend chain, and
+  private helper names from different vendors resolve against each other on
+  the shared ancestry (the wrong-arity `annotate_span_with_response!`
+  collision class: every export crashes, zero rows land, the app looks
+  healthy). The upstream exporter's `untraced` suppression does NOT protect
+  the send — foreign agents never check OTel's flag; the exporter died with
+  it active. Reproduced at production parity against a real proprietary
+  auto-instrumenting agent (docs/decisions/export-isolation-ruby.md, with
+  before/after crash and rows-landed counts).
+- **Sources**:
+  - Installed source — the vulnerable transport: `Net::HTTP.new` inside
+    `http_connection` and the `Net::HTTPResponse`-matching send loop
+    (opentelemetry-exporter-otlp `exporter.rb:129,150-258`; same shape in
+    -otlp-logs `logs_exporter.rb` and -otlp-metrics `metrics_exporter.rb` —
+    with drifting private `backoff?` signatures across the three gems).
+  - Design reference (strongest industry mechanism, isolation by
+    construction): the Go OTLP exporter's owned internal transport and its
+    documented warning against injecting an instrumented transport; the
+    error-tracking vendors' native-fetch browser transports.
+  - The prior collision incident class: the upstream contrib `net_http`
+    patch's private helper namespace
+    (opentelemetry-instrumentation-net_http `patches/stable/instrumentation.rb:81`).
+- **Decision & why**: Isolation by construction, layered over suppression —
+  never suppression alone. `Foam::Otel::IsolatedHttpClient` is a hand-written
+  HTTP/1.1 sender over foam-owned `TCPSocket`/`OpenSSL::SSL::SSLSocket`
+  (VERIFY_PEER + hostname verification, CA/mTLS options, HTTP(S)_PROXY /
+  NO_PROXY with CONNECT tunneling, deadline IO, keep-alive with one
+  stale-socket retransmit, chunked/`Connection: close` reading, pid-keyed
+  reconnect for fork safety). `IsolatedExporters::{Trace,Logs,Metrics}Exporter`
+  subclass the upstream exporters, replacing exactly `http_connection` and
+  `send_bytes` (foam-owned retry loop, upstream semantics verbatim: 429/503
+  honor Retry-After, 408/502/504 + transient socket errors back off with
+  jitter, other 4xx drop; `untraced` kept as layer two). All six construction
+  sites (door 1 + door 2 × three signals) — the package's entire outbound
+  surface — build these subclasses. Capture is untouched; and foam's own
+  prepends (LLM shims, Logger bridge, fork hook) define ONLY the intercepted
+  public method, so foam can never be the colliding party on anyone's class.
+- **Mitigation**: a foreign prepend chain on `Net::HTTP` structurally cannot
+  sit in foam's delivery path; a hostile wrong-arity prepend that crashes
+  every ordinary `Net::HTTP` caller leaves foam's rows landing.
+- **Test**: `spec/export_isolation_spec.rb` (hostile prepend in a forked
+  child + spy-prepend never-dispatches proof, 503/429 Retry-After retries,
+  CONNECT-tunnel and absolute-form proxy paths, NO_PROXY, TLS wrong-hostname
+  rejection, chunked/keep-alive/stale-socket/deadline/fork-safety units, the
+  untraced layer-two pin, and the zero-collidable-private-helpers invariant);
+  `spec/export_isolation_hardening_spec.rb` (protocol edges: 1xx skip,
+  duplicate/trailered/extension-chunked responses, EOF-framed bodies,
+  keep-alive expiry, malformed status lines, IPv6 Host framing, 8-thread
+  concurrency; retry accounting with the backoff clock stubbed: exact
+  retry-cap exhaustion, Retry-After delta AND HTTP-date, 408/502/504,
+  redirects never followed, zero/mid-loop budget exhaustion; compression
+  none + its env var; loud non-protobuf 5xx handling; shutdown lifecycle;
+  mTLS e2e via the spec CERTIFICATE/CLIENT_CERTIFICATE/CLIENT_KEY env vars
+  incl. the rejected no-client-cert half; proxy credentials on CONNECT,
+  refused CONNECT, lowercase env twins, the NO_PROXY shape matrix; all
+  three signals through a full init, door-2 tap e2e, and a REAL fork);
+  `spec/ingest_spec.rb` (case 4 half 3: zero feedback spans with BOTH
+  cooperative layers defeated); `spec/transport_spec.rb` (the exact isolated
+  classes on all six sites); and the REAL-agent coexistence gate
+  `test-apps/ruby-coexistence/run-verify.sh` (two postures booting the
+  actual commercial agents in auto-instrument mode, hard-gated on the
+  vendor module being observed live ahead of Net::HTTP in the running
+  process's ancestor chain, verdict = protobuf-decoded rows on all three
+  signals with zero export errors).
+
+---
+
+## F18: One private-method namespace per class — cross-vendor helper collisions crash the APP, and foam shields them (coexistence mandate 2026-07-29)
+
+- **Trap**: Every module prepended onto a class shares ONE private-method
+  namespace. When two observability vendors prepend same-named private
+  helpers at different signatures onto Net::HTTP, method lookup hands EVERY
+  caller the frontmost definition — one vendor's wrapper invokes the other
+  vendor's helper and raises ArgumentError on EVERY Net::HTTP request the
+  app makes. This is live in the wild today: a proprietary agent's wrapper
+  and the upstream OTel contrib net_http patch both define
+  `annotate_span_with_response!` (3-arg vs 2-arg). Foam ships that contrib
+  patch for capture, so a foam + agent process CONTAINS the collision — and
+  foam's promise is coexistence: the app must keep working.
+- **Sources**:
+  - Installed source — the two colliding definitions:
+    opentelemetry-instrumentation-net_http 0.29.0
+    `patches/stable/instrumentation.rb:81` (`annotate_span_with_response!(span, response)`)
+    and the proprietary agent's contrib HTTP instrumentation calling its own
+    3-arg spelling of the same private name (verified live in the
+    coexistence gate; backtrace pinned in
+    docs/decisions/export-isolation-ruby.md §A).
+  - Ruby semantics: prepended modules join the class's ancestor chain and
+    private methods resolve through the SAME chain for every caller — there
+    is no per-module helper namespace.
+- **Decision & why**: foam cannot rename the upstream helper (its own caller
+  resolves the name through the same shared chain — a rename breaks the
+  gem being "fixed"), and foam must never edit another vendor's module. So
+  foam owns the collision instead: after the instrumentation sweep, init
+  scans Net::HTTP's prepend chain for private-helper names defined by two
+  or more foreign modules at NON-identical positional signatures (names the
+  class itself defines are super-chains, never shielded) and prepends ONE
+  frontmost dispatch method per colliding name — routing by caller source
+  gem first, then by signature fit, falling back to the previously-frontmost
+  definition (status quo ante; the shield never makes a broken chain
+  worse). Its dispatch methods accept (*args, **kwargs, &block), so nothing
+  can arity-crash against the shield itself. No collision → NOTHING is
+  installed. Every shielded name is announced loudly (rule 15). This is the
+  ONE deliberate exception to foam's own-prepend hygiene rule (F17's
+  "foam's prepends carry zero private helpers"): the shield's whole job is
+  to own the already-colliding names.
+- **Mitigation**: with the shield installed the coexistence gate's
+  patched-client probe went from 3/3 crashes to 3/3 passes under the real
+  agent, with both vendors' helpers verifiably executing again.
+- **Residual**: an agent that patches AFTER foam's init lands ahead of the
+  shield and re-exposes the raw collision until a later init/fork re-scan;
+  agents overwhelmingly boot first (initializer/preload) — the order the
+  coexistence gate proves. Identical-signature collisions are left alone
+  (no crash class; dispatch could not disambiguate semantics).
+- **Test**: `spec/prepend_collision_shield_spec.rb` (the unshielded RED
+  control, both-vendors-work dispatch, idempotence, no-op purity on
+  collision-free chains, super-chain and identical-signature exclusions,
+  fall-through to the real error, rule-9 scan degradation, caller-source
+  dispatch across two on-disk gem roots, and the real Net::HTTP + real
+  contrib patch field scenario red→green in a forked child);
+  `test-apps/ruby-coexistence/run-verify.sh` (the patched-client probe is a
+  REQUIRED pass on every vendor posture).
 
 ---
 

data/lib/foam/otel/ingest.rb

@@ -285,23 +285,25 @@ module Foam
         # CWE-295 — see pipelines.rb setup_traces): door 2 carries the same
         # fleet ingest token over the same TLS connection, so the silent
         # OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE downgrade is pinned out
-        # here identically.
+        # here identically. All three are IsolatedExporters subclasses —
+        # door 2's delivery must be exactly as immune to foreign Net::HTTP
+        # prepends as door 1's (export-isolation design, 2026-07-29).
         def build_otlp_span_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Exporter.new(
+          IsolatedExporters::TraceExporter.new(
             endpoint: "#{endpoint}/v1/traces", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )
         end
 
         def build_otlp_log_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+          IsolatedExporters::LogsExporter.new(
             endpoint: "#{endpoint}/v1/logs", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )
         end
 
         def build_otlp_metric_exporter(endpoint, headers)
-          OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+          IsolatedExporters::MetricsExporter.new(
             endpoint: "#{endpoint}/v1/metrics", headers: headers,
             ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
           )

data/lib/foam/otel/init.rb

@@ -528,6 +528,10 @@ module Foam
         require "opentelemetry-exporter-otlp"
         require "opentelemetry-exporter-otlp-logs"
         require "opentelemetry-exporter-otlp-metrics"
+        # The isolated transport subclasses (export-isolation design) load
+        # HERE — after the upstream exporter gems they subclass — so the lazy
+        # rule-41 posture holds: a disabled boot never pays their cost.
+        require_relative "isolated_exporters"
       end
 
       # The central RAW-capture activation config (raised-floor ruling
@@ -610,6 +614,12 @@ module Foam
           FLOOR_INSTRUMENTATION_CONFIG.merge(SUPERSEDED_INSTRUMENTATION_CONFIG)
         )
         Diagnostics.info("instrumentations installed: #{gems.length} bundled gem(s)")
+        # Coexistence shield (2026-07-29, GOTCHAS F18): with the sweep done,
+        # every prepend that will sit on Net::HTTP in the realistic boot
+        # order (agent first, foam second) is in place — scan for cross-
+        # vendor private-helper collisions and shim them. A collision-free
+        # chain (the common case) installs NOTHING.
+        PrependCollisionShield.install!(::Net::HTTP) if defined?(::Net::HTTP)
       rescue StandardError => e
         Diagnostics.warn("instrumentation activation failed: #{e.class}: #{e.message}")
       end

data/lib/foam/otel/isolated_exporters.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# The isolated OTLP exporters (export-isolation design, 2026-07-29). The
+# upstream opentelemetry-exporter-otlp{,-logs,-metrics} gems each build a
+# Net::HTTP inside #http_connection and drive it from #send_bytes — which puts
+# every foreign APM's Net::HTTP prepend chain (Datadog, New Relic, Sentry…)
+# INSIDE foam's delivery path. These subclasses keep everything else the
+# upstream classes do — endpoint/headers/compression/timeout resolution
+# including the spec OTEL_EXPORTER_OTLP_* env vars, protobuf encoding, the
+# ssl/mTLS options — and replace exactly two private methods:
+#
+#   * #http_connection → returns Foam::Otel::IsolatedHttpClient (an owned,
+#     hand-written HTTP/1.1 sender; see isolated_http_client.rb);
+#   * #send_bytes → a foam-owned send loop that reimplements the upstream
+#     retry semantics VERBATIM (backoff with jitter on 429/503 honoring
+#     Retry-After, backoff on 408/502/504 and transient socket/SSL errors,
+#     drop on other 4xx/5xx) against the isolated client. Reimplemented, not
+#     inherited, because the upstream loop pattern-matches Net::HTTPResponse
+#     classes and rescues Net::* exceptions — and because its private helper
+#     signatures drift across the three gems (logs' backoff? has no reason:).
+#
+# Suppression stays as LAYER TWO: the send runs inside
+# Common::Utilities.untraced, so cooperative instrumentation (foam's own
+# included) never traces foam's export even if a future capture hook could
+# see it. Layer one — the reason the Datadog crash cannot recur — is that the
+# bytes never enter Net::HTTP at all.
+require "zlib"
+
+require_relative "diagnostics"
+require_relative "isolated_http_client"
+
+module Foam
+  module Otel
+    module IsolatedExporters
+      # Export result codes; == OpenTelemetry::SDK::*::Export::SUCCESS/FAILURE
+      # in every signal's SDK (integers, so this module never reaches into the
+      # per-signal constant trees).
+      SUCCESS = 0
+      FAILURE = 1
+      RETRY_COUNT = 5 # upstream's cap, kept verbatim
+
+      # The shared send path, included by the three per-signal subclasses
+      # below. Relies only on ivars every upstream constructor sets (@http,
+      # @path, @headers, @timeout, @compression, @uri) plus the optional
+      # @metrics_reporter (absent in the logs exporter — every use is nil-safe).
+      module SendPath
+        private
+
+        def http_connection(uri, ssl_verify_mode, certificate_file, client_certificate_file, client_key_file)
+          IsolatedHttpClient.new(
+            uri,
+            ssl_verify_mode: ssl_verify_mode,
+            certificate_file: certificate_file,
+            client_certificate_file: client_certificate_file,
+            client_key_file: client_key_file
+          )
+        end
+
+        def send_bytes(bytes, timeout:) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          return FAILURE if bytes.nil?
+
+          report_value("otel.otlp_exporter.message.uncompressed_size", bytes.bytesize)
+          if @compression == "gzip"
+            body = Zlib.gzip(bytes)
+            report_value("otel.otlp_exporter.message.compressed_size", body.bytesize)
+          else
+            body = bytes
+          end
+          request_headers = @headers.merge("Content-Type" => "application/x-protobuf")
+          request_headers["Content-Encoding"] = "gzip" if @compression == "gzip"
+
+          retry_count = 0
+          timeout ||= @timeout
+          start_time = OpenTelemetry::Common::Utilities.timeout_timestamp
+
+          # Layer two: the cooperative suppression flag, kept even though the
+          # isolated client makes it structurally unnecessary for delivery —
+          # it also stops foam ever tracing its own export.
+          OpenTelemetry::Common::Utilities.untraced do
+            loop do
+              remaining_timeout = OpenTelemetry::Common::Utilities.maybe_timeout(timeout, start_time)
+              return FAILURE if remaining_timeout.zero?
+
+              response = @http.post(@path, body: body, headers: request_headers, timeout: remaining_timeout)
+
+              case response.code
+              when 200..299
+                return SUCCESS
+              when 429, 503
+                next if foam_backoff?(retry_after: response["retry-after"],
+                                      retry_count: retry_count += 1, reason: response.code.to_s)
+
+                # Retry exhaustion is announced (fleet-review parity fix:
+                # upstream's per-retry handle_http_error kept failures
+                # visible; foam announces once, at the point data drops).
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 408, 502, 504
+                next if foam_backoff?(retry_count: retry_count += 1, reason: response.code.to_s)
+
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 404
+                foam_log_request_failure(response.code)
+                return FAILURE
+              when 300..399
+                # Upstream parity: redirects are not followed (its
+                # handle_redirect is a TODO); drop the connection and back off.
+                @http.finish
+                next if foam_backoff?(retry_after: 0, retry_count: retry_count += 1,
+                                      reason: response.code.to_s)
+
+                return FAILURE
+              when 400..599
+                foam_log_status(response.body)
+                add_to_failure_counter(response.code.to_s)
+                return FAILURE
+              else
+                @http.finish
+                foam_log_request_failure(response.code)
+                return FAILURE
+              end
+            rescue IsolatedHttpClient::TimeoutError
+              # Deliberate divergence from upstream (documented): upstream
+              # lets Net::WriteTimeout fall to the fatal catch-all while
+              # retrying read timeouts; a stalled WRITE is just as transient
+              # (proxy hiccup, slow-start collector), so foam retries both
+              # within the same budget/backoff caps.
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "timeout")
+
+              return FAILURE
+            rescue OpenSSL::SSL::SSLError => e
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "openssl_error")
+
+              OpenTelemetry.handle_error(exception: e, message: "SSL error in isolated OTLP send_bytes")
+              return FAILURE
+            rescue SocketError, IsolatedHttpClient::ProxyConnectError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "socket_error")
+
+              return FAILURE
+            rescue SystemCallError => e
+              next if foam_backoff?(retry_count: retry_count += 1, reason: e.class.name)
+
+              return FAILURE
+            rescue EOFError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "eof_error")
+
+              return FAILURE
+            rescue Zlib::DataError
+              next if foam_backoff?(retry_count: retry_count += 1, reason: "zlib_error")
+
+              return FAILURE
+            rescue StandardError => e
+              OpenTelemetry.handle_error(exception: e, message: "unexpected error in isolated OTLP send_bytes")
+              add_to_failure_counter(e.class.to_s)
+              return FAILURE
+            end
+          end
+        end
+
+        # Upstream backoff semantics verbatim (red-flag 2): count the failure,
+        # give up past RETRY_COUNT, honor Retry-After as delta-seconds or
+        # HTTP-date, else exponential jitter — foam-prefixed (rule: foam is
+        # never the colliding party on anyone's class, its own included).
+        def foam_backoff?(retry_count:, reason:, retry_after: nil)
+          add_to_failure_counter(reason)
+          return false if retry_count > RETRY_COUNT
+
+          sleep_interval = nil
+          unless retry_after.nil?
+            sleep_interval = Integer(retry_after, exception: false)
+            sleep_interval ||=
+              begin
+                Time.httpdate(retry_after) - Time.now
+              rescue StandardError
+                nil
+              end
+            sleep_interval = nil unless sleep_interval&.positive?
+          end
+          sleep_interval ||= rand(2**retry_count)
+
+          sleep(sleep_interval)
+          true
+        end
+
+        def foam_log_status(body)
+          status = Google::Rpc::Status.decode(body.to_s)
+          details = status.details.filter_map do |detail|
+            klass = ::Google::Protobuf::DescriptorPool.generated_pool.lookup(detail.type_name).msgclass
+            detail.unpack(klass) if klass
+          end
+          OpenTelemetry.handle_error(
+            message: "OTLP exporter received rpc.Status{message=#{status.message}, details=#{details}} for uri=#{@uri}"
+          )
+        rescue StandardError
+          # A body that isn't a valid rpc.Status (HTML error page from a
+          # proxy, empty 500…) still gets a readable failure line.
+          OpenTelemetry.handle_error(message: "OTLP exporter received an error response for uri=#{@uri}")
+        end
+
+        def foam_log_request_failure(response_code)
+          OpenTelemetry.handle_error(
+            message: "OTLP exporter received http.code=#{response_code} for uri='#{@uri}' in isolated send_bytes"
+          )
+          add_to_failure_counter(response_code.to_s)
+        end
+
+        def add_to_failure_counter(reason)
+          @metrics_reporter&.add_to_counter("otel.otlp_exporter.failure", labels: { "reason" => reason })
+        rescue StandardError
+          nil
+        end
+
+        def report_value(metric, value)
+          @metrics_reporter&.record_value(metric, value: value)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # The three per-signal exporters. Constructors, protobuf encoding,
+      # spec env-var handling, force_flush/shutdown all inherit from upstream;
+      # only the transport-touching privates are replaced by SendPath (module
+      # ancestry: subclass → SendPath → upstream class, so the upstream
+      # constructor's http_connection call dispatches into SendPath's).
+      class TraceExporter < ::OpenTelemetry::Exporter::OTLP::Exporter
+        include SendPath
+      end
+
+      class LogsExporter < ::OpenTelemetry::Exporter::OTLP::Logs::LogsExporter
+        include SendPath
+      end
+
+      class MetricsExporter < ::OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter
+        include SendPath
+      end
+    end
+  end
+end

data/lib/foam/otel/isolated_http_client.rb

@@ -0,0 +1,586 @@
+# frozen_string_literal: true
+
+# The isolation-by-construction transport (export-isolation design, 2026-07-29;
+# GOTCHAS F17). foam's delivery path — every byte foam sends on its own behalf —
+# must never travel a client a third party can modify at runtime. Ruby's whole
+# APM ecosystem prepends modules onto Net::HTTP ITSELF: every instance in the
+# process dispatches through the prepend chain, so there is no such thing as an
+# unwrapped Net::HTTP instance, and private helpers from different vendors
+# collide on the class (the Datadog × OTel `annotate_span_with_response!` arity
+# crash: 464 export crashes, zero rows landed, healthy-looking app). The
+# suppression flag (Common::Utilities.untraced) does NOT protect the send —
+# foreign vendors never check it; the upstream Ruby OTLP exporter died WITH
+# untraced active, because the send itself travels the patched class.
+#
+# This client is the fix, modeled on the strongest industry mechanism (the Go
+# OTLP exporter's owned transport; Sentry's native-fetch browser transport):
+# a hand-written HTTP/1.1 sender over a TCPSocket / OpenSSL::SSL::SSLSocket
+# that foam constructs and owns. Nothing here calls Net::HTTP, and nothing
+# outside foam's exporters holds a reference — a foreign prepend chain on
+# Net::HTTP structurally cannot sit in this path.
+#
+# Feature parity with the layer it replaces (non-negotiable — red-flags 1/4/5):
+#   * proxies: HTTP_PROXY / HTTPS_PROXY / NO_PROXY (+ lowercase), with CONNECT
+#     tunneling (and Proxy-Authorization) for https through a proxy — the
+#     enterprise egress pattern Net::HTTP handled implicitly;
+#   * TLS: VERIFY_PEER with HOSTNAME verification (context verify_hostname +
+#     post_connection_check), custom CA bundle, and client cert/key for mTLS —
+#     the OTEL_EXPORTER_OTLP_{CERTIFICATE,CLIENT_CERTIFICATE,CLIENT_KEY}
+#     options arrive here through the exporter constructors unchanged;
+#   * timeouts: connect/read/write deadlines via nonblocking IO + IO.select
+#     (one per-request deadline, matching the exporters' remaining-timeout
+#     accounting);
+#   * keep-alive with a single silent reconnect+retransmit on a stale pooled
+#     socket (EPIPE/ECONNRESET/EOF before any response byte), plus chunked and
+#     Connection: close response reading;
+#   * fork safety: the cached connection is keyed by Process.pid — a forked
+#     worker's first export discards the inherited socket and reconnects
+#     (rule 37; makes after_fork! free for the transport).
+#
+# What it deliberately does NOT do: capture. foam keeps instrumenting the
+# app's Net::HTTP exactly as before — isolation applies to DELIVERY only.
+require "openssl"
+require "socket"
+require "uri"
+
+module Foam
+  module Otel
+    class IsolatedHttpClient
+      # Timeout/tunnel errors, foam-owned so the exporters' retry loop never
+      # rescues (or raises) a Net::* class.
+      class TimeoutError < StandardError; end
+      class OpenTimeoutError < TimeoutError; end
+      class ReadTimeoutError < TimeoutError; end
+      class WriteTimeoutError < TimeoutError; end
+      class ProxyConnectError < StandardError; end
+
+      # A plain value response — code (Integer), lowercased header Hash,
+      # body (String). Not a Net::HTTPResponse: response handling must not
+      # touch patchable Net::* classes either.
+      class Response
+        attr_reader :code, :headers, :body
+
+        def initialize(code, headers, body)
+          @code = code
+          @headers = headers
+          @body = body
+        end
+
+        def [](name) = @headers[name.to_s.downcase]
+      end
+
+      KEEP_ALIVE_TIMEOUT = 30 # seconds a pooled socket may idle, like Net::HTTP's
+      READ_CHUNK = 16 * 1024
+      # Response-size ceiling (fleet-review fix): OTLP success/error bodies
+      # are tiny (empty, or a small rpc.Status); a hostile or broken endpoint
+      # must not drive unbounded allocation in the app's process.
+      MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+      private_constant :READ_CHUNK
+
+      def initialize(uri, ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER, certificate_file: nil,
+                     client_certificate_file: nil, client_key_file: nil,
+                     keep_alive_timeout: KEEP_ALIVE_TIMEOUT)
+        @uri = uri
+        @host = uri.hostname
+        @port = uri.port
+        @use_ssl = uri.scheme == "https"
+        @ssl_verify_mode = ssl_verify_mode
+        @ssl_context = build_ssl_context(ssl_verify_mode, certificate_file,
+                                         client_certificate_file, client_key_file) if @use_ssl
+        @keep_alive_timeout = keep_alive_timeout
+        # Proxy config resolves ONCE at construction (Net::HTTP.new's :ENV
+        # behavior) — the exporter lives for the process, like its env config.
+        @proxy = resolve_proxy_from_env
+        @mutex = Mutex.new
+        @socket = nil
+        @pid = nil
+        @last_used = nil
+        @rbuf = +""
+      end
+
+      # Net::HTTP-facade introspection: the TLS pin audits (F-RB1 specs) read
+      # the constructed connection's verify mode; kept as real surface so the
+      # pin stays checkable on the isolated client.
+      attr_reader :ssl_verify_mode
+      alias verify_mode ssl_verify_mode
+
+      # Net::HTTP-facade lifecycle bits the exporters' shutdown path calls.
+      def started? = !@socket.nil?
+
+      def finish
+        @mutex.synchronize { close_socket }
+        nil
+      end
+
+      # POST `body` to `path` with `headers`, all within `timeout` seconds
+      # (connect + write + full response read share one deadline). Returns a
+      # Response; raises the foam-owned timeout/socket errors above plus
+      # OpenSSL::SSL::SSLError / SocketError / SystemCallError / EOFError for
+      # the exporters' retry loop to classify.
+      def post(path, body:, headers:, timeout:)
+        @mutex.synchronize do
+          deadline = monotonic_now + timeout
+          begin
+            reused = ensure_connection(deadline)
+            begin
+              write_request(path, body, headers, deadline)
+              read_response(deadline)
+            rescue EOFError, Errno::EPIPE, Errno::ECONNRESET
+              # Stale keep-alive socket (server closed between exports): one
+              # silent reconnect + retransmit, ONLY when the failed attempt
+              # rode a pooled connection. A fresh connection failing is a
+              # real error.
+              raise unless reused
+
+              close_socket
+              ensure_connection(deadline)
+              write_request(path, body, headers, deadline)
+              read_response(deadline)
+            end
+          rescue StandardError
+            # Fleet-review fix (2026-07-29): ANY transport error — timeout,
+            # SSL, syscall, malformed response — poisons the connection
+            # (half-written request, partial @rbuf). Net::HTTP closed on
+            # every transport error; so does this client. The next post
+            # dials fresh instead of desyncing on a dirty stream.
+            close_socket
+            raise
+          end
+        end
+      end
+
+      private
+
+      def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # ---- connection management -------------------------------------------
+
+      # Returns true when an existing pooled socket was reused, false when a
+      # fresh connection was made.
+      def ensure_connection(deadline)
+        if @socket
+          if @pid != Process.pid
+            # Fork safety (rule 37): a pid change means this socket is the
+            # PARENT's. Close ONLY our copy of the fd — SSLSocket#close
+            # would SSL_shutdown and write a close_notify record into the
+            # TCP stream the parent is still using (fleet-review fix
+            # 2026-07-29: close_notify is application-visible bytes, not fd
+            # state).
+            discard_socket
+          elsif !keep_alive_expired?
+            @last_used = monotonic_now
+            return true
+          else
+            close_socket
+          end
+        end
+        connect(deadline)
+        false
+      end
+
+      # Drop the socket WITHOUT protocol goodbyes: closes the raw fd only
+      # (no SSL_shutdown), for fds shared with a parent process across fork.
+      def discard_socket
+        io = @socket.respond_to?(:to_io) ? @socket.to_io : @socket
+        io&.close
+      rescue StandardError
+        nil
+      ensure
+        @socket = nil
+        @rbuf = +""
+      end
+
+      def keep_alive_expired?
+        @last_used && (monotonic_now - @last_used) > @keep_alive_timeout
+      end
+
+      def connect(deadline)
+        tcp =
+          if @proxy
+            sock = open_tcp(@proxy.hostname, @proxy.port, deadline)
+            establish_connect_tunnel(sock, deadline) if @use_ssl
+            sock
+          else
+            open_tcp(@host, @port, deadline)
+          end
+
+        @socket =
+          if @use_ssl
+            ssl = OpenSSL::SSL::SSLSocket.new(tcp, @ssl_context)
+            ssl.hostname = @host # SNI
+            ssl.sync_close = true
+            ssl_connect(ssl, deadline)
+            # Hostname verification (red-flag 4, CWE-295): verify_hostname on
+            # the context covers the handshake; post_connection_check is the
+            # belt-and-braces explicit check Net::HTTP performed for us.
+            ssl.post_connection_check(@host) unless @ssl_verify_mode == OpenSSL::SSL::VERIFY_NONE
+            ssl
+          else
+            tcp
+          end
+        @pid = Process.pid
+        @last_used = monotonic_now
+        @rbuf = +""
+      rescue StandardError
+        begin
+          tcp&.close
+        rescue StandardError
+          nil
+        end
+        @socket = nil
+        raise
+      end
+
+      def open_tcp(host, port, deadline)
+        remaining = remaining_or_raise(deadline, OpenTimeoutError, "connect")
+        # resolv_timeout bounds the DNS lookup by the same deadline the TCP
+        # connect gets (fleet-review fix: a hung resolver must not stall the
+        # export past its budget).
+        sock = Socket.tcp(host, port, connect_timeout: remaining, resolv_timeout: remaining)
+        sock.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+        sock
+      rescue Errno::ETIMEDOUT
+        raise OpenTimeoutError, "connect to #{host}:#{port} timed out"
+      end
+
+      # CONNECT tunnel for https-through-proxy (red-flag 1): speak plain HTTP
+      # to the proxy, then start TLS INSIDE the established tunnel.
+      def establish_connect_tunnel(sock, deadline)
+        authority = "#{bracketed_host}:#{@port}"
+        request = +"CONNECT #{authority} HTTP/1.1\r\nHost: #{authority}\r\n"
+        request << "Proxy-Authorization: Basic #{proxy_basic_credentials}\r\n" if @proxy.user
+        request << "\r\n"
+        write_all(sock, request.b, deadline)
+
+        status_line, headers = read_head(sock, deadline)
+        code = parse_status_code(status_line)
+        raise ProxyConnectError, "proxy CONNECT to #{authority} failed: #{status_line.strip}" unless (200..299).cover?(code)
+
+        # RFC 7231 §4.3.6: a 2xx CONNECT response has no body; any buffered
+        # bytes past the head belong to the TLS handshake. Nothing to drain.
+        headers
+      end
+
+      def ssl_connect(ssl, deadline)
+        loop do
+          case ssl.connect_nonblock(exception: false)
+          when :wait_readable then wait_io(ssl, :read, deadline)
+          when :wait_writable then wait_io(ssl, :write, deadline)
+          else return
+          end
+        end
+      end
+
+      def close_socket
+        @socket&.close
+      rescue StandardError
+        nil
+      ensure
+        @socket = nil
+        @rbuf = +""
+      end
+
+      # ---- TLS context --------------------------------------------------------
+
+      def build_ssl_context(verify_mode, certificate_file, client_certificate_file, client_key_file)
+        context = OpenSSL::SSL::SSLContext.new
+        context.verify_mode = verify_mode
+        context.verify_hostname = verify_mode != OpenSSL::SSL::VERIFY_NONE
+        if certificate_file
+          context.ca_file = certificate_file
+        else
+          store = OpenSSL::X509::Store.new
+          store.set_default_paths
+          context.cert_store = store
+        end
+        # mTLS (spec OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE / _CLIENT_KEY,
+        # threaded through the exporter constructors). PKey.read handles RSA
+        # and EC keys (upstream's PKey::RSA.new was RSA-only).
+        context.cert = OpenSSL::X509::Certificate.new(File.read(client_certificate_file)) if client_certificate_file
+        context.key = OpenSSL::PKey.read(File.read(client_key_file)) if client_key_file
+        context
+      end
+
+      # ---- proxy resolution ---------------------------------------------------
+
+      # HTTP_PROXY / HTTPS_PROXY / NO_PROXY (+ lowercase twins), the same env
+      # contract Net::HTTP honored implicitly via URI::Generic#find_proxy.
+      def resolve_proxy_from_env
+        raw = if @use_ssl
+                env_first("HTTPS_PROXY", "https_proxy")
+              else
+                # Uppercase HTTP_PROXY is deliberately honored here too: this
+                # client never runs under CGI (where REQUEST_METHOD makes
+                # HTTP_PROXY attacker-controlled — httpoxy), and the exporter
+                # is a background sender.
+                env_first("HTTP_PROXY", "http_proxy")
+              end
+        return nil if raw.nil? || raw.strip.empty?
+        return nil if no_proxy?(@host, @port)
+
+        proxy = URI(raw)
+        return nil if proxy.hostname.nil? || proxy.hostname.empty?
+
+        proxy
+      rescue URI::Error
+        nil
+      end
+
+      def env_first(*names)
+        names.each do |name|
+          value = ENV.fetch(name, nil)
+          return value if value && !value.empty?
+        end
+        nil
+      end
+
+      def no_proxy?(host, port)
+        raw = env_first("NO_PROXY", "no_proxy")
+        return false if raw.nil?
+
+        host = host.downcase
+        raw.split(",").any? do |entry|
+          entry = entry.strip.downcase
+          next false if entry.empty?
+          next true if entry == "*"
+
+          entry_host, entry_port = entry.split(":", 2)
+          entry_host = entry_host.delete_prefix(".")
+          next false if entry_port && entry_port.to_i != port
+
+          host == entry_host || host.end_with?(".#{entry_host}")
+        end
+      end
+
+      def unescape(component)
+        URI.decode_www_form_component(component)
+      rescue StandardError
+        component
+      end
+
+      def proxy_basic_credentials
+        ["#{unescape(@proxy.user)}:#{unescape(@proxy.password || '')}"].pack("m0")
+      end
+
+      # ---- request writing ----------------------------------------------------
+
+      def bracketed_host
+        @host.include?(":") ? "[#{@host}]" : @host # IPv6 literal
+      end
+
+      def host_header
+        default_port = @use_ssl ? 443 : 80
+        @port == default_port ? bracketed_host : "#{bracketed_host}:#{@port}"
+      end
+
+      def request_target(path)
+        # http through a proxy speaks absolute-form; https tunnels via CONNECT
+        # and http(s) direct speak origin-form.
+        return "http://#{host_header}#{path}" if @proxy && !@use_ssl
+
+        path
+      end
+
+      def write_request(path, body, headers, deadline)
+        head = +"POST #{request_target(path)} HTTP/1.1\r\n"
+        head << "Host: #{host_header}\r\n"
+        head << "Content-Length: #{body.bytesize}\r\n"
+        # Plain-HTTP proxying authenticates per request (fleet-review fix:
+        # Net::HTTP sent proxy_basic_auth on every non-CONNECT proxied
+        # request; without this an authenticated proxy 407s every export).
+        head << "Proxy-Authorization: Basic #{proxy_basic_credentials}\r\n" if @proxy && !@use_ssl && @proxy.user
+        headers.each do |key, value|
+          key = key.to_s
+          next if /\A(host|content-length|connection|transfer-encoding)\z/i.match?(key)
+
+          # Header-injection hardening: a header value can never smuggle CRLF
+          # into foam's own framing.
+          head << "#{key.gsub(/[\r\n]/, ' ')}: #{value.to_s.gsub(/[\r\n]/, ' ')}\r\n"
+        end
+        head << "\r\n"
+        write_all(@socket, head.b + body.b, deadline)
+        @last_used = monotonic_now
+      end
+
+      # ---- response reading -----------------------------------------------------
+
+      def read_response(deadline)
+        code = nil
+        headers = nil
+        # Skip 1xx informational responses (we never send Expect, but a proxy
+        # or server may still emit one).
+        loop do
+          status_line, headers = read_head(@socket, deadline)
+          code = parse_status_code(status_line)
+          break if code >= 200
+        end
+
+        body = read_body(code, headers, deadline)
+
+        if headers["connection"].to_s.downcase.include?("close")
+          close_socket
+        elsif !@rbuf.empty?
+          # Fleet-review fix (2026-07-29): bytes beyond the response framing
+          # mean the stream is desynced (a lying Content-Length, pipelined
+          # junk). Poisoned leftovers must never become the NEXT response's
+          # prefix — drop the connection; the next post dials fresh.
+          close_socket
+        else
+          @last_used = monotonic_now
+        end
+        Response.new(code, headers, body)
+      end
+
+      # Reads a status line + header block (shared by responses and the
+      # CONNECT tunnel reply). Returns [status_line, headers-hash(lowercased)].
+      def read_head(io, deadline)
+        head = buffered_read_until(io, "\r\n\r\n", deadline)
+        lines = head.split("\r\n")
+        status_line = lines.shift.to_s
+        headers = {}
+        lines.each do |line|
+          name, _, value = line.partition(":")
+          next if name.empty?
+
+          name = name.strip.downcase
+          value = value.strip
+          # Duplicate headers combine per RFC 9110 §5.2 (retry-after is
+          # single-valued in practice; combining keeps the reader total).
+          headers[name] = headers.key?(name) ? "#{headers[name]}, #{value}" : value
+        end
+        [status_line, headers]
+      end
+
+      def parse_status_code(status_line)
+        match = %r{\AHTTP/\d(?:\.\d)? (\d{3})}.match(status_line)
+        raise EOFError, "malformed HTTP status line from #{@host}: #{status_line.inspect[0, 80]}" unless match
+
+        match[1].to_i
+      end
+
+      def read_body(code, headers, deadline)
+        # RFC 9112 §6.3: 204 and 304 never carry a body, framing headers or
+        # not — without this guard a keep-alive "204 No Content\r\n\r\n"
+        # (nginx/ALB idiom) would fall into the read-to-EOF branch and stall
+        # every export until its deadline (fleet-review fix 2026-07-29).
+        return +"" if code == 204 || code == 304
+
+        if headers["transfer-encoding"].to_s.downcase.include?("chunked")
+          read_chunked_body(deadline)
+        elsif (length = headers["content-length"])
+          length = length.to_i
+          raise EOFError, "response Content-Length #{length} exceeds the #{MAX_RESPONSE_BYTES}-byte cap" if length > MAX_RESPONSE_BYTES
+
+          buffered_read_exact(@socket, length, deadline)
+        else
+          # No framing → body runs to EOF and the connection dies with it
+          # (Connection: close semantics / HTTP/1.0 servers).
+          body = +""
+          body << @rbuf
+          @rbuf = +""
+          while (chunk = read_more(@socket, deadline))
+            body << chunk
+            raise EOFError, "unframed response exceeded the #{MAX_RESPONSE_BYTES}-byte cap" if body.bytesize > MAX_RESPONSE_BYTES
+          end
+          close_socket
+          body
+        end
+      end
+
+      def read_chunked_body(deadline)
+        body = +""
+        loop do
+          size_line = buffered_read_until(@socket, "\r\n", deadline)
+          token = size_line.split(";").first.to_s.strip
+          # A malformed size token must be a LOUD protocol error — to_i(16)
+          # would silently parse garbage as 0 and truncate the body while
+          # leaving the stream desynced (fleet-review fix 2026-07-29).
+          raise EOFError, "malformed chunk-size line from #{@host}: #{size_line.inspect[0, 40]}" unless /\A[0-9a-fA-F]+\z/.match?(token)
+
+          size = token.to_i(16)
+          raise EOFError, "chunked response exceeded the #{MAX_RESPONSE_BYTES}-byte cap" if body.bytesize + size > MAX_RESPONSE_BYTES
+
+          if size.zero?
+            # Trailers (if any) run to the terminating blank line.
+            loop do
+              line = buffered_read_until(@socket, "\r\n", deadline)
+              break if line.empty?
+            end
+            break
+          end
+          body << buffered_read_exact(@socket, size, deadline)
+          buffered_read_until(@socket, "\r\n", deadline) # chunk terminator
+        end
+        body
+      end
+
+      # ---- buffered + nonblocking IO with one deadline ---------------------------
+
+      def buffered_read_until(io, delimiter, deadline)
+        until (index = @rbuf.index(delimiter))
+          chunk = read_more(io, deadline)
+          raise EOFError, "connection to #{@host} closed mid-response" if chunk.nil?
+
+          @rbuf << chunk
+        end
+        out = @rbuf.slice!(0, index + delimiter.bytesize)
+        out.delete_suffix(delimiter)
+      end
+
+      def buffered_read_exact(io, length, deadline)
+        while @rbuf.bytesize < length
+          chunk = read_more(io, deadline)
+          raise EOFError, "connection to #{@host} closed mid-body" if chunk.nil?
+
+          @rbuf << chunk
+        end
+        @rbuf.slice!(0, length)
+      end
+
+      # One nonblocking read; nil at EOF. IO::Wait* loops through the deadline
+      # (SSL reads can want WRITABLE during renegotiation and vice versa).
+      def read_more(io, deadline)
+        loop do
+          result = io.read_nonblock(READ_CHUNK, exception: false)
+          case result
+          when :wait_readable then wait_io(io, :read, deadline)
+          when :wait_writable then wait_io(io, :write, deadline)
+          when nil then return nil
+          else return result
+          end
+        end
+      end
+
+      def write_all(io, data, deadline)
+        offset = 0
+        while offset < data.bytesize
+          result = io.write_nonblock(data.byteslice(offset..), exception: false)
+          case result
+          when :wait_writable then wait_io(io, :write, deadline, kind: WriteTimeoutError)
+          when :wait_readable then wait_io(io, :read, deadline, kind: WriteTimeoutError)
+          else offset += result
+          end
+        end
+      end
+
+      def wait_io(io, direction, deadline, kind: ReadTimeoutError)
+        remaining = remaining_or_raise(deadline, kind, direction)
+        plain = io.respond_to?(:to_io) ? io.to_io : io
+        ready =
+          if direction == :read
+            IO.select([plain], nil, nil, remaining)
+          else
+            IO.select(nil, [plain], nil, remaining)
+          end
+        raise kind, "#{direction} on #{@host} timed out" unless ready
+      end
+
+      def remaining_or_raise(deadline, kind, what)
+        remaining = deadline - monotonic_now
+        raise kind, "#{what} deadline exceeded for #{@host}" if remaining <= 0
+
+        remaining
+      end
+    end
+  end
+end

data/lib/foam/otel/pipelines.rb

@@ -28,8 +28,15 @@ module Foam
       # carrying the fleet ingest token and the full OTLP payload. There is
       # deliberately NO foam option to weaken this; init warns when the env
       # var is set (env_vars posture, rule 15).
+      # Every exporter below is a Foam::Otel::IsolatedExporters subclass
+      # (export-isolation design, 2026-07-29): identical construction surface
+      # and retry semantics to the upstream OTLP exporters, but the bytes ride
+      # foam's owned IsolatedHttpClient — never Net::HTTP, which every foreign
+      # APM in the process is free to prepend onto (the Datadog
+      # auto_instrument outage class: 464 export crashes, zero rows landed,
+      # with the untraced suppression flag active the whole time).
       def setup_traces(endpoint, headers, resource, config, extra_processors)
-        inner = OpenTelemetry::Exporter::OTLP::Exporter.new(
+        inner = IsolatedExporters::TraceExporter.new(
           endpoint: "#{endpoint}/v1/traces", headers: headers,
           ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER
         )
@@ -88,7 +95,7 @@ module Foam
       end
 
       def setup_logs(endpoint, headers, resource, config, extra_processors)
-        inner = OpenTelemetry::Exporter::OTLP::Logs::LogsExporter.new(
+        inner = IsolatedExporters::LogsExporter.new(
           endpoint: "#{endpoint}/v1/logs", headers: headers,
           ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER # F-RB1 pin — see setup_traces
         )
@@ -149,7 +156,7 @@ module Foam
       # additional_metric_readers. The reader needs explicit after_fork
       # recovery (GOTCHAS R1) — tracked in @metric_readers.
       def setup_metrics(endpoint, headers, resource, config, extra_readers)
-        inner = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
+        inner = IsolatedExporters::MetricsExporter.new(
           endpoint: "#{endpoint}/v1/metrics", headers: headers,
           ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER # F-RB1 pin — see setup_traces
         )

data/lib/foam/otel/prepend_collision_shield.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+# The prepend-collision shield (coexistence mandate 2026-07-29, GOTCHAS F18).
+#
+# Ruby APM agents instrument shared clients by PREPENDING modules onto the
+# class itself, and Ruby gives all of those modules ONE private-method
+# namespace: when two vendors define a same-named private helper at different
+# signatures, method lookup hands every caller the FRONTMOST definition — so
+# one vendor's wrapper invokes the other vendor's helper and crashes with an
+# ArgumentError. This is the exact live collision between a proprietary
+# agent's Net::HTTP wrapper and the upstream OTel contrib net_http patch
+# (`annotate_span_with_response!`, 3-arg vs 2-arg): every HTTP request the
+# APP makes dies inside the chain. Foam ships that contrib patch for capture,
+# so a foam + agent process contains the collision — and foam's contract is
+# to COEXIST: the app must keep working with foam installed next to any
+# agent.
+#
+# The shield is the structural fix, applied WITHOUT touching either vendor's
+# code (renaming the upstream helper alone would break the upstream caller,
+# which resolves the name through the same shared chain). At init, after
+# foam's instrumentation sweep, the shield scans the prepend chain of the
+# known collision-prone class (Net::HTTP) for helper names — private or
+# public; the shim preserves the shielded definitions' visibility — defined by
+# TWO OR MORE foreign modules at non-identical positional signatures, where
+# the name does NOT exist on the class itself or behind it (those are the
+# normal super-chains, not collisions). For each colliding name it prepends
+# ONE frontmost dispatch method that routes each call to the implementation
+# the caller intended:
+#   1. by caller source: the implementation living in the same gem root as
+#      the calling frame wins (each vendor gets its own helper back);
+#   2. else by signature: the unique implementation whose positional arity
+#      accepts the call;
+#   3. else the previously-frontmost definition (status quo ante — the
+#      shield never makes an already-broken chain worse).
+#
+# No collision found → NOTHING is installed (the common, foam-only case is a
+# scan and nothing else). Every shielded name is announced loudly (rule 15).
+#
+# Deliberate exception to foam's own-prepend hygiene rule: foam's other
+# prepends carry zero private helpers precisely so foam can never collide;
+# the shield's whole job is to OWN the already-colliding names, and its
+# dispatch methods accept (*args, **kwargs, &block) so no caller can ever
+# arity-crash against the shield itself.
+#
+# Residual (documented in GOTCHAS F18): an agent that patches AFTER foam's
+# init lands ahead of the shield and re-exposes the raw collision until the
+# next init/fork re-scan; agents overwhelmingly boot first (initializer /
+# preload), which is the order the coexistence gate proves.
+require_relative "diagnostics"
+
+module Foam
+  module Otel
+    module PrependCollisionShield
+      class << self
+        # Scan + shield the class's prepend chain. Idempotent per collision
+        # set: names already shielded by a live foam shim are skipped.
+        # Never raises (rule 9): a scan failure degrades to a loud no-op.
+        def install!(klass)
+          front = klass.ancestors.take_while { |m| !m.equal?(klass) }
+          already = front.select { |m| shim?(m) }.flat_map { |m| m.instance_variable_get(:@foam_shielded_names) || [] }
+          foreign = front.reject { |m| shim?(m) }
+          collisions = colliding_helpers(klass, foreign).reject { |name, _| already.include?(name) }
+          return [] if collisions.empty?
+
+          klass.prepend(build_shim(collisions))
+          collisions.each do |name, defs|
+            owners = defs.map { |d| d[:mod].name || d[:mod].inspect }.join(" AND ")
+            Diagnostics.warn("coexistence shield: private helper ##{name} on #{klass} is defined at " \
+                             "incompatible signatures by #{owners} — one would crash the other's callers " \
+                             "(and every #{klass} user). Foam installed a signature-dispatch shim so both " \
+                             "keep working (GOTCHAS F18).")
+          end
+          collisions.keys
+        rescue StandardError, SystemStackError => e
+          Diagnostics.warn("coexistence shield: scan of #{klass} failed (#{e.class}: #{e.message}) — " \
+                           "no shim installed")
+          []
+        end
+
+        # The dispatch core, called from every shim method. Public for the
+        # shim modules only; not customer surface.
+        def dispatch(receiver, defs, caller_path, args, kwargs, block)
+          impl = resolve(defs, caller_path, args, kwargs)
+          if kwargs.empty?
+            impl.bind_call(receiver, *args, &block)
+          else
+            impl.bind_call(receiver, *args, **kwargs, &block)
+          end
+        end
+
+        private
+
+        def shim?(mod)
+          mod.instance_variable_defined?(:@foam_shielded_names)
+        end
+
+        # name => [{mod:, um:, min:, max:, kw:, root:}, ...] for every private
+        # helper defined by >= 2 foreign front modules at non-identical
+        # positional signatures, excluding names the class (or anything
+        # behind it) defines — those are super-chains, not collisions.
+        def colliding_helpers(klass, foreign)
+          behind = klass.ancestors.drop_while { |m| !m.equal?(klass) }
+          table = Hash.new { |h, k| h[k] = [] }
+          foreign.each do |mod|
+            (mod.instance_methods(false) + mod.private_instance_methods(false)).each do |name|
+              table[name] << describe(mod, name)
+            end
+          end
+          table.select do |name, defs|
+            defs.length >= 2 &&
+              behind.none? { |m| m.method_defined?(name, false) || m.private_method_defined?(name, false) } &&
+              defs.map { |d| [d[:min], d[:max]] }.uniq.length > 1
+          end
+        end
+
+        def describe(mod, name)
+          um = mod.instance_method(name)
+          min = 0
+          max = 0
+          kw = false
+          is_public = mod.instance_methods(false).include?(name)
+          um.parameters.each do |kind, _|
+            case kind
+            when :req
+              min += 1
+              max += 1 if max
+            when :opt
+              max += 1 if max
+            when :rest
+              max = nil
+            when :key, :keyreq, :keyrest
+              kw = true
+            end
+          end
+          # Gem root = everything before the LAST "/lib/" segment.
+          # rpartition, not split: on /var/lib/gems, /usr/lib/ruby and rbenv
+          # layouts the FIRST "/lib/" is the interpreter's, and splitting
+          # there collapses every gem to one shared root, disabling
+          # caller-source dispatch entirely (fleet-review fix 2026-07-29).
+          source = um.source_location&.first.to_s
+          root = source.include?("/lib/") ? source.rpartition("/lib/").first : nil
+          { mod: mod, um: um, min: min, max: max, kw: kw, public: is_public,
+            root: root.to_s.empty? ? nil : root }
+        end
+
+        def resolve(defs, caller_path, args, kwargs)
+          # 1. the caller's own gem gets its own helper back; several
+          # same-root candidates (or none) narrow the pool and fall through
+          # to the signature test.
+          pool = defs
+          if caller_path
+            own = defs.select { |d| d[:root] && caller_path.start_with?(d[:root]) }
+            return own.first[:um] if own.length == 1
+
+            pool = own unless own.empty?
+          end
+          # 2. signature match — first within the narrowed pool, then across
+          # every definition.
+          fitting = pool.select { |d| fits?(d, args, kwargs) }
+          fitting = defs.select { |d| fits?(d, args, kwargs) } if fitting.empty?
+          return fitting.first[:um] unless fitting.empty?
+
+          # 3. status quo ante: the frontmost definition (defs are collected
+          # in ancestry order), exactly what an unshielded chain would run.
+          defs.first[:um]
+        end
+
+        def fits?(definition, args, kwargs)
+          args.length >= definition[:min] &&
+            (definition[:max].nil? || args.length <= definition[:max]) &&
+            (kwargs.empty? || definition[:kw])
+        end
+
+        def build_shim(collisions)
+          shim = Module.new
+          shim.instance_variable_set(:@foam_shielded_names, collisions.keys.freeze)
+          collisions.each do |name, defs|
+            shim.define_method(name) do |*args, **kwargs, &block|
+              location = caller_locations(1, 1)&.first
+              PrependCollisionShield.dispatch(self, defs, location&.absolute_path || location&.path,
+                                              args, kwargs, block)
+            end
+            # Visibility follows the shielded definitions: privatizing a name
+            # some vendor exposes publicly would break that vendor's external
+            # callers with NoMethodError (fleet-review fix 2026-07-29).
+            shim.send(:private, name) unless defs.any? { |d| d[:public] }
+          end
+          shim
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/version.rb

@@ -145,6 +145,36 @@ module Foam
     #   service-container fallback, pg_isready gate, leak cleanup, numeric
     #   version pick. Hooks run on the export thread — non-blocking only
     #   (documented, GOTCHAS F16).
-    VERSION = "1.8.1"
+    # 1.9.0: EXPORT ISOLATION (export-isolation design 2026-07-29,
+    #   docs/decisions/export-isolation-ruby.md, GOTCHAS F17; MINOR —
+    #   reliability-motivated transport change, zero API/config/wire-shape
+    #   change). Foam's OTLP delivery no longer travels Net::HTTP — the class
+    #   every co-resident APM prepends onto (the wrong-arity private-helper
+    #   collision class: every export crashes, zero rows land, healthy app,
+    #   WITH the untraced flag active). All six exporters (door 1 + door 2 ×
+    #   traces/logs/metrics) now ride Foam::Otel::IsolatedHttpClient, an
+    #   owned hand-written HTTP/1.1 sender: TLS VERIFY_PEER + hostname check,
+    #   CA/mTLS options, HTTP(S)_PROXY/NO_PROXY with CONNECT tunneling,
+    #   per-request deadlines, keep-alive with one stale-socket retransmit,
+    #   chunked/Connection: close reading, pid-keyed fork-safe reconnect.
+    #   Upstream retry semantics preserved verbatim (429/503 honor
+    #   Retry-After, 408/502/504 + transient socket errors back off with
+    #   jitter, other 4xx drop); spec OTEL_EXPORTER_OTLP_* env handling and
+    #   the endpoint policy unchanged; untraced suppression kept as layer
+    #   two. Capture untouched — foam still instruments the app's Net::HTTP
+    #   exactly as before.
+    #   ALSO (coexistence mandate, same release, GOTCHAS F18): the prepend-
+    #   collision shield. Cross-vendor private-helper collisions on
+    #   Net::HTTP (the live `annotate_span_with_response!` 3-arg vs 2-arg
+    #   arity crash between a proprietary agent and the upstream contrib
+    #   net_http patch foam ships) crash the APP's own HTTP calls; init now
+    #   scans the prepend chain after the sweep and installs one frontmost
+    #   signature-dispatch method per colliding name (caller-source gem
+    #   first, then arity fit, else status quo ante) so every vendor's
+    #   wrapper gets its own helper back. Collision-free chains (the common
+    #   case) install NOTHING. Proven against the real agents in
+    #   test-apps/ruby-coexistence (six vendors, both patch mechanisms,
+    #   patched-client probe REQUIRED green).
+    VERSION = "1.9.0"
   end
 end

data/lib/foam/otel.rb

@@ -28,4 +28,5 @@ require_relative "otel/redaction"
 require_relative "otel/errors"
 require_relative "otel/metrics"
 require_relative "otel/api"   # customer-facing helpers (API gem only)
+require_relative "otel/prepend_collision_shield" # coexistence shield (stdlib-only; F17)
 require_relative "otel/init"  # init() + orchestration (SDK loaded lazily)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 1.8.1
+  version: 1.9.0
 platform: ruby
 authors:
 - Foam
@@ -390,6 +390,8 @@ files:
 - lib/foam/otel/ingest_metric_reader.rb
 - lib/foam/otel/init.rb
 - lib/foam/otel/instance.rb
+- lib/foam/otel/isolated_exporters.rb
+- lib/foam/otel/isolated_http_client.rb
 - lib/foam/otel/llm.rb
 - lib/foam/otel/llm/anthropic_shim.rb
 - lib/foam/otel/llm/gemini_shim.rb
@@ -399,6 +401,7 @@ files:
 - lib/foam/otel/metrics.rb
 - lib/foam/otel/payload_capture.rb
 - lib/foam/otel/pipelines.rb
+- lib/foam/otel/prepend_collision_shield.rb
 - lib/foam/otel/redacting_exporter.rb
 - lib/foam/otel/redaction.rb
 - lib/foam/otel/resource.rb