foam-otel 1.6.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb5e4f91fea3170bbb206582adade6ca516824edad064a4be911ebe912ce7abf
-  data.tar.gz: 67ee9186826b4bc31c7f51deeaf8fd91bec6aaec393099f23b000384821230b9
+  metadata.gz: 48166d05b120dd8bdca15a9b45db5b4c16a6574fcb6890f4caff2c17c2ae9add
+  data.tar.gz: 2dcd4b3b146a0221c231ba5efc057085418b74e21b24d8441396d47cfc0a8288
 SHA512:
-  metadata.gz: 4c4c7288e2b049a9f686d0eae3637a74261820bc779d6e8ec4daf14347b6ed3b423648c4c0d226982663465907465fc350a44cd52b998ad97b4766b69ecb727b
-  data.tar.gz: 7eb2f27f17fc9fcd9649b72c68b59493b366ff66950c86ff42f4baa414b7ea222b9e251f30264adbfe32400fe7851b2cf64505bf666c5385546b44f4a5714768
+  metadata.gz: 4e92c7af8cc5cf7cc177b792f87a8107b918035efdce080e2a974750180ebbb9aac4a5460cb08372f3ded2724d136804bcb8f0574ee4685ebbdd94fde7afb3e8
+  data.tar.gz: ddd7b6e431034663ec94dacd8b7b051ee63bfecdbeb2a38d383c58531854ba0580f34c9a04ed56473b654b89155fc9a3b7ce140b073ba346d90a5a801b9c6d4b

data/GOTCHAS.md

@@ -721,6 +721,91 @@ exfiltratable — the value-pattern secret layer is the required second control
   no-op + registration idempotence; `spec/conventions_spec.rb` (rule 21:
   header capture never grows a `rack.input` body tee).
 
+## F15: Opt-in payload (body) capture must TEE, never consume — and the rack span's lifetime decides when body attributes can land
+
+- **Trap**: five ways foam's opt-in body capture (`payload_capture.rb`,
+  behind `capture_payloads:` — default `:off`) could break the customer or
+  silently lose data. (1) Reading `env['rack.input']` ahead of the app —
+  or rewinding it — breaks Rack 3 apps: inputs are no longer required to
+  be rewindable, and a consumed stream starves the framework's own parser.
+  (2) Buffering the response to capture it breaks streaming (SSE, large
+  downloads), and Rack 3 `#call`-only streaming bodies must not be wrapped
+  at all — defining `#each` on the wrapper would change how the server
+  drives the response. (3) The official rack instrumentation ends its span
+  at DIFFERENT times per mode: the default `Rack::Events` handler finishes
+  it when the response body is CLOSED (`EventedBodyProxy` fires
+  `on_finish` after the inner body's close — so a tee flushing at close
+  writes in time), but the non-events `TracerMiddleware` ends it when
+  `@app.call` RETURNS — attributes flushed from a streamed body's close
+  there would hit an ENDED span (upstream logs a warning per write). (4)
+  An OUTER middleware (`Rack::MethodOverride`) reads the form body,
+  rewinds — or repositions via `seek(0)`/`pos=`, equivalent idioms on the
+  rewindable inputs real servers hand out — and the framework re-reads it:
+  a naive tee (or one that dedupes `rewind` alone) captures and counts it
+  twice. (5) The `:errors` mode needs "an exception was recorded on the
+  span" — re-implementing that check would duplicate
+  `Errors.record_once`'s dedupe registry and drift from it.
+- **Sources**: installed source — rack `body_proxy.rb:28-35` (`close`
+  closes the inner body BEFORE the proxy's block) and `:47-53` (`to_ary`
+  auto-closes), rack `events.rb:140-142` (the body proxy that fires
+  `on_finish` on close); opentelemetry-instrumentation-rack-0.31.1 stable
+  `event_handler.rb:109-117,199-205` (`on_finish`/`detach_context` finish
+  the span at body close) vs stable `tracer_middleware.rb:78-90`
+  (`in_span` ends the span when the block — `@app.call(env).tap` —
+  returns); Rack SPEC (input `gets`/`read`/`each`; `to_ary` bodies;
+  streaming `#call` bodies); `errors.rb:17-43` (the span-carried
+  `@__foam_otel_recorded` ivar registry).
+- **Decision & why**: delegating tees only, on BOTH directions, behind the
+  ONE mode switch. `:off` (the default) ships ZERO middleware (the Railtie
+  hook runs after `:load_config_initializers` — when init has resolved the
+  mode — and stands down; a manual `use` line is a one-branch
+  passthrough). The input tee observes exactly what the APP reads
+  (read/gets/each), delegates everything else with truthful `respond_to?`
+  (a non-rewindable input stays non-rewindable), and dedupes across EVERY
+  repositioning method — `rewind`, `seek`, `pos=` — with a
+  position/high-water scheme — bytes are captured and counted once no
+  matter how often an outer middleware repositions the stream. The response side
+  captures `to_ary`-able (buffered) bodies SYNCHRONOUSLY at middleware
+  return — the span is provably alive in both official modes — returning
+  the array as the new body (the Rack spec's sanctioned move;
+  `BodyProxy#to_ary` closes the original). Genuinely streaming `#each`
+  bodies are teed chunk-by-chunk, unbuffered, flushing attributes on
+  iteration-complete/close: that lands in the default `Rack::Events` mode
+  and is silently skipped (a `recording?` gate, no upstream warn-spam) in
+  `TracerMiddleware` mode — a recorded, documented loss shape, never a
+  broken stream. `#call`-only bodies are never wrapped (sizes ride the
+  declared Content-Length when present). `:errors` reads the SAME ivar
+  registry `Errors.record_once` stamps, through the thin
+  `Errors.recorded?` seam — one registry, no duplicated dedupe — plus the
+  status >= 500 triplet check; an exception raised through the middleware
+  attaches the request side before the IDENTICAL re-raise. Capture is
+  gated on foam OWNING the traces slot (rule 18 B — a foreign SDK's rack
+  span is never enriched) and on a recording span; every path is
+  individually rescued (rule 9). Redaction stays central: JSON-shaped body
+  strings are deep-masked BY FIELD NAME at the exporter boundary
+  (`redaction.rb` `BODY_ATTRIBUTE_NAMES` — floor + customer lists reach
+  inside the body JSON; a cap-truncated body no longer parses, so only the
+  value-shape scans cover it — documented limit).
+- **Mitigation**: `lib/foam/otel/payload_capture.rb` (the whole module:
+  the mode gate + FOAM_CAPTURE_PAYLOADS clamp plumbing, ownership/
+  recording gates, tees, `to_ary`/streaming discrimination,
+  textual/identity classification, the 8192-char cap + fleet truncation
+  marker); `lib/foam/otel/init.rb` (option validation + env clamp,
+  mode-gated Railtie-fallback wiring); `lib/foam/otel/errors.rb`
+  (`recorded?`); `lib/foam/otel/redaction.rb` (`mask_body_attribute`).
+- **Test**: `spec/payload_capture_spec.rb` — all three modes on the real
+  redacting wire path (`:off` ships zero middleware and zero attrs;
+  `:errors` attaches on exception AND 5xx and on the record_exception ivar
+  seam, NOT on 200/404; `:always` attaches on 200), env-clamp precedence
+  both directions + invalid-env fallback, the streaming-body proof (chunks
+  intact, close preserved, attributes landed), the rewind/seek/pos=
+  re-read dedupe, the
+  never-reads case, cap/true-size/truncation, binary/gzip sizes-only,
+  concurrent-request isolation, the foreign-provider and non-recording
+  no-ops, the hostile-input battery, the error-path capture, and the
+  JSON-body deep-redaction wire proof; `spec/conventions_spec.rb` (rule 21
+  as amended: `rack.input` touched ONLY by payload_capture.rb).
+
 ---
 
 ## General gotchas (applicable to Ruby)

