Reconcile concurrency docs with handoff immutability plan

Distinguish preemptive concurrency hazards (removed by single-threading)
from data-mutation hazards across handoffs (not removed); reframe the
Threads/Ractors note as a scoping decision that is Ractor-compatible; and
scope the thread-safety caveat to worker/pipeline objects and closure
state. Forward-reference docs/planning/handoff-immutability-policies.md.

Author: joelhelbling

README.md

@@ -11,6 +11,8 @@ _"How many Ruby fibers does it take to screw in a lightbulb?"_
 
 Shifty utilizes Ruby Fibers for cooperative multitasking. This means that all tasks (or "workers") run within a single operating system thread and explicitly yield control to one another. This model is intentionally chosen for its simplicity, which makes it easier to reason about and build sequential data processing pipelines.
 
+Single-threading frees you from *preemptive* concurrency hazards (races, mutexes) within a pipeline. It does not, by itself, make the data passing between workers safe — a worker that mutates a value it was handed can still corrupt what later workers see. Governing those handoffs is a separate concern; see the planned [handoff immutability policies](docs/planning/handoff-immutability-policies.md). The Fiber model is also deliberately compatible with a future Ractor-backed worker type, rather than a rejection of parallelism.
+
 For a more detailed explanation of Shifty's design and typical use cases, please see the [Use Cases Document](docs/use_cases.md).
 
 ## Quick Start

docs/use_cases.md

@@ -39,6 +39,19 @@ Here are a few conceptual examples of how Shifty could be applied:
     2.  A `BatchWorker` (Shifty provides a `batch_worker` for this purpose) accumulates these items. It passes the accumulated batch to the next worker once a certain number of items are collected or a timeout occurs.
     3.  A `BatchProcessorWorker` then processes the entire batch of items at once (e.g., bulk database insert, writing to a file).
 
+## A Note on Values Passed Between Workers
+
+The examples above pass data from one worker to the next. Because Shifty runs
+each value through every worker before starting the next value, workers should
+treat a handed-off value as read-only and express changes as new values
+(`arr + [x]`, `hash.merge(...)`, `value.with(...)`) rather than mutating in
+place (`arr <<`, `hash[k] =`, `map!`). This keeps failures local and is the
+direction Shifty is moving: a planned release makes deeply frozen handoffs the
+default, with opt-in policies for workers that genuinely need a private scratch
+copy or a shared mutable reference. See
+[handoff immutability policies](planning/handoff-immutability-policies.md) for
+the full design and migration guidance.
+
 ## Conclusion
 
 Shifty aims to provide an intuitive and straightforward way to construct data processing systems within Ruby applications. By breaking down complex tasks into manageable, cooperatively multitasking workers, it helps in building modular, maintainable, and easy-to-understand data pipelines.

lib/shifty/worker.rb

@@ -92,18 +92,27 @@ def task_method_accepts_a_value?
     # ### Concurrency Model
     # Shifty utilizes Ruby Fibers to achieve cooperative multitasking. This means
     # that workers voluntarily yield control, allowing other workers to execute.
-    # The entire processing pipeline runs within a single thread, simplifying
-    # state management and avoiding many common concurrency issues.
+    # The entire processing pipeline runs within a single thread, which removes
+    # an entire class of *preemptive* concurrency hazards (races on shared
+    # objects, the need for mutexes around Shifty's own state).
+    #
+    # Note that single-threading does NOT make the data flowing between workers
+    # safe on its own: because each value passes through every worker before the
+    # next value begins, a worker that mutates a handed-off value can silently
+    # corrupt what downstream workers observe. That hazard is orthogonal to
+    # threading and is addressed separately by handoff immutability policies
+    # (see docs/planning/handoff-immutability-policies.md).
     #
     # ### Alternatives (Threads/Ractors)
-    # While Ruby's Threads could be used for parallelism, especially for I/O-bound
-    # tasks, and Ractors (in Ruby 3.0+) for CPU-bound tasks, they would
-    # introduce significant complexity. Managing thread safety with Threads
-    # (e.g., using mutexes, avoiding race conditions) or adhering to Ractor's
-    # message passing and object sharing restrictions would make the framework
-    # harder to use and reason about. The current Fiber-based model aligns
-    # well with Shifty's primary goal of providing an easy-to-use framework
-    # for building sequential data processing pipelines.
+    # Threads and Ractors are not used for parallelism *yet*. Shifty's current
+    # goal is an easy-to-use framework for sequential data pipelines, and a
+    # single-threaded Fiber model serves that directly without the overhead of
+    # mutexes (Threads) or the sharing restrictions of Ractors. This is a
+    # scoping decision, not a rejection: the planned move to deeply frozen,
+    # shareable handoff values is deliberately Ractor-compatible and lays the
+    # groundwork for a future Ractor-backed worker type. (Fibers cannot cross
+    # Ractor boundaries, so such a worker would be a distinct type, not a
+    # retrofit of this one.)
     #
     # ### Thread Safety
     # `Shifty::Worker` instances, and by extension `Shifty::Gang` or
@@ -114,6 +123,9 @@ def task_method_accepts_a_value?
     # Shifty pipelines in parallel using separate Threads), they are responsible
     # for implementing appropriate synchronization mechanisms (like mutexes)
     # to protect shared Shifty objects from concurrent access and modification.
+    # (Handoff immutability policies govern only the *values* passed between
+    # workers, not the worker/pipeline objects themselves or their closure
+    # state — those remain the user's responsibility across threads.)
     # For typical use cases where a Shifty pipeline is built and run, no
     # external threading is usually involved by the user.
   end