shifty 0.4.2 → 0.6.0

data/docs/wiki/Testing-Workers.md

@@ -0,0 +1,127 @@
+# Testing Workers
+
+Shifty 0.6.0 ships an opt-in test harness (`require "shifty/testing"`) and RSpec sugar (`require "shifty/rspec"`) so your unit tests exercise workers under the **same handoff policy the production pipeline will** (see [[Handoff-Policies]]). Neither is loaded by `require "shifty"` — they're deliberately opt-in. This page covers the parity problem they solve, `Shifty::Testing.run`, the mutation detector, the RSpec matcher and shared example, and the "test at the ceiling" guidance.
+
+## The parity problem
+
+A pipeline runs `:frozen`; a unit test exercises the worker's raw proc with an ordinary mutable object:
+
+```ruby
+worker.task.call(input)  # bypasses the framework — and the policy
+```
+
+The test passes; the pipeline raises. The gap closes from two directions:
+
+1. **Worker-level policy declarations win** over pipeline defaults, so the policy travels *with* the worker. Any test that runs the worker through the framework automatically exercises production semantics.
+2. **The framework path is the convenient path** — that's `Shifty::Testing.run`.
+
+With `:frozen` as the global default, the common case requires no test configuration at all.
+
+## `Shifty::Testing.run`
+
+```ruby
+require "shifty/testing"
+
+Shifty::Testing.run(worker, inputs:, policy: nil, max_shifts: 10_000)
+```
+
+Feeds the inputs to the worker via a synthetic source and collects its outputs until the end-of-stream sentinel (`nil`). The worker's declared/effective policy governs each handoff, exactly as in production; the harness restores the worker's policy, supply, and Fiber afterward, so it never leaves a mark on the worker under test.
+
+```ruby
+worker = relay_worker { |v| v.upcase }
+Shifty::Testing.run(worker, inputs: ["a", "b", "c"])  #=> ["A", "B", "C"]
+
+# Parity with production — a mutating task raises under the default policy:
+mutator = Shifty::Worker.new { |v| v && v << :x }
+Shifty::Testing.run(mutator, inputs: [[:a]])          # raises PolicyViolation
+
+# A worker that declared :isolated runs under :isolated:
+scratch = Shifty::Worker.new(policy: :isolated) { |v| v && v << :x }
+Shifty::Testing.run(scratch, inputs: [[:a]])          #=> [[:a, :x]]
+
+# Explicit policy: override beats the worker's declaration (policy-matrix testing);
+# the worker's real declaration is untouched afterward:
+loose = Shifty::Worker.new(policy: :shared) { |v| v && v << :x }
+Shifty::Testing.run(loose, inputs: [[:a]], policy: :frozen)  # raises PolicyViolation
+loose.effective_policy                                       #=> :shared
+
+# Non-1:1 output streams collect naturally:
+evens = filter_worker { |v| v.even? }
+Shifty::Testing.run(evens, inputs: [1, 2, 3, 4])      #=> [2, 4]
+```
+
+### Sentinel semantics
+
+`nil` is Shifty's end-of-stream sentinel; collection stops at the first `nil` output. **`false` is a legitimate payload**, not end-of-stream — it flows through and gets collected:
+
+```ruby
+flipper = relay_worker { |v| !v }
+Shifty::Testing.run(flipper, inputs: [true, false, true])
+#=> [false, false, false]
+# (relay_worker's `value &&` guard passes the false input through untouched.)
+```
+
+If a worker's task converts `nil` into something non-nil, the run would never terminate — so after `max_shifts` (default 10,000) the harness raises a diagnostic `Shifty::Error` telling you to let `nil` pass through (e.g. `value && ...`) or raise `max_shifts:`.
+
+## The mutation detector: `mutates_input?`
+
+```ruby
+Shifty::Testing.mutates_input?(worker, input)  #=> true / false
+```
+
+Hands the task a private mutable deep copy of `input`, runs it through the framework under `:shared`, and compares the copy before and after (via `Marshal.dump`). It surfaces mutation **even when the worker's current policy permits or hides it**:
+
+```ruby
+sneaky = side_worker(policy: :isolated) { |v| v << :boo }
+Shifty::Testing.mutates_input?(sneaky, [:a])  #=> true — the :isolated copy hid it in production
+
+clean = relay_worker { |v| v + [:x] }
+Shifty::Testing.mutates_input?(clean, [:a])   #=> false
+```
+
+This is exactly the information you need **before** loosening a policy — moving to `:shared` never raises, so the detector is your only warning (the silent-loosening asymmetry; see [[Handoff-Policies]]). It's also the pre-upgrade inventory tool for [[Migration-Guide-0.6]]. The input must be Marshal-dumpable; anything else raises a descriptive `Shifty::Error`.
+
+## RSpec sugar
+
+```ruby
+# spec_helper.rb
+require "shifty/rspec"   # pulls in shifty/testing; assumes RSpec is loaded
+```
+
+### The `mutate_input` matcher
+
+Takes the input as an argument and delegates to the mutation detector:
+
+```ruby
+expect(worker).not_to mutate_input([:a])
+```
+
+The negated failure message spells out the consequences: a mutating task is only correct under `:isolated` (mutation stays local) or `:shared` (mutation is intentional); it will raise under `:frozen`.
+
+### The `"a policy-safe worker"` shared example
+
+Expects `worker` and `safe_input` to be defined with `let`:
+
+```ruby
+RSpec.describe "my enricher" do
+  let(:worker)     { relay_worker { |v| v.merge(enriched: true) } }
+  let(:safe_input) { {id: 1} }
+
+  it_behaves_like "a policy-safe worker"
+end
+```
+
+It runs two checks: the worker processes a **deeply frozen** input through the framework without raising (`Testing.run(..., policy: :frozen)`), and it does not mutate its input.
+
+## Test at the ceiling
+
+Policy safety is (almost) a one-way ratchet: a task correct on deeply frozen input is correct under every policy; the reverse does not hold. So the guidance is to **test under `:frozen`** — the ceiling — unless the worker explicitly declares mutation as part of its design. Consequences:
+
+- Loosening a pipeline's policy can never break a ceiling-tested worker.
+- Tightening is the only breaking direction, and tightening fails loudly with `PolicyViolation` diagnostics.
+
+**The "almost":** `:isolated` hands the task a *copy*, so a worker depending on object **identity** (rare, but conceivable with identity-keyed caches) behaves differently there. This is the one spot where strict-passing does not imply lax-passing. If your worker cares about `equal?`, test it under `:isolated` explicitly:
+
+```ruby
+Shifty::Testing.run(worker, inputs: [thing], policy: :isolated)
+```

