fiber_stream 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6ac2f9ec0d6888789ac2535538124b9057895b52e226d812d002e5d2955d437
-  data.tar.gz: df4722fff9e5020b24e7e23d2d4cc98ea98aa54a3f17dd86ff0825f41f007de4
+  metadata.gz: 1cc93666d0610e659313a12dc756fca935579e62711972a9ea65d9ad818f6020
+  data.tar.gz: 97f315765ba573a5c047752fd083006db89404eff06e92bda5afbfa0f1933ed1
 SHA512:
-  metadata.gz: 11389c5aaf69a315a9a932ddd06488eb7fe81b72ca265ecf2e45e7d96b4d984a67c2eee49b38dbde267ce35b4e5dfe7dff4d2e61a32330d5e09153058ad2fb22
-  data.tar.gz: e231b92f6c0ddb08aae7e0db1791b17325705705a76ace92b197d626954ae72dd1510359c5ea8f0c5cff19985f01b78cc4e62179699d244afa4d988ed4da9d51
+  metadata.gz: 5e635531f9e34510ef0eab76254c33e70f36124be779f48d2f9692c351a2f26ed36c7c14fa0d1d596c5645b511bb4fa1abe2bb773fc434c1f4da39a6e19dbefc
+  data.tar.gz: 67eb50ae0a1d727c65fd172be572f7bf08ba82b3ee0cf4d9094c7e9ad579aac327155cc772bcd4e94b778cef53f63decf64a08e12e7ea5ef6949a6d813336b04

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.4.0 - 2026-06-09
+
+### Added
+
+- `Flow.parallel_unordered_map(concurrency:)` and
+  `Source#parallel_unordered_map(concurrency:)` for scheduler-backed mapping
+  that emits results in completion order instead of preserving input order.
+- `Source.ractor_producer` for FiberStream-owned single producer Ractors with
+  one-outstanding-ack backpressure and cooperative cleanup.
+- `Source.ractor_merge_producers` for ready-order fan-in from multiple
+  FiberStream-owned producer Ractors without requiring a `Fiber.scheduler`.
+- `Flow.scan(initial)` and `Source#scan(initial)` for lazy running
+  accumulators using `Sink.fold`-style reducer semantics.
+
+### Changed
+
+- Updated README and website reference coverage for owned Ractor producers,
+  unordered parallel mapping, and scan.
+- Prefer high-level owned Ractor producer examples in user-facing
+  documentation while keeping low-level port APIs documented for externally
+  owned producers.
+- Updated the project Ruby pin to 4.0.5.
+
+## 0.3.0 - 2026-06-06
+
+### Added
+
+- `Flow.grouped(count)` and `Source#grouped(count)` for fixed-size batches
+  with final partial-group emission.
+- `Source#merge(source)` for scheduler-backed ready-order merging of two
+  sources while preserving each input source's own order.
+- `Source.ractor_merge_ports(ports)` for backpressure-aware merging of
+  multiple producer Ractor ports without requiring a `Fiber.scheduler`.
+- `Flow.split(separator)` and `Source#split(separator)` for delimiter-based
+  framing with optional separator retention and per-frame length limits.
+- Benchmarks and examples for async IO fanout, stream lifecycle probes, and
+  Ractor port merge workflows.
+
+### Changed
+
+- Reworked flow operator tests into focused per-operator test files.
+- Expanded README and repository documentation for source merging, Ractor port
+  merging, split framing, grouped batches, and runtime safety guidance.
+- Clarified that `Flow.lines(max_length: nil)` and
+  `Flow.split(max_length: nil)` may buffer one unterminated frame without
+  bound, and documented explicit `max_length` usage for untrusted streams.
+- Clarified `Source.io` `chunk_size` allocation behavior and Ractor failure
+  metadata exposure.
+
+### Fixed
+
+- Deferred `Source#concat` receiver materialization until downstream demand
+  reaches the concatenated source.
+- Cancelled async and buffer producers when downstream closes early.
+- Removed polling from Ractor map enqueue and cleanup paths.
+- Re-raised background pipeline process-control exceptions instead of treating
+  them as ordinary stream failures.
+- Hardened Ractor map worker teardown notifications so secondary send failures
+  do not cascade during shutdown.
+
 ## 0.2.0 - 2026-06-05
 
 ### Added