data/README.md

@@ -231,8 +231,86 @@ end
 skipped, not monkey-patched): outbound **Net::HTTP / Excon / HTTP (httprb)
 / HTTPX** headers (their official instrumentations expose no
 request/response hook or header option) and gRPC metadata. Outbound header
-coverage today is Faraday. **Bodies/payloads are not captured** — a
-separate, future capability, not part of header capture.
+coverage today is Faraday. **Bodies/payloads are not captured by header
+capture** — bodies are the separate, opt-in `capture_payloads:` capability
+below.
+
+### Payload (body) capture — opt-in, `capture_payloads:`
+
+**Off by default.** One init option turns on inbound HTTP **body** capture
+on the official rack SERVER span (headers stay the header-capture seam
+above — this never duplicates them):
+
+```ruby
+Foam::Otel.init(
+  name: "checkout-api", environment: ENV.fetch("APP_ENV"),
+  enabled: ENV.fetch("APP_ENV") == "production", token: ENV.fetch("FOAM_OTEL_TOKEN"),
+  capture_payloads: :errors # :off (default) | :errors | :always — equivalent strings accepted
+)
+```
+
+- **`:off` (default)** — zero body teeing, zero per-request allocation, and
+  **zero middleware shipped**: with the default, foam's Rails wiring
+  installs nothing at all.
+- **`:errors`** — bodies are teed per request but attributes attach to the
+  span **only when the request errored**: `Foam::Otel.record_exception`
+  called while the rack server span is current, an exception raised through
+  the middleware, or a response status **>= 500**. A clean 2xx/4xx
+  attaches **nothing**.
+- **`:always`** — attach on every request.
+
+An invalid option value raises `ArgumentError` at boot. The operator env
+clamp **`FOAM_CAPTURE_PAYLOADS=off|errors|always` overrides the option in
+both directions** (force payloads off on a misbehaving deploy, or force
+them on without a code change — one loud `[foam]` line when it changes the
+mode); an invalid env value warns and falls back to the option, never a
+crashed boot.
+
+**What lands on the span** (in `:always`, or in `:errors` on an errored
+request): `http.request.body` / `http.response.body` for **textual**
+payloads (`text/*`, JSON/`+json`, urlencoded forms, XML/`+xml`, GraphQL;
+skipped when `Content-Encoding` is not identity), capped at **8192 chars**
+with an `…[truncated]` marker, plus `http.request.body.size` /
+`http.response.body.size` — **true byte sizes** when known (declared
+`Content-Length`, else the bytes actually observed). Non-textual payloads
+contribute sizes only.
+
+**Stream safety (GOTCHAS F15):** bodies are TEED, never consumed — foam
+records exactly what your app reads from `rack.input` (an app that never
+reads its body captures nothing; a re-read form body — rewound, or
+repositioned via `seek`/`pos=` — is captured and counted once), and
+streaming/SSE responses pass through
+unbuffered chunk-by-chunk with `close` preserved. Rack 3 `#call`-only
+streaming bodies are never wrapped. The request and response are never
+altered, and an app exception re-raises identically.
+
+**Redaction stays central, on export:** a JSON-shaped body is
+**deep-redacted by field name** at the exporter boundary — the credential
+floor (`password`, `authorization`, …) and your `redact_keys` /
+`redact: {secrets:/pii:}` lists reach *inside* the body JSON; urlencoded
+bodies get their `k=v` pair names masked by the same tokenizer that covers
+query strings; and the value-pattern secret layer scans all captured body
+text. (A body truncated at the cap no longer parses as JSON, so field-name
+deep-redaction cannot apply to it — the value-shape scans still run.)
+
+**Wiring:** in **Rails**, automatic when the mode is not `:off` (foam's
+railtie inserts `Foam::Otel::PayloadCapture` directly inside the official
+rack middleware after your initializers run; when foam-otel loads before
+rails, `init` wires it instead, as long as init runs during boot — the
+standard `config/initializers/foam.rb` recipe). **Plain Rack / Sinatra**
+apps add one line under the official middleware:
+
+```ruby
+# config.ru
+use(*OpenTelemetry::Instrumentation::Rack::Instrumentation.instance.middleware_args)
+use Foam::Otel::PayloadCapture   # opt-in body capture (inert while capture_payloads is :off)
+run MyApp
+```
+
+The middleware enriches only: it never creates a span, and it stands down
+per request when foam is disabled/killed, when the span is not recording,
+or when a foreign SDK owns the traces slot. Outbound (client) bodies are
+not captured — inbound only.
 
 ---
 
@@ -253,6 +331,7 @@ separate, future capability, not part of header capture.
 | `additional_metric_readers:` | Array | no | `[]` | Tenant seam, metrics. |
 | `additional_instrumentations:` | Array | no | `[]` | Constructed tier-2 instrumentation instances to register (fault-isolated: one that throws is skipped with a `[foam]` warning). |
 | `ignored_outbound_hosts:` | Array<String> | no | `[]` | Hosts whose outbound calls produce no spans — EXTENDS the built-in export-loop guard. For a co-resident agent's intake or a tenant exporter's endpoint. Applies to the clients whose official instrumentation supports host suppression: **Net::HTTP and Excon**. Faraday/HTTP (httprb)/HTTPX have no upstream `untraced_hosts` option — foam warns loudly at init when one of those is bundled (GOTCHAS G13); foam's own export loop is guarded for every client regardless. |
+| `capture_payloads:` | Symbol/String | no | `:off` | Inbound HTTP **body** capture on the rack server span (see "Payload (body) capture"). `:off` = zero teeing, zero middleware (the default); `:errors` = tee per request, attach only on exception/5xx; `:always` = attach on every request. Equivalent strings accepted; anything else raises at boot. Overridden in both directions by the `FOAM_CAPTURE_PAYLOADS` env clamp (env table below). Textual payloads only, 8192-char cap + `…[truncated]`, true `.size` attributes; sizes-only for binary/compressed. |
 | `diagnostics:` | Boolean | no | false | Verbose `[foam]` self-reporting of init/health. Warnings and errors are always loud regardless. |
 | `secret_heuristics:` | Boolean | no | true | The value-pattern secret layer's HEURISTIC tier (generic keyword+entropy detection, see "The value-pattern secret layer"). `false` disables ONLY the heuristics — the named provider patterns, the credential floor and the redaction-coverage contract have no off switch. Disabling logs one loud `[foam]` line at init (an explicit, audited decision for telemetry whose legitimate values collide with the heuristics). |
 