data/docs/wiki/Worker-Types.md

@@ -0,0 +1,171 @@
+# Worker Types
+
+Shifty's DSL (`include Shifty::DSL`) provides shorthand constructors for the common worker shapes; underneath them all is `Shifty::Worker`, and above them sits `Shifty::Gang` for treating a chain as one unit. This page is the per-type reference for 0.6.0, including how each type behaves under the default `:frozen` handoff policy (see [[Handoff-Policies]]). All DSL constructors except `source_worker` and `trailing_worker` accept an options hash that passes through to `Worker.new` — so `policy:`, `name:`, `tags:` work everywhere.
+
+## `source_worker`
+
+At the headwater of every pipeline: a worker that generates its own work items. Its block takes no arguments; `nil` signals end-of-stream (and once a source returns `nil`, it returns `nil` henceforth).
+
+```ruby
+worker = source_worker { "Number 9" }   # generates forever
+
+counter = 0
+finite = source_worker do               # generates until it returns nil
+  if counter < 3
+    counter += 1
+    counter + 1000
+  end
+end
+
+w1 = source_worker [0, 1, 2]            # or hand it a series
+w2 = source_worker (0..2)               # ranges work too
+```
+
+A series-based source yields each element and then `nil` forever. Strings are split into characters; a bare scalar becomes a one-element series. You can also combine a series with a block, which acts as a transform: `source_worker([1,2]) { |v| v * 10 }`.
+
+Sources are where "mutable within, immutable between" starts: build values freely in closure scope, and hand off snapshots (see [[Coding-Idioms-Under-Frozen]]).
+
+## `relay_worker`
+
+The most "normal" worker: accepts a value, returns a transformation of it. `nil` passes through untouched (the end-of-stream sentinel survives).
+
+```ruby
+squarer = relay_worker { |number| number ** 2 }
+pipeline = source_worker(0..3) | squarer
+pipeline.shift #=> 0, 1, 4, 9, nil
+```
+
+Under `:frozen`, relay tasks must be non-destructive — `v.merge(...)`, `v + [...]`, `v.with(...)`. A `v <<` raises `PolicyViolation` at this worker, by name if you gave it one.
+
+## `side_worker`
+
+Passes through the value it received while performing a side effect — logging, metrics, stashing. Its purpose is *intentionality*: side effects live in named, removable workers, so pulling one out of the pipeline never changes the pipeline's output.
+
+```ruby
+evens = []
+even_stasher = side_worker { |value| evens << value if value.even? }
+```
+
+Policy behavior is where 0.6.0 makes the side worker's contract real:
+
+- **Under `:frozen` (default):** a block that mutates the passed value raises `PolicyViolation`. Observation is enforced.
+- **Under `:isolated`:** the block observes a private scratch copy; since a side worker's return value is discarded, its mutations simply **evaporate** and the untouched value flows on:
+
+```ruby
+source = source_worker [[:foo], [:bar]]
+unsafe = side_worker(policy: :isolated) { |v| v << :boo }
+pipeline = source | unsafe
+pipeline.shift #=> [:foo]  — shenanigans contained
+pipeline.shift #=> [:bar]
+```
+
+- **`mode:` is deprecated:** `mode: :hardened` maps to `policy: :isolated` with a warning; any other `mode:` value warns and is ignored. Removed in 1.0.0 — see [[Migration-Guide-0.6]].
+
+## `filter_worker`
+
+Passes through only values for which the block is truthy; falsy values are discarded (the worker pulls from its supply until something passes).
+
+```ruby
+evens_only = filter_worker { |value| value % 2 == 0 }
+pipeline = source_worker(0..5) | evens_only
+pipeline.shift #=> 0, 2, 4, nil
+```
+
+Every value the filter pulls mid-task crosses the boundary under the worker's policy — including the ones it discards.
+
+## `batch_worker`
+
+Gathers values into batches. Either a fixed size:
+
+```ruby
+batch = batch_worker gathering: 3
+pipeline = source_worker(0..7) | batch
+pipeline.shift #=> [0, 1, 2], then [3, 4, 5], then [6, 7], then nil
+```
+
+(the final batch may be short), or a condition — batch until the block is truthy:
+
+```ruby
+line_reader = batch_worker { |value| value.end_with?("\n") }
+```
+
+## `splitter_worker`
+
+Accepts one value, produces an array from it, and hands off each element successively before asking its supply for more.
+
+```ruby
+splitter = splitter_worker { |value| value.split(" ") }
+pipeline = source_worker(["A bold", "move westward"]) | splitter
+pipeline.shift #=> "A", "bold", "move", "westward", nil
+```
+
+Every part a splitter yields is policy-governed as it crosses into the next worker — under `:frozen`, each part arrives frozen downstream.
+
+## `trailing_worker`
+
+Returns an array of the last *n* values — useful for rolling averages. Nothing is returned until *n* values have accumulated; new values are unshifted into position zero.
+
+```ruby
+trailer = trailing_worker 4
+pipeline = source_worker(0..5) | trailer
+pipeline.shift #=> [3, 2, 1, 0], then [4, 3, 2, 1], then [5, 4, 3, 2], then nil
+```
+
+New in 0.6.0: the trailing worker **hands off a snapshot** (`trail.dup`) rather than its live closure array. It keeps mutating that array across calls, and a downstream `:frozen` intake would otherwise freeze the live array in place. This is the canonical example of the builder snapshot rule — see [[Coding-Idioms-Under-Frozen]].
+
+(Signature note: `trailing_worker(trail_length = 2)` takes the length positionally and no options hash.)
+
+## Raw `Shifty::Worker.new`
+
+When the DSL shapes don't fit, build a worker directly:
+
+```ruby
+worker = Shifty::Worker.new(
+  supply:   upstream,           # or wire later: worker.supply = upstream
+  policy:   :isolated,          # this worker's contract; validated eagerly
+  name:     "enricher",         # used in PolicyViolation / UnshareableValue messages
+  tags:     [:etl],             # also reported in diagnostics
+  criteria: ->(w) { ... },      # when falsy, the task is bypassed (value still policy-governed)
+  task:     some_callable       # or pass a block
+) { |value, supply, context| ... }
+```
+
+The task's arity matters:
+
+- **Arity 0** — a source; it cannot accept a supply (`supply=` raises). Use `handoff(value)` (which is `Fiber.yield`) to emit from inside loops.
+- **Arity 1+** — `|value|` receives the policy-governed intake value.
+- **Second argument** — a policy-governed supply proxy responding only to `#shift`, for tasks that pull additional values themselves (this is how filter/batch/trailing work). It is *not* the raw upstream worker.
+- **Third argument** — the worker's `context`, an `OpenStruct` by default or whatever you pass as `context:`; per-worker mutable state that survives across shifts (and survives a rescued `PolicyViolation`).
+
+A worker with no task gets a default pass-through task. `worker.effective_policy` reports the resolved policy (own declaration, else pipeline default, else global default).
+
+## Composition: `|`, `with_policy`, `freeze!`
+
+```ruby
+pipeline = source | filter | transform | sink   # tail-returned; call shift on it
+
+pipeline = (source | filter | transform | sink)
+  .with_policy(:frozen)   # pipeline default for workers with no declaration
+  .freeze!                # lock the topology; upstream walk from the tail
+```
+
+Both `with_policy` and `freeze!` walk **upstream** through the supply chain from their receiver and return it, so they chain — and both should be called on the pipeline's tail. `freeze!` locks topology only (supply wiring, Gang rosters); closure and context state stay mutable. Use `#freeze!`, never bare `#freeze`. Details in [[Handoff-Policies]].
+
+## `Shifty::Gang`
+
+A Gang wraps an ordered roster of workers so a whole chain acts like one worker: it has a `supply`, a `shift`, and composes with `|` like anything else.
+
+```ruby
+gang = Shifty::Gang[parser, enricher]          # or Gang.new([parser, enricher])
+pipeline = reader | gang | writer
+```
+
+Policy features:
+
+- **Construction fanout:** `Gang.new(workers, policy: :isolated)` sets the pipeline default on every roster member.
+- **`with_policy` fanout:** `gang.with_policy(:shared)` does the same, chainably.
+- **Append inheritance:** the gang persists its declared policy, so workers appended *after* the declaration inherit it too.
+- **Member contracts win:** a roster member's own `policy:` declaration beats the gang's, per the usual precedence.
+- **Chains walk through:** `(upstream | gang | tail).with_policy(:isolated)` reaches the gang's roster *and* workers upstream of it; `freeze!` walks the same path.
+- **Freezing:** a frozen gang still runs, but its roster membership is locked — `append` raises `FrozenError`.
+- **Criteria bypass is still governed:** when a gang's `criteria` bypasses its workers, the value crossing the gang boundary is still policy-governed at the entry worker.

