diff --git a/CHANGELOG.md b/CHANGELOG.md
index c15d19e..53d7ff4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -106,15 +106,53 @@ described below. Everything here is relative to `deepl_diff` 2.2.0.
   configuration still setting `deepl_host` raises `NoMethodError` on
   `TranslationDiff.configure`. Rename it.
 - A provider returning the wrong number of translations now raises
-  `TranslationDiff::ResponseError`, not `TranslationDiff::Request::Error`.
-  `Request::Error` still exists, and still means "`from:` is missing and the
-  provider cannot detect"; a `rescue TranslationDiff::Request::Error` written
-  to catch a short response no longer catches one. Both are
-  `TranslationDiff::Error`, so a rescue of the base class is unaffected.
+  `TranslationDiff::ResponseError`, not the error that used to live on
+  `Request`; a `rescue` written to catch a short response that way no longer
+  catches one. Both are `TranslationDiff::Error`, so a rescue of the base
+  class is unaffected.
 - A provider returning a well-formed response that carries no translation for
   one input -- Azure answers 200 for a batch where a single string failed --
   also raises `TranslationDiff::ResponseError`, naming the position. It
-  previously reached `Spacing.restore` and died there as `NoMethodError`.
+  previously reached the spacing step and died there as `NoMethodError`.
+- **The translation pipeline is new code.** `TranslationDiff::Linearizer`,
+  `Spacing`, `Chunker`, `Tokenizer`, `Cache` and `Request` are gone as public
+  constants. What replaces them: `Document` and `Leaves` (walking the
+  caller's structure), `Passage`, `Fragment` and `Segment` (markup and prose,
+  cut into sentences), `Markup` (entity references and a `<` that opens no
+  tag), `Batch` (packing sentences into provider requests), `SentenceCache`
+  (the cache key, read and write) and `Translator` (the coordinator
+  `TranslationDiff.translate` and `Context#translate` now build). See
+  [How it works](docs/how-it-works.md). If you referenced any of the six by
+  name, that reference is now a `NameError`.
+- `TranslationDiff::Request::Error` is now `TranslationDiff::Translator::Error`
+  and `TranslationDiff::Cache::Error` is now
+  `TranslationDiff::SentenceCache::Error`. There is no alias for either: this
+  gem has never been published under the name `translation_diff` with those
+  constants in it. `TranslationDiff::Chunker::Error` is gone with no
+  replacement -- a single sentence too large to send now raises
+  `TranslationDiff::Batch::Error`. All three remain
+  `TranslationDiff::Error`, so a rescue of the base class is unaffected.
+- **`TranslationDiff.translate` and `Context#translate` raise `ArgumentError`
+  when `to:` is missing or `nil`.** The keyword still defaults to `nil` in the
+  signature, and the message names it. Previously a `nil` target compared
+  equal to a `nil` source, the call short-circuited as "same language" and
+  your values came back untranslated, silently. If you have a caller reading
+  `to:` out of a configuration that can be blank, it has been a no-op and will
+  now raise.
+- **The `cache` instrumentation event fires once per `translate` call, not
+  once per chunk.** The cache is now consulted for every sentence in one
+  `read_multi` before anything is batched. `hits` and `misses` still sum to
+  the same totals over a call, so a counter that adds them up is unaffected;
+  a counter of *events*, or a histogram of per-chunk hit ratios, will see the
+  cardinality drop. `request` and `rate_limit` still fire once per batch sent.
+- **Two more cache keys move, beyond the entity and `<` fixes below.** A
+  sentence padded with Unicode whitespace -- a non-breaking space, say -- now
+  keys as the bare sentence: the pipeline uses one Unicode-aware definition
+  of padding everywhere, where the key used to be built with ASCII `strip`,
+  which leaves a `U+00A0` in place. And the whole document key format is
+  otherwise unmoved: it is pinned by test against recorded values, and every
+  other input in the corpus this rewrite was judged against produces the same
+  key it did before.
 
 ### Removed
 
@@ -297,6 +335,29 @@ described below. Everything here is relative to `deepl_diff` 2.2.0.
 - DeepL's batch limit was declared as 300 sentences per request; DeepL
   documents 50. The request-size limit (1,700 escaped characters) was
   already correct and is unchanged.
+- **An entity reference no longer reaches the provider raw.** `Salt &amp;
+  pepper.` was sent to the provider as the six characters `&amp;`, so the
+  provider translated the entity's spelling as if it were words -- and was
+  billed for it. It is now sent as `Salt & pepper.`, the text the document
+  actually says, and re-encoded on the way out. Named entities, `&#38;` and
+  `&#x26;` alike are decoded; anything neither decoder knows is left as it
+  arrived.
+- **A bare `<` no longer swallows the rest of the sentence.** `if a < b then
+  stop. Fine.` was parsed by `ox` as prose followed by an unclosed tag, so
+  only `if a` was ever sent for translation and everything after the `<` came
+  back untranslated. A `<` that no element name, closing name, declaration or
+  instruction follows is now escaped before parsing and restored after, so the
+  whole sentence is translated. `5 < 6 and 7 > 6. True.` was sent as three
+  fragments and is now sent as two sentences.
+- **These two fixes move the cache key for the documents they affect.** A
+  document containing an entity reference, or a `<` that opens no tag, will
+  miss the cache once and be re-translated. That is the point: what was cached
+  for it was translated from the wrong text.
+- **A known remaining limit: `&lt;` still reaches a provider undecoded**, and
+  `a <b then stop. Fine.` still loses everything after the `<`. Both fall out
+  of escaping a bare `<` as `&lt;` to work around `ox` rather than replacing
+  it with a lexer of this gem's own, which is out of scope here. `<b` cannot
+  be told apart from a tag without one. Every other entity is decoded.
 
 ## [2.2.0] - 2026-09-07
 
diff --git a/README.md b/README.md
index dd97818..8b9d6a2 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,6 @@
 
 A translation cache that helps translate only changes between revisions of long texts.
 