@@ -926,6 +1005,7 @@ end
 | `OTEL_EXPORTER_OTLP_ENDPOINT` | HONORED — the one operator-level override of the pinned fleet endpoint (for foam's own conformance rig / enterprise egress). Active → loud `[foam]` warning naming the destination. Applies to door-2 taps identically (and moves the host the required loop step must name). |
 | `OTEL_PROPAGATORS=none` | HONORED — turns trace propagation OFF (links lost) while telemetry keeps flowing; warns. Any other value warns and is ignored (foam's propagator set is fixed: W3C tracecontext + baggage). |
 | `OTEL_BSP_SCHEDULE_DELAY` / `OTEL_BLRP_SCHEDULE_DELAY` / `OTEL_METRIC_EXPORT_INTERVAL` | HONORED — batch cadence, read natively by the upstream SDK. |
+| `FOAM_CAPTURE_PAYLOADS` | HONORED — the operator clamp over the `capture_payloads:` init option (`off`/`errors`/`always`, case-insensitive), overriding it in BOTH directions with one loud `[foam]` line when it changes the mode. An invalid value warns and falls back to the init option (never crashes a boot). This is the ONE foam-named env var the gem reads — an override valve over an init-declared option, never an on/off switch, token, or config fallback (those still arrive only through `init`'s explicit arguments). Read once at init; changing it implies a restart. |
 | `OTEL_RUBY_INSTRUMENTATION_RACK_CONFIG_OPTS` | HONORED (by the contrib rack gem itself) and RESPECTED by foam — a header option you set here (`allowed_request_headers=…` / `allowed_response_headers=…`) governs that option; foam's default header list fills only the option you did not touch (never widened, never overridden — see "Header capture"). The other `OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS` vars are likewise the contrib gems' own standard levers (e.g. the Sidekiq `propagation_style` note above). |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | INERT — foam wires ONE resolved endpoint into all three exporters explicitly, so per-signal endpoint vars never redirect (or split) foam's export. Set → loud `[foam]` warning that it is inert. |
 | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | INERT — as above (warns when set). |

data/lib/foam/otel/config.rb

@@ -12,7 +12,7 @@ module Foam
     Config = Struct.new(
       :name, :environment, :version, :enabled,
       :redact_keys, :redact_pii_keys, :redact_detect, :ignored_outbound_hosts,
-      :diagnostics, :endpoint, :secret_heuristics,
+      :diagnostics, :endpoint, :secret_heuristics, :capture_payloads,
       keyword_init: true
     )
 
@@ -22,6 +22,14 @@ module Foam
     # opts into the PII detection tier. Anything else raises at boot.
     REDACT_OPTION_FIELDS = %w[secrets pii detect].freeze
 
+    # The exact modes the `capture_payloads:` init option accepts
+    # (payload-capture mandate 2026-07-28; equivalent strings — trimmed,
+    # case-insensitive — are accepted and canonicalized to these symbols).
+    # :off is the default: zero body teeing, zero per-request allocation, no
+    # middleware shipped. The FOAM_CAPTURE_PAYLOADS operator env clamp
+    # (init.rb) accepts the same spellings and overrides the option.
+    CAPTURE_PAYLOAD_MODES = %i[off errors always].freeze
+
     class << self
       # The inert config the helpers read before init() runs (everything a
       # no-op needs: empty redaction lists, export disabled).
@@ -32,7 +40,7 @@ module Foam
           redact_detect: [].freeze,
           ignored_outbound_hosts: [].freeze,
           diagnostics: false, endpoint: FOAM_OTEL_ENDPOINT,
-          secret_heuristics: true
+          secret_heuristics: true, capture_payloads: :off
         ).freeze
       end
 
@@ -44,8 +52,13 @@ module Foam
 
       def resolve_config(name:, environment:, version:, enabled:,
                          redact_keys:, redact_pii_keys:, ignored_outbound_hosts:,
-                         diagnostics:, endpoint:, secret_heuristics: true, redact: nil)
+                         diagnostics:, endpoint:, secret_heuristics: true, redact: nil,
+                         capture_payloads: :off)
         keys, pii, detect = merged_redact_lists(redact_keys, redact_pii_keys, redact)
+        # capture_payloads is validated LOUDLY at boot (rule 10, exactly like
+        # the redact: object): a value outside CAPTURE_PAYLOAD_MODES (or its
+        # string spellings) raises here — never a silent :off.
+        capture_mode = validate_capture_payloads!(capture_payloads)
         Config.new(
           name: name,
           environment: environment,
@@ -71,12 +84,44 @@ module Foam
           # module-constant machinery no config shape can narrow. Anything
           # but literal false means ON (default-on preserves the fleet's
           # no-leakage bar; disabling is an explicit, audited decision).
-          secret_heuristics: secret_heuristics == false ? false : true
+          secret_heuristics: secret_heuristics == false ? false : true,
+          # The payload-capture mode (2026-07-28 mandate): :off (the default
+          # — zero teeing, zero middleware) | :errors | :always, canonical
+          # symbol form. init.rb applies the FOAM_CAPTURE_PAYLOADS operator
+          # env clamp BEFORE this resolves.
+          capture_payloads: capture_mode
         ).freeze
       end
 
       private
 
+      # ---- the capture_payloads option (payload-capture mandate 2026-07-28)
+      # Canonicalize a mode value: the three symbols, or their string
+      # spellings trimmed + case-insensitive, map to the canonical symbol;
+      # anything else is nil (the callers decide raise-vs-fallback).
+      def normalize_capture_payloads(value)
+        return value if CAPTURE_PAYLOAD_MODES.include?(value)
+        return nil unless value.is_a?(String) || value.is_a?(Symbol)
+
+        mode = value.to_s.strip.downcase.to_sym
+        CAPTURE_PAYLOAD_MODES.include?(mode) ? mode : nil
+      rescue StandardError
+        nil
+      end
+
+      # The loud-at-boot door (rule 10): an invalid INIT value is a
+      # programming error the engineer must catch on their machine.
+      # (The env clamp's invalid values warn + fall back instead — init.rb.)
+      def validate_capture_payloads!(value, context: "Foam::Otel.init")
+        mode = normalize_capture_payloads(value)
+        if mode.nil?
+          raise ArgumentError, "#{context} capture_payloads: must be one of " \
+                               "#{CAPTURE_PAYLOAD_MODES.map(&:inspect).join(', ')} " \
+                               "(equivalent strings accepted), got #{value.inspect}"
+        end
+        mode
+      end
+
       def downcase_list(list)
         Array(list).map { |k| k.to_s.downcase }.reject(&:empty?).uniq.freeze
       end
@@ -162,7 +207,12 @@ module Foam
           ignored_outbound_hosts: existing.ignored_outbound_hosts,
           diagnostics: diagnostics ? true : false,
           endpoint: existing.endpoint,
-          secret_heuristics: secret_heuristics == false ? false : true
+          secret_heuristics: secret_heuristics == false ? false : true,
+          # Like enabled/endpoint, capture_payloads is process-global after
+          # the first init: middleware insertion already happened (or
+          # deliberately did not — an :off boot shipped none), so a second
+          # init cannot meaningfully flip it. Carried forward unchanged.
+          capture_payloads: existing.capture_payloads
         ).freeze
       end
     end

data/lib/foam/otel/errors.rb

@@ -41,6 +41,18 @@ module Foam
         # exception" into a host-thread crash (rule 9).
         false
       end