data/docs/wiki/_Sidebar.md

@@ -0,0 +1,13 @@
+**[[Home]]**
+
+*Concepts*
+- [[Handoff-Policies]]
+- [[Coding-Idioms-Under-Frozen]]
+- [[Worker-Types]]
+
+*Doing things*
+- [[Migration-Guide-0.6]]
+- [[Testing-Workers]]
+
+*Reference*
+- [[Performance]]

data/lib/shifty/configuration.rb

@@ -0,0 +1,27 @@
+module Shifty
+  class Configuration
+    attr_reader :default_policy
+
+    def initialize
+      @default_policy = :frozen
+    end
+
+    def default_policy=(policy_name)
+      @default_policy = Policy.validate!(policy_name)
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_configuration!
+      @config = Configuration.new
+    end
+  end
+end

data/lib/shifty/dsl.rb

@@ -1,6 +1,4 @@
 module Shifty
-  class WorkerInitializationError < StandardError; end
-
   module DSL
     def source_worker(argument = nil, &block)
       ensure_correct_arity_for!(argument, block)
@@ -19,36 +17,46 @@ module Shifty
       end
     end
 
-    def relay_worker(&block)
-      ensure_regular_arity(block)
+    def relay_worker(options = {}, &block)
+      options[:tags] ||= []
+      options[:tags] << :relay
+      ensure_regular_arity!(block)
 
