Juno Vale

A Year of Property Testing

2026-05-06T00:00:00Z

A year ago I put property tests into a codebase that already had good example-based coverage, mostly to find out whether the enthusiasm was warranted. Here is what they actually caught.

The score

Eleven genuine defects. Nine of them were in code that parsed, normalised, or merged data — the boring seams between systems. Two were in domain logic. None were in the places I expected.

The single most productive property was also the dullest:

elixir

property "a document survives a round trip" do
  check all document <- document_generator() do
    assert document == document |> Codec.encode() |> Codec.decode!()
  end
end

That one found four bugs on its own: an empty tag list that came back as nil, a timestamp that lost microseconds, a nested map whose key order the encoder depended on, and a Unicode normalisation difference that only appeared for strings containing combining characters.

Every one of those would have been possible to write as an example test. The point is that nobody did, for years, because nobody thought of them.

The properties worth writing

Four shapes covered nearly everything useful:

Round trips. decode(encode(x)) == x. Cheap, and it finds encoder bugs example tests never reach.

Invariants. Something that must be true of every output, regardless of input. Ours: a stock projection never disagrees with a fold over the same events.

Oracles. A second, slower, obviously correct implementation to compare against. We had a naive O(n²) deduplicator; the fast one had a bug at exactly the block boundary.

Idempotence. f(f(x)) == f(x) for anything that normalises. This found a sanitiser that stripped one layer of nesting per call.

Where they were not worth it

I wrote properties for our HTTP handlers and deleted them a month later. The generators were more code than the handlers, most of the interesting behaviour was in the dependencies, and every failure took twenty minutes to interpret. Example tests read better there and caught the same things.

I also stopped trying to shrink my way to understanding. stream_data's shrinking is good, but a minimal counterexample for a complex generator is still a puzzle. Now, when a property fails, my first move is to write the shrunk case down as an ordinary test with a name. The property found it; the example test explains it.

That split — properties to search, examples to document — is the habit I would keep if I had to give up everything else from this year.

Reading a Supervision Tree Like a Map

2026-01-20T00:00:00Z

When I join a BEAM codebase, the first file I open is application.ex. Not the router, not the schema — the supervision tree. It is the only place where the system states, in code, what it thinks should happen when things break.

elixir

def start(_type, _args) do
  children = [
    Ledgerbeam.Repo,
    {Phoenix.PubSub, name: Ledgerbeam.PubSub},
    {Finch, name: Ledgerbeam.HTTP},
    Ledgerbeam.Inventory.Supervisor,
    Ledgerbeam.Ingest.Pipeline,
    LedgerbeamWeb.Endpoint
  ]

  Supervisor.start_link(children, strategy: :one_for_one, name: Ledgerbeam.Supervisor)
end

Six lines, and each one is a claim.

What the order tells you

Children start in order and stop in reverse. So this tree claims the endpoint should be the last thing up and the first thing down — traffic only arrives once the repo, the pipeline, and the domain supervisors are ready, and traffic stops before they go away.

That is almost always what you want, and it is worth checking, because the failure mode is subtle: put the endpoint too early and you accept requests against a half-built system for a few hundred milliseconds on every deploy.

What the strategy tells you

:one_for_one says these six things are independent — if the ingest pipeline dies, the endpoint should carry on. Is that true? For us it was: the site stays up and serves reads while ingestion restarts.

But look for a :one_for_all and ask what it is protecting. It says the children share state that cannot survive one of them restarting, which is a real thing, and also a design smell worth a second look.

:rest_for_one is the interesting one: it says there is a dependency order here, and everything after this child needs it. That is a map of your real coupling, drawn by someone who had to think about it.

Where the tree lies

The tree is a set of beliefs, and outages are where the beliefs were wrong. Two that catch people:

A process that restarts fine but reconnects slowly. The supervisor's job is done in microseconds; the connection pool underneath takes eight seconds. The tree looks healthy and the system is not.

restart: :temporary on something that matters. It will not come back, ever, and the supervisor will not tell you. This is correct for a one-shot task and quietly catastrophic on a consumer.

Neither shows up in the diagram. Both show up in :observer, and in the first five minutes of an incident, which is why I read the tree before I read anything else.

The Kata I Keep Coming Back To