-**TranslationDiff** based on [GoogleTranslateDiff](https://github.com/gzigzigzeo/google_translate_diff)
-
 ## Why TranslationDiff?
 
 Assume your project contains a significant amount of products descriptions which:
diff --git a/docs/caching.md b/docs/caching.md
index e4d1d2f..f257a25 100644
--- a/docs/caching.md
+++ b/docs/caching.md
@@ -20,6 +20,35 @@ once.
 Both read and write the same cache, keyed per provider, so switching one
 never serves you the other's translations.
 
+`TranslationDiff::SentenceCache` is the class that builds the key and does
+both the read and the write.
+
+## The options digest is lossy, on purpose
+
+The per-call options are canonicalised to a string before they are digested,
+and that canonical form flattens more than it distinguishes. Nesting is not
+recorded, so `["x", ["y", "z"]]` and `["x", "y", "z"]` canonicalise
+identically; neither is emptiness typed, so `tags: []` and `tags: {}` do
+too. Two calls whose options differ only in one of those ways share a cache
+entry.
+
+This is a known property, not an oversight. The pipeline this replaced
+collides on exactly the same inputs -- that was checked, not assumed -- so
+reproducing it was the choice that left every warm cache warm. Fixing it
+would give those calls new keys and re-translate everything already cached
+under the old ones, for a distinction no provider option this gem ships
+actually makes. If you pass an option where that distinction matters, give
+the configuration its own `cache_namespace`.
+
+A value the canonical form cannot render at all -- anything that is not a
+String, Symbol, Numeric, `true`, `false`, `nil`, or an Array or Hash of
+those -- raises `TranslationDiff::SentenceCache::Error` rather than being
+guessed at. A key that is silently wrong costs you the whole cache and tells
+you nothing.
+
+No options at all contributes no field to the key, which is the four-field
+key every already-warm cache is keyed on.
+
 ## The cache store contract
 
 `config.cache` accepts either a registered name (`:redis`, `:memory`) or an
diff --git a/docs/errors.md b/docs/errors.md
index bef6093..34b0756 100644
--- a/docs/errors.md
+++ b/docs/errors.md
@@ -23,13 +23,13 @@ TranslationDiff::Error
 │                                                # that returned no translation for an input
 ├── TranslationDiff::InvalidProviderError       # a class registered without inheriting
 │                                                # TranslationDiff::Provider
-├── TranslationDiff::Request::Error             # from: missing and the provider cannot
+├── TranslationDiff::Translator::Error          # from: missing and the provider cannot
 │                                                # detect, cache_key missing on an
 │                                                # assigned provider object
-├── TranslationDiff::Cache::Error               # provider options have no stable
+├── TranslationDiff::SentenceCache::Error       # provider options have no stable
 │                                                # serialisation for the cache key
-├── TranslationDiff::Chunker::Error             # a single value is larger than the
-│                                                # provider's declared max_request_size
+├── TranslationDiff::Batch::Error               # one sentence, once escaped, is larger
+│                                                # than the provider's declared limit
 ├── TranslationDiff::Segmenters::Pragmatic::Error
 │                                                # Pragmatic computed offsets that
 │                                                # violate its own postcondition --
@@ -43,6 +43,24 @@ and `#status` (the HTTP status code), so a caller can log or branch on which
 service and which response caused the failure without parsing the message.
 
 `TranslationDiff::Registry` -- which backs the provider, cache store and
-segmenter registries -- also raises `TranslationDiff::Error` directly (not a
+segmenter registries -- raises `TranslationDiff::Error` directly (not a
 dedicated subclass) for an unknown name, listing what is actually
-registered.
+registered. `TranslationDiff::Batch::Error` is its own class rather than a
+direct `TranslationDiff::Error`, so a caller can catch "this sentence is too
+long for this provider" without also catching an unrelated registry miss; it
+is raised when one sentence is larger once escaped than the provider's
+declared `max_request_size` or `max_text_size` and so could never be sent
+even in a batch of its own. The message names a short prefix of the
+offending text and both numbers.
+
+`ArgumentError`, not a `TranslationDiff::Error`, is what
+`TranslationDiff.translate` and `Context#translate` raise when `to:` is
+missing or `nil`. It is a caller's mistake before it is a translation, and
+the message names the keyword.
+
+**Renamed in 3.1.0.** `TranslationDiff::Request::Error` is now
+`TranslationDiff::Translator::Error` and `TranslationDiff::Cache::Error` is
+now `TranslationDiff::SentenceCache::Error`; both classes they hung off are
+gone. `TranslationDiff::Chunker::Error` is gone with no replacement -- the
+condition it named now raises `TranslationDiff::Batch::Error`. A
+`rescue TranslationDiff::Error` catches all three exactly as before.
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 64d1c2c..2e9adb3 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -1,11 +1,59 @@
 # How it works
 
-- Text nodes are extracted from HTML.
-- Every text node is split into sentences by `config.segmenter` (see
-  [The segmenter contract](contracts.md#the-segmenter-contract)).
-- Cache is checked for the presence of each sentence (using language couple and a hash of string).
-- Missing sentences are translated via the provider and cached.
-- Original HTML is recombined from translations and cache data.
+A call to `TranslationDiff.translate` walks a value, cuts the prose in it
+into sentences, translates only the sentences no cache already holds, and
+puts the value back together in the shape it arrived in.
+
+`TranslationDiff::Translator` is the one class that coordinates all of it.
+Everything below is a collaborator it drives.
+
+## The steps
+
+1. **The caller's structure is walked, not flattened.**
+   `TranslationDiff::Document` visits every leaf `String` of a String, Array
+   or deep Hash and can rebuild the same shape from new leaves.
+   `TranslationDiff::Leaves` holds the two promises the structure itself does
+   not: a nested `nil` comes back as `""`, and the `values` count in an event
+   payload is every leaf the caller wrote, translatable or not.
+
+2. **Each leaf becomes a passage of markup and prose.**
+   `TranslationDiff::Passage` parses the string with `ox` and records where
+   every construct begins, so each run of the source is either markup --
+   tags, comments, CDATA, doctypes, processing instructions, `<script>` and
+   `<style>` bodies, and anything inside `class="notranslate"` -- or prose.
+   Each run becomes a `TranslationDiff::Fragment`, and a fragment is always a
+   slice of the source, never a rebuilt string.
+
+3. **Prose is cut into sentences.**
+   A prose fragment is split by `config.segmenter` (see [The segmenter
+   contract](contracts.md#the-segmenter-contract)) into
+   `TranslationDiff::Segment`s. A segment keeps the whitespace it was found
+   in: its `#core` is the text a provider sees, with entity references
+   decoded to the characters they mean, and its `#render` is markup again.
+
+4. **The cache is consulted once, for every sentence at once.**
+   `TranslationDiff::SentenceCache` builds one key per sentence and reads
+   them all in a single `read_multi`. Sentences it answers for are already
+   done; the rest are misses. See [Caching](caching.md).
+
+5. **The misses are packed into requests.**
+   `TranslationDiff::Batch.pack` groups the missing sentences into batches
+   that fit inside the provider's declared `max_batch_size` and
+   `max_request_size` -- its `TranslationDiff::Capabilities` (see
+   [Providers](providers.md)). Each batch is sent, and the reply is
+   applied back onto the very segments that produced it -- no step ever
+   correlates a translation to a sentence by position after the fact.
+
+6. **What came back is written home, and the value is rebuilt.**
+   Only sentences that actually got a translation are cached. Then each
+   passage renders itself -- markup fragments byte-exact, translated
+   sentences re-encoded as HTML text -- and `Document` puts the renders back
+   into the caller's shape.
+
+`TranslationDiff::Markup` is the small module underneath steps 2, 3 and 6: it
+decodes entity references on the way to a provider, encodes `&` and `<` again
+on the way out, and escapes a `<` that opens no tag so `ox` cannot read the
+rest of the sentence as markup.
 
 *NOTE:* if `:from` is not specified or equal to nil, then the provider's `#detect` will be called once with a sample of text up to 100 characters long to determine the language, and `#translate` will be called separately with the entire text.
         Try to specify `:from` explicitly to save the extra call -- it also improves segmentation, since the segmenter only sees a language when `:from` is given (see [The segmenter contract](contracts.md#the-segmenter-contract)).
@@ -22,7 +70,13 @@ TranslationDiff.translate(
 )
 ```
 
-See `TranslationDiff::Linearizer` for details.
+A leaf that is not a `String` -- a number, a symbol, `true` -- is handed back
+untouched. A nested `nil` comes back as `""`. See
+`TranslationDiff::Document` and `TranslationDiff::Leaves` for details.
+
+`to:` is not optional. It defaults to `nil` in the signature and a `nil`
+target raises `ArgumentError` naming the keyword, rather than silently
+handing your values back untranslated.
 
 ## HTML
 
diff --git a/docs/instrumentation.md b/docs/instrumentation.md
index e3d51ce..f26f285 100644
--- a/docs/instrumentation.md
+++ b/docs/instrumentation.md
@@ -11,9 +11,16 @@ A translation emits up to four events, each named `<name>.translation_diff`:
 | Event | Fired | Payload |
 | --- | --- | --- |
 | `translate` | Once per `translate` call that reaches the provider, wrapping the whole thing. A call whose source and target languages are the same, or whose values hold no translatable text at all, returns early and emits no events. | `from`, `to`, `provider`, `values` (number of texts) |
-| `cache` | Once per chunk, after checking the cache. | `provider`, `hits`, `misses` |
-| `request` | Once per chunk actually sent to the provider (skipped entirely on a full cache hit). | `provider`, `batch` (values sent), `characters` |
-| `rate_limit` | Once per chunk sent to the provider, only when a rate limiter is configured. | `provider`, `characters` |
+| `cache` | Once per `translate` call that reaches the provider, after checking the cache for every sentence at once. | `provider`, `hits`, `misses` |
+| `request` | Once per batch actually sent to the provider (skipped entirely on a full cache hit). | `provider`, `batch` (values sent), `characters` |
+| `rate_limit` | Once per batch sent to the provider, only when a rate limiter is configured. | `provider`, `characters` |
+
+**`cache` fires once per call as of 3.1.0, not once per chunk.** The cache is
+now consulted for every sentence in one `read_multi` before anything is
+batched, so there is one event where there used to be one per chunk. `hits`
+and `misses` still sum to the same totals over a call, so a counter that adds
+them up is unaffected; a counter of *events*, or a histogram of per-chunk hit
+ratios, will see the cardinality drop.
 
 **Instrumentation payloads never contain the text being translated, its
 translation, or a credential.** This is a guarantee, not an implementation
diff --git a/docs/providers.md b/docs/providers.md
index 44d9392..24bf308 100644
--- a/docs/providers.md
+++ b/docs/providers.md
@@ -146,7 +146,7 @@ subtag is its own. A provider of your own gets the same rule from
 `TranslationDiff::Provider#language`; declare `def self.language_case =
 :upcase` if your vendor wants upper case.
 
-"Request size" is what `Chunker` measures: the URL-escaped form of each
+"Request size" is what `TranslationDiff::Batch` measures: the URL-escaped form of each
 string (`CGI.escape(text).size`), which is never smaller than its UTF-8 byte
 count. "HTML support" names the provider option that turns HTML handling on
 -- every vendor spells it differently, which is exactly what
diff --git a/lib/translation_diff.rb b/lib/translation_diff.rb
index 2011962..fa1639d 100644
--- a/lib/translation_diff.rb
+++ b/lib/translation_diff.rb
@@ -13,6 +13,14 @@
 require "translation_diff/translation/request"
 require "translation_diff/translation/response"
 require "translation_diff/registry"
+require "translation_diff/document"
+require "translation_diff/leaves"
+require "translation_diff/markup"
+require "translation_diff/segment"
+require "translation_diff/batch"
+require "translation_diff/fragment"
+require "translation_diff/passage"
+require "translation_diff/sentence_cache"
 require "translation_diff/configuration"
 require "translation_diff/configuration/provider_option_owners"
 
@@ -31,17 +39,12 @@
 require "translation_diff/segmenters"
 require "translation_diff/segmenters/simple"
 require "translation_diff/segmenters/pragmatic"
-require "translation_diff/tokenizer"
-require "translation_diff/linearizer"
-require "translation_diff/chunker"
-require "translation_diff/spacing"
-require "translation_diff/cache"
 require "translation_diff/stores"
 require "translation_diff/memory_cache_store"
 require "translation_diff/redis_cache_store"
 require "translation_diff/redis_rate_limiter"
 require "translation_diff/instrumentation"
-require "translation_diff/request"
+require "translation_diff/translator"
 require "translation_diff/context"
 
 module TranslationDiff
@@ -58,7 +61,7 @@ def context(&) = Context.new(config.copy.tap(&))
 
     # `provider:` and `config:` are reserved; every other keyword is forwarded to the provider.
     def translate(values, from: nil, to: nil, provider: nil, **)
-      Request.new(values, from: from, to: to, provider: provider, config: config, **).call
+      Translator.new(values, from: from, to: to, provider: provider, config: config, **).call
     end
   end
 end
diff --git a/lib/translation_diff/batch.rb b/lib/translation_diff/batch.rb
new file mode 100644
index 0000000..7b82e0f
--- /dev/null
+++ b/lib/translation_diff/batch.rb
@@ -0,0 +1,98 @@
+# Segments grouped to one provider request; a reply lands back on them through #apply, never by position after the fact.
+class TranslationDiff::Batch
+  # Its own class, so rescuing a sentence too long to send cannot also swallow a registry miss.
+  class Error < TranslationDiff::Error; end
+
+  attr_reader :segments
+
+  def initialize(segments)
+    @segments = segments
+  end
+
+  def texts = segments.map(&:core)
+
+  # Each translation lands on the segment at the same index in this batch, the segment that produced it.
+  def apply(translations)
+    ensure_reply_size!(translations)
+    segments.each_with_index { |segment, index| segment.translation = translations[index] }
+  end
+
+  class << self
+    # Skips blank segments -- a provider has no use for whitespace -- then fills batches within both declared limits.
+    def pack(segments, capabilities:)
+      filler = Filler.new(capabilities)
+      segments.reject(&:empty?).each { |segment| filler.add(segment) }
+      filler.batches
+    end
+  end
+
+  private
+
+  def ensure_reply_size!(translations)
+    return if translations.size == segments.size
+
+    raise TranslationDiff::ResponseError,
+          "Provider returned #{translations.size} translations for #{segments.size} segments"
+  end
+
+  # Fills one batch until its count or its cumulative escaped size would cross the limit, then starts the next.
+  class Filler
+    def initialize(capabilities)
+      @capabilities = capabilities
+      @batches = []
+      @current = []
+      @current_size = 0
+    end
+
+    def add(segment)
+      size = escaped_size(segment)
+      flush if full?(size)
+      @current << segment
+      @current_size += size
+    end
+
+    def batches
+      flush
+      @batches
+    end
+
+    private
+
+    # Escaped, because that is the size a provider's own limit is documented against and what goes over the wire.
+    def escaped_size(segment)
+      size = CGI.escape(segment.core).size
+      ensure_sendable!(segment, size)
+      size
+    end
+
+    # A text over either declared limit can never be sent, alone or otherwise, so this raises before any batch fills.
+    def ensure_sendable!(segment, size)
+      limit = [@capabilities.max_request_size, @capabilities.max_text_size].compact.min
+      return if size <= limit
+
+      raise TranslationDiff::Batch::Error,
+            "#{preview(segment.core)} is #{size} characters once escaped, over this provider's limit of #{limit}"
+    end
+
+    # A short prefix locates the offending text without reproducing it -- the rest is the customer's content.
+    def preview(text)
+      return text.dup if text.size <= 20
+
+      "#{text[0, 20]}..."
+    end
+
+    def full?(size)
+      return false if @current.empty?
+
+      @current.size >= @capabilities.max_batch_size || @current_size + size > @capabilities.max_request_size
+    end
+
+    def flush
+      return if @current.empty?
+
+      @batches << TranslationDiff::Batch.new(@current)
+      @current = []
+      @current_size = 0
+    end
+  end
+end
diff --git a/lib/translation_diff/cache.rb b/lib/translation_diff/cache.rb
deleted file mode 100644
index 15afd92..0000000
--- a/lib/translation_diff/cache.rb
+++ /dev/null
@@ -1,69 +0,0 @@
-class TranslationDiff::Cache
-  class Error < TranslationDiff::Error; end
-
-  # 32 bits of digest is ample to keep option sets apart without bloating every key in the cache.
-  DIGEST_LENGTH = 8
-
-  # No attr_reader for `store`: #store is already the public method that writes translations back.
-  def initialize(from, to, provider:, store:, options: {})
-    @from = from
-    @to = to
-    @provider = provider
-    @store = store
-    @options = options
-  end
-
-  def cached_and_missing(values)
-    keys = values.map { |v| key(v) }
-    cached = @store.read_multi(keys)
-    missing = values.map.with_index { |v, i| v if cached[i].nil? }.compact
-
-    [cached, missing]
-  end
-
-  # Indexes rather than shifting: #store is public and takes an outside array, which is not ours to consume.
-  def store(values, cached, updates)
-    update = -1
-
-    cached.map.with_index do |value, index|
-      value || store_value(values[index], updates[update += 1])
-    end
-  end
-
-  private
-
-  attr_reader :from, :to, :provider, :options
-
-  def store_value(value, translation)
-    @store.write(key(value), translation)
-    translation
-  end
-
-  def key(value)
-    hash = Digest::MD5.hexdigest(value.strip) # No matter how much spaces
-
-    [provider, language(from), language(to), options_digest, hash].compact.join(":")
-  end
-
-  # "EN" and :en are the same language; also must never introduce a colon, the key-join separator.
-  def language(code)
-    code.to_s.downcase
-  end
-
-  # Two calls differing only in formality or glossary must not share a key.
-  def options_digest
-    return @options_digest if defined?(@options_digest)
-
-    @options_digest = options.empty? ? nil : Digest::MD5.hexdigest(canonical(options))[0, DIGEST_LENGTH]
-  end
-
-  # Object#inspect isn't stable: Ruby 3.4 changed hash rendering, and default #inspect embeds an address.
-  def canonical(value)
-    case value
-    when Hash then value.sort_by { |key, _| key.to_s }.map { |key, item| "#{key}=#{canonical(item)}" }.join(",")
-    when Array then value.map { |item| canonical(item) }.join(",")
-    when String, Symbol, Numeric, true, false, nil then value.inspect
-    else raise Error, "Cannot build a stable cache key from #{value.class} in the provider options"
-    end
-  end
-end
diff --git a/lib/translation_diff/chunker.rb b/lib/translation_diff/chunker.rb
deleted file mode 100644
index 60268dd..0000000
--- a/lib/translation_diff/chunker.rb
+++ /dev/null
@@ -1,57 +0,0 @@
-class TranslationDiff::Chunker
-  class Error < TranslationDiff::Error; end
-
-  Chunk = Struct.new(:texts, :escaped_size)
-
-  # No defaults: a default silently lies about the second provider, a bug this file already had once.
-  def initialize(values, limit:, count_limit:)
-    @values = values
-    @limit = limit
-    @count_limit = count_limit
-  end
-
-  def call
-    chunks.map(&:texts)
-  end
-
-  def chunks
-    values.each_with_object([]) do |value, chunks|
-      validate_value_size(value)
-
-      tail = chunks.last
-
-      if next_chunk?(tail, value)
-        chunks << Chunk.new([], 0)
-        tail = chunks.last
-      end
-
-      update_chunk(tail, value)
-    end
-  end
-
-  private
-
-  attr_reader :values, :limit, :count_limit
-
-  def next_chunk?(tail, value)
-    tail.nil? ||
-      (escaped_size(value) + tail.escaped_size > limit) ||
-      tail.texts.size >= count_limit
-  end
-
-  # The limit is on wire size, so measure the escaped form -- String#size lets non-ASCII text run over.
-  def escaped_size(text)
-    CGI.escape(text).size
-  end
-
-  def update_chunk(chunk, value)
-    chunk.texts << value
-    chunk.escaped_size += escaped_size(value)
-  end
-
-  def validate_value_size(value)
-    size = escaped_size(value)
-
-    raise Error, "Too long part #{size} > #{limit}" if size > limit
-  end
-end
diff --git a/lib/translation_diff/context.rb b/lib/translation_diff/context.rb
index e0c94b0..44f9a12 100644
--- a/lib/translation_diff/context.rb
+++ b/lib/translation_diff/context.rb
@@ -7,7 +7,7 @@ def initialize(config)
   end
 
   def translate(values, from: nil, to: nil, provider: nil, **)
-    TranslationDiff::Request.new(
+    TranslationDiff::Translator.new(
       values, from: from, to: to, provider: provider, config: config, **
     ).call
   end
diff --git a/lib/translation_diff/document.rb b/lib/translation_diff/document.rb
new file mode 100644
index 0000000..18a1f16
--- /dev/null
+++ b/lib/translation_diff/document.rb
@@ -0,0 +1,23 @@
+# A caller's value together with its Hash/Array shape, walked without ever flattening it into an array.
+class TranslationDiff::Document
+  def initialize(value) = @value = value
+
+  # Returns a new structure of the same shape with every leaf String replaced by the block's result.
+  def map(&) = walk(@value, &)
+
+  # Returns the leaf strings in document order, without touching the original value.
+  def strings
+    [].tap { |acc| walk(@value) { |string| acc << string } }
+  end
+
+  private
+
+  def walk(node, &block)
+    case node
+    when Hash then node.to_h { |key, value| [key, walk(value, &block)] }
+    when Array then node.map { |value| walk(value, &block) }
+    when String then block.call(node)
+    else node
+    end
+  end
+end
diff --git a/lib/translation_diff/fragment.rb b/lib/translation_diff/fragment.rb
new file mode 100644
index 0000000..1dcdd33
--- /dev/null
+++ b/lib/translation_diff/fragment.rb
@@ -0,0 +1,33 @@
+# A run of the source that is either markup, handed back as found, or prose, handed back through its segments.
+class TranslationDiff::Fragment
+  EMPTY = [].freeze
+
+  attr_reader :source
+
+  # Markup has nothing a provider should see, so it carries no segments and renders the bytes it was cut from.
+  def self.markup(source) = new(source, nil)
+
+  # Prose is cut where the segmenter says sentences begin, so every segment keeps the whitespace it was found in.
+  def self.prose(source, segmenter:, language: nil)
+    new(source, cut(source, segmenter.split_offsets(source, language: language)))
+  end
+
+  # The offsets start at 0 and strictly increase, so slicing between them and from the last to the end is exact.
+  def self.cut(source, offsets)
+    sentences = offsets.each_cons(2).map { |from, to| source[from...to] } << source[offsets.last..]
+    sentences.map { |sentence| TranslationDiff::Segment.new(sentence) }
+  end
+  private_class_method :cut
+
+  def initialize(source, segments)
+    @source = source
+    @segments = segments
+  end
+
+  def markup? = @segments.nil?
+
+  def segments = @segments || EMPTY
+
+  # The slice is copied on the way out, as Segment copies its own: rendering must not hand a caller the passage.
+  def render = markup? ? source.dup : @segments.map(&:render).join
+end
diff --git a/lib/translation_diff/leaves.rb b/lib/translation_diff/leaves.rb
new file mode 100644
index 0000000..de6d191
--- /dev/null
+++ b/lib/translation_diff/leaves.rb
@@ -0,0 +1,22 @@
+# The two things this pipeline has always promised about a caller's structure that Document deliberately does not:
+# a nested nil comes back as the empty string, and the size of a document is every leaf in it, translatable or not.
+module TranslationDiff::Leaves
+  # Document hands every non-String leaf straight back, which is the honest behaviour for a general structural map.
+  # Answering a nested nil with "" is the pipeline's own promise, so it is made here rather than there.
+  def self.collapse_nils(node)
+    case node
+    when Hash then node.to_h { |key, value| [key, collapse_nils(value)] }
+    when Array then node.map { |value| collapse_nils(value) }
+    when nil then ""
+    else node
+    end
+  end
+
+  # Every leaf the caller wrote, whatever its type: the number a `translate` payload reports as `values`.
+  def self.count(node)
+    return node.each_value.sum { |value| count(value) } if node.is_a?(Hash)
+    return node.sum { |value| count(value) } if node.is_a?(Array)
+
+    1
+  end
+end
diff --git a/lib/translation_diff/linearizer.rb b/lib/translation_diff/linearizer.rb
deleted file mode 100644
index 3e2f913..0000000
--- a/lib/translation_diff/linearizer.rb
+++ /dev/null
@@ -1,27 +0,0 @@
-class TranslationDiff::Linearizer
-  class << self
-    def linearize(struct, array = [])
-      case struct
-      when Hash
-        struct.each_value { |v| linearize(v, array) }
-      when Array
-        struct.each { |v| linearize(v, array) }
-      else
-        array << struct
-      end
-
-      array
-    end
-
-    def restore(struct, array)
-      case struct
-      when Hash
-        struct.transform_values { |v| restore(v, array) }
-      when Array
-        struct.map { |v| restore(v, array) }
-      else
-        array.shift
-      end
-    end
-  end
-end
diff --git a/lib/translation_diff/markup.rb b/lib/translation_diff/markup.rb
new file mode 100644
index 0000000..e359922
--- /dev/null
+++ b/lib/translation_diff/markup.rb
@@ -0,0 +1,76 @@
+# Entity references, and a `<` that opens no tag: the two places a document's text is not the text `ox` reports.
+module TranslationDiff::Markup
+  # Escaping a lone `<` is a workaround around `ox`, not a fix of it: the real fix is our own lexer, and out of scope.
+
+  # A `<` opens a tag only when an element name, a closing name, a declaration or an instruction follows it.
+  TAG_OPENER = %r{[A-Za-z!?]|/[A-Za-z]}
+
+  # The two characters escaping has to move: a lone `<`, and an `&` that would read as an escape this module wrote.
+  AMBIGUOUS = /&(?=(?:amp;)*lt;)|<(?!#{TAG_OPENER})/
+
+  # `&lt;` was a lone `<`; every further `amp;` is a level the source itself wrote and escaping pushed up by one.
+  ESCAPED_ANGLE = /&((?:amp;)*)lt;/
+
+  # The bargain: an untranslated segment renders byte-exact, a translated one renders equivalent HTML, not equal bytes.
+
+  # Named and numeric alike, so nothing an `&` opens survives to be escaped again and rendered as its own spelling.
+  DECODABLE = /&(?:[A-Za-z][A-Za-z0-9]*|#\d+|#[xX]\h+);/
+
+  # Which of the two decoders an entity belongs to: Ox knows every HTML5 name, CGI knows both numeric forms.
+  NAMED = /\A&([A-Za-z][A-Za-z0-9]*);\z/
+
+  # Only the two characters that are unsafe in HTML text; every other decoded character is left as the character it is.
+  ENCODED = { "&" => "&amp;", "<" => "&lt;" }.freeze
+
+  ENCODABLE = /[&<]/
+
+  # Hands back markup `ox` can parse: same document, with every lone `<` written as the entity it should have been.
+  def self.escape_bare_angles(source)
+    source.gsub(AMBIGUOUS) { |ambiguous| ambiguous == "&" ? "&amp;" : "&lt;" }
+  end
+
+  # The exact inverse: one `amp;` off every escaped angle, and the angles with none left were the lone ones.
+  def self.restore_bare_angles(rendered)
+    rendered.gsub(ESCAPED_ANGLE) do
+      levels = Regexp.last_match(1)
+      levels.empty? ? "<" : "&#{levels.delete_prefix('amp;')}lt;"
+    end
+  end
+
+  # What a provider is sent is text, so it gets the characters; one left-to-right pass, so nothing is decoded twice.
+  def self.decode_entities(text) = text.gsub(DECODABLE) { |entity| decoded(entity) }
+
+  # An entity neither decoder knows stays as it arrived, and so does a surrogate: that decodes to invalid UTF-8.
+  def self.decoded(entity)
+    name = entity[NAMED, 1]
+    plain = name ? named(name) : CGI.unescapeHTML(entity)
+    plain.valid_encoding? ? plain : entity
+  end
+
+  # A document repeats the same handful of names, and only a name that resolved is kept, so the table cannot be grown.
+  def self.named(name) = resolved[name] || resolve(name)
+
+  def self.resolved = @resolved ||= {}
+
+  # One well-formed entity alone in an element is the only input Ox decodes safely -- prose with a lone `&` raises.
+  def self.resolve(name)
+    entity = "&#{name};"
+    resolver = Resolver.new
+    Ox.sax_html(resolver, StringIO.new("<e>#{entity}</e>"))
+    return entity if resolver.text.nil? || resolver.text == entity
+
+    resolved[name] = resolver.text
+  rescue StandardError
+    entity
+  end
+
+  # What a document renders is markup, so text that changed is made safe again -- and only where it is unsafe.
+  def self.encode_entities(text) = text.gsub(ENCODABLE, ENCODED)
+
+  # Ox hands back the decoded text of the one element it was given; a name it does not know arrives as the text it was.
+  class Resolver < Ox::Sax
+    attr_reader :text
+
+    def value(value) = @text = value.as_s
+  end
+end
diff --git a/lib/translation_diff/passage.rb b/lib/translation_diff/passage.rb
new file mode 100644
index 0000000..fa1117d
--- /dev/null
+++ b/lib/translation_diff/passage.rb
@@ -0,0 +1,141 @@
+# A source document as markup and prose: the markup kept as found, the prose cut into segments a provider can take.
+class TranslationDiff::Passage
+  attr_reader :fragments
+
+  # The source is scanned with every lone `<` escaped, so the offsets, the slices and the render all agree on it.
+  def initialize(source, segmenter:, language: nil)
+    @source = TranslationDiff::Markup.escape_bare_angles(source)
+    @segmenter = segmenter
+    @language = language
+    @fragments = Scanner.new(@source).runs.map { |run| fragment(run) }
+  end
+
+  # The translatable sentences, in document order; the empty ones are whitespace a provider has no use for.
+  def segments = fragments.flat_map(&:segments)
+
+  # Entities are a segment's business, so the only thing left to undo here is the escape this class put in.
+  def render
+    TranslationDiff::Markup.restore_bare_angles(fragments.map(&:render).join)
+  end
+
+  private
+
+  # Every fragment is a slice of the source, never a rebuilt string; that is what makes an untranslated render exact.
+  def fragment(run)
+    from, to, prose = run
+    slice = @source.byteslice(from, to - from)
+    return TranslationDiff::Fragment.markup(slice) unless prose
+
+    TranslationDiff::Fragment.prose(slice, segmenter: @segmenter, language: @language)
+  end
+
+  # Ox reports a byte position for every construct it sees; recording those is what lets rendering slice the source.
+  class Scanner < Ox::Sax
+    # Content nobody wants translated, however much of it looks like prose.
+    OPAQUE = %i[script style].freeze
+
+    # Providers honour this class themselves under the HTML mode this gem sends, so the element must reach them whole.
+    PROTECTED = "notranslate".freeze
+
+    OPENING_ANGLE = "<".ord
+
+    # Where a run begins and whether it is prose; prose is set after the fact when an element claims protection.
+    Mark = Struct.new(:offset, :prose)
+
+    # Ox reports positions only to a handler that already has the ivar, so @pos exists before parsing starts.
+    def initialize(source)
+      super()
+      @source = source
+      @pos = 0
+      @marks = []
+      @protected_depth = 0
+      @opaque_depth = 0
+      @pending = nil
+    end
+
+    # Triples of [first byte, last byte + 1, prose?], contiguous, covering the source exactly once.
+    def runs
+      Ox.sax_html(self, StringIO.new(@source))
+      merge(bounds)
+    end
+
+    # Protection beats opacity on purpose: a caller wrapping a subtree asked for it to be passed through as it is.
+    def start_element(name)
+      return @protected_depth += 1 if @protected_depth.positive?
+
+      @opaque_depth += 1 if @opaque_depth.positive? || OPAQUE.include?(name)
+      @pending = mark(prose: false)
+    end
+
+    # Attributes arrive straight after their own start element, so @pending is that element and never another.
+    def attr(name, value)
+      return unless @pending && protection?(name, value)
+
+      @pending.prose = true
+      @protected_depth = 1
+      @pending = nil
+    end
+
+    def end_element(_name)
+      return @protected_depth -= 1 if @protected_depth.positive?
+
+      @opaque_depth -= 1 if @opaque_depth.positive?
+      record(prose: false)
+    end
+
+    def value(_value) = record(prose: @opaque_depth.zero?)
+
+    def comment(_content) = record(prose: false)
+
+    def cdata(_content) = record(prose: false)
+
+    def doctype(_content) = record(prose: false)
+
+    def instruct(_target) = record(prose: false)
+
+    private
+
+    # Ox lowercases element names but not attribute names; the value stays exact because HTML class tokens are.
+    def protection?(name, value)
+      name.to_s.casecmp?("class") && value.split.include?(PROTECTED)
+    end
+
+    # Everything inside a protected element belongs to the run that element opened, so it records nothing of its own.
+    def record(prose:)
+      @pending = nil
+      return if @protected_depth.positive?
+
+      mark(prose: prose)
+    end
+
+    # Ox counts from one. A markup mark that does not land on a "<" is a tag Ox implied, not one the source holds.
+    def mark(prose:)
+      offset = @pos - 1
+      return nil if offset.negative? || (!prose && @source.getbyte(offset) != OPENING_ANGLE)
+
+      Mark.new(offset, prose).tap { |recorded| @marks << recorded }
+    end
+
+    # Each mark owns the source as far as the next one begins, and the last one owns whatever is left.
+    def bounds
+      marks = ordered
+      finishes = marks.drop(1).map(&:offset) << @source.bytesize
+      marks.zip(finishes).map { |mark, finish| [mark.offset, finish, mark.prose] }
+    end
+
+    # Ox skips the whitespace ahead of the first construct it reports, so a prose run is seeded where it starts.
+    def ordered
+      sorted = @marks.sort_by.with_index { |mark, index| [mark.offset, index] }
+      return sorted if sorted.first&.offset&.zero?
+
+      sorted.unshift(Mark.new(0, true))
+    end
+
+    # Adjacent prose has to become one run, or a notranslate element would be cut off from the sentence it sits in.
+    def merge(spans)
+      spans.reject { |from, to, _prose| from == to }
+           .chunk_while { |before, after| before.last == after.last }
+           .map { |chunk| [chunk.first[0], chunk.last[1], chunk.first[2]] }
+    end
+  end
+end
diff --git a/lib/translation_diff/request.rb b/lib/translation_diff/request.rb
deleted file mode 100644
index b193084..0000000
--- a/lib/translation_diff/request.rb
+++ /dev/null
@@ -1,198 +0,0 @@
-class TranslationDiff::Request
-  extend Forwardable
-  include TranslationDiff::Instrumentation
-
-  class Error < TranslationDiff::Error; end
-
-  def_delegators :"TranslationDiff::Linearizer", :linearize, :restore
-
-  def initialize(values, from: nil, to: nil, provider: nil, config: nil, **options)
-    @values = values
-    @from = from
-    @to = to
-    @provider = provider
-    @config = config || TranslationDiff.config
-    @options = options
-  end
-
-  def call
-    return values if same_language? || nothing_to_translate?
-
-    instrument("translate", from: from.to_s, to: to.to_s,
-                            provider: provider_cache_key, values: texts.size) do
-      translation
-    end
-  end
-
-  private
-
-  attr_reader :values, :options, :to, :config
-
-  # The `provider:` keyword when the caller gave one, otherwise whatever the configuration resolves to.
-  def api
-    @api ||= (@provider.nil? ? config.provider_instance : resolve_provider(@provider))
-             .tap { |provider| log("provider #{provider.class}") }
-  end
-
-  def resolve_provider(value)
-    return TranslationDiff::Providers.build(value, config) if value.is_a?(Symbol) || value.is_a?(String)
-
-    TranslationDiff::Providers.ensure_provider!(value)
-  end
-
-  def rate_limiter = config.rate_limiter_instance
-
-  def from
-    @from ||= detect_language
-  end
-
-  # A detected language is a String while :to is usually a Symbol -- without casecmp? this never short-circuits.
-  def same_language?
-    !to.nil? && from.to_s.casecmp?(to.to_s)
-  end
-
-  # Covers "", nil, an empty collection, or a scalar the tokenizer has nothing to say about.
-  def nothing_to_translate?
-    text_tokens_texts.all?(&:empty?)
-  end
-
-  def capabilities = api.class.capabilities
-
-  def detect_language
-    unless capabilities.detects_language?
-      raise Error, "Pass from: -- provider #{provider_cache_key} cannot detect the source language"
-    end
-
-    api.detect(text_tokens_texts.join(" ")[0..100])
-  end
-
-  def texts
-    @texts ||= linearize(values)
-  end
-
-  def tokens
-    @tokens ||= texts.map do |value|
-      TranslationDiff::Tokenizer.tokenize(value, segmenter: config.segmenter_instance, language: source_language)
-    end
-  end
-
-  # Not the resolved `from`: detection builds its sample from the segmented text, so asking `from` here is circular.
-  def source_language
-    @from&.to_s
-  end
-
-  def text_tokens
-    @text_tokens ||= extract_text_tokens.to_h
-  end
-
-  def extract_text_tokens
-    tokens.each_with_object([]).with_index do |(group, result), group_index|
-      group.each_with_index do |(value, type), index|
-        result << ["#{group_index}_#{index}", value] if type == :text
-      end
-    end
-  end
-
-  def text_tokens_texts
-    @text_tokens_texts ||= linearize(text_tokens).map(&:to_s).map(&:strip)
-  end
-
-  def chunks
-    @chunks ||= TranslationDiff::Chunker.new(
-      text_tokens_texts,
-      limit: capabilities.max_request_size,
-      count_limit: capabilities.max_batch_size
-    ).call
-  end
-
-  def chunks_translated
-    @chunks_translated ||= chunks.map do |chunk|
-      cached, missing = cache.cached_and_missing(chunk)
-      instrument("cache", provider: provider_cache_key,
-                          hits: cached.count { |value| !value.nil? },
-                          misses: missing.size)
-      next cached if missing.empty?
-
-      cache.store(chunk, cached, call_api(missing))
-    end
-  end
-
-  def text_tokens_translated
-    @text_tokens_translated ||=
-      restore(text_tokens, chunks_translated.flatten)
-  end
-
-  # rubocop:disable-next Metrics/AbcSize
-  def tokens_translated
-    @tokens_translated ||= tokens.dup.tap do |tokens|
-      text_tokens_translated.each do |index, value|
-        group_index, index = index.split("_")
-        tokens[group_index.to_i][index.to_i][0] =
-          restore_spacing(tokens[group_index.to_i][index.to_i][0], value)
-      end
-    end
-  end
-
-  def restore_spacing(source_value, value)
-    TranslationDiff::Spacing.restore(source_value, value)
-  end
-
-  def texts_translated
-    @texts_translated ||= tokens_translated.map.with_index do |group, index|
-      source = texts[index]
-      # Only strings are rebuilt from tokens; nil keeps collapsing to "" the way it always has.
-      next source unless source.nil? || source.is_a?(String)
-
-      group.map { |value, type| type == :text ? value : fix_ascii(value) }.join
-    end
-  end
-
-  # Final result
-  def translation
-    @translation ||= restore(values, texts_translated)
-  end
-
-  def call_api(values)
-    check_rate_limit(values)
-    request = TranslationDiff::Translation::Request.new(
-      texts: values, from: from, to: to, options: options
-    )
-    response = instrument("request", provider: provider_cache_key, batch: values.size,
-                                     characters: values.sum(&:size)) do
-      api.translate(request)
-    end
-    # Dup'd: the array is the provider's own, and handing it to a collaborator makes it the collaborator's too.
-    response.texts.dup
-  end
-
-  def cache
-    @cache ||= TranslationDiff::Cache.new(
-      from, to, provider: provider_cache_key, store: config.cache_store, options: options
-    )
-  end
-
-  # An object assigned straight to `config.provider` never passed through the registry's stamping.
-  def provider_cache_key
-    key = api.cache_key if api.respond_to?(:cache_key)
-    return key unless key.nil? || key.to_s.strip.empty?
-
-    raise Error,
-          "#{api.class} must define #cache_key. A provider assigned directly rather " \
-          "than registered by name has no name to fall back on, and without a key its " \
-          "translations would share cache entries with every other provider."
-  end
-
-  def check_rate_limit(values)
-    return if rate_limiter.nil?
-
-    size = values.sum(&:size)
-    instrument("rate_limit", provider: provider_cache_key, characters: size) do
-      rate_limiter.check(size)
-    end
-  end
-
-  # Markup should not contain control characters
-  def fix_ascii(value)
-    value.gsub(/[\u0000-\u001F]/, " ")
-  end
-end
diff --git a/lib/translation_diff/segment.rb b/lib/translation_diff/segment.rb
new file mode 100644
index 0000000..9b04f0a
--- /dev/null
+++ b/lib/translation_diff/segment.rb
@@ -0,0 +1,24 @@
+# A sentence with the whitespace it was found in: its core is the text a provider sees, its render is markup again.
+class TranslationDiff::Segment
+  attr_reader :source, :body, :core
+  attr_accessor :translation
+
+  # A core is compared decoded, so a sentence that was only `&nbsp;` counts as the padding it is and is never sent.
+  BLANK = /\A[[:space:]]*\z/
+
+  def initialize(source)
+    @source = source.dup
+    @leading, @body, @trailing = @source.partition(/[^[:space:]].*[^[:space:]]|[^[:space:]]/m)
+    @core = TranslationDiff::Markup.decode_entities(@body)
+  end
+
+  # Reflects whether a translation is set right now, not history -- clearing it to nil flips this back to false.
+  def translated? = !translation.nil?
+
+  def empty? = core.match?(BLANK)
+
+  # Untranslated hands back the bytes it was cut from; a translation is text, so it is encoded as markup on the way out.
+  def render
+    "#{@leading}#{translated? ? TranslationDiff::Markup.encode_entities(translation) : @body}#{@trailing}"
+  end
+end
diff --git a/lib/translation_diff/sentence_cache.rb b/lib/translation_diff/sentence_cache.rb
new file mode 100644
index 0000000..9c18207
--- /dev/null
+++ b/lib/translation_diff/sentence_cache.rb
@@ -0,0 +1,67 @@
+# Reads and writes sentence translations under the pipeline's cache key format, without touching the caller's array.
+class TranslationDiff::SentenceCache
+  # Its own class, so rescuing an unusable option cannot also swallow a store or provider failure.
+  class Error < TranslationDiff::Error; end
+
+  # The value types the key format can render. An allowlist: what it cannot render must raise, not be guessed at.
+  SCALARS = [String, Symbol, Numeric, TrueClass, FalseClass, NilClass].freeze
+
+  def initialize(store:, provider:, from:, to:, options: {})
+    @store = store
+    @provider = provider
+    @from = from.downcase
+    @to = to.downcase
+    @options = options
+  end
+
+  # provider:from:to:sentence, with a digest of the per-call options wedged in as a field of its own when there are any.
+  def key(segment)
+    [@provider, @from, @to, *options_digest, Digest::MD5.hexdigest(segment.body)].join(":")
+  end
+
+  # Sets a translation on every segment the store already has cached, and hands back the rest as a new array.
+  def fill(segments)
+    values = @store.read_multi(segments.map { |segment| key(segment) })
+    misses = []
+    segments.each_with_index do |segment, index|
+      value = values[index]
+      value.nil? ? misses << segment : segment.translation = value
+    end
+    misses
+  end
+
+  # Writes back only the segments that carry a translation; an untranslated segment has nothing worth caching.
+  def store(segments)
+    segments.select(&:translated?).each { |segment| @store.write(key(segment), segment.translation) }
+  end
+
+  private
+
+  # No options contributes no field at all, which is the four-field key every already-warm cache is keyed on.
+  def options_digest
+    return [] if @options.empty?
+
+    [Digest::MD5.hexdigest(canonical_options)[0, 8]]
+  end
+
+  # Sorted on the name's string form, because a Symbol and a String key are not comparable with each other.
+  def canonical_options
+    @options.sort_by { |name, _| name.to_s }.map { |name, value| "#{name}=#{canonical(name, value)}" }.join(",")
+  end
+
+  # A Hash canonicalises the way the options hash itself does, an Array its elements in order, joined the same way.
+  def canonical(name, value)
+    case value
+    when Hash then value.sort_by { |k, _| k.to_s }.map { |k, v| "#{k}=#{canonical(name, v)}" }.join(",")
+    when Array then value.map { |element| canonical(name, element) }.join(",")
+    else scalar(name, value)
+    end
+  end
+
+  # A key that is silently wrong costs a caller their whole cache and tells them nothing, so refuse to build one.
+  def scalar(name, value)
+    return value.inspect if SCALARS.any? { |type| value.is_a?(type) }
+
+    raise Error, "cache option #{name} (a #{value.class}) has no stable string form"
+  end
+end
diff --git a/lib/translation_diff/spacing.rb b/lib/translation_diff/spacing.rb
deleted file mode 100644
index 85f0aef..0000000
--- a/lib/translation_diff/spacing.rb
+++ /dev/null
@@ -1,29 +0,0 @@
-# Adds same count leading-trailing spaces left has to the right
-class TranslationDiff::Spacing
-  class << self
-    # TranslationDiff::Spacing.restore("  a ", "Z") # => "   Z "
-    def restore(left, right)
-      leading(left) + right.strip + trailing(left)
-    end
-
-    private
-
-    def spaces(count)
-      ([" "] * count).join
-    end
-
-    def leading(value)
-      pos = value =~ /[^[:space:]]+/ui
-      return "" if pos.nil? || pos.zero?
-
-      value[0..(pos - 1)]
-    end
-
-    def trailing(value)
-      pos = value =~ /[[:space:]]+\z/ui
-      return "" if pos.nil?
-
-      value[pos..]
-    end
-  end
-end
diff --git a/lib/translation_diff/tokenizer.rb b/lib/translation_diff/tokenizer.rb
deleted file mode 100644
index 91e2188..0000000
--- a/lib/translation_diff/tokenizer.rb
+++ /dev/null
@@ -1,163 +0,0 @@
-class TranslationDiff::Tokenizer < Ox::Sax
-  SKIP = %i[script style].freeze
-  INNER_SPANS = %i[notranslate span end_span end_notranslate].freeze
-  HTML_OPTIONS = { smart: true, skip: :skip_none }.freeze
-
-  # Ox::Sax provides no initializer to chain to.
-  # rubocop:disable-next Lint/MissingSuper
-  def initialize(source, segmenter:, language: nil)
-    @pos = nil
-    @source = source
-    @segmenter = segmenter
-    @language = language
-    @tokens = nil
-    @context = []
-    @sequence = []
-    @indicies = []
-  end
-
-  def instruct(target)
-    start_markup(target)
-  end
-
-  def end_instruct(target)
-    end_markup(target)
-  end
-
-  def start_element(name)
-    start_markup(name)
-  end
-
-  # Without a handler here, a mid-sentence comment leaks "<!" and hands its own contents to the provider as prose.
-  def comment(_value) = mark_markup
-  def doctype(_value) = mark_markup
-  def cdata(_value) = mark_markup
-
-  def end_element(name)
-    end_markup(name)
-  end
-
-  def attr(name, value)
-    return unless @context.last == :span
-    return unless name == :class && value == "notranslate"
-    return if notranslate?
-
-    @sequence[-1] = :notranslate
-  end
-
-  def text(value)
-    return if value == ""
-
-    @sequence << (SKIP.include?(@context.last) ? :markup : :text)
-    @indicies << (@pos - 1)
-  end
-
-  def tokens
-    @tokens ||= token_sequences_joined
-                .tap { |tokens| make_sentences_from_last_token(tokens) }
-  end
-
-  private
-
-  def token_sequences_joined
-    raw_tokens.each_with_object([]) do |token, tokens|
-      if tokens.empty? # Initial state
-        tokens << token
-      elsif tokens.last[1] == token[1]
-        # Join series of tokens of the same type into one
-        tokens.last[0].concat(token[0])
-      else
-        # If token before :markup is :text we need to split it into sentences
-        make_sentences_from_last_token(tokens)
-        tokens << token
-      end
-    end
-  end
-
-  def make_sentences_from_last_token(tokens)
-    return if tokens.empty?
-
-    tokens.concat(sentences(tokens.pop[0])) if tokens.last[1] == :text
-  end
-
-  def sentences(value)
-    return [] if value.strip.empty?
-
-    offsets = @segmenter.split_offsets(value, language: @language)
-    return [[value, :text]] if offsets.size == 1
-
-    offsets.each_cons(2).map { |left, right| [value[left...right], :text] } +
-      [[value[offsets.last..], :text]]
-  end
-
-  # Whether the sequence is between `:notranslate` and `:end_notranslate`
-  def notranslate?
-    @sequence.select { |item| item[/notranslate/] }.last == :notranslate
-  end
-
-  # Returns the item for last opened span
-  def end_span
-    return :markup unless notranslate?
-
-    opened_spans = @sequence
-                   .reverse
-                   .take_while { |item| item != :notranslate }
-                   .map { |item| { span: 1, end_span: -1 }.fetch(item, 0) }
-                   .reduce(0, :+)
-
-    opened_spans.positive? ? :end_span : :end_notranslate
-  end
-
-  def raw_tokens
-    @raw_tokens ||= @indicies.map.with_index do |i, n|
-      first = i
-      last = (@indicies[n + 1] || 0) - 1
-      value = fix_utf(@source.byteslice(first..last))
-      type = @sequence[n]
-      type = :text if INNER_SPANS.include?(type)
-      [value, type]
-    end
-  end
-
-  def fix_utf(value)
-    value.encode("UTF-8", undef: :replace, invalid: :replace, replace: " ")
-  end
-
-  # Inside a notranslate region this becomes :text: the whole region is handed to the provider as one unit.
-  def mark_markup
-    @sequence << (notranslate? ? :text : :markup)
-    @indicies << (@pos - 1)
-  end
-
-  def start_markup(name)
-    @context << name
-    @sequence << (if notranslate?
-                    name == :span ? :span : :text
-                  else
-                    :markup
-                  end)
-    @indicies << (@pos - 1)
-  end
-
-  def end_markup(name)
-    @context.pop
-    @sequence << (if notranslate?
-                    name == :span ? end_span : :text
-                  else
-                    :markup
-                  end)
-    @indicies << (@pos - 1) unless @pos == @source.bytesize
-  end
-
-  class << self
-    def tokenize(value, segmenter:, language: nil)
-      # Anything that is not a string has no markup and no sentences in it.
-      return [] unless value.is_a?(String)
-
-      tokenizer = new(value, segmenter: segmenter, language: language).tap do |h|
-        Ox.sax_parse(h, StringIO.new(value), HTML_OPTIONS)
-      end
-      tokenizer.tokens
-    end
-  end
-end
diff --git a/lib/translation_diff/translator.rb b/lib/translation_diff/translator.rb
new file mode 100644
index 0000000..5d7bdb7
--- /dev/null
+++ b/lib/translation_diff/translator.rb
@@ -0,0 +1,142 @@
+# One translation, coordinated: each step hands its value to the next, and a translation rides home on its own segment.
+class TranslationDiff::Translator
+  # Its own class, so rescuing a mis-driven translator cannot also swallow a provider or a cache failure.
+  class Error < TranslationDiff::Error; end
+
+  include TranslationDiff::Instrumentation
+
+  attr_reader :config
+
+  # `provider:` and `config:` are reserved; every other keyword is forwarded to the provider untouched.
+  def initialize(values, from: nil, to: nil, provider: nil, config: nil, **options)
+    raise ArgumentError, "a translation needs a target language: pass `to:` a language code." if to.nil?
+
+    @values = values
+    @from = from
+    @to = to
+    @options = options
+    @config = config || TranslationDiff.config
+    @requested_provider = provider
+  end
+
+  # Hands back the caller's value untouched unless something in it was actually translated.
+  def call
+    document = TranslationDiff::Document.new(TranslationDiff::Leaves.collapse_nils(@values))
+    passages = document.strings.map { |string| passage(string) }
+    segments = passages.flat_map(&:segments).reject(&:empty?)
+    return @values if segments.empty?
+    return @values if same_language?(@from)
+
+    provider = resolve_provider
+    from = source_language(provider, segments)
+    return @values if same_language?(from)
+
+    translated(document, passages, segments, provider, from)
+  end
+
+  private
+
+  # The `translate` event wraps everything a call that reaches a provider does, and nothing an early return does.
+  def translated(document, passages, segments, provider, from)
+    values = TranslationDiff::Leaves.count(@values)
+    payload = { from: from.to_s, to: @to.to_s, provider: provider.cache_key, values: values }
+    instrument("translate", payload) do
+      fill(provider, segments, from)
+      rebuild(document, passages)
+    end
+  end
+
+  # Resolved at first use, never in the constructor: a value with nothing to translate needs no provider at all.
+  def resolve_provider
+    build_provider.tap do |provider|
+      log("provider #{provider.class}")
+      ensure_cache_key!(provider)
+    end
+  end
+
+  # A provider arrives as a name to build, as an object to use as it is, or not at all -- then it is the configured one.
+  def build_provider
+    requested = @requested_provider
+    return config.provider_instance if requested.nil?
+    return TranslationDiff::Providers.build(requested, config) if requested.is_a?(Symbol) || requested.is_a?(String)
+
+    TranslationDiff::Providers.ensure_provider!(requested)
+  end
+
+  # The cache key names the provider in every payload too: it is the one identifier every provider must have.
+  def ensure_cache_key!(provider)
+    return unless provider.cache_key.to_s.strip.empty?
+
+    raise Error, "#{provider.class} must define #cache_key: a blank one would file its " \
+                 "translations in every other provider's cache namespace."
+  end
+
+  def passage(string)
+    TranslationDiff::Passage.new(string, segmenter: config.segmenter_instance, language: @from)
+  end
+
+  # The strings walk and the map walk visit the same leaves in the same order, and the value itself was never touched.
+  def rebuild(document, passages)
+    rendered = passages.map(&:render)
+    document.map { rendered.shift }
+  end
+
+  # Detection is attempted only where it is declared: every provider inherits a #detect that raises.
+  def source_language(provider, segments)
+    return @from unless @from.nil?
+
+    ensure_detects_language!(provider)
+    provider.detect(segments.first.core)
+  end
+
+  def ensure_detects_language!(provider)
+    return if provider.class.capabilities.detects_language?
+
+    raise Error, "Provider #{provider.cache_key} cannot detect the source language. Pass " \
+                 "`from:` with the source language code of the values you are translating."
+  end
+
+  # A detected language arrives as a String while `to:` is usually a Symbol, so neither type nor case can be assumed.
+  # A `from:` the caller gave settles this before a provider is resolved; a nil one cannot, and never matches.
+  def same_language?(from) = from.to_s.casecmp?(@to.to_s)
+
+  # The cache answers for what it has, the provider for the rest, and only what came back is written home.
+  def fill(provider, segments, from)
+    cache = sentence_cache(provider, from)
+    misses = cache.fill(segments)
+    instrument("cache", provider: provider.cache_key, hits: segments.size - misses.size, misses: misses.size)
+    dispatch(provider, misses, from)
+    cache.store(misses)
+  end
+
+  def sentence_cache(provider, from)
+    TranslationDiff::SentenceCache.new(store: config.cache_store, provider: provider.cache_key,
+                                       from: from, to: @to, options: @options)
+  end
+
+  def dispatch(provider, segments, from)
+    batches = TranslationDiff::Batch.pack(segments, capabilities: provider.class.capabilities)
+    batches.each { |batch| send_batch(provider, batch, from) }
+  end
+
+  # The batch applies the reply to the segments that produced it, so no step ever correlates by position again.
+  def send_batch(provider, batch, from)
+    texts = batch.texts
+    payload = { provider: provider.cache_key, batch: texts.size, characters: texts.sum(&:size) }
+    throttle(provider, payload[:characters])
+    response = instrument("request", payload) { provider.translate(request(texts, from)) }
+    batch.apply(response.texts)
+  end
+
+  def request(texts, from)
+    TranslationDiff::Translation::Request.new(texts: texts, from: from, to: @to, options: @options)
+  end
+
+  # Consulted with what is about to be sent, before it is sent; nil means no rate limiting was configured at all.
+  def throttle(provider, characters)
+    limiter = config.rate_limiter_instance
+    return if limiter.nil?
+
+    instrument("rate_limit", provider: provider.cache_key, characters: characters) { limiter.check(characters) }
+  end
+end
diff --git a/test/fixtures/pipeline_baseline.txt b/test/fixtures/pipeline_baseline.txt
new file mode 100644
index 0000000..3bb896b
--- /dev/null
+++ b/test/fixtures/pipeline_baseline.txt
@@ -0,0 +1,130 @@
+# Baseline captured before the pipeline rewrite, against the :null provider (cache_key "null").
+# Every input below is translated with from: "en", to: "ru", provider: :null.
+# Cache keys are the sorted, de-duplicated set of every key this run passed to read_multi or write,
+# on a fresh cache store per input -- so the list is exactly what that one input asked for.
+# Generated 2026-09-09 by .superpowers/sdd/2026-09-09-pipeline-plan task 1.
+
+=== plain sentence ===
+OUTPUT: "Hello there."
+CACHE_KEYS: ["null:en:ru:9d6a2963872077db674a27a39c492e61"]
+
+=== two sentences ===
+OUTPUT: "Hello there. Second sentence!"
+CACHE_KEYS: ["null:en:ru:1520f71fffb5adf0da75e7c17059bfd1", "null:en:ru:9d6a2963872077db674a27a39c492e61"]
+
+=== nested hash ===
+OUTPUT: {title: "One. Two.", body: "Third."}
+CACHE_KEYS: ["null:en:ru:3f77101fc43570a61d5bc042bb908651", "null:en:ru:900019fa233e608091ba641d50d69b81", "null:en:ru:fdb02803abc46fba06ce1cc96d6399c5"]
+
+=== nested array ===
+OUTPUT: ["A. B.", ["C."], "D."]
+CACHE_KEYS: ["null:en:ru:9bce147872014965a531500da2666847", "null:en:ru:d0904fd99a2cfb13f897223b9213c6f1", "null:en:ru:d898b880dda075d3ce1b5feee4a7bb6f"]
+
+=== hash with non-strings ===
+OUTPUT: {title: "One.", count: 42, missing: "", flag: true}
+CACHE_KEYS: ["null:en:ru:900019fa233e608091ba641d50d69b81"]
+
+=== empty string ===
+OUTPUT: ""
+CACHE_KEYS: []
+
+=== nil ===
+OUTPUT: nil
+CACHE_KEYS: []
+
+=== not a string ===
+OUTPUT: 42
+CACHE_KEYS: []
+
+=== bold markup ===
+OUTPUT: "<b>Bold</b> text here. Second sentence."
+CACHE_KEYS: ["null:en:ru:114c3050111d8b8ddd830b99ccebd246", "null:en:ru:dd05cca0ae0eb637e49788e6daf8c23f", "null:en:ru:edcabe153bd4ad9b4a376c3af9d2dc8f"]
+
+=== attributes preserved ===
+OUTPUT: "<a href=\"/x?a=1&b=2\" title='q'>Link text.</a> After."
+CACHE_KEYS: ["null:en:ru:3300dc3f426997c4c0c8e9bcd4af8863", "null:en:ru:97f4ef09e0c768ce8bf87f7b64a3faad"]
+
+=== void element ===
+OUTPUT: "One line.<br>Two lines."
+CACHE_KEYS: ["null:en:ru:41d035f96f8712251d0ac9bb500e24cd", "null:en:ru:694fe8da2b6d6101fb916106f5c23ca0"]
+
+=== unclosed paragraph ===
+OUTPUT: "<p>First para.<p>Second para."
+CACHE_KEYS: ["null:en:ru:24e35fe61038aed7aea27bf6dfcbe623", "null:en:ru:a95237990255526ebf59cf9ffc511064"]
+
+=== uppercase tags ===
+OUTPUT: "<B>Bold</B> text."
+CACHE_KEYS: ["null:en:ru:114c3050111d8b8ddd830b99ccebd246", "null:en:ru:bde8d910cfb3b4d1670021fce1fd2592"]
+
+=== script and style ===
+OUTPUT: "аль<span>бра</span>кил<script>js</script><style>b</style>"
+CACHE_KEYS: ["null:en:ru:34430bf88522e4c1c49479eb2feeb3f3", "null:en:ru:3c11ac7405538ffcaad48db9d7149347", "null:en:ru:b1d36c7c01d8359faddba68b671e7d47"]
+
+=== processing instruction ===
+OUTPUT: "Hey!<br />Look!<?xml:namespace ns=\"urn:office\" ?>"
+CACHE_KEYS: ["null:en:ru:6ae99d4d2de5e3cbd29fec87ae7d76eb", "null:en:ru:8bd5669756914fb1c9a11cbd755dcd31"]
+
+=== comment ===
+OUTPUT: "<!-- internal note --> Visible text here."
+CACHE_KEYS: ["null:en:ru:d41646cf35fd5a9a6959f6715d5e14bc"]
+
+=== doctype ===
+OUTPUT: "<!DOCTYPE html><p>Body text.</p>"
+CACHE_KEYS: ["null:en:ru:ac9d6317208a722c1c19bd667c374d22"]
+
+=== cdata ===
+OUTPUT: "Before.<![CDATA[raw & unparsed]]>After."
+CACHE_KEYS: ["null:en:ru:97f4ef09e0c768ce8bf87f7b64a3faad", "null:en:ru:d5639cb2ca1fb06574bd02a8435be8ad"]
+
+=== notranslate span ===
+OUTPUT: "<span class=\"notranslate\">Bold Mountain</span> is a good place."
+CACHE_KEYS: ["null:en:ru:68980e62d2581d949019300826e1b197"]
+
+=== nested notranslate ===
+OUTPUT: "<span class='notranslate'>foo<span class='notranslate'>bar</span>baz</span>"
+CACHE_KEYS: ["null:en:ru:eafcec3766a26334358d8df31c5a82cc"]
+
+=== notranslate inside span ===
+OUTPUT: "<span><span class='notranslate'>foo<span>bar<br></span>baz</span></span>"
+CACHE_KEYS: ["null:en:ru:5b513613cd49691d47e6df65921f5264"]
+
+=== br before closing tag ===
+OUTPUT: "<font size='3'>Смеркалось.<br></font>"
+CACHE_KEYS: ["null:en:ru:e1583f8217a1cfc2b7ee21afd908e955"]
+
+=== blank line between sentences ===
+OUTPUT: "Первое предложение.\n\nВторое предложение."
+CACHE_KEYS: ["null:en:ru:b83f03a6405a6e2d24f9d89380c661d4", "null:en:ru:f1af66af7c0dc420d4267696c7d0aa13"]
+
+=== single newline ===
+OUTPUT: "test\nphrase"
+CACHE_KEYS: ["null:en:ru:fae8d0840a5c100965609a9d7a55135e"]
+
+=== leading and trailing space ===
+OUTPUT: "  Padded sentence.  "
+CACHE_KEYS: ["null:en:ru:fe3bf43723a64fb32bcac8d99bb431af"]
+
+=== many sentences ===
+OUTPUT: "Sentence number 1. Sentence number 2. Sentence number 3. Sentence number 4. Sentence number 5. Sentence number 6. Sentence number 7. Sentence number 8. Sentence number 9. Sentence number 10. Sentence number 11. Sentence number 12. Sentence number 13. Sentence number 14. Sentence number 15. Sentence number 16. Sentence number 17. Sentence number 18. Sentence number 19. Sentence number 20. Sentence number 21. Sentence number 22. Sentence number 23. Sentence number 24. Sentence number 25. Sentence number 26. Sentence number 27. Sentence number 28. Sentence number 29. Sentence number 30. Sentence number 31. Sentence number 32. Sentence number 33. Sentence number 34. Sentence number 35. Sentence number 36. Sentence number 37. Sentence number 38. Sentence number 39. Sentence number 40."
+CACHE_KEYS: ["null:en:ru:028166de0c432e30aa01d79966d36e27", "null:en:ru:042f7dfcdaf51c2812e9975436ff7163", "null:en:ru:0b1fa3a903f7429246b94933e1c65a22", "null:en:ru:13b8656fe18559c2e98fff3aa3b25136", "null:en:ru:1c3a311a4eef441e056310213a1051e2", "null:en:ru:27c36e35e03a99369e2b60cee64758df", "null:en:ru:2fde1f57bcf20df4087f574ae00d9692", "null:en:ru:42c04e1e1ea3177d2921386c91d0c579", "null:en:ru:43d0f7cdc6be74da0e4cfd4ef8e9b886", "null:en:ru:4c94cb29ddbbbc231ac855011456f46d", "null:en:ru:4d00adc400cec01a812aed2a741778ef", "null:en:ru:522df2f9bbac92f9714bbbb2aa229bc7", "null:en:ru:5b885db48f0a06635ab079fd96c3c7e6", "null:en:ru:5c6d3d369e65d4e33708b48263f7aa16", "null:en:ru:62992cce554f47436aa2ebc09bfa4389", "null:en:ru:80c4df8aced58f66cc564ec992836c09", "null:en:ru:817375736915088db4c098d047232820", "null:en:ru:81c38a3ec70d697ec7c10480b40a82d2", "null:en:ru:831d768717f5c58649e33141ba610e22", "null:en:ru:881e7f42d84eeac1ee76c4db213304a3", "null:en:ru:a298c866d524ed0e6a6f81eea80eb3c6", "null:en:ru:a677508b1eadd12106cc9f3f604d7d51", "null:en:ru:a98a84ab5702ea2f29c01ac35ebd4a2e", "null:en:ru:aa0e7ef164f4b6a60049265162d7b1eb", "null:en:ru:b0dc3760c308f5db9454ff53afed6842", "null:en:ru:bb716ddca5d51bae619894f6fc092337", "null:en:ru:bbd3042479feacc0e179bc05eca8a762", "null:en:ru:be90cce4c0800e090bb1127e102aaa72", "null:en:ru:bfc9abd6522e8eb83e1c05d2a84f5b67", "null:en:ru:c41c34620d095e2db18519e409a58dcf", "null:en:ru:c6a1605fb42cad1439b88d5e1a62ea97", "null:en:ru:c8a3cab86135767607d8b6cff57f7e26", "null:en:ru:d49160d08ac9cb12ca8b1c2373085b12", "null:en:ru:daf84cfee6e6a35e13e9e994850e39e3", "null:en:ru:e299181f4980628d4b3ef62ad0042c4c", "null:en:ru:e6560e25669e4af82fc667a67b74b001", "null:en:ru:e9acf5c038149e3f8e03f6c62c317c89", "null:en:ru:eba0b3330f77dbe64b70db689be5e046", "null:en:ru:fb7c729c821d5b4d5ebdab2e5273b869", "null:en:ru:fe9379e1a22ff0052f72ef22dbaf1d96"]
+
+=== non-ascii ===
+OUTPUT: "Привет. Как дела? Всё хорошо."
+CACHE_KEYS: ["null:en:ru:3ae1adb068af8b1ca435825a5f6a2dd9", "null:en:ru:6440c78297d465869ba8f86b114f7328", "null:en:ru:cc34260931ed7b37f90ec7dc5b44f3ad"]
+
+=== entity ampersand ===
+OUTPUT: "Salt &amp; pepper. Fine."
+CACHE_KEYS: ["null:en:ru:05d12994070fdde458e566149f42472f", "null:en:ru:b5010567e209726a125c9ed59162eca5"]
+
+=== entity nbsp ===
+OUTPUT: "Hard&nbsp;space here. Fine."
+CACHE_KEYS: ["null:en:ru:98abf3f0bf3b826e8f2c21fd72823687", "null:en:ru:b5010567e209726a125c9ed59162eca5"]
+
+=== bare less-than ===
+OUTPUT: "if a < b then stop. Fine."
+CACHE_KEYS: ["null:en:ru:56b4445b422a53efdff59cb72a58f599"]
+
+=== bare less-than and greater ===
+OUTPUT: "5 < 6 and 7 > 6. True."
+CACHE_KEYS: ["null:en:ru:4363b12ae39947f045a4fb5fad740dc8", "null:en:ru:65364203e430439161a97b3d245a0168", "null:en:ru:e4da3b7fbbce2345d7772b0674a318d5"]
+
diff --git a/test/support/pipeline_corpus.rb b/test/support/pipeline_corpus.rb
new file mode 100644
index 0000000..2da7416
--- /dev/null
+++ b/test/support/pipeline_corpus.rb
@@ -0,0 +1,48 @@
+# The inputs the pipeline rewrite is judged against. Every one of these is a
+# case some earlier bug or review turned up; none is invented.
+module PipelineCorpus
+  INPUTS = {
+    "plain sentence" => "Hello there.",
+    "two sentences" => "Hello there. Second sentence!",
+    "nested hash" => { title: "One. Two.", body: "Third." },
+    "nested array" => ["A. B.", ["C."], "D."],
+    "hash with non-strings" => { title: "One.", count: 42, missing: nil, flag: true },
+    "empty string" => "",
+    "nil" => nil,
+    "not a string" => 42,
+    "bold markup" => "<b>Bold</b> text here. Second sentence.",
+    "attributes preserved" => %(<a href="/x?a=1&b=2" title='q'>Link text.</a> After.),
+    "void element" => "One line.<br>Two lines.",
+    "unclosed paragraph" => "<p>First para.<p>Second para.",
+    "uppercase tags" => "<B>Bold</B> text.",
+    "script and style" => "аль<span>бра</span>кил<script>js</script><style>b</style>",
+    "processing instruction" => %(Hey!<br />Look!<?xml:namespace ns="urn:office" ?>),
+    "comment" => "<!-- internal note --> Visible text here.",
+    "doctype" => "<!DOCTYPE html><p>Body text.</p>",
+    "cdata" => "Before.<![CDATA[raw & unparsed]]>After.",
+    "notranslate span" => %(<span class="notranslate">Bold Mountain</span> is a good place.),
+    "nested notranslate" => "<span class='notranslate'>foo<span class='notranslate'>bar</span>baz</span>",
+    "notranslate inside span" => "<span><span class='notranslate'>foo<span>bar<br></span>baz</span></span>",
+    "br before closing tag" => "<font size='3'>Смеркалось.<br></font>",
+    "blank line between sentences" => "Первое предложение.\n\nВторое предложение.",
+    "single newline" => "test\nphrase",
+    "leading and trailing space" => "  Padded sentence.  ",
+    "many sentences" => (1..40).map { |i| "Sentence number #{i}." }.join(" "),
+    "non-ascii" => "Привет. Как дела? Всё хорошо.",
+    "entity ampersand" => "Salt &amp; pepper. Fine.",
+    "entity nbsp" => "Hard&nbsp;space here. Fine.",
+    "bare less-than" => "if a < b then stop. Fine.",
+    "bare less-than and greater" => "5 < 6 and 7 > 6. True.",
+    # A recorded limit, not a defect: `<b` cannot be prose here and a tag in "<b>Bold</b>" without a lexer of our own.
+    "bare less-than before a letter" => "a <b then stop. Fine."
+  }.freeze
+
+  # Written before the rewrite, on purpose, so it can fail -- unlike a list assembled after seeing what changed.
+  EXPECTED_TO_CHANGE = [
+    "entity ampersand",
+    "entity nbsp",
+    "bare less-than",
+    "bare less-than and greater",
+    "bare less-than before a letter"
+  ].freeze
+end
diff --git a/test/translation_diff/batch_test.rb b/test/translation_diff/batch_test.rb
new file mode 100644
index 0000000..75c1362
--- /dev/null
+++ b/test/translation_diff/batch_test.rb
@@ -0,0 +1,89 @@
+require "test_helper"
+
+class BatchTest < Minitest::Test
+  def capabilities(request_size: 1_000, batch_size: 10, text_size: nil)
+    TranslationDiff::Capabilities.new(
+      max_request_size: request_size, max_batch_size: batch_size, max_text_size: text_size,
+      html: :none, notranslate: false, detects_language: false, reports_billing: false
+    )
+  end
+
+  def segments(*sources) = sources.map { |s| TranslationDiff::Segment.new(s) }
+
+  def pack(sources, **)
+    TranslationDiff::Batch.pack(segments(*sources), capabilities: capabilities(**))
+  end
+
+  def test_everything_fits_in_one_batch_when_it_fits
+    batches = pack(%w[one two three])
+
+    assert_equal 1, batches.size
+    assert_equal %w[one two three], batches.first.texts
+  end
+
+  def test_the_count_limit_starts_a_new_batch
+    batches = pack(%w[one two three four five], batch_size: 2)
+
+    assert_equal [%w[one two], %w[three four], %w[five]], batches.map(&:texts)
+  end
+
+  def test_the_size_limit_starts_a_new_batch
+    batches = pack(%w[aaaa bbbb cccc], request_size: 9)
+
+    assert_equal [%w[aaaa bbbb], %w[cccc]], batches.map(&:texts)
+  end
+
+  # A provider that cannot batch gets one text per request, and that is
+  # correct rather than a degenerate case -- Amazon Translate has no batch
+  # form of its endpoint at all.
+  def test_a_batch_size_of_one_produces_one_request_per_text
+    assert_equal [%w[one], %w[two], %w[three]], pack(%w[one two three], batch_size: 1).map(&:texts)
+  end
+
+  # Size is the escaped length, because that is what goes over the wire.
+  def test_size_is_measured_escaped_not_in_characters
+    batches = pack(%w[привет привет], request_size: 40)
+
+    assert_equal 2, batches.size, "each Cyrillic word is 36 escaped characters"
+  end
+
+  # A caller who wants to catch "too long for this provider" must not also catch an unrelated registry miss.
+  def test_a_text_larger_than_the_request_limit_raises_naming_the_limit
+    error = assert_raises(TranslationDiff::Batch::Error) { pack(["x" * 50], request_size: 10) }
+
+    assert_match(/10/, error.message)
+    assert_match(/50/, error.message)
+  end
+
+  # The error locates the sentence without reproducing it: the whole sentence
+  # is the customer's content and this message may be logged.
+  def test_the_too_long_error_does_not_carry_the_whole_sentence
+    sentence = "Secret #{'y' * 200}"
+    error = assert_raises(TranslationDiff::Batch::Error) { pack([sentence], request_size: 10) }
+
+    refute_includes error.message, "y" * 200
+  end
+
+  def test_apply_puts_each_translation_on_its_own_segment
+    batch = pack(%w[one two]).first
+    batch.apply(%w[один два])
+
+    assert_equal %w[один два], batch.segments.map(&:translation)
+  end
+
+  def test_apply_refuses_a_reply_of_the_wrong_length
+    batch = pack(%w[one two]).first
+
+    assert_raises(TranslationDiff::ResponseError) { batch.apply(%w[один]) }
+  end
+
+  def test_empty_segments_are_never_packed
+    batches = TranslationDiff::Batch.pack(segments("one", "   ", "two"), capabilities: capabilities)
+
+    assert_equal [%w[one two]], batches.map(&:texts)
+  end
+
+  def test_no_segments_produce_no_batches
+    assert_empty TranslationDiff::Batch.pack([], capabilities: capabilities)
+  end
+end
diff --git a/test/translation_diff/cache_test.rb b/test/translation_diff/cache_test.rb
deleted file mode 100644
index 2c345db..0000000
--- a/test/translation_diff/cache_test.rb
+++ /dev/null
@@ -1,148 +0,0 @@
-require "test_helper"
-
-class CacheTest < Minitest::Test
-  class RecordingStore
-    attr_reader :keys
-
-    def initialize
-      @keys = []
-    end
-
-    def read_multi(keys)
-      @keys.concat(keys)
-      [nil] * keys.size
-    end
-
-    def write(_key, value)
-      value
-    end
-  end
-
-  # Answers with fixed results regardless of keys asked, to pin the positional contract.
-  class PositionalStore
-    def initialize(responses)
-      @responses = responses
-    end
-
-    def read_multi(_keys)
-      @responses
-    end
-  end
-
-  def setup
-    @store = RecordingStore.new
-  end
-
-  # Two providers writing to one store used to collide, silently returning DeepL's translations for another.
-  def test_the_provider_is_part_of_the_key
-    key_for(provider: "deepl")
-    key_for(provider: "google")
-
-    refute_equal @store.keys[0], @store.keys[1]
-  end
-
-  # formality: :less used to share a key with the default, so whichever translated first won.
-  def test_the_provider_options_are_part_of_the_key
-    key_for(options: {})
-    key_for(options: { formality: :less })
-
-    refute_equal @store.keys[0], @store.keys[1]
-  end
-
-  def test_the_options_digest_is_order_independent
-    key_for(options: { a: 1, b: 2 })
-    key_for(options: { b: 2, a: 1 })
-
-    assert_equal @store.keys[0], @store.keys[1]
-  end
-
-  # "EN" and :en are the same language and used to produce two entries for identical work.
-  def test_the_language_codes_are_normalised
-    key_for(from: "EN", to: "RU")
-    key_for(from: :en, to: :ru)
-
-    assert_equal @store.keys[0], @store.keys[1]
-  end
-
-  def test_leading_and_trailing_space_does_not_change_the_key
-    key_for(value: "text")
-    key_for(value: "  text  ")
-
-    assert_equal @store.keys[0], @store.keys[1]
-  end
-
-  # nil and "" are different values; #to_s would collide them.
-  def test_nil_and_empty_string_option_values_produce_different_keys
-    key_for(options: { a: nil })
-    key_for(options: { a: "" })
-
-    refute_equal @store.keys[0], @store.keys[1]
-  end
-
-  # Exercises the Array branch of #canonical, which no other test in this file reaches.
-  def test_an_array_option_value_is_part_of_the_digest
-    key_for(options: { glossary_ids: %w[a b] })
-    key_for(options: { glossary_ids: %w[a c] })
-
-    refute_equal @store.keys[0], @store.keys[1]
-  end
-
-  # An option value with no stable serialisation must not silently produce an unreproducible cache key.
-  def test_an_unsupported_option_value_raises
-    assert_raises(TranslationDiff::Cache::Error) { key_for(options: { a: Object.new }) }
-  end
-
-  # Trusts the store to return results in key order; a `WHERE key IN (...)` store will not.
-  def test_cached_and_missing_pairs_results_positionally
-    store = PositionalStore.new(["cached one", nil, "cached three"])
-
-    cached, missing = TranslationDiff::Cache.new(:en, :ru, provider: "deepl", store: store)
-                                            .cached_and_missing(%w[one two three])
-
-    assert_equal ["cached one", nil, "cached three"], cached
-    assert_equal ["two"], missing
-  end
-
-  # #store is public and takes an outside array; shifting it emptied the caller's own array.
-  def test_store_does_not_consume_the_updates_it_is_given
-    updates = %w[один три]
-    cache = TranslationDiff::Cache.new(:en, :ru, provider: "deepl", store: @store)
-
-    cache.store(%w[one two three], [nil, "два", nil], updates)
-
-    assert_equal %w[один три], updates
-  end
-
-  def test_store_fills_the_gaps_in_key_order
-    cache = TranslationDiff::Cache.new(:en, :ru, provider: "deepl", store: @store)
-
-    assert_equal %w[один два три],
-                 cache.store(%w[one two three], [nil, "два", nil], %w[один три])
-  end
-
-  # The exact keys a translation is stored under, verified equal to main's -- move one and every user
-  # re-translates their whole corpus, so the digest of the options and of the sentence are pinned too.
-  # rubocop:disable-next Metrics/MethodLength
-  def test_the_keys_are_the_ones_users_already_have_in_their_caches
-    key_for(value: "text", from: :en, to: :ru, provider: "deepl")
-    key_for(value: "  text  ", from: "EN", to: "RU", provider: "deepl")
-    key_for(value: "text", from: :en, to: :ru, provider: "deepl", options: { formality: :less })
-    key_for(value: "Hello there.", from: :en, to: :"pt-BR", provider: "google",
-            options: { glossary_ids: %w[a b], nested: { z: 1, a: nil } })
-    key_for(value: "Ein Satz.", from: :de, to: :en, provider: "azure",
-            options: { a: "", b: 2, c: true })
-
-    assert_equal ["deepl:en:ru:1cb251ec0d568de6a929b520c4aed8d1",
-                  "deepl:en:ru:1cb251ec0d568de6a929b520c4aed8d1",
-                  "deepl:en:ru:80df90b8:1cb251ec0d568de6a929b520c4aed8d1",
-                  "google:en:pt-br:2744ebab:9d6a2963872077db674a27a39c492e61",
-                  "azure:de:en:da1fef03:84f8c5b939a540fa8da132c838a8d61d"], @store.keys
-  end
-
-  private
-
-  def key_for(value: "text", from: :en, to: :ru, provider: "deepl", options: {})
-    TranslationDiff::Cache.new(from, to, provider: provider, store: @store, options: options)
-                          .cached_and_missing([value])
-  end
-end
diff --git a/test/translation_diff/chunker_test.rb b/test/translation_diff/chunker_test.rb
deleted file mode 100644
index fd30ce6..0000000
--- a/test/translation_diff/chunker_test.rb
+++ /dev/null
@@ -1,64 +0,0 @@
-require "test_helper"
-
-class ChunkerTest < Minitest::Test
-  LIMIT = 20
-  COUNT_LIMIT = 5
-
-  LONG = "a" * 10
-  MEDIUM = "a" * 7
-  SHORT = "x".freeze
-  OVERSIZED = "a" * 30
-
-  CASES = {
-    "keeps_values_in_one_chunk_when_they_fit" => [
-      %w[a b c],
-      [%w[a b c]]
-    ],
-    "splits_on_the_size_limit" => [
-      [LONG] * 3,
-      [[LONG, LONG], [LONG]]
-    ],
-    "splits_between_values_of_uneven_size" => [
-      ([MEDIUM] * 3) + [LONG],
-      [[MEDIUM, MEDIUM], [MEDIUM, LONG]]
-    ],
-    "splits_on_the_count_limit" => [
-      [SHORT] * 10,
-      [[SHORT] * 5, [SHORT] * 5]
-    ]
-  }.freeze
-
-  CASES.each do |name, (values, expected)|
-    define_method(:"test_#{name}") do
-      assert_equal expected, chunk(values)
-    end
-  end
-
-  def test_raises_when_a_single_value_exceeds_the_limit
-    error = assert_raises(TranslationDiff::Chunker::Error) { chunk([OVERSIZED]) }
-
-    assert_match(/Too long part/, error.message)
-  end
-
-  # CGI.escape inflates Cyrillic sixfold; measuring raw String#size let chunks of non-ASCII text run over.
-  def test_measures_non_ascii_values_by_their_escaped_size
-    value = "я" * 3
-
-    # Measured raw, both values fit in one chunk of 20; measured as sent, they cannot.
-    assert_equal 3, value.size
-    assert_equal 18, CGI.escape(value).size
-    assert_equal [[value], [value]], chunk([value, value])
-  end
-
-  def test_raises_when_the_escaped_size_of_one_value_exceeds_the_limit
-    error = assert_raises(TranslationDiff::Chunker::Error) { chunk(["я" * 4]) }
-
-    assert_match(/Too long part 24 > 20/, error.message)
-  end
-
-  private
-
-  def chunk(values)
-    TranslationDiff::Chunker.new(values, limit: LIMIT, count_limit: COUNT_LIMIT).call
-  end
-end
diff --git a/test/translation_diff/context_test.rb b/test/translation_diff/context_test.rb
index 9f7c062..d2a4f49 100644
--- a/test/translation_diff/context_test.rb
+++ b/test/translation_diff/context_test.rb
@@ -45,4 +45,12 @@ def test_a_context_translates_through_its_own_configuration
 
     assert_equal "Hello.", context.translate("Hello.", from: "en", to: "ru")
   end
+
+  # `to:` still defaults to nil here too, so a context refuses a missing target by naming the keyword.
+  def test_a_missing_target_language_is_refused_by_name
+    context = TranslationDiff.context { |c| c.cache_namespace = "tenant" }
+    error = assert_raises(ArgumentError) { context.translate("Hello.", from: "en") }
+
+    assert_match(/to:/, error.message)
+  end
 end
diff --git a/test/translation_diff/document_test.rb b/test/translation_diff/document_test.rb
new file mode 100644
index 0000000..e66f925
--- /dev/null
+++ b/test/translation_diff/document_test.rb
@@ -0,0 +1,76 @@
+require "test_helper"
+
+class DocumentTest < Minitest::Test
+  def map(value, &) = TranslationDiff::Document.new(value).map(&)
+
+  def test_a_bare_string_is_mapped
+    assert_equal "HELLO", map("hello", &:upcase)
+  end
+
+  def test_a_hash_keeps_its_keys_and_their_order
+    result = map({ title: "one", body: "two" }, &:upcase)
+
+    assert_equal({ title: "ONE", body: "TWO" }, result)
+    assert_equal %i[title body], result.keys
+  end
+
+  def test_an_array_keeps_its_order
+    assert_equal %w[A B C], map(%w[a b c], &:upcase)
+  end
+
+  def test_nesting_of_both_kinds_survives
+    value = { a: ["one", { b: "two" }], c: "three" }
+
+    assert_equal({ a: ["ONE", { b: "TWO" }], c: "THREE" }, map(value, &:upcase))
+  end
+
+  # Anything that is not a String is not translatable and must arrive on the
+  # other side as the same object, in the same place.
+  def test_non_strings_pass_through_untouched
+    value = { text: "one", count: 42, missing: nil, flag: true, at: :symbol }
+
+    assert_equal({ text: "ONE", count: 42, missing: nil, flag: true, at: :symbol },
+                 map(value, &:upcase))
+  end
+
+  def test_the_block_is_not_called_for_non_strings
+    seen = []
+    map({ text: "one", count: 42, missing: nil }) do |s|
+      seen << s
+      s
+    end
+
+    assert_equal ["one"], seen
+  end
+
+  def test_an_empty_string_is_still_a_string
+    assert_equal [""], TranslationDiff::Document.new([""]).strings
+  end
+
+  def test_strings_are_returned_in_document_order
+    value = { a: ["one", { b: "two" }], c: "three" }
+
+    assert_equal %w[one two three], TranslationDiff::Document.new(value).strings
+  end
+
+  def test_strings_does_not_modify_the_value
+    value = { a: ["one"] }
+    TranslationDiff::Document.new(value).strings
+
+    assert_equal({ a: ["one"] }, value)
+  end
+
+  # The caller's structure is theirs. Mapping returns a new one.
+  def test_map_does_not_mutate_the_original
+    value = { a: ["one"] }
+    map(value, &:upcase)
+
+    assert_equal({ a: ["one"] }, value)
+  end
+
+  def test_deep_nesting_does_not_lose_its_shape
+    value = [[[["deep"]]]]
+
+    assert_equal [[[["DEEP"]]]], map(value, &:upcase)
+  end
+end
diff --git a/test/translation_diff/fragment_test.rb b/test/translation_diff/fragment_test.rb
new file mode 100644
index 0000000..19bf34e
--- /dev/null
+++ b/test/translation_diff/fragment_test.rb
@@ -0,0 +1,12 @@
+require "test_helper"
+
+class FragmentTest < Minitest::Test
+  # Rendering used to hand back the slice itself, so appending to it edited the document it came from.
+  def test_rendering_markup_does_not_hand_out_the_fragment_source
+    fragment = TranslationDiff::Fragment.markup("<b>")
+
+    fragment.render << "XXX"
+
+    assert_equal "<b>", fragment.render
+  end
+end
diff --git a/test/translation_diff/leaves_test.rb b/test/translation_diff/leaves_test.rb
new file mode 100644
index 0000000..13f8f73
--- /dev/null
+++ b/test/translation_diff/leaves_test.rb
@@ -0,0 +1,39 @@
+require "test_helper"
+
+class LeavesTest < Minitest::Test
+  def collapse(value) = TranslationDiff::Leaves.collapse_nils(value)
+
+  def count(value) = TranslationDiff::Leaves.count(value)
+
+  def test_a_nested_nil_becomes_an_empty_string
+    assert_equal({ a: "one", skip: "" }, collapse({ a: "one", skip: nil }))
+    assert_equal ["one", "", 42], collapse(["one", nil, 42])
+  end
+
+  def test_a_bare_nil_becomes_an_empty_string_too
+    assert_equal "", collapse(nil)
+  end
+
+  def test_every_other_leaf_is_handed_back_as_it_is
+    assert_equal({ a: "one", n: 42, f: false }, collapse({ a: "one", n: 42, f: false }))
+  end
+
+  def test_the_caller_s_own_structure_is_never_modified
+    value = { a: "one", nested: ["two", nil] }
+    collapse(value)
+
+    assert_equal({ a: "one", nested: ["two", nil] }, value)
+  end
+
+  def test_counting_covers_every_leaf_whatever_its_type
+    assert_equal 3, count({ a: "one", n: 42, skip: nil })
+    assert_equal 5, count({ a: "one", b: { c: "two", d: [1, "three", nil] } })
+  end
+
+  def test_a_scalar_is_one_leaf_and_an_empty_container_is_none
+    assert_equal 1, count("one")
+    assert_equal 1, count(nil)
+    assert_equal 0, count([])
+    assert_equal 0, count({})
+  end
+end
diff --git a/test/translation_diff/linearizer_test.rb b/test/translation_diff/linearizer_test.rb
deleted file mode 100644
index be37589..0000000
--- a/test/translation_diff/linearizer_test.rb
+++ /dev/null
@@ -1,17 +0,0 @@
-require "test_helper"
-
-class LinearizerTest < Minitest::Test
-  CASES = {
-    "a_single_value" => "Value",
-    "an_array" => [1, :two, "Three"],
-    "a_nested_hash" => { a: "1", b: 2, c: { d: :three } }
-  }.freeze
-
-  CASES.each do |name, value|
-    define_method(:"test_round_trips_#{name}") do
-      linearized = TranslationDiff::Linearizer.linearize(value)
-
-      assert_equal value, TranslationDiff::Linearizer.restore(value, linearized)
-    end
-  end
-end
diff --git a/test/translation_diff/markup_test.rb b/test/translation_diff/markup_test.rb
new file mode 100644
index 0000000..400f408
--- /dev/null
+++ b/test/translation_diff/markup_test.rb
@@ -0,0 +1,194 @@
+require "test_helper"
+
+class MarkupTest < Minitest::Test
+  def passage(source)
+    TranslationDiff::Passage.new(source, segmenter: TranslationDiff::Segmenters::Pragmatic.new)
+  end
+
+  def cores(source) = passage(source).segments.reject(&:empty?).map(&:core)
+
+  def translated(source)
+    subject = passage(source)
+    subject.segments.reject(&:empty?).each { |s| s.translation = s.core.upcase }
+    subject.render
+  end
+
+  # What the :null provider does: every sentence comes back as the text it was sent, so only markup handling shows.
+  def echoed(source)
+    subject = passage(source)
+    subject.segments.reject(&:empty?).each { |s| s.translation = s.core }
+    subject.render
+  end
+
+  def assert_round_trips(source)
+    assert_equal source, passage(source).render, "render must return the source byte for byte"
+  end
+
+  # -- entities ------------------------------------------------------------
+
+  # What reaches a provider is text, so it gets the character, not the entity.
+  def test_an_entity_is_decoded_before_translation
+    assert_equal ["Salt & pepper.", "Fine."], cores("Salt &amp; pepper. Fine.")
+  end
+
+  def test_a_non_breaking_space_is_decoded
+    assert_equal ["Hard\u00A0space here.", "Fine."], cores("Hard&nbsp;space here. Fine.")
+  end
+
+  # The document keeps the entities it arrived with.
+  def test_entities_are_restored_on_render
+    assert_equal "SALT &amp; PEPPER. FINE.", translated("Salt &amp; pepper. Fine.")
+  end
+
+  def test_an_untranslated_document_with_entities_round_trips
+    source = "Salt &amp; pepper. Hard&nbsp;space. Fine."
+
+    assert_equal source, passage(source).render
+  end
+
+  # -- the bare < ----------------------------------------------------------
+
+  def test_a_bare_less_than_stays_in_the_sentence
+    assert_equal ["if a < b then stop.", "Fine."], cores("if a < b then stop. Fine.")
+  end
+
+  def test_bare_angles_on_both_sides_stay_prose
+    assert_equal ["5 < 6 and 7 > 6.", "True."], cores("5 < 6 and 7 > 6. True.")
+  end
+
+  def test_a_bare_less_than_survives_rendering_untranslated
+    source = "if a < b then stop. Fine."
+
+    assert_equal source, passage(source).render
+  end
+
+  # The distinction that makes this hard: a real tag must still be a tag when
+  # the same string also contains a bare <.
+  def test_a_real_tag_beside_a_bare_less_than_is_still_markup
+    assert_equal ["if a < b then", "stop."], cores("if a < b then <b>stop.</b>")
+    assert_equal "IF A < B THEN <b>STOP.</b>", translated("if a < b then <b>stop.</b>")
+  end
+
+  def test_a_less_than_immediately_before_a_letter_is_a_tag
+    assert_equal ["Bold", "text."], cores("<b>Bold</b> text.")
+  end
+
+  # -- the escape and its inverse ------------------------------------------
+
+  # Every mixture of real tags, bare angles and already-escaped angles the
+  # workaround has to survive; each must come back exactly as it went in.
+  MIXED = [
+    "if a < b then stop.",
+    "5 < 6 and 7 > 6.",
+    "<b>Bold</b> and a < b.",
+    "a < b and <i>c</i> < d.",
+    "&lt; is already an entity.",
+    "&amp;lt; is an entity for an entity.",
+    "a < b, &lt; c, &amp;lt; d, <b>e</b>.",
+    "<!-- a < b --> Visible.",
+    %(<a title="a &lt; b">Link.</a> After.),
+    "trailing angle <",
+    "<",
+    "<3 is not a tag.",
+    ""
+  ].freeze
+
+  def test_restoring_undoes_escaping
+    MIXED.each do |source|
+      escaped = TranslationDiff::Markup.escape_bare_angles(source)
+
+      assert_equal source, TranslationDiff::Markup.restore_bare_angles(escaped),
+                   "escape and restore must be a matched pair for #{source.inspect}"
+    end
+  end
+
+  def test_escaping_leaves_no_bare_angle_for_ox_to_swallow
+    MIXED.each do |source|
+      escaped = TranslationDiff::Markup.escape_bare_angles(source)
+
+      refute_match(%r{<(?![A-Za-z!?]|/[A-Za-z])}, escaped, "#{escaped.inspect} still holds a bare <")
+    end
+  end
+
+  def test_every_mixed_input_round_trips_through_a_passage
+    MIXED.each { |source| assert_round_trips(source) }
+  end
+
+  # -- decoding and encoding -----------------------------------------------
+
+  # Every entity is decoded, not the two that were measured: an `&` we leave behind is an `&` encoding corrupts.
+  def test_decoding_resolves_named_and_numeric_entities
+    assert_equal "\u00A9 \u2014 \u2026", TranslationDiff::Markup.decode_entities("&copy; &mdash; &hellip;")
+    assert_equal "& < > \" ' \u00A0", TranslationDiff::Markup.decode_entities("&amp; &lt; &gt; &quot; &apos; &nbsp;")
+    assert_equal "& & \u00A0 \u00A0", TranslationDiff::Markup.decode_entities("&#38; &#x26; &#160; &#xA0;")
+  end
+
+  # Sane rather than an exception, and sane here means untouched: what is not an entity is text, and stays text.
+  def test_decoding_leaves_a_malformed_entity_exactly_as_it_arrived
+    ["&notanentity;", "&#xZZ;", "&#;", "&#999999999;", "&Bogus9;", "AT&T", "a &gt b", "&"].each do |text|
+      assert_equal text, TranslationDiff::Markup.decode_entities(text)
+    end
+  end
+
+  # A numeric reference can name a surrogate; decoding one would hand back invalid UTF-8 for a later regexp to raise on.
+  def test_decoding_refuses_a_reference_that_would_not_be_valid_utf8
+    decoded = TranslationDiff::Markup.decode_entities("&#xD800;")
+
+    assert_equal "&#xD800;", decoded
+    assert_predicate decoded, :valid_encoding?
+  end
+
+  # Only the two characters that are unsafe in HTML text; a decoded character stays the character it decoded to.
+  def test_encoding_touches_only_the_ampersand_and_the_opening_angle
+    assert_equal "&amp; &lt;b> > \" ' \u00A0", TranslationDiff::Markup.encode_entities("& <b> > \" ' \u00A0")
+  end
+
+  # -- entities we never decoded -------------------------------------------
+
+  # Every one of these came back with its `&` escaped a second time before the decode was made whole.
+  def test_an_entity_outside_the_decoded_set_is_not_escaped_again
+    assert_round_trips("A &gt; B here. Fine.")
+    assert_round_trips("AT&T is a company. Fine.")
+    assert_round_trips("&copy; 2026. Fine.")
+    assert_round_trips("&notanentity; here. Fine.")
+    assert_round_trips("One &mdash; two &hellip; three. Fine.")
+  end
+
+  # The bargain, in a test: bytes are promised only while a segment is untranslated.
+  def test_a_translated_sentence_renders_equivalent_markup_rather_than_equal_bytes
+    assert_equal "A > B here. Fine.", echoed("A &gt; B here. Fine.")
+    assert_equal "AT&amp;T is a company. Fine.", echoed("AT&T is a company. Fine.")
+    assert_equal "Hard\u00A0space here. Fine.", echoed("Hard&nbsp;space here. Fine.")
+  end
+
+  # The whole HTML5 named set, not just the specials CGI knows: a spelled-out `&copy;` would display as text, not as ©.
+  def test_a_named_entity_outside_cgis_table_is_translated_as_the_character_it_means
+    assert_equal ["\u00A9 2026.", "Fine."], cores("&copy; 2026. Fine.")
+    assert_equal "\u00A9 2026. Fine.", echoed("&copy; 2026. Fine.")
+    assert_equal "One \u2014 two \u2026 three. Fine.", echoed("One &mdash; two &hellip; three. Fine.")
+  end
+
+  # A lone `&` is invalid XML and Ox raises on it, so nothing but a single well-formed entity is ever handed over.
+  def test_a_lone_ampersand_never_reaches_the_entity_resolver
+    assert_equal ["AT&T is a company.", "Fine."], cores("AT&T is a company. Fine.")
+    assert_equal "AT&amp;T is a company. Fine.", echoed("AT&T is a company. Fine.")
+    assert_equal "R&D; x", TranslationDiff::Markup.decode_entities("R&D; x")
+  end
+
+  # -- what still has to hold ----------------------------------------------
+
+  # A notranslate element is prose that contains real tags; encoding must not eat them.
+  def test_a_notranslate_element_keeps_its_tags_through_a_render
+    assert_round_trips(%(<span class="notranslate">Bold Mountain</span> is a good place.))
+  end
+
+  # Passed through untouched means untouched: an `&` inside a protected element is not ours to respell.
+  def test_a_notranslate_element_keeps_its_ampersands_through_a_render
+    assert_round_trips(%(<span class="notranslate">R&D & more</span> Fine.))
+  end
+
+  def test_an_entity_inside_markup_is_left_for_the_browser
+    assert_round_trips(%(<a href="/x?a=1&b=2" title='q'>Link text.</a> After.))
+    assert_round_trips("Before.<![CDATA[raw & unparsed]]>After.")
+  end
+end
diff --git a/test/translation_diff/passage_test.rb b/test/translation_diff/passage_test.rb
new file mode 100644
index 0000000..808f062
--- /dev/null
+++ b/test/translation_diff/passage_test.rb
@@ -0,0 +1,152 @@
+require "test_helper"
+
+class PassageTest < Minitest::Test
+  def passage(source)
+    TranslationDiff::Passage.new(source, segmenter: TranslationDiff::Segmenters::Pragmatic.new)
+  end
+
+  # What a provider would be asked to translate, in order.
+  def cores(source) = passage(source).segments.reject(&:empty?).map(&:core)
+
+  def assert_round_trips(source)
+    assert_equal source, passage(source).render, "render must return the source byte for byte"
+  end
+
+  # -- byte-exact reconstruction ------------------------------------------
+
+  # rubocop:disable-next Metrics/MethodLength
+  def test_every_corpus_input_round_trips_untranslated
+    [
+      "Hello there.",
+      "<b>Bold</b> text here. Second sentence.",
+      %(<a href="/x?a=1&b=2" title='q'>Link text.</a> After.),
+      "One line.<br>Two lines.",
+      "<p>First para.<p>Second para.",
+      "<B>Bold</B> text.",
+      "аль<span>бра</span>кил<script>js</script><style>b</style>",
+      %(Hey!<br />Look!<?xml:namespace ns="urn:office" ?>),
+      "<!-- internal note --> Visible text here.",
+      "<!DOCTYPE html><p>Body text.</p>",
+      "Before.<![CDATA[raw & unparsed]]>After.",
+      "<font size='3'>Смеркалось.<br></font>",
+      "  Padded sentence.  ",
+      "Первое предложение.\n\nВторое предложение.",
+      ""
+    ].each { |source| assert_round_trips(source) }
+  end
+
+  # -- what counts as prose ----------------------------------------------
+
+  def test_text_around_markup_is_prose
+    assert_equal ["Bold", "text here.", "Second sentence."],
+                 cores("<b>Bold</b> text here. Second sentence.")
+  end
+
+  def test_script_and_style_contents_are_not_prose
+    assert_equal %w[аль бра кил], cores("аль<span>бра</span>кил<script>js</script><style>b</style>")
+  end
+
+  def test_a_comment_is_not_prose
+    assert_equal ["Visible text here."], cores("<!-- internal note --> Visible text here.")
+  end
+
+  def test_a_doctype_is_not_prose
+    assert_equal ["Body text."], cores("<!DOCTYPE html><p>Body text.</p>")
+  end
+
+  def test_a_processing_instruction_is_not_prose
+    assert_equal %w[Hey! Look!], cores(%(Hey!<br />Look!<?xml:namespace ns="urn:office" ?>))
+  end
+
+  def test_attribute_values_are_not_prose
+    assert_equal ["Link text.", "After."], cores(%(<a href="/x" title="Do not translate me">Link text.</a> After.))
+  end
+
+  # -- notranslate, which is prose ON PURPOSE ------------------------------
+
+  # The provider honours class="notranslate" itself, under the HTML mode all
+  # six providers send. Holding the span back as markup would deprive it of
+  # the protection it exists to request.
+  def test_a_notranslate_span_reaches_the_provider_with_its_tags
+    source = %(<span class="notranslate">Bold Mountain</span> is a good place.)
+
+    assert_equal [%(<span class="notranslate">Bold Mountain</span> is a good place.)], cores(source)
+  end
+
+  # Ox lowercases element names but not attribute names, and HTML attribute names are case-insensitive.
+  def test_an_uppercase_class_attribute_still_protects
+    source = %(<span CLASS="notranslate">Bold Mountain</span> is a good place.)
+
+    assert_equal [source], cores(source)
+  end
+
+  # Class token values are case-sensitive in HTML and providers look for the lowercase word, so this asks for nothing.
+  def test_an_uppercase_notranslate_value_does_not_protect
+    assert_equal ["Bold Mountain", "is a good place."],
+                 cores(%(<span class="NOTRANSLATE">Bold Mountain</span> is a good place.))
+  end
+
+  def test_a_notranslate_span_nested_in_another_is_one_unit
+    source = "<span class='notranslate'>foo<span class='notranslate'>bar</span>baz</span>"
+
+    assert_equal [source], cores(source)
+  end
+
+  def test_a_notranslate_span_inside_an_ordinary_span_keeps_the_outer_span_as_markup
+    source = "<span><span class='notranslate'>foo<span>bar<br></span>baz</span></span>"
+
+    assert_equal ["<span class='notranslate'>foo<span>bar<br></span>baz</span>"], cores(source)
+  end
+
+  # Protection beats opacity: the caller asked for this subtree to be passed through, script and all.
+  def test_a_script_inside_a_notranslate_element_stays_inside_the_protected_unit
+    source = %(<span class="notranslate"><script>alert(1)</script></span>)
+
+    assert_equal [source], cores(source)
+  end
+
+  # -- sentence boundaries -------------------------------------------------
+
+  def test_prose_is_cut_into_sentences
+    assert_equal ["! Киловольт.", "Смеркалось.", "Ворчало.", "Кричало."],
+                 cores("! Киловольт. <span>Смеркалось.    Ворчало. Кричало.</span>")
+  end
+
+  def test_a_blank_line_separates_sentences
+    assert_equal ["Первое предложение.", "Второе предложение."],
+                 cores("Первое предложение.\n\nВторое предложение.")
+  end
+
+  # A lone newline is not a sentence boundary -- this was a real regression.
+  def test_a_single_newline_does_not_split_a_sentence
+    assert_equal ["test\nphrase"], cores("test\nphrase")
+  end
+
+  def test_markup_holding_nothing_but_a_line_break_offers_nothing_to_translate
+    assert_empty cores("<div>\n</div>")
+    assert_round_trips("<div>\n</div>")
+  end
+
+  # -- translation and rendering -------------------------------------------
+
+  def test_translating_every_segment_rebuilds_the_document
+    subject = passage("<b>Bold</b> text here. Second sentence.")
+    subject.segments.reject(&:empty?).each { |s| s.translation = s.core.upcase }
+
+    assert_equal "<b>BOLD</b> TEXT HERE. SECOND SENTENCE.", subject.render
+  end
+
+  def test_padding_between_sentences_survives_translation
+    subject = passage("  One.   Two.  ")
+    subject.segments.reject(&:empty?).each { |s| s.translation = s.core.upcase }
+
+    assert_equal "  ONE.   TWO.  ", subject.render
+  end
+
+  def test_an_untranslated_segment_renders_its_source
+    subject = passage("One. Two.")
+    subject.segments.reject(&:empty?).first.translation = "ОДИН."
+
+    assert_equal "ОДИН. Two.", subject.render
+  end
+end
diff --git a/test/translation_diff/pipeline_corpus_test.rb b/test/translation_diff/pipeline_corpus_test.rb
new file mode 100644
index 0000000..01b083c
--- /dev/null
+++ b/test/translation_diff/pipeline_corpus_test.rb
@@ -0,0 +1,94 @@
+require "test_helper"
+require "support/pipeline_corpus"
+
+# Judges the pipeline rewrite against test/fixtures/pipeline_baseline.txt, captured before any of the pipeline
+# changed, translating every input the way the baseline script did: through the :null provider, en to ru.
+class PipelineCorpusTest < ConfiguredTest
+  # Committed, not read from a developer's home directory: a test that depends on an untracked file on one machine
+  # passes there and fails everywhere else, which is what it did in CI.
+  BASELINE_PATH = File.expand_path("../fixtures/pipeline_baseline.txt", __dir__)
+
+  def self.baseline_outputs
+    @baseline_outputs ||= File.read(BASELINE_PATH).scan(/^=== (.+) ===\nOUTPUT: (.*)\n/).to_h
+  end
+
+  def translated(name)
+    TranslationDiff.translate(PipelineCorpus::INPUTS.fetch(name), from: "en", to: "ru", provider: :null).inspect
+  end
+
+  def passage(name)
+    TranslationDiff::Passage.new(PipelineCorpus::INPUTS.fetch(name),
+                                 segmenter: TranslationDiff::Segmenters::Pragmatic.new)
+  end
+
+  # What Passage now hands a provider, which is where the fixed inputs actually differ.
+  def provider_texts(name) = passage(name).segments.reject(&:empty?).map(&:core)
+
+  # Nothing translated, so the document owes its caller the bytes it arrived as.
+  def untranslated_render(name) = passage(name).render
+
+  # Every sentence back as it was sent, which is what :null does -- the new pipeline's answer to the document column.
+  def echoed_render(name)
+    subject = passage(name)
+    subject.segments.reject(&:empty?).each { |segment| segment.translation = segment.core }
+    subject.render
+  end
+
+  def self.method_name_for(name) = :"test_#{name.gsub(/[^a-zA-Z0-9]+/, '_')}"
+
+  (PipelineCorpus::INPUTS.keys - PipelineCorpus::EXPECTED_TO_CHANGE).each do |name|
+    define_method(method_name_for(name)) do
+      assert_equal self.class.baseline_outputs.fetch(name), translated(name)
+    end
+  end
+
+  # The names in EXPECTED_TO_CHANGE, written out: the texts a provider is sent, what TranslationDiff.translate
+  # returns end to end, and Passage's render round trip -- byte-exact untranslated, equivalent markup once every
+  # sentence is back. document: and echoed: are independent literals, kept apart even where they agree, so a
+  # regression in either translate or render is caught by its own assertion rather than by one value checked twice.
+  # The pipeline this replaced sent ["Salt &amp; pepper.", "Fine."] for the first, ["Hard&nbsp;space here.", "Fine."]
+  # for the second, ["if a"] for the third, ["5", "6.", "True."] for the fourth and ["a"] for the fifth.
+  CHANGED = {
+    "entity ampersand" => {
+      texts: ["Salt & pepper.", "Fine."],
+      document: "Salt &amp; pepper. Fine.",
+      echoed: "Salt &amp; pepper. Fine."
+    },
+    "entity nbsp" => {
+      texts: ["Hard\u00A0space here.", "Fine."],
+      # The entity is spelled as the character it means, which is the same document to a browser and not the same bytes.
+      document: "Hard\u00A0space here. Fine.",
+      echoed: "Hard\u00A0space here. Fine."
+    },
+    "bare less-than" => {
+      texts: ["if a < b then stop.", "Fine."],
+      document: "if a < b then stop. Fine.",
+      echoed: "if a < b then stop. Fine."
+    },
+    "bare less-than and greater" => {
+      texts: ["5 < 6 and 7 > 6.", "True."],
+      document: "5 < 6 and 7 > 6. True.",
+      echoed: "5 < 6 and 7 > 6. True."
+    },
+    # The recorded limit: `<b` is read as a tag, so the sentence after it is markup and never reaches a provider.
+    "bare less-than before a letter" => {
+      texts: ["a"],
+      document: "a <b then stop. Fine.",
+      echoed: "a <b then stop. Fine."
+    }
+  }.freeze
+
+  CHANGED.each do |name, expected|
+    define_method(method_name_for(name)) do
+      assert_equal expected[:texts], provider_texts(name)
+      assert_equal expected[:document].inspect, translated(name)
+      assert_equal PipelineCorpus::INPUTS.fetch(name), untranslated_render(name)
+      assert_equal expected[:echoed], echoed_render(name)
+    end
+  end
+
+  # Without this, a sixth name in EXPECTED_TO_CHANGE would be subtracted from the generic loop and tested by neither.
+  def test_every_expected_change_is_actually_asserted
+    assert_equal PipelineCorpus::EXPECTED_TO_CHANGE.sort, CHANGED.keys.sort
+  end
+end
diff --git a/test/translation_diff/request_test.rb b/test/translation_diff/request_test.rb
deleted file mode 100644
index ebce31c..0000000
--- a/test/translation_diff/request_test.rb
+++ /dev/null
@@ -1,343 +0,0 @@
-require "test_helper"
-
-class RequestTest < ConfiguredTest
-  # Records what it was asked to translate, and answers with a canned response.
-  class FakeApi < TranslationDiff::Provider
-    CAPABILITIES = TranslationDiff::Capabilities.new(
-      max_request_size: 1_000_000, max_batch_size: 1_000_000, max_text_size: nil,
-      html: :none, notranslate: false, detects_language: true, reports_billing: false
-    ).freeze
-
-    def self.capabilities = CAPABILITIES
-
-    attr_reader :calls
-
-    def initialize(response, detected: nil)
-      super(TranslationDiff::Configuration.new)
-      @response = response
-      @detected = detected
-      @calls = []
-    end
-
-    def translate(request)
-      @calls << [request.texts, request.from, request.to, request.options]
-      TranslationDiff::Translation::Response.build(
-        request: request, texts: @response.shift(request.texts.size)
-      )
-    end
-
-    def detect(text)
-      @calls << [:detect, text]
-      @detected
-    end
-
-    def cache_key = "fake"
-  end
-
-  # Proves the generalisation took effect: capabilities capping the batch at one must change the chunking.
-  class NarrowBatchApi < FakeApi
-    def self.capabilities
-      TranslationDiff::Capabilities.new(
-        max_request_size: 1_000_000, max_batch_size: 1, max_text_size: nil,
-        html: :none, notranslate: false, detects_language: true, reports_billing: false
-      )
-    end
-  end
-
-  # Registered under :echo to exercise resolving a provider by name through the registry.
-  class EchoProvider < TranslationDiff::Provider
-    def self.capabilities
-      TranslationDiff::Capabilities.new(
-        max_request_size: 1_000_000, max_batch_size: 1_000_000, max_text_size: nil,
-        html: :none, notranslate: false, detects_language: false, reports_billing: false
-      )
-    end
-
-    def translate(request) = TranslationDiff::Translation::Response.build(request: request, texts: request.texts)
-
-    def cache_key = "echo"
-  end
-  TranslationDiff::Providers.register(:echo, EchoProvider) unless TranslationDiff::Providers.registered?(:echo)
-
-  # Always misses, so every value reaches the API.
-  class FakeCacheStore
-    attr_reader :writes
-
-    def initialize
-      @writes = {}
-    end
-
-    def read_multi(keys)
-      [nil] * keys.size
-    end
-
-    def write(key, value)
-      @writes[key] = value
-    end
-  end
-
-  # An object assigned straight to `config.provider` never passed through the registry's stamping.
-  class NamelessApi < FakeApi
-    def cache_key = ""
-  end
-
-  # A whitespace-only key is just as blank as an empty one; it must not slip past the guard.
-  class WhitespaceNamedApi < FakeApi
-    def cache_key = "   "
-  end
-
-  # Proves the all-cached short circuit: serving a translation from cache without calling the adapter at all.
-  class AllCachedStore
-    def initialize(responses)
-      @responses = responses
-    end
-
-    def read_multi(keys)
-      @responses.first(keys.size)
-    end
-
-    def write(*)
-      raise "should not write when nothing was missing"
-    end
-  end
-
-  def test_translates_a_plain_string
-    result, api = translate("Some string", ["Какая-то строка"])
-
-    assert_equal "Какая-то строка", result
-    assert_equal [[["Some string"], :en, :ru, {}]], api.calls
-  end
-
-  def test_translates_the_values_of_a_flat_hash
-    result, api = translate({ title: "One", description: "Two" }, %w[Один Два])
-
-    assert_equal({ title: "Один", description: "Два" }, result)
-    assert_equal [[%w[One Two], :en, :ru, {}]], api.calls
-  end
-
-  def test_translates_nested_values_and_blanks_out_nils
-    values = { title: "One", more: { description: "Two" }, skip: nil }
-
-    result, api = translate(values, %w[Один Два])
-
-    assert_equal({ title: "Один", more: { description: "Два" }, skip: "" }, result)
-    assert_equal [[%w[One Two], :en, :ru, {}]], api.calls
-  end
-
-  MARKUP_VALUES = {
-    title: "One",
-    more: {
-      description: "<b>Black</b>",
-      color: %(So   <font size='35'><script>One</script><!-- Test -->Red\n</font> that)
-    }
-  }.freeze
-
-  MARKUP_TRANSLATED = {
-    title: "Один",
-    more: {
-      description: "<b>Черный</b>",
-      color: %(Что   <font size='35'><script>One</script><!-- Test -->Кра\n</font> что)
-    }
-  }.freeze
-
-  def test_translates_text_around_markup_and_leaves_the_markup_alone
-    result, api = translate(MARKUP_VALUES, %w[Один Черный Что Кра что])
-
-    assert_equal MARKUP_TRANSLATED, result
-    assert_equal [[%w[One Black So Red that], :en, :ru, {}]], api.calls
-  end
-
-  # True of the public interface, but not new: 2.1.0 already protected the caller's hash by dup-ing it.
-  def test_repeated_calls_leave_the_callers_options_hash_alone
-    options = { from: :en, to: :ru }
-
-    configure_with(FakeApi.new(["Какая-то строка", "Какая-то строка"]))
-
-    2.times do
-      assert_equal "Какая-то строка", TranslationDiff.translate("Some string", **options)
-    end
-    assert_equal({ from: :en, to: :ru }, options)
-  end
-
-  # The initializer now declares one positional parameter, so a positional options hash is no longer accepted.
-  def test_the_positional_options_hash_is_no_longer_accepted
-    assert_raises(ArgumentError) do
-      TranslationDiff::Request.new("text", { from: :en, to: :ru })
-    end
-  end
-
-  # A detected language is a String while :to is usually a Symbol -- without casecmp? this never short-circuits.
-  def test_skips_the_translation_when_the_detected_language_is_the_target
-    api = FakeApi.new([], detected: "RU")
-    configure_with(api)
-
-    result = TranslationDiff::Request.new("привет", to: :ru).call
-
-    assert_equal "привет", result
-    assert_equal [[:detect, "привет"]], api.calls
-  end
-
-  # Chunker's limits used to come from two provider methods; they now come from the declared capabilities.
-  # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
-  def test_chunking_uses_the_providers_declared_capabilities
-    narrow = Class.new(TranslationDiff::Provider) do
-      def self.capabilities
-        TranslationDiff::Capabilities.new(
-          max_request_size: 20, max_batch_size: 1, max_text_size: nil,
-          html: :none, notranslate: false, detects_language: false, reports_billing: false
-        )
-      end
-
-      attr_reader :batches
-
-      def initialize(config)
-        super
-        @batches = []
-      end
-
-      def translate(request)
-        @batches << request.texts
-        TranslationDiff::Translation::Response.build(request: request, texts: request.texts)
-      end
-
-      def cache_key = "narrow"
-    end
-
-    provider = narrow.new(TranslationDiff::Configuration.new)
-    TranslationDiff.translate("One. Two. Three.", from: "en", to: "ru", provider: provider)
-
-    assert(provider.batches.all? { |batch| batch.size == 1 },
-           "expected one text per request, got #{provider.batches.inspect}")
-  end
-
-  # The old check was `respond_to?(:detect)`, satisfied by inheriting the base class's raising stub.
-  def test_a_provider_that_cannot_detect_says_so_before_it_is_called
-    error = assert_raises(TranslationDiff::Request::Error) do
-      TranslationDiff.translate("Some text.", to: "ru", provider: :null)
-    end
-
-    assert_match(/cannot detect/, error.message)
-    assert_match(/null/, error.message)
-  end
-
-  # The count check now lives in Translation::Response.build, so it holds for every provider, hence ResponseError.
-  def test_raises_when_the_api_returns_fewer_translations_than_asked_for
-    configure_with(FakeApi.new(%w[Один]))
-
-    error = assert_raises(TranslationDiff::ResponseError) do
-      TranslationDiff::Request.new({ a: "One", b: "Two" }, from: :en, to: :ru).call
-    end
-
-    assert_match(/returned 1 translations for 2 values/, error.message)
-  end
-
-  # These used to raise NoMethodError on #empty? or TypeError inside Ox.
-  UNTRANSLATABLE = [42, :sym, "", "   "].freeze
-
-  UNTRANSLATABLE.each do |value|
-    define_method(:"test_passes_through_#{value.inspect.gsub(/\W/, '_')}_untouched") do
-      api = FakeApi.new([])
-      configure_with(api)
-
-      assert_equal value, TranslationDiff::Request.new(value, from: :en, to: :ru).call
-      assert_empty api.calls
-    end
-  end
-
-  def test_passes_through_nil_untouched
-    api = FakeApi.new([])
-    configure_with(api)
-
-    assert_nil TranslationDiff::Request.new(nil, from: :en, to: :ru).call
-    assert_empty api.calls
-  end
-
-  # Scalars nested in a structure are passed through too, while nil keeps collapsing to "".
-  def test_passes_nested_scalars_through_and_still_blanks_out_nils
-    configure_with(FakeApi.new(%w[Один]))
-
-    result = TranslationDiff::Request.new({ a: "One", n: 42, skip: nil }, from: :en, to: :ru).call
-
-    assert_equal({ a: "Один", n: 42, skip: "" }, result)
-  end
-
-  # Proves the generalisation took effect: a provider declaring tiny limits must change the batching.
-  def test_batches_according_to_the_limits_the_adapter_declares
-    api = NarrowBatchApi.new(%w[Один Два])
-    configure_with(api)
-
-    TranslationDiff::Request.new({ a: "One", b: "Two" }, from: :en, to: :ru).call
-
-    assert_equal 2, api.calls.size, "one call per text at a batch size of 1"
-  end
-
-  # The only Request-level test exercising a cache hit; every other fake store in this file always misses.
-  def test_serves_a_translation_from_cache_without_calling_the_adapter
-    api = FakeApi.new([])
-    configure_with(api, AllCachedStore.new(["Какая-то строка"]))
-
-    result = TranslationDiff::Request.new("Some string", from: :en, to: :ru).call
-
-    assert_equal "Какая-то строка", result
-    assert_empty api.calls
-  end
-
-  # `provider:` picks the provider for one call; the configured provider is left untouched and unused.
-  def test_the_provider_keyword_overrides_the_configured_provider_for_one_call
-    api = FakeApi.new(%w[Один])
-    configure_with(api)
-
-    result = TranslationDiff::Request.new("One", from: :en, to: :ru, provider: :echo).call
-
-    assert_equal "One", result
-    assert_empty api.calls
-  end
-
-  # The `provider:` keyword is the third way to supply one; it must fail in the same words as the other two.
-  def test_a_provider_object_passed_for_one_call_that_is_not_a_provider_is_refused
-    error = assert_raises(TranslationDiff::InvalidProviderError) do
-      TranslationDiff::Request.new("One", from: :en, to: :ru, provider: Object.new).call
-    end
-
-    assert_match(/TranslationDiff::Provider/, error.message)
-  end
-
-  # An empty cache-key segment would put this provider's translations in every other provider's namespace.
-  def test_a_provider_whose_cache_key_is_empty_is_refused_rather_than_sharing_a_namespace
-    configure_with(NamelessApi.new(%w[Один]))
-
-    error = assert_raises(TranslationDiff::Request::Error) do
-      TranslationDiff::Request.new("One", from: :en, to: :ru).call
-    end
-
-    assert_match(/must define #cache_key/, error.message)
-  end
-
-  def test_a_provider_whose_cache_key_is_whitespace_is_refused_rather_than_sharing_a_namespace
-    configure_with(WhitespaceNamedApi.new(%w[Один]))
-
-    error = assert_raises(TranslationDiff::Request::Error) do
-      TranslationDiff::Request.new("One", from: :en, to: :ru).call
-    end
-
-    assert_match(/must define #cache_key/, error.message)
-  end
-
-  private
-
-  # Returns the translation and the API fake, so the call can be asserted on.
-  def translate(values, response)
-    api = FakeApi.new(response)
-    configure_with(api)
-
-    [TranslationDiff::Request.new(values, from: :en, to: :ru).call, api]
-  end
-
-  # An object assigned to `provider` or `cache` is used as-is, so a fake goes in exactly where a name would.
-  def configure_with(api, store = FakeCacheStore.new)
-    TranslationDiff.configure do |config|
-      config.provider = api
-      config.cache = store
-    end
-  end
-end
diff --git a/test/translation_diff/segment_test.rb b/test/translation_diff/segment_test.rb
new file mode 100644
index 0000000..94182a6
--- /dev/null
+++ b/test/translation_diff/segment_test.rb
@@ -0,0 +1,82 @@
+require "test_helper"
+
+class SegmentTest < Minitest::Test
+  def test_core_is_the_sentence_without_its_padding
+    assert_equal "It was getting dark.", TranslationDiff::Segment.new("  It was getting dark.  ").core
+  end
+
+  def test_source_is_kept_exactly
+    assert_equal "  It was getting dark.  ", TranslationDiff::Segment.new("  It was getting dark.  ").source
+  end
+
+  def test_render_puts_the_translation_back_inside_the_original_padding
+    segment = TranslationDiff::Segment.new("  It was getting dark.  ")
+    segment.translation = "Смеркалось."
+
+    assert_equal "  Смеркалось.  ", segment.render
+  end
+
+  # The padding is whatever was there, not a normalised guess at it.
+  def test_padding_is_reproduced_character_for_character
+    segment = TranslationDiff::Segment.new("\n\t One. \n")
+    segment.translation = "Один."
+
+    assert_equal "\n\t Один. \n", segment.render
+  end
+
+  def test_an_untranslated_segment_renders_its_source
+    assert_equal "  One.  ", TranslationDiff::Segment.new("  One.  ").render
+  end
+
+  def test_translated_reports_whether_a_translation_was_set
+    segment = TranslationDiff::Segment.new("One.")
+
+    refute_predicate segment, :translated?
+    segment.translation = "Один."
+    assert_predicate segment, :translated?
+  end
+
+  # A run of whitespace between two sentences is a segment with nothing to
+  # translate. It must render unchanged and never reach a provider.
+  def test_a_segment_of_only_whitespace_is_empty
+    segment = TranslationDiff::Segment.new("   \n ")
+
+    assert_predicate segment, :empty?
+    assert_equal "   \n ", segment.render
+  end
+
+  def test_a_segment_with_words_is_not_empty
+    refute_predicate TranslationDiff::Segment.new(" One. "), :empty?
+  end
+
+  def test_an_empty_source_is_empty
+    assert_predicate TranslationDiff::Segment.new(""), :empty?
+  end
+
+  # String literals are mutable in this project -- the magic comment was
+  # removed everywhere -- so a segment must not alias the string it was given.
+  def test_mutating_the_source_afterwards_does_not_change_the_segment
+    source = +"  One.  "
+    segment = TranslationDiff::Segment.new(source)
+    source << "trailing junk"
+
+    assert_equal "  One.  ", segment.source
+    assert_equal "One.", segment.core
+    assert_equal "  One.  ", segment.render
+  end
+
+  def test_a_segment_of_only_a_non_breaking_space_is_empty
+    segment = TranslationDiff::Segment.new(" ")
+
+    assert_predicate segment, :empty?
+    assert_equal " ", segment.render
+  end
+
+  def test_a_non_breaking_space_around_a_sentence_is_padding
+    segment = TranslationDiff::Segment.new(" One. ")
+    segment.translation = "Один."
+
+    assert_equal "One.", segment.core
+    assert_equal " Один. ", segment.render
+  end
+end
diff --git a/test/translation_diff/sentence_cache_test.rb b/test/translation_diff/sentence_cache_test.rb
new file mode 100644
index 0000000..c70f8bb
--- /dev/null
+++ b/test/translation_diff/sentence_cache_test.rb
@@ -0,0 +1,208 @@
+require "test_helper"
+
+class SentenceCacheTest < Minitest::Test
+  # Records what it is asked for, so a test can assert on keys as well as
+  # values. Minitest 6 has no mocking library; this is the whole contract.
+  class RecordingStore
+    attr_reader :reads, :writes
+
+    def initialize(values = {})
+      @values = values
+      @reads = []
+      @writes = {}
+    end
+
+    def read_multi(keys)
+      @reads.concat(keys)
+      keys.map { |k| @values[k] }
+    end
+
+    def write(key, value) = @writes[key] = value
+  end
+
+  def cache(store, **)
+    TranslationDiff::SentenceCache.new(
+      store: store, provider: "deepl", from: "en", to: "ru", **
+    )
+  end
+
+  def segments(*sources) = sources.map { |s| TranslationDiff::Segment.new(s) }
+
+  def test_a_hit_fills_the_segment_and_is_not_returned_as_a_miss
+    subject = segments("One.")
+    store = RecordingStore.new
+    key = cache(store).key(subject.first)
+    store = RecordingStore.new(key => "Один.")
+
+    misses = cache(store).fill(subject)
+
+    assert_equal "Один.", subject.first.translation
+    assert_empty misses
+  end
+
+  def test_a_miss_is_returned_and_left_untranslated
+    subject = segments("One.")
+
+    misses = cache(RecordingStore.new).fill(subject)
+
+    assert_equal subject, misses
+    refute_predicate subject.first, :translated?
+  end
+
+  def test_store_writes_only_the_translated_ones
+    subject = segments("One.", "Two.")
+    subject.first.translation = "Один."
+    store = RecordingStore.new
+    subject_cache = cache(store)
+
+    subject_cache.store(subject)
+
+    assert_equal ["Один."], store.writes.values
+  end
+
+  # The bug this replaces: the old cache consumed the array of updates it was
+  # handed, emptying a collection that belonged to its caller.
+  def test_neither_operation_modifies_the_collection_it_is_given
+    subject = segments("One.", "Two.")
+    original = subject.dup
+
+    subject_cache = cache(RecordingStore.new)
+    subject_cache.fill(subject)
+    subject_cache.store(subject)
+
+    assert_equal original, subject
+    assert_equal 2, subject.size
+  end
+
+  def test_the_same_sentence_in_two_languages_gets_two_keys
+    segment = segments("One.").first
+    en_ru = cache(RecordingStore.new).key(segment)
+    en_de = TranslationDiff::SentenceCache.new(
+      store: RecordingStore.new, provider: "deepl", from: "en", to: "de"
+    ).key(segment)
+
+    refute_equal en_ru, en_de
+  end
+
+  def test_two_providers_do_not_share_a_key
+    segment = segments("One.").first
+    deepl = cache(RecordingStore.new).key(segment)
+    google = TranslationDiff::SentenceCache.new(
+      store: RecordingStore.new, provider: "google", from: "en", to: "ru"
+    ).key(segment)
+
+    refute_equal deepl, google
+  end
+
+  def test_per_call_options_are_part_of_the_key
+    segment = segments("One.").first
+    plain = cache(RecordingStore.new).key(segment)
+    formal = cache(RecordingStore.new, options: { formality: :more }).key(segment)
+
+    refute_equal plain, formal
+  end
+
+  # The promise that a released cache keeps working. These values come from
+  # the baseline Task 1 recorded against the pipeline being replaced.
+  # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
+  def test_keys_match_the_ones_the_previous_pipeline_produced
+    subject_cache = TranslationDiff::SentenceCache.new(
+      store: RecordingStore.new, provider: "null", from: "en", to: "ru"
+    )
+
+    assert_equal "null:en:ru:9d6a2963872077db674a27a39c492e61",
+                 subject_cache.key(segments("Hello there.").first)
+    assert_equal "null:en:ru:1520f71fffb5adf0da75e7c17059bfd1",
+                 subject_cache.key(segments("Second sentence!").first)
+    assert_equal "null:en:ru:900019fa233e608091ba641d50d69b81",
+                 subject_cache.key(segments("One.").first)
+    assert_equal "null:en:ru:fdb02803abc46fba06ce1cc96d6399c5",
+                 subject_cache.key(segments("Two.").first)
+    assert_equal "null:en:ru:3f77101fc43570a61d5bc042bb908651",
+                 subject_cache.key(segments("Third.").first)
+    assert_equal "null:en:ru:fe3bf43723a64fb32bcac8d99bb431af",
+                 subject_cache.key(segments("  Padded sentence.  ").first)
+    assert_equal "null:en:ru:05d12994070fdde458e566149f42472f",
+                 subject_cache.key(segments("Salt &amp; pepper.").first)
+    assert_equal "null:en:ru:b5010567e209726a125c9ed59162eca5",
+                 subject_cache.key(segments("Fine.").first)
+  end
+
+  # Four fields without options, five with: the options digest is its own field, not folded into the sentence.
+  def test_the_options_digest_is_a_field_of_its_own
+    segment = segments("One.").first
+
+    assert_equal 4, cache(RecordingStore.new).key(segment).split(":").size
+    assert_equal 5, cache(RecordingStore.new, options: { formality: :more }).key(segment).split(":").size
+  end
+
+  # Recovered from the pipeline being replaced by running it against a recording store: one option, two
+  # options, and two whose sort order is not their literal order, which is the pair that proves the sort.
+  def test_the_options_digest_matches_the_keys_the_previous_pipeline_produced
+    segment = segments("One.").first
+
+    { { formality: :more } => "null:en:ru:c09f3c46:900019fa233e608091ba641d50d69b81",
+      { formality: :more, glossary_id: "g1" } => "null:en:ru:c1ee2461:900019fa233e608091ba641d50d69b81",
+      { b: 2, a: 1 } => "null:en:ru:9dc867b7:900019fa233e608091ba641d50d69b81" }.each do |options, expected|
+      subject_cache = TranslationDiff::SentenceCache.new(
+        store: RecordingStore.new, provider: "null", from: "en", to: "ru", options: options
+      )
+
+      assert_equal expected, subject_cache.key(segment)
+    end
+  end
+
+  # Container values recurse: a Hash canonicalises the way the options hash itself does, an Array in order.
+  # The first two were captured from the pipeline being replaced; the third goes a level deeper than either.
+  def test_container_option_values_recurse_the_way_the_previous_pipeline_did
+    segment = segments("One.").first
+
+    { { glossary: { a: 1, b: 2 } } => "null:en:ru:4dbc310c:900019fa233e608091ba641d50d69b81",
+      { tags: %w[x y] } => "null:en:ru:6b1bf7d6:900019fa233e608091ba641d50d69b81",
+      { glossary: { a: [1, 2] } } => "null:en:ru:1948f701:900019fa233e608091ba641d50d69b81" }.each do |options, key|
+      subject_cache = TranslationDiff::SentenceCache.new(
+        store: RecordingStore.new, provider: "null", from: "en", to: "ru", options: options
+      )
+
+      assert_equal key, subject_cache.key(segment)
+    end
+  end
+
+  # An allowlist, not a denylist: a tidy #inspect with no address in it is still one the old pipeline refused.
+  def test_a_value_outside_the_permitted_types_raises_even_when_its_inspect_is_stable
+    subject_cache = cache(RecordingStore.new, options: { glossary: Struct.new(:x).new(1) })
+
+    error = assert_raises(TranslationDiff::SentenceCache::Error) { subject_cache.key(segments("One.").first) }
+
+    assert_includes error.message, "glossary"
+  end
+
+  # A Symbol and a String are not comparable with each other, so sorting on the raw keys raises on this hash.
+  def test_mixed_option_key_types_canonicalise_instead_of_raising
+    segment = segments("One.").first
+    symbol_first = cache(RecordingStore.new, options: { formality: :more, "glossary" => "g" })
+    string_first = cache(RecordingStore.new, options: { "glossary" => "g", formality: :more })
+
+    assert_equal symbol_first.key(segment), string_first.key(segment)
+  end
+
+  # A value rendering as an address gives a key that can never be hit twice, so it fails where a user can see it.
+  def test_an_option_with_no_stable_string_form_raises_and_names_it
+    subject_cache = cache(RecordingStore.new, options: { glossary: Object.new })
+
+    error = assert_raises(TranslationDiff::SentenceCache::Error) { subject_cache.key(segments("One.").first) }
+
+    assert_kind_of TranslationDiff::Error, error
+    assert_includes error.message, "glossary"
+  end
+
+  # One definition of padding, the one Segment already makes: the key hashes the body it cut, not a copy of its regex.
+  def test_the_key_hashes_the_body_segment_cut
+    segment = segments("  Padded sentence.  ").first
+
+    key = cache(RecordingStore.new).key(segment)
+
+    assert_equal "Padded sentence.", segment.body
+    assert_equal Digest::MD5.hexdigest(segment.body), key.split(":").last
+  end
+end
diff --git a/test/translation_diff/spacing_test.rb b/test/translation_diff/spacing_test.rb
deleted file mode 100644
index fa9df39..0000000
--- a/test/translation_diff/spacing_test.rb
+++ /dev/null
@@ -1,11 +0,0 @@
-require "test_helper"
-
-class SpacingTest < Minitest::Test
-  def test_restores_trailing_spaces
-    assert_equal "А   ", TranslationDiff::Spacing.restore("a   ", "А")
-  end
-
-  def test_restores_leading_and_trailing_spaces
-    assert_equal "  Б ", TranslationDiff::Spacing.restore("  b ", "Б")
-  end
-end
diff --git a/test/translation_diff/tokenizer_test.rb b/test/translation_diff/tokenizer_test.rb
deleted file mode 100644
index 24d5e07..0000000
--- a/test/translation_diff/tokenizer_test.rb
+++ /dev/null
@@ -1,156 +0,0 @@
-require "test_helper"
-
-class TokenizerTest < Minitest::Test
-  PLAIN_TEXT = "test\nphrase".freeze
-
-  NESTED_NOTRANSLATE = "<span class='notranslate'>foo" \
-                       "<span class='notranslate'>bar</span>baz" \
-                       "</span>".freeze
-
-  # source => expected tokens
-  CASES = {
-    "an_empty_source" => [
-      "",
-      []
-    ],
-    "markup_holding_nothing_but_a_line_break" => [
-      "<div>\n</div>",
-      [["<div>", :markup], ["</div>", :markup]]
-    ],
-    "text_without_markup" => [
-      PLAIN_TEXT,
-      [[PLAIN_TEXT, :text]]
-    ],
-    "markup_ending_with_text" => [
-      "alfa<span>bravo</span>kilo",
-      [
-        ["alfa", :text],
-        ["<span>", :markup],
-        ["bravo", :text],
-        ["</span>", :markup],
-        ["kilo", :text]
-      ]
-    ],
-    "markup_ending_with_a_tag" => [
-      "alfa<span>bravo</span>",
-      [
-        ["alfa", :text],
-        ["<span>", :markup],
-        ["bravo", :text],
-        ["</span>", :markup]
-      ]
-    ],
-    "non_ascii_text_around_script_and_style" => [
-      "аль<span>бра</span>кил<script>js</script><style>b</style>",
-      [
-        ["аль", :text],
-        ["<span>", :markup],
-        ["бра", :text],
-        ["</span>", :markup],
-        ["кил", :text],
-        ["<script>js</script><style>b</style>", :markup]
-      ]
-    ],
-    "text_split_into_sentences" => [
-      "! Киловольт. <span>Смеркалось.    Ворчало. Кричало.</span>",
-      [
-        # A lone terminator with no preceding content stays merged: a missed boundary, not a false one.
-        ["! Киловольт. ", :text],
-        ["<span>", :markup],
-        ["Смеркалось.    ", :text],
-        ["Ворчало. ", :text],
-        ["Кричало.", :text],
-        ["</span>", :markup]
-      ]
-    ],
-    "notranslate_spans_kept_as_text" => [
-      "<span class='notranslate'>test</span><b>\n<span class='notranslate'>x</span>y</b>",
-      [
-        ["<span class='notranslate'>test</span>", :text],
-        ["<b>", :markup],
-        ["\n<span class='notranslate'>x</span>y", :text],
-        ["</b>", :markup]
-      ]
-    ],
-    "a_notranslate_span_inside_another_span" => [
-      "<span><span class='notranslate'>foo<span>bar<br></span>baz</span></span>",
-      [
-        ["<span>", :markup],
-        ["<span class='notranslate'>foo<span>bar<br></span>baz</span>", :text],
-        ["</span>", :markup]
-      ]
-    ],
-    "a_notranslate_span_inside_another_notranslate_span" => [
-      NESTED_NOTRANSLATE,
-      [[NESTED_NOTRANSLATE, :text]]
-    ],
-    "a_br_tag_before_a_closing_tag" => [
-      "<font size='3'>Смеркалось.<br></font>",
-      [
-        ["<font size='3'>", :markup],
-        ["Смеркалось.", :text],
-        ["<br></font>", :markup]
-      ]
-    ],
-    "a_processing_instruction" => [
-      "Hey!<br />Look!<?xml:namespace ns=\"urn:office\" ?>",
-      [
-        ["Hey!", :text],
-        ["<br />", :markup],
-        ["Look!", :text],
-        ["<?xml:namespace ns=\"urn:office\" ?>", :markup]
-      ]
-    ],
-    # Without a handler, the bytes a comment/doctype/CDATA event covers vanish from the rebuilt string.
-    "an_html_comment" => [
-      "<!-- note --> Visible text.",
-      [
-        ["<!-- note -->", :markup],
-        [" Visible text.", :text]
-      ]
-    ],
-    "a_doctype" => [
-      "<!DOCTYPE html><p>Body text.</p>",
-      [
-        ["<!DOCTYPE html><p>", :markup],
-        ["Body text.", :text],
-        ["</p>", :markup]
-      ]
-    ],
-    "a_cdata_section" => [
-      "Before.<![CDATA[raw & unparsed]]>After.",
-      [
-        ["Before.", :text],
-        ["<![CDATA[raw & unparsed]]>", :markup],
-        ["After.", :text]
-      ]
-    ],
-    "a_comment_between_two_sentences" => [
-      "First sentence. <!-- aside --> Second sentence.",
-      [
-        ["First sentence. ", :text],
-        ["<!-- aside -->", :markup],
-        [" Second sentence.", :text]
-      ]
-    ],
-    "sentences_separated_by_blank_lines" => [
-      "Набор «Солнечная механика» от 4М — это 6 экспериментов." \
-      "\n\nЮному изобретателю предстоит воочию посмотреть на чудеса.",
-      [
-        ["Набор «Солнечная механика» от 4М — это 6 экспериментов.\n\n", :text],
-        ["Юному изобретателю предстоит воочию посмотреть на чудеса.", :text]
-      ]
-    ]
-  }.freeze
-
-  CASES.each do |name, (source, expected)|
-    define_method(:"test_tokenizes_#{name}") do
-      assert_equal expected, TranslationDiff::Tokenizer.tokenize(source, segmenter: segmenter)
-    end
-  end
-
-  private
-
-  # Passed explicitly now that the tokenizer takes its segmenter as a collaborator, not a global.
-  def segmenter = TranslationDiff::Segmenters::Pragmatic.new
-end
diff --git a/test/translation_diff/translation/response_test.rb b/test/translation_diff/translation/response_test.rb
index 1ce7f7e..96bc511 100644
--- a/test/translation_diff/translation/response_test.rb
+++ b/test/translation_diff/translation/response_test.rb
@@ -25,7 +25,7 @@ def test_build_raises_when_the_provider_returned_the_wrong_number_of_texts
     assert_match(/2/, error.message)
   end
 
-  # A nil translation used to reach Spacing.restore and die there as NoMethodError, naming nothing.
+  # A nil translation used to reach the old pipeline's spacing step and die there as NoMethodError, naming nothing.
   def test_build_raises_when_a_translation_is_not_a_string
     error = assert_raises(TranslationDiff::ResponseError) do
       TranslationDiff::Translation::Response.build(request: request, texts: ["один", nil])
diff --git a/test/translation_diff/translator_test.rb b/test/translation_diff/translator_test.rb
new file mode 100644
index 0000000..e84fbab
--- /dev/null
+++ b/test/translation_diff/translator_test.rb
@@ -0,0 +1,361 @@
+require "test_helper"
+
+class TranslatorTest < ConfiguredTest
+  class RecordingProvider < TranslationDiff::Provider
+    def self.capabilities
+      TranslationDiff::Capabilities.new(
+        max_request_size: 1_000, max_batch_size: 10, max_text_size: nil,
+        html: :none, notranslate: false, detects_language: true, reports_billing: false
+      )
+    end
+
+    attr_reader :requests
+
+    def initialize(config)
+      super
+      @requests = []
+    end
+
+    def translate(request)
+      @requests << request
+      TranslationDiff::Translation::Response.build(
+        request: request, texts: request.texts.map(&:upcase)
+      )
+    end
+
+    def detect(_text) = "en"
+    def cache_key = "recording"
+  end
+
+  # The capability is the only honest test: every provider inherits a #detect that raises.
+  class BlindProvider < RecordingProvider
+    def self.capabilities
+      TranslationDiff::Capabilities.new(
+        max_request_size: 1_000, max_batch_size: 10, max_text_size: nil,
+        html: :none, notranslate: false, detects_language: false, reports_billing: false
+      )
+    end
+
+    def cache_key = "blind"
+  end
+
+  # An empty cache key would file this provider's translations in every other provider's namespace.
+  class NamelessProvider < RecordingProvider
+    def cache_key = "   "
+  end
+
+  class FakeLogger
+    attr_reader :lines
+
+    def initialize = @lines = []
+
+    def debug(&) = @lines << yield
+  end
+
+  class Recorder
+    attr_reader :events
+
+    def initialize = @events = []
+
+    def instrument(name, payload)
+      @events << [name, payload]
+      yield if block_given?
+    end
+  end
+
+  # Always lets the call through, so the `rate_limit` event fires without a real Redis connection.
+  class FakeRateLimiter
+    attr_reader :sizes
+
+    def initialize = @sizes = []
+
+    def check(size) = @sizes << size
+  end
+
+  def setup
+    super
+    @provider = RecordingProvider.new(TranslationDiff::Configuration.new)
+    # Pinned so a developer with REDIS_URL set doesn't have these tests open a real socket.
+    TranslationDiff.configure { |c| c.cache = :memory }
+  end
+
+  def translate(values, **)
+    TranslationDiff::Translator.new(values, provider: @provider, **).call
+  end
+
+  def test_it_translates_a_nested_structure_and_keeps_its_shape
+    result = translate({ title: "one.", body: ["two.", 42] }, from: "en", to: "ru")
+
+    assert_equal({ title: "ONE.", body: ["TWO.", 42] }, result)
+  end
+
+  def test_the_same_language_never_reaches_the_provider
+    assert_equal "one.", translate("one.", from: "en", to: "en")
+    assert_empty @provider.requests
+  end
+
+  def test_the_same_language_is_compared_across_string_and_symbol
+    assert_equal "one.", translate("one.", from: "EN", to: :en)
+    assert_empty @provider.requests
+  end
+
+  def test_a_value_with_nothing_to_translate_never_reaches_the_provider
+    assert_equal "", translate("", from: "en", to: "ru")
+    assert_nil translate(nil, from: "en", to: "ru")
+    assert_empty @provider.requests
+  end
+
+  def test_a_missing_source_language_is_detected
+    translate("one.", to: "ru")
+
+    assert_equal "en", @provider.requests.first.from
+  end
+
+  def test_per_call_options_reach_the_provider_untouched
+    translate("one.", from: "en", to: "ru", formality: :less)
+
+    assert_equal({ formality: :less }, @provider.requests.first.options)
+  end
+
+  def test_a_second_translation_of_the_same_sentence_is_served_from_cache
+    translate("one.", from: "en", to: "ru")
+    translate("one.", from: "en", to: "ru")
+
+    assert_equal 1, @provider.requests.size
+  end
+
+  def test_only_the_missing_sentences_are_sent
+    translate("one. two.", from: "en", to: "ru")
+    translate("one. three.", from: "en", to: "ru")
+
+    assert_equal [%w[one. two.], %w[three.]], @provider.requests.map(&:texts)
+  end
+
+  # The old check was `respond_to?(:detect)`, satisfied by inheriting the base class's raising stub.
+  def test_a_provider_that_cannot_detect_says_so_before_it_is_called
+    @provider = BlindProvider.new(TranslationDiff::Configuration.new)
+
+    error = assert_raises(TranslationDiff::Translator::Error) { translate("one.", to: "ru") }
+
+    assert_match(/cannot detect/, error.message)
+    assert_match(/blind/, error.message)
+    assert_empty @provider.requests
+  end
+
+  def test_a_provider_whose_cache_key_is_blank_is_refused_rather_than_sharing_a_namespace
+    @provider = NamelessProvider.new(TranslationDiff::Configuration.new)
+
+    error = assert_raises(TranslationDiff::Translator::Error) { translate("one.", from: "en", to: "ru") }
+
+    assert_match(/must define #cache_key/, error.message)
+  end
+
+  def test_a_provider_named_for_one_call_overrides_the_configured_one
+    configured = RecordingProvider.new(TranslationDiff::Configuration.new)
+    TranslationDiff.configure { |c| c.provider = configured }
+
+    assert_equal "ONE.", translate("one.", from: "en", to: "ru")
+    assert_empty configured.requests
+  end
+
+  def test_without_a_provider_keyword_the_configured_provider_is_used
+    TranslationDiff.configure { |c| c.provider = @provider }
+
+    assert_equal "ONE.", TranslationDiff::Translator.new("one.", from: "en", to: "ru").call
+    assert_equal 1, @provider.requests.size
+  end
+
+  def test_an_object_that_is_not_a_provider_is_refused
+    assert_raises(TranslationDiff::InvalidProviderError) do
+      TranslationDiff::Translator.new("one.", from: "en", to: "ru", provider: Object.new).call
+    end
+  end
+
+  def test_a_translation_emits_translate_cache_request_and_rate_limit_events
+    recorder = instrumented { |c| c.rate_limiter = FakeRateLimiter.new }
+    instrumented_translate("Hello there.")
+
+    assert_equal ALL_EVENT_NAMES, recorder.events.map(&:first).sort
+  end
+
+  def test_the_translate_event_carries_languages_provider_and_a_count
+    recorder = instrumented
+    instrumented_translate(%w[one two])
+
+    payload = payload_for(recorder, "translate")
+
+    assert_equal "en", payload[:from]
+    assert_equal "ru", payload[:to]
+    assert_equal "recording", payload[:provider]
+    assert_equal 2, payload[:values]
+  end
+
+  def test_the_cache_event_carries_hit_and_miss_counts
+    recorder = instrumented
+    instrumented_translate("Hello there.")
+
+    payload = payload_for(recorder, "cache")
+
+    assert_equal 0, payload[:hits]
+    assert_equal 1, payload[:misses]
+    assert_equal "recording", payload[:provider]
+  end
+
+  def test_the_request_event_carries_the_provider_a_batch_size_and_a_character_count
+    recorder = instrumented
+    instrumented_translate("Hello there.")
+
+    payload = payload_for(recorder, "request")
+
+    assert_equal "recording", payload[:provider]
+    assert_equal 1, payload[:batch]
+    assert_equal "Hello there.".size, payload[:characters]
+  end
+
+  def test_the_rate_limit_event_carries_the_provider_and_a_character_count
+    limiter = FakeRateLimiter.new
+    recorder = instrumented { |c| c.rate_limiter = limiter }
+    instrumented_translate("Hello there.")
+
+    payload = payload_for(recorder, "rate_limit")
+
+    assert_equal "recording", payload[:provider]
+    assert_equal "Hello there.".size, payload[:characters]
+    assert_equal ["Hello there.".size], limiter.sizes
+  end
+
+  # The limiter is consulted with what is about to be sent, before it is sent.
+  def test_the_rate_limiter_is_consulted_before_the_provider
+    limiter = FakeRateLimiter.new
+    recorder = instrumented { |c| c.rate_limiter = limiter }
+    instrumented_translate("Hello there.")
+
+    names = recorder.events.map(&:first).select { |name| name.start_with?("rate_limit", "request") }
+
+    assert_equal %w[rate_limit.translation_diff request.translation_diff], names
+  end
+
+  def test_no_rate_limit_event_without_a_rate_limiter
+    recorder = instrumented
+    instrumented_translate("Hello there.")
+
+    refute_includes recorder.events.map(&:first), "rate_limit.translation_diff"
+  end
+
+  # A call that returns early reaches no provider and so reports nothing.
+  def test_a_call_that_returns_early_emits_no_events
+    recorder = instrumented
+    instrumented_translate("Hello there.", to: "en")
+
+    assert_empty recorder.events
+  end
+
+  ALL_EVENT_NAMES = %w[translate.translation_diff cache.translation_diff
+                       request.translation_diff rate_limit.translation_diff].sort.freeze
+
+  # A guard that only checked payload content would pass even if an event quietly stopped firing.
+  def test_no_payload_ever_contains_the_text_being_translated
+    secret = "Zaphod Beeblebrox is president."
+    recorder = instrumented { |c| c.rate_limiter = FakeRateLimiter.new }
+    instrumented_translate(secret)
+
+    assert_equal ALL_EVENT_NAMES, recorder.events.map(&:first).sort
+
+    serialised = recorder.events.map { |name, payload| "#{name}#{payload}" }.join
+    refute_includes serialised, "Zaphod"
+    refute_includes serialised, secret
+    refute_includes serialised, secret.upcase
+  end
+
+  # Captured from the old pipeline: a nested nil has always come back as "" from a call that reached a provider.
+  def test_a_nested_nil_collapses_to_an_empty_string
+    assert_equal({ a: "ONE.", n: 42, skip: "" },
+                 translate({ a: "one.", n: 42, skip: nil }, from: "en", to: "ru"))
+    assert_equal ["ONE.", "", 42], translate(["one.", nil, 42], from: "en", to: "ru")
+  end
+
+  # And only then: a call with nothing to translate hands the caller's value back exactly as it was given.
+  def test_a_nil_survives_a_call_that_translates_nothing
+    assert_nil translate(nil, from: "en", to: "ru")
+    assert_equal [nil], translate([nil], from: "en", to: "ru")
+    assert_equal({ a: nil }, translate({ a: nil }, from: "en", to: "ru"))
+  end
+
+  # A subscriber grouping by payload[:to] must not see :ru and "ru" as two different series.
+  def test_the_translate_event_reports_languages_as_strings_whatever_the_caller_passed
+    recorder = instrumented
+    TranslationDiff::Translator.new("Hello there.", from: :en, to: :ru, provider: @provider).call
+
+    payload = payload_for(recorder, "translate")
+
+    assert_equal "en", payload[:from]
+    assert_equal "ru", payload[:to]
+  end
+
+  # `values` is the size of the document as the caller wrote it, not the number of translatable strings in it.
+  def test_the_translate_event_counts_every_leaf_the_caller_wrote
+    recorder = instrumented
+    instrumented_translate({ a: "one.", n: 42, skip: nil })
+
+    assert_equal 3, payload_for(recorder, "translate")[:values]
+  end
+
+  def test_a_value_with_nothing_to_translate_never_resolves_a_provider
+    assert_equal 42, TranslationDiff::Translator.new(42, from: "en", to: "ru", provider: Object.new).call
+  end
+
+  # A call that hands the caller's value straight back should not need a provider to do it: an app that has
+  # configured none at all still gets its value. Configured with something that is not a provider rather than
+  # left unset, so resolving one raises whatever the developer has in their environment.
+  def test_the_same_language_does_not_even_resolve_a_provider
+    TranslationDiff.configure { |c| c.provider = Object.new }
+
+    assert_equal "Hello", TranslationDiff::Translator.new("Hello", from: :ru, to: :ru).call
+  end
+
+  def test_a_value_with_nothing_to_translate_does_not_resolve_the_configured_provider_either
+    TranslationDiff.configure { |c| c.provider = Object.new }
+
+    assert_equal 42, TranslationDiff::Translator.new(42, from: "en", to: "ru").call
+  end
+
+  def test_the_provider_is_logged_once_and_only_when_it_is_resolved
+    logger = FakeLogger.new
+    TranslationDiff.configure { |c| c.logger = logger }
+
+    translate(42, from: "en", to: "ru")
+
+    assert_empty logger.lines
+
+    translate("one.", from: "en", to: "ru")
+
+    assert_equal 1, logger.lines.size
+    assert_match(/RecordingProvider/, logger.lines.first)
+  end
+
+  # A nil target used to reach the cache key and die there on #downcase; it is a caller's mistake, not a defect.
+  def test_a_missing_target_language_is_refused_by_name
+    error = assert_raises(ArgumentError) { translate("one.", from: "en") }
+
+    assert_match(/to:/, error.message)
+  end
+
+  private
+
+  def instrumented
+    Recorder.new.tap do |recorder|
+      TranslationDiff.configure do |c|
+        c.instrumenter = recorder
+        yield c if block_given?
+      end
+    end
+  end
+
+  def instrumented_translate(values, from: "en", to: "ru")
+    TranslationDiff::Translator.new(values, from: from, to: to, provider: @provider).call
+  end
+
+  def payload_for(recorder, event)
+    recorder.events.find { |name, _| name == "#{event}.translation_diff" }.last
+  end
+end
diff --git a/test/translation_diff_test.rb b/test/translation_diff_test.rb
index 0b4f449..bf62fea 100644
--- a/test/translation_diff_test.rb
+++ b/test/translation_diff_test.rb
@@ -1,6 +1,15 @@
 require "test_helper"
 
 class TranslationDiffTest < ConfiguredTest
+  def setup
+    super
+    TranslationDiff.configure do |c|
+      c.provider = :null
+      # Pinned so a developer with REDIS_URL set doesn't have these tests reach for a socket.
+      c.cache = :memory
+    end
+  end
+
   def test_has_a_version_number
     refute_nil TranslationDiff::VERSION
   end
@@ -8,4 +17,27 @@ def test_has_a_version_number
   def test_the_default_segmenter_is_pragmatic
     assert_instance_of TranslationDiff::Segmenters::Pragmatic, TranslationDiff.config.segmenter_instance
   end
+
+  # The entry point builds a Translator, so a nested value comes back with its shape and its non-strings intact.
+  def test_translate_runs_the_values_through_the_pipeline
+    result = TranslationDiff.translate({ title: "One. Two.", count: 42 }, from: "en", to: "ru")
+
+    assert_equal({ title: "One. Two.", count: 42 }, result)
+  end
+
+  # A caller who splats the same options hash into every call must get the same hash back out of it.
+  def test_repeated_calls_leave_the_callers_options_hash_alone
+    options = { from: :en, to: :ru }
+
+    2.times { assert_equal "Some string.", TranslationDiff.translate("Some string.", **options) }
+
+    assert_equal({ from: :en, to: :ru }, options)
+  end
+
+  # `to:` still defaults to nil in the signature, so the keyword it names is what the caller has to read.
+  def test_a_missing_target_language_is_refused_by_name
+    error = assert_raises(ArgumentError) { TranslationDiff.translate("One.", from: "en") }
+
+    assert_match(/to:/, error.message)
+  end
 end