+
+      # Read-only view of the registry above (the payload-capture :errors
+      # mode's thin seam, mandate 2026-07-28): true when at least one
+      # exception was recorded on this span via record_once. Reads the SAME
+      # span-carried ivar — never a second registry, never duplicated dedupe
+      # logic. Never raises (rule 9).
+      def recorded?(span)
+        seen = span.instance_variable_get(IVAR)
+        seen.is_a?(Array) && !seen.empty?
+      rescue StandardError
+        false
+      end
     end
   end
 end

data/lib/foam/otel/init.rb

@@ -19,6 +19,7 @@ require_relative "logger_bridge"
 require_relative "runtime_metrics"
 require_relative "llm"
 require_relative "header_capture" # default-on header capture (rule 32a module; wired below)
+require_relative "payload_capture" # opt-in body capture behind capture_payloads: (rule 32a module; wired below)
 
 module Foam
   module Otel
@@ -57,7 +58,8 @@ module Foam
                additional_metric_readers: nil,
                ignored_outbound_hosts: nil,
                diagnostics: false,
-               secret_heuristics: true)
+               secret_heuristics: true,
+               capture_payloads: :off)
         # Identity is validated at boot (rule 10): a blank required value is a
         # programming error the engineer must catch on their machine.
         validate_present!(:name, name)
@@ -88,7 +90,13 @@ module Foam
           redact_keys: redact_keys, redact_pii_keys: redact_pii_keys, redact: redact,
           ignored_outbound_hosts: ignored_outbound_hosts,
           diagnostics: diagnostics, endpoint: endpoint,
-          secret_heuristics: secret_heuristics
+          secret_heuristics: secret_heuristics,
+          # The payload-capture mode: the init option validated loudly (an
+          # invalid option raises inside resolve_config), with the
+          # FOAM_CAPTURE_PAYLOADS operator env clamp applied first (a valid
+          # env value overrides the option in BOTH directions; an invalid
+          # one warns + falls back — never a crashed boot).
+          capture_payloads: resolve_capture_payloads(capture_payloads)
         )
         # The heuristic-tier opt-out is an explicit, audited customer decision
         # (security-fixes-design §V.8) — always one loud line, never silent.
@@ -212,10 +220,38 @@ module Foam
         RuntimeMetrics.reset_for_tests!
         Redaction.reset_secret_scan_warnings!
         HeaderCapture.reset_for_tests!
+        PayloadCapture.reset_for_tests!
       end
 
       private
 
+      # The capture_payloads mode init hands to resolve_config: the INIT
+      # OPTION validated loudly first (rule 10 — garbage in code raises at
+      # boot even when an env clamp would override it), then the
+      # FOAM_CAPTURE_PAYLOADS operator env clamp applied on top. A VALID env
+      # value OVERRIDES the option in BOTH directions (the FDE valve: force
+      # payloads :off on a misbehaving deploy, or force :errors/:always on
+      # without a code change), with one loud line naming the override; an
+      # INVALID env value warns and falls back to the option — an env typo
+      # must never crash a boot (rule 9).
+      def resolve_capture_payloads(option)
+        mode = validate_capture_payloads!(option)
+        raw = ENV["FOAM_CAPTURE_PAYLOADS"]
+        return mode if raw.nil? || raw.strip.empty?
+
+        env_mode = normalize_capture_payloads(raw)
+        if env_mode.nil?
+          Diagnostics.warn("FOAM_CAPTURE_PAYLOADS=#{raw.inspect} is invalid — expected off|errors|always; " \
+                           "falling back to the init option (capture_payloads: :#{mode})")
+          return mode
+        end
+        if env_mode != mode
+          Diagnostics.warn("FOAM_CAPTURE_PAYLOADS=#{env_mode} overrides capture_payloads: :#{mode} " \
+                           "(operator env clamp)")
+        end
+        env_mode
+      end
+
       # Classifies the slot IMMEDIATELY before registering into it (the
       # narrowest pre-read→set window Ruby's non-atomic globals allow —
       # GOTCHAS F8), registers into a FREE slot, and warns once (honestly)
@@ -608,6 +644,20 @@ module Foam
           Diagnostics.warn("header capture: Faraday registration failed: #{e.class}: #{e.message}")
         end
 
+        begin
+          # Rails fallback wiring for the opt-in payload-capture middleware:
+          # covers apps whose Gemfile loads foam-otel BEFORE rails (no
+          # Railtie was defined at require time). Idempotent — the Railtie
+          # path, when it runs, shares the same one-insertion record. Gated
+          # on foam owning traces (rule 18 B — this branch), on the resolved
+          # mode not being :off (an :off config ships ZERO middleware), and
+          # per request on ownership + a recording span inside the
+          # middleware itself.
+          PayloadCapture.install_rails_middleware!
+        rescue StandardError => e
+          Diagnostics.warn("payload capture activation failed: #{e.class}: #{e.message}")
+        end
+
         begin
           LLM.activate!
         rescue StandardError => e

data/lib/foam/otel/payload_capture.rb

