shifty 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2d09c087eca2d3c2790efab38c0e12230edd9738daf7e43c6788a8671c64356
-  data.tar.gz: 98fe18da84e2889e1b0c1bb90ea41ffcb6928e50868033fa33627bce58482052
+  metadata.gz: 8e7ad29ca6b77f1216ed40460e252d48743f6b6786a8adbd1e277fc673115829
+  data.tar.gz: ab8d5fced324f9b7d1834ac9c1741428122de18acd03f02d1e7d550d8f190879
 SHA512:
-  metadata.gz: 0fb0046526de78394da2a742f9c9d41d07d58717592f0ce40f13d32e6cdf8e2c0c42d30fffe2bc53e164398422639c5f42943c0e7edb064eb0ec8c21960fe833
-  data.tar.gz: 45792b0187073a88781217d1559afc185471bbdbd849c233af81055a9dc5d71ebf8bbd018a3224baa4d0a32795109802eadfcfe9dba754f964907154dabc0e4c
+  metadata.gz: f7884214ed282f0d200d18391989c04af01493f2f17477e2b0f4fe69ebe782e1401fcaed5dcd40561f23f4e05831b79dd09b50e8b09d422262de7af1310e5ec3
+  data.tar.gz: 67c9354307d51baf7628b4079cf0f86dd9d80e7444d6c286fc65d6dd3df6316c9f24d62190281ba127700d2f64562d716cedec5fa5f605d337d81639e1cd37f8

data/.gitignore

@@ -16,3 +16,4 @@
 Gemfile.lock
 
 shifty-*.gem