2025-10-15T00:00:00Z

Every so often I redo the string-date-parsing kata. Not because I have forgotten how to parse a date, but because it is the shortest exercise I know that punishes vagueness.

The brief: given a string, return a date. Start with "2025-10-15".

elixir

def parse(input), do: Date.from_iso8601(input)

Four minutes in, you are done. Then the examples arrive.

The examples

"2025-10-15"     the easy one
"15/10/2025"     day first
"10/15/2025"     month first
"15 Oct 2025"    names, abbreviated
"October 15th"   no year, ordinal suffix
"yesterday"      relative to what?
"" and nil       the caller has a bug

Nothing here is hard. What is hard is that "01/02/2025" is genuinely ambiguous, and you cannot resolve it inside the parser. It is January 2nd or February 1st depending on a fact the string does not contain.

The kata's real lesson is that this is where the design happens. Every attempt I make eventually arrives at the same shape: the ambiguity becomes a parameter.

elixir

@type locale_order :: :day_first | :month_first

@spec parse(String.t(), keyword()) :: {:ok, Date.t()} | {:error, term()}
def parse(input, opts \\ []) do
  order = Keyword.get(opts, :order, :day_first)
  today = Keyword.get(opts, :today, Date.utc_today())

  input
  |> String.trim()
  |> attempt([&iso/1, &numeric(&1, order), &named/1, &relative(&1, today)])
end

Two details that took me several attempts to arrive at:

today is an argument. A parser that reads the clock cannot be tested for "yesterday" without either freezing time or accepting flaky tests. Passing the date in makes the whole thing a pure function, and the tests get boring.

The strategies are a list. Each one returns {:ok, date} or :error, and attempt/2 walks them in order. Adding a format is adding a function, and the precedence is visible in one place rather than distributed across a cond.

Why it stays useful

Most katas train you to write code. This one trains you to notice that the requirements are underspecified, and to put the missing decision somewhere the caller can see it. That skill transfers to almost everything, which is more than I can say for FizzBuzz.

Event Sourcing Taught Me to Delete Code

2025-07-09T00:00:00Z

I came to event sourcing expecting an audit log and got something more useful: a reason to delete about a third of the inventory service.

The code that went away

The old service had a table of stock levels and a great deal of code protecting it. Compensating updates when a shipment was cancelled. A nightly reconciliation job. A stock_adjustments table nobody could explain, holding rows that existed only to correct earlier rows.

All of that was there because the current level was the only thing we stored. When it went wrong, we had no way to ask how, so we wrote code to guess.

Storing decisions instead of state removed the guessing:

elixir

defmodule Inventory.Events do
  defstruct StockReceived, [:sku, :quantity, :received_at, :purchase_order]
  defstruct StockPicked, [:sku, :quantity, :picked_at, :order_id]
  defstruct StockWrittenOff, [:sku, :quantity, :reason, :approved_by]
end

The level is now a fold:

elixir

def level(sku) do
  sku
  |> Store.stream()
  |> Enum.reduce(0, fn
    %StockReceived{quantity: n}, level -> level + n
    %StockPicked{quantity: n}, level -> level - n
    %StockWrittenOff{quantity: n}, level -> level - n
  end)
end

The reconciliation job had nothing left to reconcile. The adjustments table became a write-off event with a reason and an approved_by, which is what everyone had wanted from it in the first place.

What it did not fix

It is worth being clear about what event sourcing cost us, because the posts that skip this part are the ones that get people into trouble.

Versioning is forever. The moment an event is persisted, its shape is a public API. We now write upcasters, and we treat an event struct with the same care as a database migration.

Projections drift. Every read model is eventually consistent with the stream, and every part of the UI that pretended otherwise had to learn to say "pending".

Streams grow. A fold over five years of movements for a fast-moving SKU is not free. Snapshots solve it, and snapshots are cache invalidation wearing a hat.

Those are real costs. I would pay them again for the deletions alone. The service went from a thing we were afraid to touch on a Friday to one where the question "how did this SKU get to negative four" has a literal answer.

A Rust NIF Without the Fear

2025-04-22T00:00:00Z

The received wisdom about NIFs is that they can bring down the entire VM, which is true, and that you should therefore avoid them, which does not follow.