@@ -0,0 +1,655 @@
+# frozen_string_literal: true
+
+require "opentelemetry"
+
+require_relative "diagnostics"
+require_relative "errors"
+require_relative "redaction"
+
+module Foam
+  module Otel
+    # Opt-in HTTP network payload (BODY) capture behind ONE init option —
+    # `capture_payloads:` — DEFAULT OFF (payload-capture mandate 2026-07-28;
+    # rule 32a: one graduated addition, one module — init.rb and config.rb
+    # carry only thin wiring). Headers are NOT this module's job: they are
+    # captured upstream by the official rack gem's own header options
+    # (header_capture.rb) — this middleware tees BODIES only.
+    #
+    # The three modes (constants.rb-style frozen set lives on Config —
+    # Foam::Otel::CAPTURE_PAYLOAD_MODES; equivalent strings accepted):
+    #
+    #   * :off    — THE DEFAULT. Zero body teeing, zero per-request
+    #     allocation: init ships NO middleware at all (the Railtie and the
+    #     init fallback both stand down), and a manually-`use`d middleware is
+    #     a one-branch passthrough.
+    #   * :errors — bodies are TEED on every request, but attributes ATTACH
+    #     to the rack server span ONLY when the request ERRORED: an exception
+    #     raised through the middleware, an exception recorded on the span
+    #     (the Errors.record_once ivar registry — read through the thin
+    #     Errors.recorded? seam, never a second dedupe), or a response status
+    #     >= 500. A clean 2xx/4xx attaches NOTHING.
+    #   * :always — attach on every request.
+    #
+    # The operator env clamp FOAM_CAPTURE_PAYLOADS=off|errors|always
+    # OVERRIDES the init option in BOTH directions (resolved by init.rb —
+    # the FDE valve: force payloads off on a misbehaving deploy, or force
+    # them on without a code change); an invalid env value warns and falls
+    # back to the init option, never a crashed boot.
+    #
+    # What attaches (wire names, fleet parity with the js cores):
+    #
+    #   * http.request.body / http.response.body — TEXTUAL payloads only
+    #     (text/*, JSON/+json, urlencoded forms, XML/+xml, GraphQL; skipped
+    #     when Content-Encoding is not identity), capped at
+    #     MAX_CAPTURED_BODY_CHARS with the fleet truncation marker;
+    #   * http.request.body.size / http.response.body.size — TRUE byte sizes
+    #     when known (declared Content-Length, else bytes observed);
+    #     non-textual payloads contribute sizes alone.
+    #
+    # This middleware NEVER creates a span of its own — one producer per
+    # signal (rules 1/16): it writes to OpenTelemetry::Trace.current_span
+    # (the official rack gem's span, which surrounds this middleware) and
+    # no-ops entirely when that span is non-recording, when foam is
+    # uninitialized/disabled/killed, or when foam does not own the traces
+    # slot (rule 18 B — foam never enriches data flowing through a FOREIGN
+    # pipeline; a foreign SDK's rack span is theirs, untouched).
+    #
+    # Bodies are TEED, never consumed: the request tee observes exactly what
+    # the APP reads from env['rack.input'] (an app that never reads its body
+    # captures nothing — correct; Rack 3 non-rewindable inputs are never
+    # rewound or read ahead), and the response tee observes chunks in flight
+    # during #each without buffering the stream (Rack 3 to_ary/streaming-#call
+    # contracts honored — GOTCHAS F15). Every capture path is individually
+    # rescued (rule 9): recording can never break a request, alter a
+    # response, or swallow the app's own exception (identical re-raise).
+    #
+    # Redaction is NOT this module's job: every attribute lands BEFORE span
+    # finish, so the central exporter-boundary pass masks it — a JSON-shaped
+    # body string is DEEP-masked by field name there (redaction.rb
+    # BODY_ATTRIBUTE_NAMES: the credential floor + the customer's redact
+    # lists reach inside the JSON), urlencoded/free-text bodies ride the C1
+    # tokenizer + the value-pattern secret layer. Never a local key list
+    # here. scrub_utf8 at capture is encoding hygiene only (one invalid byte
+    # would drop the whole OTLP batch upstream — rule 15).
+    class PayloadCapture
+      # Bound on captured body text so a single span cannot balloon the
+      # batch — same name and value as the js/otel and browser caps.
+      MAX_CAPTURED_BODY_CHARS = 8192
+
+      # Appended when the captured text was cut at the cap (fleet parity).
+      TRUNCATION_MARKER = "…[truncated]"
+
+      # Worst-case UTF-8 is 4 bytes per character: buffering this many raw
+      # bytes always yields MAX_CAPTURED_BODY_CHARS characters when the
+      # payload has them, while the transient per-request buffer stays
+      # hard-bounded either way.
+      CAPTURE_BYTE_CAP = MAX_CAPTURED_BODY_CHARS * 4
+
+      # Textual payloads only (the fleet set): text/*, JSON (+json),
+      # urlencoded forms, XML (+xml), GraphQL. Everything else — and any
+      # non-identity content-encoding — contributes sizes alone.
+      TEXTUAL_MIME_TYPES = %w[
+        application/json
+        application/x-www-form-urlencoded
+        application/xml
+        application/graphql
+      ].freeze
+      TEXTUAL_MIME_SUFFIXES = %w[+json +xml].freeze
+
+      class << self
+        # The resolved capture mode: the active config's capture_payloads
+        # (init option, already clamped by FOAM_CAPTURE_PAYLOADS — init.rb).
+        # Anything unexpected degrades to :off, never a raise (rule 9).
+        def mode
+          config = Foam::Otel.active_config
+          value = config.respond_to?(:capture_payloads) ? config.capture_payloads : nil
+          CAPTURE_PAYLOAD_MODES.include?(value) ? value : :off
+        rescue StandardError
+          :off
+        end
+
+        def active?
+          mode != :off
+        end
+
+        # ---- zero-effort Rails wiring (idempotent, never boot-breaking) ----
+        # Mirrors the action_pack railtie's mechanism: the official rack
+        # middleware is inserted at position 0 (outermost) by that railtie's
+        # own before_initialize hook, so inserting foam AFTER index 0 places
+        # this middleware directly INSIDE the official span in every replay
+        # order (the middleware-op list is applied when the stack finalizes).
+        # Records at most one insertion per process.
+        def insert_into!(app)
+          return false if @inserted
+
+          @inserted = true
+          app.middleware.insert_after(0, self)
+          true
+        rescue StandardError => e
+          Diagnostics.warn("payload capture: Rails middleware insertion failed " \
+                           "(#{e.class}: #{e.message}) — body capture is OFF; " \
+                           "wire it manually with `use Foam::Otel::PayloadCapture` (README)")
+          false
+        end
+
+        # Shared by the Railtie hook and the init-time fallback below.
+        # Installs ONLY when the resolved mode captures at all — an :off
+        # config ships ZERO middleware, the cheapest possible default — and
+        # never after the stack finalized (inserting then would be a silent
+        # no-op, so foam stands down; manual `use` is the documented
+        # fallback). Ownership/recording are per-request gates in #call.
+        def install_into_app!(app)
+          return false unless active?
+          return false if app.nil?
+          return false if app.respond_to?(:initialized?) && app.initialized?
+
+          insert_into!(app)
+        rescue StandardError => e
+          Diagnostics.warn("payload capture: Rails wiring failed (#{e.class}: #{e.message})")
+          false
+        end
+
+        # init-time fallback for apps whose Gemfile loads foam-otel BEFORE
+        # rails (the Railtie at the bottom of this file never got defined
+        # because ::Rails::Railtie did not exist yet): as long as init runs
+        # before Rails.application.initialize! completes — the README recipe
+        # — the middleware op still lands before the stack is built.
+        def install_rails_middleware!
+          return false unless defined?(::Rails) && ::Rails.respond_to?(:application)
+
+          install_into_app!(::Rails.application)
+        rescue StandardError => e
+          Diagnostics.warn("payload capture: Rails wiring failed (#{e.class}: #{e.message})")
+          false
+        end
+
+        # Test hook (mirrors Foam::Otel.reset_for_tests!).
+        def reset_for_tests!
+          @inserted = false
+        end
+      end
+
+      def initialize(app)
+        @app = app
+      end
+
+      # Bracketed by the mode gate (an :off mode is a one-branch
+      # passthrough — zero per-request allocation) and the two capture gates
+      # (recording span + foam owns traces); past them, every capture step is
+      # individually rescued so the request NEVER breaks and the response is
+      # NEVER altered beyond the delegating body tee (rule 9).
+      def call(env)
+        mode = self.class.mode
+        return @app.call(env) if mode == :off
+
+        span = capturable_span
+        return @app.call(env) if span.nil?
+
+        acc = attach_input_tee(env)
+        begin
+          response = @app.call(env)
+        rescue Exception # rubocop:disable Lint/RescueException
+          # The app's error re-raises IDENTICALLY — and raising through the
+          # middleware IS the errored case, so BOTH attach modes flush the
+          # request side first: the official rack middleware ABOVE us records
+          # the exception and finishes the span only after this re-raise.
+          flush_request_capture(span, env, acc)
+          raise
+        end
+        # :errors — a clean request attaches NOTHING (the tee's transient
+        # accumulator is simply dropped); errored is: exception recorded on
+        # the span (the Errors.record_once ivar seam), or status >= 500.
+        return response if mode == :errors && !errored?(span, response)
+
+        flush_request_capture(span, env, acc)
+        capture_response(span, env, response)
+      end
+
+      private
+
+      # The official rack gem's span, and only when it is foam's OWN to
+      # enrich: a recording current span AND the traces slot still holding
+      # the provider foam registered (rule 18 B — pre-init, disabled, killed,
+      # foreign-owned and displaced-after-init all land here as nil).
+      def capturable_span
+        registered = Foam::Otel.instance_variable_get(:@foam_registered)
+        provider = registered && registered[:traces]
+        return nil if provider.nil? || !OpenTelemetry.tracer_provider.equal?(provider)
+
+        span = OpenTelemetry::Trace.current_span
+        span.respond_to?(:recording?) && span.recording? ? span : nil
+      rescue StandardError
+        nil
+      end
+
+      # The :errors attach predicate, decided when the middleware sees the
+      # triplet: an exception was recorded on the span (foam's record_once
+      # ivar registry, read through the thin Errors.recorded? seam — never a
+      # second dedupe here), or the response status is a server error.
+      def errored?(span, response)
+        return true if Errors.recorded?(span)
+
+        response.is_a?(Array) && response.length == 3 && response[0].to_i >= 500
+      rescue StandardError
+        false
+      end
+
+      # ---- request side ------------------------------------------------------
+
+      # Wrap env['rack.input'] in the delegating tee. NEVER reads ahead and
+      # never rewinds — it observes exactly the bytes the app itself pulls.
+      # A binary/compressed payload WITH a declared size has nothing left to
+      # learn, so the stream is not touched at all (sizes ride the declared
+      # Content-Length at flush).
+      def attach_input_tee(env)
+        input = env["rack.input"]
+        return nil if input.nil?
+
+        textual = textual_content_type?(env["CONTENT_TYPE"]) &&
+                  identity_encoding?(env["HTTP_CONTENT_ENCODING"])
+        return nil if !textual && content_length_from(env["CONTENT_LENGTH"])
+
+        acc = BodyAccumulator.new(capture_text: textual)
+        env["rack.input"] = InputTee.new(input, acc)
+        acc
+      rescue StandardError
+        nil
+      end
+
+      # After the app ran (or raised), on the attach path only: the captured
+      # text, plus the true size — the declared Content-Length when present,
+      # else the high-water byte count of what the app actually read.
+      def flush_request_capture(span, env, acc)
+        declared = content_length_from(env["CONTENT_LENGTH"])
+        size = declared
+        size = acc.bytes if size.nil? && acc && acc.saw_data?
+        set_attr(span, "http.request.body.size", size) unless size.nil? || size.zero?
+        return if acc.nil? || !acc.saw_data?
+
+        text = acc.snapshot
+        set_attr(span, "http.request.body", text) if text
+      rescue StandardError
+        nil
+      end
+
+      # ---- response side -----------------------------------------------------
+
+      # Only a well-formed [status, headers, body] triplet is touched; any
+      # other shape (or any internal failure) returns the app's response
+      # VERBATIM (rule 9: never alter the response). A BODILESS exchange —
+      # a HEAD request (Rack::Head strips the body but keeps the entity's
+      # Content-Length), a 204, a 304, a 1xx — attaches NO response body
+      # attributes at all: a declared Content-Length there describes an
+      # entity that is NOT on the wire, and capturing it would fabricate a
+      # body the response never had.
+      def capture_response(span, env, response)
+        return response unless response.is_a?(Array) && response.length == 3
+
+        status, headers, body = response
+        return response if bodiless?(env, status)
+
+        [status, headers, capture_response_body(span, headers, body)]
+      rescue StandardError
+        response
+      end
+
+      def bodiless?(env, status)
+        return true if env.is_a?(Hash) && env["REQUEST_METHOD"].to_s.upcase == "HEAD"
+
+        code = status.to_i
+        code == 204 || code == 304 || (code >= 100 && code < 200)
+      rescue StandardError
+        false
+      end
+
+      # Body strategy, in Rack-3 contract order (GOTCHAS F15):
+      #   * to_ary-able (buffered) bodies are captured SYNCHRONOUSLY — the
+      #     span is provably alive in both official middleware modes — and
+      #     the array is returned as the new body (BodyProxy#to_ary closes
+      #     the original per the Rack spec);
+      #   * streaming #call-only bodies (Rack 3 hijack-style) are NEVER
+      #     wrapped — defining #each on them would change how the server
+      #     drives the response;
+      #   * everything else is teed chunk-by-chunk during #each, unbuffered,
+      #     with the attributes flushed when iteration completes or on close.
+      def capture_response_body(span, headers, body)
+        declared = content_length_from(header_value(headers, "content-length"))
+        # Zero-guard parity with the request side: an empty body never
+        # contributes a size-0 attribute.
+        set_attr(span, "http.response.body.size", declared) if declared&.positive?
+        textual = textual_content_type?(header_value(headers, "content-type")) &&
+                  identity_encoding?(header_value(headers, "content-encoding"))
+
+        return capture_buffered_body(span, body, textual, declared) if body.respond_to?(:to_ary)
+        return body unless body.respond_to?(:each)
+        return body if !textual && declared # nothing left to learn — leave it alone
+
+        acc = BodyAccumulator.new(capture_text: textual)
+        BodyTee.new(body, acc) do |completed|
+          flush_response_body(span, acc, declared, completed)
+        end
+      rescue StandardError
+        body
+      end
+
+      def capture_buffered_body(span, body, textual, declared)
+        parts = body.to_ary # the full body; a BodyProxy's to_ary also closes it (Rack spec)
+        return body unless parts.is_a?(Array)
+
+        if textual || !declared
+          acc = BodyAccumulator.new(capture_text: textual)
+          parts.each { |chunk| acc.observe(chunk) }
+          flush_response_body(span, acc, declared, true)
+        end
+        parts
+      rescue StandardError
+        body
+      end
+
+      # `completed` guards the size: a stream closed mid-flight has an
+      # UNKNOWN true size (the declared Content-Length, when present, was
+      # already set up front). set_attr's recording? gate makes this a silent
+      # no-op when the span already ended (the TracerMiddleware streaming
+      # divergence — GOTCHAS F15).
+      def flush_response_body(span, acc, declared, completed)
+        return unless acc.saw_data?
+
+        text = acc.snapshot
+        set_attr(span, "http.response.body", text) if text
+        set_attr(span, "http.response.body.size", acc.bytes) if !declared && completed
+      rescue StandardError
+        nil
+      end
+
+      # ---- shared helpers ------------------------------------------------------
+
+      def set_attr(span, key, value)
+        return if value.nil?
+
+        span.set_attribute(key, value) if span.respond_to?(:recording?) && span.recording?
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      def header_value(headers, want)
+        return nil unless headers.respond_to?(:each)
+
+        headers.each do |key, value|
+          next unless key.to_s.downcase == want
+
+          return value.is_a?(Array) ? value.first : value
+        end
+        nil
+      rescue StandardError
+        nil
+      end
+
+      def content_length_from(raw)
+        return nil if raw.nil?
+
+        parsed = Integer(raw.to_s, 10)
+        parsed >= 0 ? parsed : nil
+      rescue StandardError
+        nil
+      end
+
+      def textual_content_type?(raw)
+        return false if raw.nil?
+
+        mime = raw.to_s.split(";").first.to_s.strip.downcase
+        return false if mime.empty?
+        return true if mime.start_with?("text/")
+        return true if TEXTUAL_MIME_TYPES.include?(mime)
+
+        TEXTUAL_MIME_SUFFIXES.any? { |suffix| mime.end_with?(suffix) }
+      rescue StandardError
+        false
+      end
+
+      def identity_encoding?(raw)
+        return true if raw.nil?
+
+        encoding = raw.to_s.strip.downcase
+        encoding.empty? || encoding == "identity"
+      rescue StandardError
+        false
+      end
+
+      # Bounded, defensive accumulation shared by both directions. Tracks a
+      # stream POSITION and a HIGH-WATER mark so a reposition + re-read (the
+      # Rack::MethodOverride shape: an outer middleware reads the form body,
+      # rewinds, and the framework re-reads it) never double-captures or
+      # double-counts — only bytes beyond the high-water mark are new. The
+      # raw buffer is binary and hard-capped; text is scrubbed to valid
+      # UTF-8 and cap-cut only at snapshot time.
+      class BodyAccumulator
+        def initialize(capture_text:)
+          @buffer = capture_text ? String.new(encoding: Encoding::BINARY) : nil
+          @pos = 0
+          @high_water = 0
+        end
+
+        def observe(chunk)
+          return unless chunk.is_a?(String)
+
+          size = chunk.bytesize
+          return if size.zero?
+
+          new_pos = @pos + size
+          if new_pos > @high_water
+            # Never more than the chunk itself: a forward seek past the
+            # high-water mark makes the positional gap look "fresh", but the
+            # skipped bytes were never observed — only the chunk's own tail
+            # is appendable (the high-water mark still advances to the true
+            # stream position, so re-reads after it stay deduped).
+            fresh = [new_pos - @high_water, size].min
+            append(chunk.byteslice(size - fresh, fresh))
+            @high_water = new_pos
+          end
+          @pos = new_pos
+          nil
+        rescue StandardError, SystemStackError
+          nil
+        end
+
+        # A reposition on the underlying stream (rewind / seek / pos=): track
+        # the new position so a re-read never double-captures or
+        # double-counts. Anything non-sensical degrades to 0 — the
+        # rewind-equivalent — which can only UNDER-position (bytes below the
+        # high-water mark are never appended twice; rule 9 direction).
+        def note_position(new_pos)
+          @pos = new_pos.is_a?(Integer) && new_pos >= 0 ? new_pos : 0
+        end
+
+        def saw_data?
+          @high_water.positive?
+        end
+
+        # The true byte count observed (the high-water mark: rewound
+        # re-reads never inflate it).
+        def bytes
+          @high_water
+        end
+
+        # The captured text — scrubbed to valid UTF-8, cut at
+        # MAX_CAPTURED_BODY_CHARS with the fleet truncation marker — or nil
+        # when text capture is off or nothing was seen.
+        def snapshot
+          return nil if @buffer.nil? || !saw_data?
+
+          text = Redaction.scrub_utf8(@buffer.dup)
+          return nil unless text.is_a?(String) && !text.empty?
+
+          if text.length > MAX_CAPTURED_BODY_CHARS
+            text[0, MAX_CAPTURED_BODY_CHARS] + TRUNCATION_MARKER
+          elsif @high_water > @buffer.bytesize
+            text + TRUNCATION_MARKER # bytes beyond the buffer cap were observed
+          else
+            text
+          end
+        rescue StandardError, SystemStackError
+          nil
+        end
+
+        private
+
+        def append(fresh)
+          return if @buffer.nil? || fresh.nil?
+
+          remaining = CAPTURE_BYTE_CAP - @buffer.bytesize
+          return if remaining <= 0
+
+          @buffer << fresh.b[0, remaining].to_s
+          nil
+        end
+      end
+
+      # The delegating rack.input tee: observes what the APP reads through
+      # the three Rack-SPEC input methods, delegates EVERYTHING else
+      # untouched (rewind/size/close/read_nonblock… exist exactly iff the
+      # underlying input has them — respond_to? stays truthful, so a Rack 3
+      # non-rewindable input still reports itself non-rewindable). Never
+      # reads ahead, never rewinds on its own.
+      class InputTee
+        # EVERY repositioning method is tracked for the re-read dedupe — a
+        # middleware that repositions via seek(0) or pos= 0 instead of
+        # rewind (all three are common Rack::MethodOverride-shape idioms on
+        # the rewindable inputs real servers hand out) must not make the
+        # framework's re-read double-capture the body.
+        REPOSITION_METHODS = %i[rewind seek pos=].freeze
+
+        def initialize(io, acc)
+          @io = io
+          @acc = acc
+        end
+
+        def read(*args)
+          result = @io.read(*args)
+          @acc.observe(result)
+          result
+        end
+
+        def gets(*args)
+          line = @io.gets(*args)
+          @acc.observe(line)
+          line
+        end
+
+        def each(*args, &block)
+          return enum_for(:each, *args) unless block
+
+          @io.each(*args) do |chunk|
+            @acc.observe(chunk)
+            yield chunk
+          end
+        end
+
+        def method_missing(name, *args, **kwargs, &block)
+          result = @io.__send__(name, *args, **kwargs, &block)
+          @acc.note_position(position_after(name, args)) if REPOSITION_METHODS.include?(name)
+          result
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @io.respond_to?(name, include_private)
+        end
+
+        private
+
+        # The stream position after a successful rewind/seek/pos= — the
+        # underlying IO's own #pos wherever it exists (every rewindable
+        # input real servers hand out — StringIO, Tempfile — has it), else
+        # the absolute target when the call spelled one out, else 0 (the
+        # rewind-equivalent: under-positioning can only ever SKIP capture of
+        # already-seen bytes, never duplicate them).
+        def position_after(name, args)
+          return 0 if name == :rewind
+
+          pos = (@io.pos if @io.respond_to?(:pos))
+          return pos if pos.is_a?(Integer)
+
+          target = args[0]
+          return target if target.is_a?(Integer) && (name == :pos= || absolute_seek?(args))
+
+          0
+        rescue StandardError
+          0
+        end
+
+        def absolute_seek?(args)
+          whence = args[1]
+          whence.nil? || whence == IO::SEEK_SET || whence == :SET
+        end
+      end
+
+      # The delegating response-body tee: observes chunks in flight during
+      # #each (never buffering the stream), preserves #close (flushing the
+      # attributes exactly once — on iteration completion or on close,
+      # whichever comes first), and delegates everything else (to_path for
+      # sendfile servers) with truthful respond_to?.
+      class BodyTee
+        def initialize(body, acc, &on_done)
+          @body = body
+          @acc = acc
+          @on_done = on_done
+          @flushed = false
+        end
+
+        def each(*args, &block)
+          return enum_for(:each, *args) unless block
+
+          @body.each(*args) do |chunk|
+            @acc.observe(chunk)
+            yield chunk
+          end
+          finish!(true)
+        end
+
+        def close
+          @body.close if @body.respond_to?(:close)
+        ensure
+          finish!(false)
+        end
+
+        def method_missing(name, ...)
+          @body.__send__(name, ...)
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @body.respond_to?(name, include_private)
+        end
+
+        private
+
+        def finish!(completed)
+          return if @flushed
+
+          @flushed = true
+          @on_done.call(completed)
+          nil
+        rescue StandardError, SystemStackError
+          nil
+        end
+      end
+    end
+
+    if defined?(::Rails::Railtie)
+      # The zero-effort Rails path, defined only when Rails loaded first (the
+      # standard Gemfile order). Unlike the action_pack railtie's
+      # before_initialize (which runs before config/initializers — before
+      # Foam::Otel.init has resolved the capture mode), this hook runs AFTER
+      # :load_config_initializers, when the mode is known, and still before
+      # the middleware stack finalizes — so an :off config really ships ZERO
+      # middleware. When foam-otel loads first (no Railtie), init()'s
+      # install_rails_middleware! fallback covers apps that init before
+      # Rails.application.initialize! completes (README recipe), and
+      # plain-Rack apps `use Foam::Otel::PayloadCapture` manually.
+      class PayloadCaptureRailtie < ::Rails::Railtie
+        initializer "foam_otel.payload_capture", after: :load_config_initializers do |app|
+          Foam::Otel::PayloadCapture.install_into_app!(app)
+        end
+      end
+    end
+  end
+end