-      Worker.new(tags: [:relay]) do |value|
+      Worker.new(options) do |value|
         value && block.call(value)
       end
     end
 
-    def side_worker(mode = :normal, &block)
-      ensure_regular_arity(block)
+    def side_worker(options = {}, &block)
+      options[:tags] ||= []
+      options[:tags] << :side_effect
+      deprecate_mode_option!(options)
+      ensure_regular_arity!(block)
 
-      Worker.new(tags: [:side_effect]) do |value|
+      # The block must ask the worker for its policy at shift time, so the
+      # local is captured by the closure before it is assigned. Not redundant.
+      worker = nil
+      worker = Worker.new(options) do |value| # standard:disable Style/RedundantAssignment
         value.tap do |v|
-          used_value = (mode == :hardened) ?
-            Marshal.load(Marshal.dump(v)) : v
+          next unless v
+          # Under :isolated the block observes a private scratch copy, so
+          # its mutations evaporate and the untouched value flows on.
+          used_value = (worker.effective_policy == :isolated) ?
+            Policy::Isolated.call(v, worker: worker) : v
 
-          v && block.call(used_value)
+          block.call(used_value)
         end
       end
+      worker
     end
 
-    def filter_worker(argument = nil, &block)
-      if block && argument.respond_to?(:call)
-        throw_with "You cannot supply two callables"
-      end
-      callable = argument.respond_to?(:call) ? argument : block
-      ensure_callable(callable)
+    def filter_worker(options = {}, &block)
+      options[:tags] ||= []
+      options[:tags] << :filter
+      ensure_callable!(block)
 