We needed SimHash over a few million documents. In pure Elixir it was about 40ms per document, which was not going to work. In Rust, via Rustler, it was under a millisecond. That is the kind of gap worth taking a risk for — provided you know which risks you are taking.

Rule one: never block a scheduler

A NIF that runs longer than about a millisecond starves the scheduler it runs on. The whole preemption model of the BEAM assumes it can take a process off a core; a native function ignores that assumption entirely.

Rustler makes the fix a single annotation:

rust

#[rustler::nif(schedule = "DirtyCpu")]
fn simhash(text: &str) -> u64 {
    hash_tokens(tokenize(text))
}

Dirty schedulers exist precisely for work that cannot be preempted. Use them for anything you have not personally measured under a millisecond, and measure before you decide you are the exception.

Rule two: do not panic

A Rust panic across the NIF boundary takes the VM with it. Every fallible path must return an error term instead:

rust

#[rustler::nif(schedule = "DirtyCpu")]
fn parse(input: &str) -> Result<Document, Error> {
    serde_json::from_str(input).map_err(|e| Error::Term(Box::new(e.to_string())))
}

Then the Elixir side gets an ordinary tagged tuple, and an ordinary supervisor handles it:

elixir

case Native.parse(payload) do
  {:ok, document} -> {:ok, document}
  {:error, reason} -> Logger.warning("unparseable payload: #{reason}"); :skip
end

Deny panics at the crate level and the compiler helps you keep the rule:

toml

[lints.clippy]
unwrap_used = "deny"
expect_used = "deny"

Rule three: keep the boundary boring

The NIF should do one computational thing and hold no state. No global mutable structures, no threads you spawn yourself, no callbacks back into Elixir. Everything that needs supervision, retries, or lifecycle belongs on the BEAM side where those things already work.

The whole architecture, honestly.

Where the fear lives

Every NIF horror story is a violation of one of the three rules. Check the story against the rules before checking your code against the story.

Three rules, and the fear mostly goes away. What is left is a normal engineering tradeoff: a build dependency and a compile step, in exchange for two orders of magnitude.

Backpressure Is a Product Decision

2025-02-11T00:00:00Z

We spent a week tuning a Broadway pipeline that kept falling behind, and the fix turned out not to be a number at all.

The pipeline ingested webhook deliveries from a payments provider. Under normal load it kept up comfortably. During a merchant's flash sale it did not, and the queue depth climbed until the delivery provider started retrying, which added load, which climbed the queue further.

The instinct is to add concurrency:

elixir

def start_link(_opts) do
  Broadway.start_link(__MODULE__,
    name: __MODULE__,
    producer: [module: {SQSProducer, []}, concurrency: 4],
    processors: [default: [concurrency: 80]]
  )
end

Eighty processors did make the queue drain. It also pushed the database to the point where unrelated requests started timing out. We had not removed the bottleneck, we had moved it somewhere with worse failure behaviour.

The question nobody had asked

What should happen when deliveries arrive faster than we can durably record them?

There are only a few honest answers, and each of them is a product decision:

Slow the producer down. Correct when the upstream can wait. The payments provider retried with backoff, so it could.
Shed load. Correct when late data is worthless. Ours was not.
Buffer, and accept that recovery takes time. Correct when the burst is bounded and you can afford the storage.
Degrade the work itself — record the delivery now, enrich it later.

We picked the last one, and the pipeline stopped being a tuning problem:

elixir

@impl true
def handle_message(_processor, message, _context) do
  message
  |> Message.update_data(&Delivery.parse!/1)
  |> Message.put_batcher(:record)
end

@impl true
def handle_batch(:record, messages, _batch_info, _context) do
  messages
  |> Enum.map(& &1.data)
  |> Deliveries.insert_all()

  messages
end

Enrichment moved to a separate pipeline reading from the recorded rows, with its own concurrency and its own failure domain. The write path got simple enough that eight processors outperformed the eighty we had before.

What the numbers were hiding

concurrency: looks like a performance knob and behaves like a policy. Setting it high says "I would rather overwhelm my dependencies than fall behind." Setting it low says the opposite. Neither is wrong, but you should be able to say which one you meant, and why, without opening the dashboard.

The BEAM makes it unusually cheap to express any of these answers. It does not tell you which one your product needs.