data/lib/foam/otel/redaction.rb

@@ -641,8 +641,66 @@ module Foam
         when :floor then floor_mask(floor_kind(key), value)
         when :erase then REDACTED
         when :mask  then masked_value_for(value, config, value_scan)
-        else descend(value, config, 0, value_scan: value_scan)
+        else
+          # The two payload-capture BODY attributes carry customer FIELD
+          # NAMES inside a JSON string — the key passes must reach them
+          # (deep-redaction below), not scan them as free text.
+          if value.is_a?(String) && body_attribute?(key)
+            mask_body_attribute(value, config, value_scan)
+          else
+            descend(value, config, 0, value_scan: value_scan)
+          end
+        end
+      end
+
+      # ---- payload-capture body attributes (mandate 2026-07-28) -------------
+      # The two value-bearing BODY names payload_capture.rb emits. A
+      # JSON-shaped string under one of these names is parsed and DEEP-masked
+      # as STRUCTURE — the credential floor and the customer's
+      # redact_keys/redact_pii_keys reach the field names inside the body
+      # exactly as they reach any nested attribute ({"password": …} masks) —
+      # then re-serialized. When nothing masks, the ORIGINAL string rides
+      # through byte-identical (raw capture stands). Non-JSON bodies — and
+      # cap-TRUNCATED JSON, which no longer parses (documented limit, GOTCHAS
+      # F15) — fall back to the central leaf-string pass: urlencoded form
+      # bodies get their k=v pairs name-matched by the C1 tokenizer, and the
+      # value-pattern secret layer scans everything. Fail CLOSED: a body that
+      # parsed but cannot be re-serialized is [REDACTED], never half-masked.
+      BODY_ATTRIBUTE_NAMES = %w[http.request.body http.response.body].freeze
+
+      # EXACT match, deliberately not canon(): the only emitters spell these
+      # names verbatim (payload_capture.rb; the js cores use the same exact
+      # strings), and this predicate runs for every unmatched string
+      # attribute on the hot export path — a canon() here would allocate per
+      # attribute for nothing.
+      def body_attribute?(name)
+        BODY_ATTRIBUTE_NAMES.include?(name)
+      end
+
+      def mask_body_attribute(text, config, value_scan = true)
+        if text.lstrip.start_with?("{", "[")
+          parsed = parse_json_body(text)
+          unless parsed.nil?
+            masked = deep_mask(parsed, config, 0, value_scan: value_scan)
+            return text if masked == parsed # nothing masked: byte-identical raw capture
+
+            begin
+              return JSON.generate(masked)
+            rescue StandardError, SystemStackError
+              return REDACTED # fail closed once the structural pass committed
+            end
+          end
         end