data/README.md

@@ -1,12 +1,12 @@
 # FiberStream
+ FiberStream is a Ruby library for linear stream processing with pull-based backpressure. 
 
-FiberStream is an early-stage Ruby library for linear, pull-based stream
-processing with backpressure.
+It builds lazy Source definitions, transforms values with Flow stages, and materializes results with Sink objects.
 
-Build a lazy `Source`, transform it with `Flow` stages, and materialize it with
-a `Sink`.
+[![Gem Version](https://badge.fury.io/rb/fiber_stream.svg)](https://badge.fury.io/rb/fiber_stream)
 
 ## Quick Start
+Please see the project [documentation](https://dakatsuka.github.io/fiber_stream/) for more details.
 
 ```ruby
 require "fiber_stream"
@@ -27,11 +27,13 @@ FiberStream currently supports linear pipelines only.
 
 Implemented capabilities:
 
-- in-memory, IO, and backpressure-aware Ractor port sources
-- lazy source concatenation and zipping
+- in-memory, IO, FiberStream-owned Ractor producer, backpressure-aware Ractor
+  port, and Ractor port merge sources
+- lazy source concatenation, zipping, and scheduler-backed merging
 - mapping, filtering, limiting, predicate-based limiting and dropping,
-  fixed-prefix dropping, line splitting, buffering, async boundaries, ordered
-  parallel mapping, and ordered Ractor-backed mapping
+  fixed-prefix dropping, fixed-size grouping, line splitting, buffering, async
+  boundaries, ordered and unordered parallel mapping, and ordered
+  Ractor-backed mapping
 - array, first-element, fold, foreach, and IO sinks
 - reusable flow composition and runnable pipelines
 - foreground and scheduler-backed background pipeline execution
@@ -78,7 +80,10 @@ result # => [[1, "a"], [2, "b"]]
 ```
 
 IO sources read chunks on demand and require a scheduler-backed non-blocking
-fiber:
+fiber. The `chunk_size` option is the maximum byte count passed to
+`readpartial` for one downstream pull; very large values may cause the IO
+implementation to attempt large allocations, so choose a bounded value
+appropriate for the workload:
 
 ```ruby
 require "async"
@@ -93,45 +98,51 @@ chunks =
   end.wait
 ```
 
-Ractor port sources connect a producer Ractor with an explicit ack handshake.
-The producer creates its acknowledgment port, waits for `RactorPort::Ack`, and
-then sends one typed message back to the FiberStream data port:
+Owned Ractor producer sources run producer blocks in FiberStream-managed
+Ractors. The producer block receives a `RactorProducer` context and emits one
+value per downstream demand:
 
 ```ruby
-data_port = Ractor::Port.new
-setup_port = Ractor::Port.new
-
-producer =
-  Ractor.new(data_port, setup_port) do |outbox, setup|
-    ack_port = Ractor::Port.new
-    setup.send(ack_port)
-
-    values = [1, 2, 3].to_enum
-
-    loop do
-      case ack_port.receive
-      in FiberStream::RactorPort::Ack
-        begin
-          outbox.send(FiberStream::RactorPort::Element.new(values.next))
-        rescue StopIteration
-          outbox.send(FiberStream::RactorPort::Complete.new)
-          break
-        end
-      in FiberStream::RactorPort::Cancel
-        break
-      end
+PRODUCE_VALUES =
+  Ractor.shareable_proc do |producer, values|
+    values.each do |value|
+      break unless producer.emit(value)
     end
   end
 
-ack_port = setup_port.receive
-
-FiberStream::Source.ractor_port(data_port, ack_port: ack_port)
+FiberStream::Source.ractor_producer([1, 2, 3], &PRODUCE_VALUES)
   .run_with(FiberStream::Sink.to_a)
 # => [1, 2, 3]
+```
+
+Multiple owned producer Ractors can be merged directly without a
+scheduler-backed `Source#merge`. Each producer still receives at most one
+outstanding ack:
+
+```ruby
+PRODUCE_TAGGED_VALUES =
+  Ractor.shareable_proc do |producer, tag, values|
+    values.each do |value|
+      break unless producer.emit([tag, value])
+    end
+  end
 
-producer.value
+source =
+  FiberStream::Source.ractor_merge_producers do |group|
+    group.producer(:a, [1, 2], &PRODUCE_TAGGED_VALUES)
+    group.producer(:b, [3, 4], &PRODUCE_TAGGED_VALUES)
+  end
+
+source.run_with(FiberStream::Sink.to_a)
+# Example result: [[:a, 1], [:b, 3], [:a, 2], [:b, 4]]
 ```
 
+Use the lower-level `Source.ractor_port` and `Source.ractor_merge_ports` APIs
+when producer Ractors are owned outside FiberStream or need custom lifecycle
+handling. `RactorPort::Failure` cause metadata is producer-provided and is
+surfaced on `RactorPortSourceError`; redact sensitive details before sending
+failures across trust boundaries.
+
 Streaming HTTP response bodies that implement `#each`, such as
 `async-http` response bodies, can be used with `Source.each` without buffering
 the full body first. Use the HTTP client's block form or an explicit `ensure`
@@ -194,6 +205,50 @@ FiberStream::Source.each([" a ", "", " b "])
 # => ["a", "b"]
 ```
 
+Use `parallel_map` for ordered scheduler-backed mapping when each element
+waits on non-blocking IO. It preserves input order while allowing up to
+`concurrency` mapping operations to be in flight:
+
+```ruby
+require "async"
+require "fiber_stream"
+
+def fetch_profile(user_id)
+  # Example: perform scheduler-aware HTTP, database, or socket IO here.
+  sleep 0.05
+  { id: user_id, name: "user-#{user_id}" }
+end
+
+profiles =
+  Sync do
+    FiberStream::Source.each([1, 2, 3, 4])
+      .parallel_map(concurrency: 4) { |user_id| fetch_profile(user_id) }
+      .run_with(FiberStream::Sink.to_a)
+  end
+
+profiles.map { |profile| profile.fetch(:id) } # => [1, 2, 3, 4]
+```
+
+Use `parallel_unordered_map` when every result can be handled independently
+and lower head-of-line blocking matters more than input order. It still limits
+in-flight mapping work to `concurrency`, but emits values as mapping jobs
+finish:
+
+```ruby
+require "async"
+require "fiber_stream"
+
+responses =
+  Sync do
+    FiberStream::Source.each(["/a", "/slow", "/b"])
+      .parallel_unordered_map(concurrency: 3) { |path| fetch_path(path) }
+      .run_with(FiberStream::Sink.to_a)
+  end
+
+# Results are in completion order, not necessarily input order.
+responses
+```
+
 Use `ractor_map` for ordered CPU-bound mapping in Ractor workers. The mapper
 must be shareable, usually by creating it with `Ractor.shareable_proc`.
 
@@ -326,6 +381,29 @@ tail =
 tail # => [3, 4]
 ```
 
+`Flow.grouped` batches adjacent elements into arrays and emits the final
+partial group:
+
+```ruby
+batches =
+  FiberStream::Source.each([1, 2, 3, 4, 5])
+    .grouped(2)
+    .run_with(FiberStream::Sink.to_a)
+
+batches # => [[1, 2], [3, 4], [5]]
+```
+
+`Flow.scan` emits the updated accumulator for each upstream element:
+
+```ruby
+running_totals =
+  FiberStream::Source.each([1, 2, 3, 4])
+    .scan(0) { |sum, number| sum + number }
+    .run_with(FiberStream::Sink.to_a)
+
+running_totals # => [1, 3, 6, 10]
+```
+
 `Flow.take_while` emits the leading prefix while a predicate is truthy, then
 closes upstream at the first false or nil result:
 
@@ -376,11 +454,31 @@ first =
 first # => [1, 2]
 ```
 
+`Source#merge` emits values from either input source in scheduler-observed
+ready order while preserving each input's own order:
+
+```ruby
+merged =
+  Sync do
+    FiberStream::Source.each([1, 2])
+      .merge(FiberStream::Source.each(["a", "b"]))
+      .run_with(FiberStream::Sink.to_a)
+  end
+
+# Example result: [1, "a", 2, "b"]
+```
+
+`merge` does not make scheduler-unaware blocking source work non-blocking and
+does not provide CPU parallelism. Use producer ractors with
+`Source.ractor_producer` or `Source.ractor_merge_producers` when producer work
+needs true isolation.
+
 `Flow.buffer(count)` allows bounded prefetch. `Flow.async`, `Flow.buffer`,
-`Flow.parallel_map`, `Source.io`, `Sink.io`, and `Pipeline#run_async` require an
-installed `Fiber.scheduler` and a non-blocking current fiber when demanded or
-started. FiberStream does not install a scheduler and does not depend on Async
-at runtime.
+`Flow.parallel_map`, `Flow.parallel_unordered_map`, `Source.io`,
+`Source#merge`, `Sink.io`, and `Pipeline#run_async` require an installed
+`Fiber.scheduler` and a non-blocking current fiber when demanded or started.
+FiberStream does not install a scheduler and does not depend on Async at
+runtime.
 
 ## API Surface
 
@@ -388,24 +486,32 @@ Sources:
 
 - `FiberStream::Source.each(enumerable)`
 - `FiberStream::Source.io(io, chunk_size: 16 * 1024, close: false)`
+- `FiberStream::Source.ractor_producer(*args, transfer: :copy, ack_transfer: :copy) { |producer, *args| ... }`
+- `FiberStream::Source.ractor_merge_producers(transfer: :copy, ack_transfer: :copy) { |group| ... }`
 - `FiberStream::Source.ractor_port(port, ack_port:, ack_transfer: :copy, cancel: true)`
+- `FiberStream::Source.ractor_merge_ports(ports, ack_transfer: :copy, cancel: true)`
 
 Source convenience methods:
 
 - `Source#via(flow)`
 - `Source#concat(source)`
 - `Source#zip(source)`
+- `Source#merge(source)`
 - `Source#map { |element| ... }`
 - `Source#parallel_map(concurrency:) { |element| ... }`
+- `Source#parallel_unordered_map(concurrency:) { |element| ... }`
 - `Source#ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `Source#select { |element| ... }`
 - `Source#take(count)`
 - `Source#drop(count)`
+- `Source#grouped(count)`
+- `Source#scan(initial) { |accumulator, element| ... }`
 - `Source#take_while { |element| ... }`
 - `Source#drop_while { |element| ... }`
 - `Source#async`
 - `Source#buffer(count)`
 - `Source#lines(chomp: true, max_length: nil)`
+- `Source#split(separator, keep_separator: false, max_length: nil)`
 - `Source#to(sink)`
 - `Source#run_with(sink)`
 
@@ -413,18 +519,26 @@ Flows:
 
 - `FiberStream::Flow.map { |element| ... }`
 - `FiberStream::Flow.parallel_map(concurrency:) { |element| ... }`
+- `FiberStream::Flow.parallel_unordered_map(concurrency:) { |element| ... }`
 - `FiberStream::Flow.ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `FiberStream::Flow.select { |element| ... }`
 - `FiberStream::Flow.take(count)`
 - `FiberStream::Flow.drop(count)`
+- `FiberStream::Flow.grouped(count)`
+- `FiberStream::Flow.scan(initial) { |accumulator, element| ... }`
 - `FiberStream::Flow.take_while { |element| ... }`
 - `FiberStream::Flow.drop_while { |element| ... }`
 - `FiberStream::Flow.async`
 - `FiberStream::Flow.buffer(count)`
 - `FiberStream::Flow.lines(chomp: true, max_length: nil)`
+- `FiberStream::Flow.split(separator, keep_separator: false, max_length: nil)`
 - `Flow#via(flow)`
 - `Flow#to(sink)`
 
+`lines` and `split` default to `max_length: nil`, which allows one
+unterminated line or frame to buffer without bound. Set a positive
+`max_length` for untrusted, network-facing, or otherwise unbounded inputs.
+
 Sinks:
 
 - `FiberStream::Sink.to_a`
@@ -454,7 +568,9 @@ bundle exec ruby examples/file_copy.rb
 bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
+bundle exec ruby examples/ractor_producer_sources.rb
 bundle exec ruby examples/ractor_port_source.rb
+bundle exec ruby examples/ractor_merge_ports_and_map.rb
 bundle exec ruby examples/async_http_requests.rb
 bundle exec ruby examples/async_http_streaming_body.rb
 ```
@@ -465,9 +581,16 @@ events so the difference between direct demand and bounded prefetch is visible.
 `examples/ractor_map_hashing.rb` demonstrates ordered Ractor-backed hashing
 with a shareable mapper proc and `input_transfer: :move`.
 
+`examples/ractor_producer_sources.rb` demonstrates high-level owned producer
+Ractors with `Source.ractor_producer` and `Source.ractor_merge_producers`.
+
 `examples/ractor_port_source.rb` demonstrates a producer Ractor that waits for
 `RactorPort::Ack` before sending each `RactorPort::Element`.
 
+`examples/ractor_merge_ports_and_map.rb` demonstrates CPU-bound producer
+Ractors merged with `Source.ractor_merge_ports`, followed by CPU-bound
+verification in `ractor_map` workers.
+
 `examples/async_http_requests.rb` starts a local HTTP server and shows
 FiberStream overlapping independent HTTP request waits with `parallel_map`.
 
@@ -480,12 +603,13 @@ Benchmark scripts live under `benchmarks/`.
 ```sh
 bundle exec ruby benchmarks/stream_transform.rb
 bundle exec ruby benchmarks/latency_overlap.rb
+bundle exec ruby benchmarks/async_io_fanout.rb
 bundle exec ruby benchmarks/heavy_cpu_map.rb
 ```
 
 ## Development
 
-This project targets Ruby 4.x. The repository currently pins Ruby 4.0.3 in
+This project targets Ruby 4.x. The repository currently pins Ruby 4.0.5 in
 `mise.toml`.
 
 Install dependencies:

data/examples/README.md

@@ -11,6 +11,8 @@ bundle exec ruby examples/backpressure_buffer.rb
 bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
 bundle exec ruby examples/ractor_port_source.rb
+bundle exec ruby examples/ractor_producer_sources.rb
+bundle exec ruby examples/ractor_merge_ports_and_map.rb
 bundle exec ruby examples/async_http_requests.rb
 bundle exec ruby examples/async_http_streaming_body.rb
 ```
@@ -47,6 +49,15 @@ pipeline runs.
 `RactorPort::Ack`, and sends one typed `RactorPort::Element` per downstream
 demand.
 
+`ractor_producer_sources.rb` demonstrates the high-level owned-producer APIs:
+`Source.ractor_producer` for one producer and `Source.ractor_merge_producers`
+for ready-order fan-in from multiple producers. FiberStream creates the ports,
+producer Ractors, and cooperative cleanup path.
+
+`ractor_merge_ports_and_map.rb` runs CPU-bound work in multiple producer
+Ractors, merges their port outputs with `Source.ractor_merge_ports`, then runs
+another CPU-bound verification stage with `ractor_map`.
+
 `async_http_requests.rb` starts a local HTTP server and compares serial
 requests with FiberStream `parallel_map` requests. It keeps responses ordered
 while overlapping independent network waits.

data/examples/ractor_merge_ports_and_map.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "digest"
+require "fiber_stream"
+
+PRODUCER_JOBS = [
+  [
+    "producer-a",
+    [
+      { name: "alpha.bin", payload: +"A" * 180_000, seed_rounds: 80, verify_rounds: 60 },
+      { name: "bravo.bin", payload: +"B" * 140_000, seed_rounds: 70, verify_rounds: 55 }
+    ]
+  ],
+  [
+    "producer-b",
+    [
+      { name: "charlie.bin", payload: +"C" * 220_000, seed_rounds: 85, verify_rounds: 65 },
+      { name: "delta.bin", payload: +"D" * 120_000, seed_rounds: 75, verify_rounds: 50 }
+    ]
+  ]
+].freeze
+
+VERIFY_RECORD =
+  Ractor.shareable_proc do |record|
+    digest = record.fetch(:seed_sha256)
+
+    record.fetch(:verify_rounds).times do |index|
+      digest = Digest::SHA256.hexdigest("#{digest}:verify:#{index}")
+    end
+
+    record.merge(final_sha256: digest)
+  end
+
+def spawn_digest_producer(data_port, producer_name, jobs)
+  setup_port = Ractor::Port.new
+  producer =
+    Ractor.new(data_port, setup_port, producer_name, jobs) do |outbox, setup, name, producer_jobs|
+      ack_port = Ractor::Port.new
+      setup.send(ack_port)
+
+      enumerator = producer_jobs.to_enum
+      sent = 0
+
+      loop do
+        case ack_port.receive
+        in FiberStream::RactorPort::Ack
+          begin
+            job = enumerator.next
+            digest = job.fetch(:payload)
+
+            job.fetch(:seed_rounds).times do |index|
+              digest = Digest::SHA256.hexdigest("#{digest}:#{name}:#{index}")
+            end
+
+            sent += 1
+            outbox.send(
+              FiberStream::RactorPort::Element.new(
+                {
+                  producer: name,
+                  name: job.fetch(:name),
+                  bytes: job.fetch(:payload).bytesize,
+                  seed_sha256: digest,
+                  verify_rounds: job.fetch(:verify_rounds)
+                }
+              ),
+              move: true
+            )
+          rescue StopIteration
+            outbox.send(FiberStream::RactorPort::Complete.new)
+            break [:completed, name, sent]
+          end
+        in FiberStream::RactorPort::Cancel[reason]
+          break [:cancelled, name, sent, reason]
+        end
+      end
+    end
+
+  [producer, setup_port.receive]
+end
+
+port_pairs = []
+producers =
+  PRODUCER_JOBS.map do |producer_name, jobs|
+    data_port = Ractor::Port.new
+    producer, ack_port = spawn_digest_producer(data_port, producer_name, jobs)
+    port_pairs << { port: data_port, ack_port: ack_port }
+    producer
+  end
+
+records =
+  FiberStream::Source.ractor_merge_ports(port_pairs)
+    .ractor_map(workers: 2, input_transfer: :move, output_transfer: :move, &VERIFY_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+
+puts "Merged producer Ractors, then verified in ractor_map workers"
+records.each do |record|
+  puts format(
+    "- %-10<producer>s %-11<name>s %7<bytes>d bytes  %<final_sha256>s",
+    producer: record.fetch(:producer),
+    name: record.fetch(:name),
+    bytes: record.fetch(:bytes),
+    final_sha256: record.fetch(:final_sha256)
+  )
+end
+
+puts
+puts "Producer statuses:"
+producers.each do |producer|
+  puts "- #{producer.value.inspect}"
+end
+
+puts
+puts "Source.ractor_merge_ports emits producers in ready order."
+puts "ractor_map preserves that merged input order while running verification in Ractor workers."

data/examples/ractor_producer_sources.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "fiber_stream"
+
+EMIT_NUMBERS =
+  Ractor.shareable_proc do |producer, range|
+    range.each do |number|
+      break unless producer.emit(number)
+    end
+  end
+
+EMIT_TAGGED_NUMBERS =
+  Ractor.shareable_proc do |producer, tag, range|
+    range.each do |number|
+      break unless producer.emit([tag, number])
+    end
+  end
+
+squares =
+  FiberStream::Source.ractor_producer(1..5, &EMIT_NUMBERS)
+    .map { |number| number * number }
+    .run_with(FiberStream::Sink.to_a)
+
+puts "Squares from one FiberStream-owned producer Ractor:"
+puts squares.join(", ")
+
+merged =
+  FiberStream::Source.ractor_merge_producers do |group|
+    group.producer(:low, 1..3, &EMIT_TAGGED_NUMBERS)
+    group.producer(:high, 10..12, &EMIT_TAGGED_NUMBERS)
+  end.run_with(FiberStream::Sink.to_a)
+
+puts
+puts "Merged values from two owned producer Ractors:"
+merged.each do |tag, number|
+  puts "- #{tag}: #{number}"
+end
+
+puts
+puts "Producer blocks use RactorProducer#emit and stop when it returns false."
+puts "FiberStream creates the data ports, ack ports, producer Ractors, and cleanup path."

data/lib/fiber_stream/errors.rb

@@ -9,7 +9,10 @@ module FiberStream
   #
   # Producer failures, invalid protocol messages, and source-side Ractor port
   # failures use this stable error shape so callers do not need to depend on
-  # Ruby's Ractor transport exceptions.
+  # Ruby's Ractor transport exceptions. For producer failures,
+  # `cause_class_name` and `cause_message` come from the producer's
+  # `RactorPort::Failure` envelope and are included in this error's public
+  # message.
   class RactorPortSourceError < RuntimeError
     attr_reader :kind, :cause_class_name, :cause_message, :original_cause