-      Worker.new(tags: [:filter]) do |value, supply|
-        while value && !callable.call(value)
+      Worker.new(options) do |value, supply|
+        while value && !block.call(value)
           value = supply.shift
         end
         value
@@ -62,14 +70,18 @@ module Shifty
       end
     end
 
-    def batch_worker(options = {gathering: 1}, &block)
-      ensure_regular_arity(block) if block
+    def batch_worker(options = {}, &block)
+      options[:tags] ||= []
+      options[:tags] << :batch
+      options[:gathering] ||= 1
+
+      ensure_regular_arity!(block) if block
       batch_full = block ||
         proc { |_, batch| batch.size >= options[:gathering] }
 
-      batch_context = BatchContext.new({batch_full: batch_full})
+      options[:context] = BatchContext.new({batch_full: batch_full})
 
-      Worker.new(tags: [:batch], context: batch_context) do |value, supply, context|
+      Worker.new(options) do |value, supply, context|
         if value
           context.collection = [value]
           until context.batch_complete?(
@@ -83,10 +95,12 @@ module Shifty
       end
     end
 
-    def splitter_worker(&block)
-      ensure_regular_arity(block)
+    def splitter_worker(options = {}, &block)
+      options[:tags] ||= []
+      options[:tags] << :splitter
+      ensure_regular_arity!(block)
 
-      Worker.new(tags: [:splitter]) do |value|
+      Worker.new(options) do |value|
         if value.nil?
           value
         else
@@ -99,9 +113,11 @@ module Shifty
       end
     end
 
+    # don't like that this is a second exception to accepting options..
     def trailing_worker(trail_length = 2)
+      options = {tags: [:trailing]}
       trail = []
-      Worker.new(tags: [:trailing]) do |value, supply|
+      Worker.new(options) do |value, supply|
         if value
           trail.unshift value
           if trail.size >= trail_length
@@ -111,9 +127,12 @@ module Shifty
             trail.unshift supply.shift
           end
 
-          trail
+          # Hand off a snapshot: the builder keeps mutating `trail` across
+          # calls, and a downstream :frozen intake would freeze the live
+          # closure array in place.
+          trail.dup
         else
-          value
+          value # hint: it's nil!
         end
       end
     end
@@ -124,17 +143,30 @@ module Shifty
 
     private
 
+    def deprecate_mode_option!(options)
+      return unless options.key?(:mode)
+      mode = options.delete(:mode)
+      if mode == :hardened
+        warn "[shifty] side_worker mode: :hardened is deprecated and will be " \
+             "removed in 1.0.0; use policy: :isolated instead."
+        options[:policy] ||= :isolated
+      else
+        warn "[shifty] side_worker's mode: option is deprecated and ignored " \
+             "(received mode: #{mode.inspect}); declare a policy: instead."
+      end
+    end
+
     def throw_with(*msg)
       raise WorkerInitializationError.new([msg].flatten.join(" "))
     end
 
-    def ensure_callable(callable)
+    def ensure_callable!(callable)
       unless callable&.respond_to?(:call)
         throw_with "You must supply a callable"
       end
     end
 
-    def ensure_regular_arity(block)
+    def ensure_regular_arity!(block)
       if block.arity != 1
         throw_with \
           "Worker must accept exactly one argument (arity == 1)"
@@ -145,7 +177,7 @@ module Shifty
     def ensure_correct_arity_for!(argument, block)
       return unless block
       if argument
-        ensure_regular_arity(block)
+        ensure_regular_arity!(block)
       elsif block.arity > 0
         throw_with \
           "Source worker cannot accept any arguments (arity == 0)"

data/lib/shifty/errors.rb

@@ -0,0 +1,121 @@
+module Shifty
+  class Error < StandardError; end
+
+  class WorkerError < Error; end
+
+  class WorkerInitializationError < Error; end
+
+  class PolicyError < Error
+    attr_reader :worker, :policy, :value
+
+    def cause
+      @wrapped_cause || super
+    end
+
+    private
+
+    def worker_label
+      label = (worker.respond_to?(:name) && worker.name) ? "`#{worker.name}`" : "(unnamed)"
+      tags = worker.respond_to?(:tags) ? worker.tags : []
+      tags&.any? ? "#{label} (tags: #{tags.inspect})" : label
+    end
+  end
+
+  # Raised when a task mutates a value it received under a policy that
+  # forbids mutation. Wraps the original FrozenError (never masks it) and
+  # names the worker, the effective policy, and the object the task tried
+  # to mutate, with a heuristic locating that object relative to the
+  # handed-off value.
+  class PolicyViolation < PolicyError
+    attr_reader :receiver
+
+    def initialize(worker:, policy:, receiver:, value:, cause:)
+      @worker = worker
+      @policy = policy
+      @receiver = receiver
+      @value = value
+      @wrapped_cause = cause
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      <<~MSG
+        Worker #{worker_label} received its value under the #{policy.inspect} handoff \
+        policy, and its task attempted to mutate #{receiver_description}.
+
+        Either make the task non-destructive — e.g. `map` instead of `map!`, \
+        `value.with(...)`, `arr + [x]`, `hash.merge(...)` — or declare a different \
+        policy on this worker: `policy: :isolated` (task works on a private scratch \
+        copy) or `policy: :shared` (raw reference; no protection). \
+        More: https://github.com/joelhelbling/shifty/wiki/Handoff-Policies
+      MSG
+    end
+
+    def receiver_description
+      if receiver.equal?(value)
+        "an instance of #{receiver.class} — the handed-off value itself"
+      elsif reachable_from_value?
+        "an instance of #{receiver.class} reachable from the handed-off value"
+      else
+        "an instance of #{receiver.class} (#{receiver.inspect[0, 80]}), which may be " \
+          "unrelated to the handed-off value (an instance of #{value.class}); " \
+          "inspect both to judge"
+      end
+    end
+
+    # Bounds the diagnostic graph walk; past this the heuristic gives up
+    # and reports the honest "inspect both to judge" fallback rather than
+    # risking a SystemStackError that would mask the violation itself.
+    MAX_REACHABILITY_NODES = 50_000
+
+    def reachable_from_value?
+      seen = {}.compare_by_identity
+      stack = [value]
+      until stack.empty?
+        node = stack.pop
+        next if node.nil? || seen[node]
+        return false if seen.size >= MAX_REACHABILITY_NODES
+        seen[node] = true
+        return true if node.equal?(receiver)
+        stack.concat(children_of(node))
+      end
+      false
+    end
+
+    def children_of(node)
+      case node
+      when Array then node
+      when Hash then node.keys + node.values
+      when Struct then node.to_a
+      else
+        members = (node.respond_to?(:to_h) && node.is_a?(Data)) ? node.to_h.values : []
+        members + node.instance_variables.map { |iv| node.instance_variable_get(iv) }
+      end
+    end
+  end
+
+  # Raised at the handoff itself when a value cannot cross the boundary
+  # under the effective policy (cannot be frozen or deep-copied).
+  class UnshareableValue < PolicyError
+    def initialize(worker:, policy:, value:, cause: nil)
+      @worker = worker
+      @policy = policy
+      @value = value
+      @wrapped_cause = cause
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      "Worker #{worker_label} received a value (an instance of #{value.class}) " \
+        "that cannot cross the handoff boundary under the #{policy.inspect} policy: " \
+        "it cannot be #{(policy == :isolated) ? "deep-copied" : "frozen"}. " \
+        "Declare `policy: :shared` on this worker (raw pass-by-reference), " \
+        "or restructure the value. " \
+        "More: https://github.com/joelhelbling/shifty/wiki/Handoff-Policies"
+    end
+  end
+end