+        value_scan ? redact_leaf_string(text, config) : text
+      rescue StandardError, SystemStackError
+        REDACTED
+      end
+
+      def parse_json_body(text)
+        parsed = JSON.parse(text)
+        parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : nil
+      rescue StandardError
+        nil
       end
 
       # A redact_keys match: the value-pattern scan runs FIRST (design §V.0 —

data/lib/foam/otel/version.rb

@@ -83,6 +83,32 @@ module Foam
     #   scope (their official instrumentations expose no hook —
     #   OTel-fundamentals ruling). Bodies are NOT captured (that is the
     #   separate capture_payloads pass).
-    VERSION = "1.6.0"
+    # 1.7.0: OPT-IN HTTP BODY CAPTURE — `capture_payloads:` (2026-07-28
+    #   payload-capture mandate; MINOR — one additive init option, default
+    #   OFF, zero default-path behavior change). New rule-32a module
+    #   PayloadCapture: a Rack middleware teeing BODIES ONLY (headers stayed
+    #   the 1.6.0 official-rack-options seam) onto the official rack SERVER
+    #   span. Modes: :off (DEFAULT — zero teeing, zero per-request
+    #   allocation, NO middleware shipped) | :errors (tee per-request, attach
+    #   ONLY on exception-recorded-on-span or status >= 500; clean 2xx/4xx
+    #   attach nothing) | :always; equivalent strings accepted; invalid init
+    #   value raises at boot. FOAM_CAPTURE_PAYLOADS=off|errors|always is the
+    #   operator env clamp overriding the option in both directions (invalid
+    #   env warns + falls back, never crashes). Wire: http.request.body /
+    #   http.response.body capped at 8192 chars + "…[truncated]", textual
+    #   content-types only, identity encoding only, plus true
+    #   http.{request,response}.body.size (declared Content-Length, else
+    #   observed bytes; non-textual payloads sizes-only; HEAD/204/304 and
+    #   other bodiless responses attach NO response-body attributes).
+    #   Stream-safe: delegating tees only (never read ahead of the app on
+    #   the rack input stream, re-reads after rewind/seek/pos= deduped,
+    #   streaming #each bodies teed unbuffered with close preserved, Rack 3
+    #   #call-only bodies never wrapped). Redaction
+    #   stays central at the exporter boundary — JSON-shaped body strings
+    #   under the body names are now DEEP-masked by field name (floor +
+    #   customer redact lists reach inside the body JSON). Rails auto-wiring
+    #   (Railtie + init fallback) inserts the middleware ONLY when the mode
+    #   is not :off; plain Rack adds one `use` line.
+    VERSION = "1.7.0"
   end
 end

data/lib/foam/otel.rb

@@ -15,9 +15,11 @@
 # allowed_response_headers options, pre-installed by foam with a documented
 # DEFAULT LIST (a named enumeration, NOT all headers — the honest divergence
 # from js/python; header_capture.rb), outbound via foam's Faraday middleware
-# on the official client span — and nothing else: no stamping, no
-# request-INPUT (body) capture, no request-id enrichment (removed per the
-# spec; stamps are the collector's job server-side).
+# on the official client span — and OPT-IN HTTP body capture behind the ONE
+# `capture_payloads:` init option (default :off — zero teeing, zero
+# middleware; payload_capture.rb) — and nothing else: no stamping, no
+# request-id enrichment (removed per the spec; stamps are the collector's
+# job server-side).
 
 require_relative "otel/version"
 require_relative "otel/constants"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Foam
@@ -396,6 +396,7 @@ files:
 - lib/foam/otel/llm/ruby_llm_shim.rb
 - lib/foam/otel/logger_bridge.rb
 - lib/foam/otel/metrics.rb
+- lib/foam/otel/payload_capture.rb
 - lib/foam/otel/pipelines.rb
 - lib/foam/otel/redacting_exporter.rb
 - lib/foam/otel/redaction.rb