The chunk-boundary bug: why streaming PII redaction is hard

How did I find this bug?

I was building the streaming path for Sether, my open-source PII redaction library. The non-streaming path was done: text in, tokens out, redactSync and a vault to restore values in the reply. Streaming looked like the easy part.

LLM responses arrive as a stream of chunks, so I wrote the obvious thing. Take each chunk, run the detectors on it, replace any matches, emit the result. It passed every test I had written by hand. It worked in every demo I ran against a live model.

Then, during the pre-release hardening pass, I added property-based tests. Instead of hand-picking inputs, a property test generates thousands of random ones and checks that an invariant holds for all of them. The invariant I wrote was simple: redacting a text should give the same output no matter how you chop it into chunks.

It failed within seconds. The failing case had split an email address across two chunks, and the email had sailed through untouched.

Why does per-chunk redaction fail?

Here is the naive version, simplified. It is the implementation almost everyone writes first, because it looks correct:

// Looks right. Is not.
async function* redactStream(chunks: AsyncIterable<string>) {
  for await (const chunk of chunks) {
    // Run detectors on this chunk in isolation
    yield redactText(chunk); // regex + validation on chunk only
  }
}

The problem is that the stream does not respect your detectors. Chunk boundaries land wherever the network and the provider's tokenizer put them. So "sarah@acme.com" can arrive as "sarah@ac" followed by "me.com".

Run an email regex on "sarah@ac" and it does not match, there is no dot-something after the domain start. Run it on "me.com" and it does not match either, there is no @ before it. Two innocent halves, one leaked email.

The moment I saw the failing case, the worse realization landed. This is not a bug in my code specifically. It is a bug in the obvious design. Every naive streaming redactor has it, including the ones people copy-paste into production request paths from blog posts.

Why do demos never catch it?

Because demos do not split mid-value. When you test by hand, you send a short prompt, get a short reply, and the whole email lands in one chunk. The redactor looks perfect.

Chunk boundaries depend on token lengths, network buffering, and provider behavior, none of which you control. A redactor can run cleanly for a long time and then split a value at exactly the wrong byte. It is not flaky in a way you can see; it is correct-looking with a hole in it.

This is why I now treat "it works in the demo" as close to zero evidence for streaming code. The input space that matters, all the ways a text can be partitioned, is exactly the space a demo never explores.

How does the hold-back window fix it?

The fix is to stop pretending each chunk is independent. Sether's streaming redactor keeps a bounded window of recent text unemitted, controlled by safeDistanceBytes, default 256 bytes. Text is only released once no possible detector match could span the boundary between what is emitted and what is still held.

So when "sarah@ac" arrives, the tail of it stays in the window instead of going out the door. When "me.com" arrives, the detector sees the joined text, matches the full email, and emits <EMAIL_1>. The reader downstream never knows the chunks were reassembled.

The window is bounded on purpose. Buffering the entire stream would also fix correctness, but it would destroy the point of streaming, the user would stare at nothing until the model finished. 256 bytes is longer than any value the built-in detectors can match, and short enough that the added latency is one small chunk, not a paragraph.

import { Sether } from '@raeven-co/sether';

const sether = new Sether();

// Node streams: redact on the way out, restore on the way back
prompt.pipe(sether.redact());       // holds back up to 256 bytes
reply.pipe(sether.restore());       // same window logic for tokens

// SSE responses have their own helpers that respect event framing:
// createSSERedactStream / createSSERestoreStream

How does a property-based test lock it down?

The test that caught the bug is now the test that guards the fix. The idea fits in a few lines of pseudocode:

// Property: redaction output must not depend on chunking.
property('chunking-invariant', (text: PiiBearingText, seed: number) => {
  const expected = redactSync(text); // whole text at once

  const chunks = randomPartition(text, seed); // split anywhere,
  // including mid-email, mid-card, mid-key

  const actual = collect(streamRedact(chunks));

  assert.equal(actual, expected);
});

The generator builds texts containing known PII, then partitions them at random positions, thousands of runs, every run a different slicing. If any partition produces different output than redacting the whole text at once, the test fails and prints the exact split that broke it.

That last part matters. When the invariant fails, you do not get "something is wrong somewhere", you get "splitting at byte 14 inside this email leaks it". The bug that would have been invisible in production is a one-line reproduction in CI.

How do you test your own implementation?

If you have a streaming redactor in production, home-grown or vendored, here is the five-minute check I would run first, and the fuller list after it.

1. The five-minute check. Feed your redactor "my email is sarah@ac" then "me.com" as two chunks. If the joined output contains the email, you have the bug.
2. Split every detector type. Repeat for phone numbers, cards, API keys, whatever you claim to catch. Long values (IBANs, JWTs) are the easiest to split and the most often missed.
3. Randomize the split point. A loop that re-runs the same text with the boundary at every byte position catches cases a single hand-picked split misses.
4. Add the invariant to CI. Redacting whole text and redacting the same text in random chunks must produce identical output. Property-based test libraries (fast-check in TypeScript, Hypothesis in Python) make this a short test.
5. Bound your buffer. If your fix is "buffer everything", measure what that does to time-to-first-token. A bounded window keeps streaming actually streaming.

I want to be precise about the timeline here, because it is the honest part of the story. This bug never reached a user. It was caught during pre-release hardening, before the streaming path shipped, by a test I almost did not write. That is the whole argument for property-based testing on this class of code: the demo said yes, and the property test said no.

For the wider context on where streaming redaction fits in an LLM data-protection setup, start with the complete guide to PII redaction for LLM apps. And if you are wiring this into a TypeScript service today, the step-by-step OpenAI walkthrough covers the full redact-then-restore round trip.