+.secrets

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 0.6.0
+
+The handoff immutability release. Values crossing worker boundaries are now
+governed by a **handoff policy**, and the default changed from raw shared
+references to deeply frozen values. This is a breaking change — see the
+[Migration Guide](https://github.com/joelhelbling/shifty/wiki/Migration-Guide-0.6).
+
+### Breaking changes
+
+- **`:frozen` is the new default handoff policy.** Every value a worker
+  receives is deeply frozen (`Ractor.make_shareable`) at intake. A task that
+  mutates its input now raises `Shifty::PolicyViolation` at the offending
+  worker — immediately and with diagnostics — instead of silently corrupting
+  what downstream workers observe. Restore the old behavior per worker with
+  `policy: :shared`, per pipeline with `.with_policy(:shared)`, or globally
+  with `Shifty.configure { |c| c.default_policy = :shared }`.
+- **Unshareable values can no longer cross a default-policy boundary.**
+  IO handles, procs, lazy enumerators, and (under `:isolated`) anything
+  Marshal rejects raise `Shifty::UnshareableValue` with guidance. Declare
+  `policy: :shared` on workers that pass such values. Note: an IO *nested
+  inside* a container is not detected — declare `:shared` for those workers.
+- **The task's second argument is now a policy-governed supply proxy** that
+  responds to `#shift` only, no longer the raw upstream worker object.
+- **Ruby floor is 3.2** (`required_ruby_version >= 3.2`). Older Rubies stay
+  on shifty 0.5.0.
+- `Shifty::WorkerError` and `Shifty::WorkerInitializationError` are
+  reparented under a new `Shifty::Error` base (still `StandardError`s).
+
+### Deprecations
+
+- **`side_worker mode: :hardened` is deprecated** (removed in 1.0.0); it maps
+  to `policy: :isolated` with a warning. Semantics preserved — both use a
+  Marshal deep copy. Any other `mode:` value now warns and is ignored.
+
+### Added
+
+- **Handoff policies**: `:frozen` (default), `:isolated` (private mutable
+  deep copy; task mutations stay local), `:shared` (raw reference — the
+  escape hatch). Declarable per worker (`policy:` kwarg), per pipeline
+  (`.with_policy(...)` on a chain or Gang, `policy:` kwarg on Gang), and
+  globally. Precedence: worker > pipeline > global.
+- **Rich diagnostics**: `Shifty::PolicyViolation` (worker, policy, receiver,
+  value, cause; a heuristic reports whether the mutated object is the
+  handed-off value, reachable from it, or possibly unrelated) and
+  `Shifty::UnshareableValue`. A rescued `PolicyViolation` does not kill the
+  pipeline — the next `shift` continues with the next value.
+- **Worker `name:` kwarg** for diagnostics.
+- **`Shifty::Testing`** (opt-in `require "shifty/testing"`):
+  `Testing.run(worker, inputs:, policy: nil)` runs a worker through the
+  framework under its production policy; `Testing.mutates_input?` is the
+  mutation detector — the pre-upgrade migration inventory tool.
+- **RSpec sugar** (opt-in `require "shifty/rspec"`): the `mutate_input`
+  matcher and the `"a policy-safe worker"` shared example.
+- **`#freeze!`** locks an assembled pipeline's topology (call it on the
+  tail). Rewiring — `supply=`, Gang `append`, roster mutation — raises
+  `FrozenError`. Worker closure/context state stays mutable.
+- **Benchmark suite** (`benchmark/handoff_policies.rb`, manual-run) with
+  results in `benchmark/RESULTS.md` and on the wiki: steady-state `:frozen`
+  costs ~71ns per handoff regardless of value size, with zero allocations.
+- **In-depth documentation** on the
+  [GitHub wiki](https://github.com/joelhelbling/shifty/wiki): policies,
+  coding idioms under `:frozen`, migration, testing, worker types,
+  performance.
+
+### Fixed
+
+- `trailing_worker` handed off its live internal array; under `:frozen` this
+  is the exact aliasing bug the policies exist to catch. It now hands off a
+  snapshot.
+- `ostruct` is declared as a runtime dependency (no longer a default gem as
+  of Ruby 4).
+- CI now tests Ruby 3.2/3.3/3.4 (was 2.6/2.7/3.0); dropped the abandoned
+  codeclimate-test-reporter (which pinned simplecov to a 2016 release).
+
+## 0.5.0 and earlier
+
+See the [release history](https://github.com/joelhelbling/shifty/releases).

data/README.md

@@ -1,12 +1,65 @@
 [![Gem Version](https://badge.fury.io/rb/shifty.svg)](https://badge.fury.io/rb/shifty)
 [![Tests](https://github.com/joelhelbling/shifty/actions/workflows/ruby.yml/badge.svg)](https://github.com/joelhelbling/shifty/actions/workflows/ruby.yml)
-[![Maintainability](https://api.codeclimate.com/v1/badges/950ded888350c1124348/maintainability)](https://codeclimate.com/github/joelhelbling/shifty/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/950ded888350c1124348/test_coverage)](https://codeclimate.com/github/joelhelbling/shifty/test_coverage)
 
 # The Shifty Framework
 
 _"How many Ruby fibers does it take to screw in a lightbulb?"_
 
+Shifty requires **Ruby 3.2 or newer** as of version 0.6.0. On older Rubies,
+use shifty 0.5.0 (which also retains the classic mutable-handoff behavior).
+
+## Concurrency Model
+
+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 could corrupt what later workers see. As of 0.6.0, those handoffs are governed by [handoff immutability policies](#handoff-policies-new-in-060). The Fiber model is also deliberately compatible with a future Ractor-backed worker type, rather than a rejection of parallelism — and frozen, shareable handoff values are exactly what Ractor boundaries want.
+
+For a more detailed explanation of Shifty's design and typical use cases, please see the [Use Cases Document](docs/use_cases.md).
+
+## Handoff Policies (new in 0.6.0)
+
+Shifty workers are easy to reason about because each one is isolated; the
+values flowing *between* them were, until now, the un-governed part of the
+system. As of 0.6.0, values are **deeply frozen at every handoff by
+default**. Workers that need a private scratch copy can declare
+`policy: :isolated`; workers that genuinely need shared mutable references
+can declare `policy: :shared`. Mutation bugs that used to surface as
+mysterious downstream corruption now either cannot happen or raise
+immediately at the worker responsible — with an error message that tells
+you exactly what to do about it.
+
+```ruby
+# Per worker — part of the worker's contract:
+scratch = Shifty::Worker.new(policy: :isolated) { |v| v << transform(v) }
+
+# Per pipeline — the default for workers that don't declare their own:
+pipeline = (source | parser | sink).with_policy(:shared)
+
+# Globally (the built-in default is :frozen):
+Shifty.configure { |c| c.default_policy = :shared }
+```
+
+| | `:frozen` (default) | `:isolated` | `:shared` |
+|---|---|---|---|
+| The task receives | frozen reference | private mutable deep copy | the raw reference |
+| Mutation in the task | raises `Shifty::PolicyViolation` | works, stays local | works, leaks |
+| Copying per handoff | none | full graph | none |
+
+### Upgrading from 0.5.0?
+
+Start with the [Migration Guide](https://github.com/joelhelbling/shifty/wiki/Migration-Guide-0.6) —
+it names everything that breaks and gives four migration paths in order of
+preference. `Shifty::Testing.mutates_input?` will inventory which of your
+workers mutate their input *before* you flip the switch.
+
+There's much more in the wiki: [Handoff Policies](https://github.com/joelhelbling/shifty/wiki/Handoff-Policies) in depth,
+[coding idioms under :frozen](https://github.com/joelhelbling/shifty/wiki/Coding-Idioms-Under-Frozen),
+the [0.6 migration guide](https://github.com/joelhelbling/shifty/wiki/Migration-Guide-0.6),
+[testing workers](https://github.com/joelhelbling/shifty/wiki/Testing-Workers), and
+[performance numbers](https://github.com/joelhelbling/shifty/wiki/Performance)
+(spoiler: at steady state, `:frozen` costs about 71 nanoseconds per handoff
+no matter how big the value is).
+
 ## Quick Start
 
 Add this line to your application's Gemfile:
@@ -134,7 +187,7 @@ work.
 source = source_worker (0..3)
 
 evens = []
-even_stasher = side_effect do |value|
+even_stasher = side_worker do |value|
   if value % 2 == 0
     evens << value
   end
@@ -163,10 +216,10 @@ it is, there really isn't a way to prevent the implementation of any
 worker from creating side effects.
 
 _And still wait,_ you'll also be wanting to say, _isn't it possible
-that a side worker could mutate the value as it's passed through?_  And
-again, yes.  It would be very difficult\* in the Ruby language (where
-so many things are passed by reference) to perfectly prevent a side
-worker from mutating the value.  But please don't.
+that a side worker could mutate the value as it's passed through?_
+As of 0.6.0: no, not by accident. A side worker's contract is
+"observe, don't modify," and the default `:frozen` handoff policy
+finally enforces it.
 
 The side effect worker's purpose is to provide _intentionality_ and
 clarity.  When you're creating a side effect, let it be very clear.
@@ -178,55 +231,40 @@ same token, if there is a problem with a side effect, troubleshooting
 it will be much simpler if the side effects are already isolated and
 named.
 
-Another measure for preventing side workers from creating unwanted
-side-effects is to use `:hardened` mode.  That's right, `side_worker`
-has a mode (which defaults to `:normal`).  When set to `:hardened`,
-each value is `Marshal.dump`ed and `Marshal.load`ed before being
-passed to the side worker's callable.  This helps to ensure that
-the original value will be passed through to the next worker in the
-queue in a pristine state (unmodified), and that no future or
-subsequent modification can take place.
-
 Given a source...
 
 ```ruby
 source = source_worker [[:foo], [:bar]]
 ```
 
-Consider this unsafe, unhardened side worker:
+...consider this mutating side worker:
 
 ```ruby
 unsafe = side_worker { |v| v << :boo }
-```
-
-This produces unwanted mutations, because of the `<<`.
 
-```ruby
 pipeline = source | unsafe
 
-pipeline.shift #=> [:foo, :boo] <-- Oh noes!
-pipeline.shift #=> [:bar, :boo] <-- Disaster!
-pipeline.shift #=> nil
+pipeline.shift #=> raises Shifty::PolicyViolation, naming this worker
 ```
 
-Let's harden it:
+Under the default `:frozen` policy that mutation raises immediately,
+at the offending worker. If the side worker's mutations are harmless
+scratch work you'd rather keep, give it a private copy instead:
 
 ```ruby
-unsafe = side_worker(:hardened) { |v| v << :boo }
-```
-
-The `:hardened` side worker doesn't have access to the original
-value, and therefore its shenanigans are moot with respect to
-the main workflow:
+unsafe = side_worker(policy: :isolated) { |v| v << :boo }
 
-```ruby
 pipeline = source | unsafe
 
-pipeline.shift #=> [:foo] <-- No changes
-pipeline.shift #=> [:bar] <-- Much better
+pipeline.shift #=> [:foo] <-- mutations evaporate
+pipeline.shift #=> [:bar] <-- the original flows on, pristine
 pipeline.shift #=> nil
 ```
 
+(Old-timers: `side_worker mode: :hardened` still works, mapped to
+`policy: :isolated` with a deprecation warning; it will be removed in
+1.0.0.)
+
 ### Filter Worker
 
 The filter worker simply passes through the values which are given
@@ -453,7 +491,13 @@ example).
 ## Shifty::Worker
 
 The Shifty::Worker documentation (which was the old README) is now
-[here](docs/shifty/worker.md).
+[here](docs/shifty/worker.md), and the
+[wiki](https://github.com/joelhelbling/shifty/wiki) goes deeper on every
+worker type, handoff policies, testing, migration, and performance.
 
 ## Roadmap
 
+- **1.0.0** — remove the deprecated `:hardened` alias; stabilize the API.
+- **Someday** — a Ractor-backed worker type for true parallelism; the
+  `:frozen` policy's shareable values are deliberately the groundwork.
+

data/benchmark/RESULTS.md

@@ -0,0 +1,69 @@
+# Handoff policy benchmark results
+
+Run: `bundle exec ruby benchmark/handoff_policies.rb`
+Environment: Ruby 4.0.5 (arm64-darwin25), Apple Silicon. 2026-07-10.
+(Re-run on your own hardware; relative ordering is what matters.)
+
+## Method note (read first)
+
+Rows labeled *fresh value* construct a new value inside each iteration, so
+they include construction cost — that keeps `:frozen`'s freeze bit honest
+(freezing is once-per-object; a pre-built value would be frozen after the
+first iteration). The *steady state* row uses a pre-built, already-shareable
+value and measures the policy call alone. Compare fresh rows against the
+`:shared` fresh row (same construction overhead); read the steady-state row
+as the per-handoff cost once a value is shareable.
+
+`:hardened` (legacy) has no separate row: its mechanism — a Marshal
+round-trip — is exactly what `:isolated` uses, so the `:isolated` rows are
+its numbers.
+
+## Per-handoff throughput (i/s; higher is better)
+
+| Shape | `:shared` (fresh) | `:frozen` first handoff (fresh) | `:frozen` steady state | `:isolated` (fresh) | `:isolated` on already-frozen (§8.3) |
+|---|---|---|---|---|---|
+| small string token | 10.56M | 5.02M | **14.04M** | 1.44M | 1.57M |
+| array, 100 strings | 140.8k | 84.3k | **14.12M** | 34.5k | 46.6k |
+| hash, 100 pairs | 48.6k | 38.4k | **13.87M** | 14.1k | 20.4k |
+| nested document, ~5k nodes | 9.9k | 5.3k | **13.74M** | 1.9k | 2.4k |
+| deep nesting, 500 levels | 49.0k | 21.3k | **13.99M** | 8.5k | 10.8k |
+
+## Allocations per handoff (GC pressure)
+
+| Shape | `:shared` | `:frozen` (steady) | `:isolated` |
+|---|---|---|---|
+| small string token | 0 | 0 | 5 |
+| array, 100 strings | 0 | 0 | 105 |
+| hash, 100 pairs | 0 | 0 | 205 |
+| nested document | 0 | 0 | 1,711 |
+| deep nesting, 500 levels | 0 | 0 | 504 |
+
+## Findings
+
+1. **The §8.2 amortization claim holds.** Once a value is shareable,
+   `:frozen`'s per-handoff cost is a flat ~71ns **independent of value
+   size** (13.7–14.1M i/s across every shape) with zero allocations.
+   In an N-worker pipeline, only the first boundary pays the freeze
+   traversal; boundaries 2..N are effectively free. Combined with
+   copy-on-write task code, per-boundary cost is proportional to the
+   *change*, not the value.
+2. **First-handoff freeze costs roughly 0.6–1.9× the value's own
+   construction cost** (e.g. ~4.8µs extra for a 100-string array that
+   costs ~7.1µs to build) — paid once per object graph, not per hop.
+3. **`:isolated` is the expensive policy, as designed**: 3–7× slower than
+   `:shared` per boundary *per hop*, and the only policy that allocates
+   (a full copy of the graph per boundary — 1,711 objects per handoff for
+   the ~5k-node document). This is why it is not the default.
+4. **§8.3 fast-path decision: keep option (b) — no fast path.** The
+   "already-frozen" column is the pure Marshal cost on a pre-built value
+   (no construction overhead): 92µs for the deep-nested shape, 21µs for
+   the mid array, versus ~71ns if a `Ractor.shareable?` check skipped
+   the copy — so a fast path would make those handoffs roughly three
+   orders of magnitude cheaper *when inputs are already shareable*.
+   It still loses: it would hand the task a frozen object where the
+   `:isolated` contract promises a mutable scratch copy. Contract
+   simplicity wins at this gem's scale. Reopen trigger: a real workload
+   where `:isolated` boundaries dominate and their inputs are typically
+   already shareable.
+5. **The `:frozen` default is vindicated**: it is the only policy that is
+   simultaneously safe and, at steady state, the cheapest of the three.

data/benchmark/handoff_policies.rb

@@ -0,0 +1,82 @@
+# Handoff policy benchmarks (spec §8.4). Manual-run, not CI:
+#
+#   bundle exec ruby benchmark/handoff_policies.rb
+#
+# Measures, per policy and value shape:
+#   1. per-handoff cost of :shared / :frozen / :isolated / legacy :hardened
+#      (Marshal), including :frozen's first-handoff vs steady-state cost
+#      (the §8.2 amortization claim), and
+#   2. the pure Marshal cost :isolated pays on an already-shareable
+#      value — the copy a Ractor.shareable? fast path would skip
+#      entirely (the §8.3 open question), and
+#   3. allocation counts per policy (GC pressure).
+#
+# Results feed the wiki Performance page.
+
+require "bundler/setup"
+require "shifty"
+require "benchmark/ips"
+
+SHAPES = {
+  "small token (string)" => -> { +"a token" },
+  "mid array (100 strings)" => -> { Array.new(100) { |i| "item-#{i}" } },
+  "mid hash (100 pairs)" => -> { Array.new(100) { |i| ["key-#{i}", "value-#{i}"] }.to_h },
+  "large document (nested, ~5k nodes)" => -> {
+    Array.new(50) do |i|
+      {"id" => i, "name" => "record-#{i}",
+       "tags" => Array.new(10) { |t| "tag-#{t}" },
+       "children" => Array.new(10) { |c| {"idx" => c, "payload" => "data-#{i}-#{c}"} }}
+    end
+  },
+  "deep nesting (500 levels)" => -> {
+    (1..500).reduce([]) { |acc, i| [i, acc] }
+  }
+}
+
+null_worker = Object.new
+def null_worker.name = "bench"
+
+def null_worker.tags = []
+
+puts "Ruby #{RUBY_VERSION} — #{RUBY_PLATFORM}"
+puts
+
+SHAPES.each do |label, build|
+  puts "=" * 72
+  puts "SHAPE: #{label}"
+  puts "=" * 72
+
+  Benchmark.ips do |x|
+    x.report(":shared") do
+      Shifty::Policy::Shared.call(build.call, worker: null_worker)
+    end
+    x.report(":frozen (first handoff — fresh value each time)") do
+      Shifty::Policy::Frozen.call(build.call, worker: null_worker)
+    end
+    frozen_value = Ractor.make_shareable(build.call)
+    x.report(":frozen (steady state — already shareable)") do
+      Shifty::Policy::Frozen.call(frozen_value, worker: null_worker)
+    end
+    x.report(":isolated (Marshal deep copy)") do
+      Shifty::Policy::Isolated.call(build.call, worker: null_worker)
+    end
+    x.report(":isolated on already-frozen value (§8.3 fast-path question)") do
+      Shifty::Policy::Isolated.call(frozen_value, worker: null_worker)
+    end
+    x.compare!
+  end
+
+  # Allocation pressure per single handoff
+  value = build.call
+  frozen_value = Ractor.make_shareable(build.call)
+  {":shared" => [Shifty::Policy::Shared, value],
+   ":frozen (steady)" => [Shifty::Policy::Frozen, frozen_value],
+   ":isolated" => [Shifty::Policy::Isolated, value]}.each do |name, (policy, v)|
+    GC.start
+    before = GC.stat(:total_allocated_objects)
+    100.times { policy.call(v, worker: null_worker) }
+    allocated = GC.stat(:total_allocated_objects) - before
+    puts format("allocations per handoff %-20s %8.1f", name, allocated / 100.0)
+  end
+  puts
+end

data/docs/planning/artifacts/.discovery-notes.md

@@ -0,0 +1,40 @@
+# Discovery Notes — Handoff Immutability Policies implementation planning
+
+## Tech stack
+- Ruby gem "shifty", current version 0.5.0 (`lib/shifty/version.rb`). No `required_ruby_version` in gemspec yet (decision: add `>= 3.2`).
+- Local Ruby: 4.0.5 (arm64-darwin). Runtime deps: none (stdlib only; `ostruct`, `forwardable`, `fiber`).
+- Tests: RSpec 3.x + rspec-given (Given/When/Then style), simplecov; specs in `spec/shifty/{worker,gang,roster,dsl}_spec.rb`; `.rspec_status` persistence; monkey-patching disabled.
+- Lint: standardrb (`.standard.yml` ignores Layout/ExtraSpacing). Rakefile standard bundler/gem_tasks (build via `rake build` / `gem build`).
+- CI: `.github/` exists (workflows not yet examined by specialists — check if Ruby matrix needs updating for the 3.2 floor).
+
+## Source spec
+- `docs/planning/handoff-immutability-policies.md` — full design doc, 13 sections + appendix. Treat as ground truth for WHAT. No plan-a-feature artifacts (no decision-log/team-findings/feature-technical-notes).
+
+## Code touch points
+- `lib/shifty/worker.rb` — Worker: `initialize(p = {}, &block)` takes `:supply, :task, :context, :criteria, :tags`. Fiber-based `workflow` loop at line ~62: `Fiber.yield @task.call(value, supply, @context)` — THE handoff site for task output; `value = supply&.shift` is the intake site. Has `supply=` writer (no `task=` writer despite spec §5.4 mentioning one — only `@task ||= default_task` lazily). Extensive concurrency-model comment block (lines 90–130) added by PR #26; forward-references this plan and must be updated from "planned" to shipped.
+- `lib/shifty/dsl.rb` — DSL worker constructors: `source_worker`, `relay_worker`, `side_worker` (has `mode: :hardened` → `Marshal.load(Marshal.dump(v))` at lines 40–41 — the feature to deprecate/subsume), `filter_worker`, `batch_worker` (BatchContext < OpenStruct), `splitter_worker` (mutates `parts` array internally via `parts.shift` — internal, not the handed-off value), `trailing_worker` (accumulates `trail` array in closure AND hands off `trail` itself — a live aliasing case under `:frozen`; hands off the same array it keeps mutating via unshift/pop!). `handoff` = `Fiber.yield`.
+- `lib/shifty/gang.rb` — Gang wraps Roster; `initialize(workers = [], p = {})`; `shift` delegates to `roster.last.shift`; `Gang[*workers]` constructor; `|`/`supplies` composition same as Worker.
+- `lib/shifty/roster.rb` — push/pop/shift/unshift rewires `supply` — mutation of topology, relevant to §5.4 `#freeze!`.
+- `lib/shifty/taggable.rb` — tags/criteria mixin shared by Worker and Gang.
+- `lib/shifty.rb` — requires all; no `Shifty.configure` exists yet (global config is new).
+- No `Shifty::Testing`, no RSpec helpers shipped by the gem today.
+
+## Important behavioral details for policy implementation
+- Composition (`|`) links workers by setting `supply`; there is NO chain/pipeline object for plain worker chains — a "pipeline" is just the last worker; Gang is the only reifying container. `.with_policy` on a composed chain must therefore live on Worker (and Gang) and propagate upstream via the supply chain.
+- `filter_worker` and `batch_worker` tasks call `supply.shift` themselves mid-task — values obtained that way ALSO cross a boundary (policy must apply at intake, not just at task-output yield, or these secondary intakes leak).
+- `splitter_worker` and `source_worker` use `handoff` (Fiber.yield) directly from inside the task — multiple handoffs per task call; policy application at the single `Fiber.yield @task.call(...)` site won't see these. Handoff site analysis is a core design task.
+- `trailing_worker` hands off its live closure array — will break under `:frozen` default; the spec (§7.3) says this is exactly the bug class the policy should catch; the shipped worker itself must be fixed (hand off a snapshot).
+- Worker's nil sentinel: nil marks end-of-stream; `relay_worker`/`side_worker` guard `value &&`. nil is already frozen/shareable — no policy cost.
+- `@context` (OpenStruct) is closure-ish per-worker state passed to tasks — NOT a handoff; stays mutable per spec §12.
+
+## ADRs / coding standards
+- None found (no docs/adr, no coding standards docs). Style = standardrb defaults. Doc precedent: `docs/use_cases.md`, `docs/shifty/worker.md`, README.md (rewritten by PR #26 with "Concurrency Model" section).
+
+## Recent activity (90 days)
+- 1dc5433 planning doc (this feature); 847ee06/d14823a PR #26 concurrency docs (README.md, docs/use_cases.md, lib/shifty/worker.rb comments); 43d5948 concurrency analysis; 5e8ca16 arity fix in dsl.rb.
+
+## Gaps searched and not found
+- No CLAUDE.md/AGENTS.md in repo. No CI examination yet. No benchmark tooling (no benchmark-ips in Gemfile). No existing implementation-plan format precedent in this repo.
+
+## User-committed decisions (from Joel, this session)
+1. Version 0.6.0, all four spec phases ship in it. 2. required_ruby_version >= 3.2. 3. API: worker `policy:` kwarg; chainable `.with_policy(:p)` on Worker AND Gang; `policy:` kwarg on Gang; `Shifty.configure { |c| c.default_policy = ... }`; built-in default `:frozen`; precedence worker > pipeline > global. 4. One PR per phase. 5. Wiki content drafted under `docs/wiki/`, pushed to GitHub wiki after merge. 6. `:hardened` deprecated → mapped to `:isolated` with warning. 7. §8.3 option (b) — no shareable? fast path initially; worker declarations authoritative, pipeline policy default-only. 8. Joel publishes the gem himself (2FA); plan ends at built gem + release prep.