Charlie's Blog

My Dotfiles: macOS Bootstrap and an Emacs Distribution

Charlie Holland — Thu, 07 May 2026 15:18:00 GMT

1. About dotfiles macos emacs setup

Figure 1: JPEG produced with DALL-E 4o

My dotfiles for my MacOS rice and Emacs configuration live in two public repositories. Both repos are shared as a reference; clone, fork, or just lift the bits that look useful to you!

This post is a thin entry point, and the READMEs in each repo carry the actual detail.

2. chiply/.files shell tmux macos bootstrap

A single bootstrap.sh that takes a clean macOS install to a fully provisioned development machine in roughly thirty minutes. It installs Xcode CLI tools, Homebrew, and a long list of CLI utilities and language toolchains, then symlinks every config in files/ into the matching path under $HOME.

See repo for installation instructions.

What gets installed:

Shell: zsh + zinit, starship prompt, atuin shared history
Terminal: Ghostty with cursor shaders, plus Nerd Fonts
Multiplexer: tmux with tmux-powerline, tmuxinator, TPM
Window manager: AeroSpace, simple-bar, JankyBorders
Languages: pyenv, Poetry, uv, nvm + Node, language servers (json, eslint, copilot, svelte)
CLI: gh, k9s, bat, fzf, ripgrep, eza, jq, lazygit, AWS CLI v2, and more

The full package list lives in the repo's Brewfile. bootstrap.sh also clones .zetta.d to ~/.zetta.d as part of the Emacs setup; if you only want the shell side, comment out the emacs section.

3. chiply/.zetta.d emacs zetta distribution

My Emacs configuration, packaged as a small distribution. Around 320 packages wired up via a module DSL, with an Elpaca lockfile pinning every package to an exact commit, and byte- and native-compilation done up front so the first launch is clean.

The name is a cheeky play on how we name certain minimalist text editors after Metric Prefixes nano (10^-9) or pico (10^-12). This maximalist editor config is named after zetta (10^21).

See repo for installation instructions.

Notable parts:

Triple-modal editing: Evil, Meow, and vanilla side-by-side, switchable on the fly
Module DSL: enable categories or individual packages via zetta-modules! in ~/.zetta.el
Reproducible: lockfile + compile-by-default install
CI-tested: Emacs 29.4, 30.2, and the 31 snapshot

Zetta also hosts several small packages I've written that live in their own public repos. See the README's "Bundled custom packages" section for the list. None of these are released or publicized yet, so bring a pinch of salt if you choose to try them.

Emacs Completion Showcase with VOMPECCC (video)

Charlie Holland — Tue, 05 May 2026 18:15:00 GMT

1. About emacs completion workflows

Figure 1: JPEG produced with DALL-E 3

This is the fifth post in my series on Emacs completion. The first, Incremental Completing Read (ICR), explains what modern completion actually is, and how Emacs exposes it as a programmable substrate rather than a closed UI. The second introduced the VOMPECCC stack of eight packages covering the six orthogonal concerns of a complete completion system. The third toured spot, a Spotify client built as a thin shim on top of those packages. And the fourth built a produce picker from scratch, demonstrating the specific features that each VOMPECCC package provides.

This post is the practical complement to all the other posts. Here, we showcase over a dozen workflows I use every day. Most are powered entirely by features that ship in the box with the VOMPECCC packages, and there are 'Bonuses' which demonstrate workflows enable by 3rd party packages that build on top of VOMPECCC. The prose is deliberately thin, and you will find most of the demonstration is in the video below.

2. The Video demo

As in the previous posts in this series, the upper-right of my Emacs (in the tab-bar) shows the keybindings and command names I am invoking, so you can map what you see onto your own configuration.

3. A Note on My Configuration setup

Two configuration choices show up repeatedly and are worth naming once upfront so the keystrokes are intelligible.

Async split character. My consult-async-split-style is comma, not the default #. In Consult commands like consult-ripgrep, everything before the first , is sent to the external tool as the search pattern, and everything after is filtered locally with my completion style.

Orderless dispatchers. My orderless-style-dispatchers bind affix characters to matching styles: @ for Marginalia-annotation matching, ~ for flex, ` for initialism, ! for negation. Each can be a prefix or suffix on a component. My orderless-component-separator is also ,, so a single comma serves double duty depending on context.

4. Multi-File Refactor ripgrep embark wgrep

consult-ripgrep → input your search term → embark-export → wgrep-change-to-wgrep-mode → edit as you like → C-

5. Async + Local Two-Stage Search consult async orderless

consult-ripgrep with , splitting external (ripgrep) from local (Orderless): for example, error,handler,~retry,!test.

6. Unified Buffer / File / Bookmark Switcher consult narrowing

consult-buffer with narrowing keys: b SPC for buffers, f SPC for recent files, m SPC for bookmarks, p SPC for project items.

7. Buffer and Project-Wide Line Search consult preview

consult-line within the current buffer; consult-line-multi across all buffers (or the project, with a prefix argument).

8. Code Symbol Navigation imenu navigation

consult-imenu within the current buffer; consult-imenu-multi across every buffer of the same major mode.

9. Documentation Search consult docs

consult-info for Info manuals (Emacs, Elisp, Org, plus every package that ships its own .info file); consult-man for system man pages.

10. Find Commands by Docstring marginalia orderless

M-x window @frame. The @ dispatcher routes a component through orderless-annotation to match against Marginalia's docstring text rather than the candidate name. This lets you query for commands by what they do rather than what they are called.

11. Mass Action Across Candidates embark batch

C-> (embark-act-all) runs a single Embark action on every candidate currently surviving in the prompt.

You can also embark-select to create a subset of displayed candidates and use embark-act-all to act on only those selected candidates.

12. Pivot Mid-Prompt embark flow

embark-become switches the active command (e.g. find-file → switch-to-buffer) without losing the input I have already typed.

13. Symbol-Aware Multi-File Refactor xref embark wgrep

xref-find-references (M-?, with xref-show-xrefs-function set to consult-xref) → embark-export → wgrep-change-to-wgrep-mode → edit → C- to write your changes. This is very similar to the ripgrep version above but driven by the language server, so foo the variable and foo the unrelated comment stay separate.

14. Recent Files as a Filesystem dired embark

consult-recent-file → embark-export produces a Dired buffer, putting every Dired operation (mark, copy, rename, chmod, batch shell command) on the recent-files set.

15. Avy-Style Jump Then Act vertico embark

In any Vertico session, C-' jumps to a labeled candidate (Avy-style); C-" does the same jump and hands the candidate to Embark.

16. Resume the Last Session vertico repeat

s-V (vertico-repeat) reopens the last completion session with its prompt, input, and selected candidate intact.

17. Bonus: Magit-Style Working Copy as Completion :consult-ls-git git

consult-ls-git surfaces working-copy status, tracked files, and branches in a single multi-source prompt with narrowing keys. A nice on-the-fly alternative to the Magit status buffer.

18. Bonus: Browse GitHub Repos from the Minibuffer :consult-gh embark

consult-gh-search-repos streams GitHub repos as candidates; C-= previews the README; M-S (vertico-suspend) (or simply moving your cursor out of the minibuffer) detaches the minibuffer for free reading; s-V (vertico-repeat) (or simply moving your cursor back into the minibuffer) resumes; C-. exposes Embark actions (clone, browse, view issues, view PRs, view files, fork).

19. Bonus: Search All Public Code on GitHub :consult-gh:code-search:

consult-gh-search-code against the contents of every public repository on GitHub. You get the same VOMPECCC features, but with the search space expanded to "all open source code in the world".

20. Bonus: Multi-Source Web Search :consult-omni web

consult-omni-web fans one query out across Google, Brave, Wikipedia, StackOverflow, YouTube, and a gptel-backed LLM source simultaneously; s-j / s-k jumps between source groups; C-= previews; C-. surfaces Embark alternates (open in EWW, copy URL, etc.).

21. Closing closing

What makes this so cool is that none of these workflows required a single line of custom code. Each is built entirely out of the features that ship with one or more of the VOMPECCC packages. Pick the two or three that map onto frictions you already feel, and the rest will reveal themselves ad-hoc as you encounter new frictions.

22. TLDR tldr

Over a dozen high-impact Emacs workflows are demonstrated in this post: multi-file refactor, two-stage ripgrep, unified buffer switching, line search with preview, symbol navigation, docs search, M-x by docstring, batch action, mid-prompt pivot, symbol-aware refactor, recent files as Dired, and quick jump + act, session resume. Each of these workflows is composed entirely from features that ship in the box with the VOMPECCC packages.

David Foster Wallace's Hidden Names: an Anagram Atlas of Infinite Jest

Charlie Holland — Sat, 02 May 2026 09:07:00 GMT

1. About infiniteJest dfw anagrams

DFW famously embedded wordplay in his character names. The surname Pemulis is an anagram of impulse. Otis P. Lord rearranges to Sport Idol, the absurd authority figure of the Eschaton game he runs. This essay catalogues every named character in Infinite Jest, computes letter-multiset anagrams of their full names, and asks of each: did DFW intend it?

Each character section can show up to three registers of name-play, depending on what the name yields. Name analysis covers non-anagram wordplay — etymology (Incandenza ← incandescere), substring derivations (Madame Psychosis ← metempsychosis), phonetic puns, initialisms (J.O.I. = joy), translations, allusions, double entendres. Possible anagrams are curated rearrangements selected for thematic resonance with the character. Algorithmic candidates are the raw output of a subset-sum search over the top 30K English words.

Three caveats. First, the only externally confirmed anagrams in the novel's character names are Pemulis (surname) and Otis P. Lord (full name) — everything else here is speculative. Second, every anagram displayed has been deterministically verified to use exactly the letters of the source name (no leftovers, no extras). Third, the name-analysis observations are interpretive readings, not claims about authorial intent.

Each section below is one character. Sections are ordered by mention count in the novel — Don Gately first, the long tail of named cleaners and Eschaton combatants last. Use the left-side table of contents to navigate.

2. Methodology methodology

Pipeline: character extraction (web sources + spaCy NER on the full PDF) → algorithmic anagram search (subset-sum-on-multisets over the top 30K English words by frequency, max 3 words per anagram) → deterministic letter-multiset verification. Possible anagrams come from a separate curatorial pass: candidate rearrangements are selected for thematic resonance with the character, then run through the same letter-multiset check.

For each character, the catalogue shows two name forms where they differ — a short form (first + last) and a full form (with middle initials/names). The two forms have different letter multisets and therefore different anagram opportunities.

Each interpretation is tagged [strong] (external corroboration), [suggestive] (internally coherent with character traits), or [speculative] (plausible but possibly Texas-sharpshooter). Default is speculative; confidence climbs only with evidence.

3. Don Gately infinitejest hugeness sobriety physicalendurance

A 6'6" former Demerol addict and burglar serving as live-in staffer at Ennet House Drug and Alcohol Recovery House, defined by gentle physical menace and an embodied, unsentimental relationship to AA-style sobriety. After a gun-shot wound from defending residents, he spends the novel's late stretches feverish and pre-verbal in a hospital bed, refusing narcotic painkillers as a last act of will.

Name analysis (non-anagram wordplay: etymology, puns, allusions)

[Etymology] gate / gately (Old English geatlic, 'belonging to a gate') — As Ennet House's live-in staffer and bouncer, Gately is literally the gatekeeper — the man at the door who decides who enters and who is removed. The surname performs the role.
[Phonetic] gait-ly — The name evokes 'gait' — fitting for a 6'6" character whose lumbering physical presence and walk are a constant feature of the prose.

Possible anagrams (thematically chosen)

Don Gately

any old get — Ennet House staffer Gately accepts any old derelict who comes through the door (suggestive).
only get ad — His sober life as one long advertisement for the AA program (loose).
today glen — An anonymous everyman name for the silent giant (loose).
dog late ny — Lenz's late dog-killing on New England streets triggers Gately's gunshot wound (loose).
any dog let — He'd let any dog into Ennet House — judgement-free, animal-shelter style (suggestive).

Donald W. Gately (full form)

along teddy law — His backstory under the law alongside his junkie pal Teddy (suggestive).
dental gold way — His gap-toothed grin and golden-hearted way (loose).
deadly long wat — His deadly long Watertown wait for the ambulance after being shot (suggestive).
delay want gold — AA's delay-want lesson: the gold of sobriety lies past the want (suggestive).
all god went day — His deathbed sense that all god went out of the day (loose).

Algorithmic candidates (subset-sum search over 30K-word vocab)

VOMPECCC from Scratch: Picking Produce with ICR in Emacs

Charlie Holland — Tue, 28 Apr 2026 09:14:00 GMT

1. About emacs completion walkthrough

Figure 1: JPEG produced with DALL-E 3

This is the fourth post in a series on Emacs completion. The first argued that Incremental Completing Read (ICR) is a structural property of an interface rather than a convenience feature. The second broke the Emacs substrate into eight packages (collectively VOMPECCC) each solving one of the six orthogonal concerns of a complete completion system. The third walked through spot, a ~1,100-line Spotify client built as a little shim on top of those packages.

This post is the hands-on complement to the spot post. Where the spot case study reviewed a finished codebase from the outside, this one builds a tiny produce picker tool from scratch, one VOMPECCC package at a time. The use case is deliberately trivial: we have a list of produce items (twenty fruits and ten vegetables) with some metadata, and we want to pick one and do something with it.

Every piece of interesting behavior; the display control, multi-component matching, metadata columns, narrowing keys, contextual actions, transformer-driven type refinement, frecency-based sorting; will be layered on by adding one VOMPECCC package at a time, in order to make it clear exactly what each package provides. By the end, we will have a ~90-line produce picker whose entire UI was composed from six packages that don't know about each other.

We will build a ~90-line produce picker whose entire UI was composed from six packages that don't know about each other.

A caveat: two of the eight VOMPECCC packages are out of scope here. Corfu and Cape target in-buffer completion, and the produce picker in this post is focused on minibuffer interaction. So this post focuses on the six packages that do show up visibly in a live walkthrough: Vertico, Orderless, Marginalia, Prescient, Embark, and Consult.

A note on format. You can open this webpage in EWW and execute the code from within there (you can see my video for an example of how to do this).

2. The Walkthrough demo

This video demo walks through the code in this post live. I have also included prose in each section explaining what each piece of code does. The article is long, so the video will likely be a quicker digestion of this post's message.

Note: wherever you see video demos, you will see, in the upper right hand side (in the tab-bar), the keybindings and associated commands that I am invoking to execute each command. This is relevant because you may have things configured differently on your side. By providing both the kbd and command name, my invocation of behaviors you see in the video should unambiguous.

3. The Produce Corpus setup data

The data is a list of candidates, which in this implementation are propertized strings, one per produce item. Each candidate is the produce item's name, with five text properties riding along: category, type, color, season, and price. Two of those properties are load-bearing for later phases. category is the completion category, the symbol Marginalia and Embark dispatch on.

A word on the name category, because it is doing more work than it looks like. Of the five property names above, four are arbitrary: type, color, season, price are labels we chose, nothing in Emacs reserves them, and you could rename them all and only have to update our own code. category is the exception because it is a reserved text-property name in Emacs. The Elisp manual specifies that when a character has a category text property whose value is a symbol, that symbol's property list serves as defaults for the character's other text properties. In other words, category is Emacs's standard hook for stamping a typed symbol onto a piece of text. Emacs's completion ecosystem overloads the same name with a second, related meaning, which is that every prompt has a completion category (a symbol like file, buffer, or in our case fruit or vegetable), which Marginalia, Embark, etc… consult through the completion metadata to decide which annotator, keymap, or exporter to dispatch.

There is one important subtlety worth surfacing now, since it explains a lot of what happens later. The framework never reads our category text property directly. Marginalia and Embark dispatch off the prompt-level completion metadata (a separate channel from text properties), and Consult, when we add it in Phase 5, communicates per-candidate categories through a different text property called multi-category rather than ours. So our category property is read only by our own code: a corpus-filtering helper in Phase 4, an Embark exporter in Phase 6, etc…. The framework dispatches because we set the Consult source's :category key to match the data's category property by hand. The two stay in sync because we keep them in sync, not because anyone cross-checks. This is the candidate-as-currency convention being load-bearing for us, with the framework reading a parallel, framework-owned slot for its own dispatch.

type is the finer classification (botanical: pome, berry, citrus, stone, tropical, melon; vegetable: root, leafy, cruciferous, nightshade) used in Phase 6 to drive an Embark transformer that gives citrus its own action set. Both classifications live on the candidate itself. No framework code in any phase below ever invents a category or hardcodes a type, and the routing keys are pulled directly off the candidates.

(defvar my-produce
  (list
   ;; Fruits
   (propertize "apple"      'category 'fruit     'type 'pome        'color "red"    'season "fall"       'price 1.29)
   (propertize "pear"       'category 'fruit     'type 'pome        'color "green"  'season "fall"       'price 1.79)
   (propertize "strawberry" 'category 'fruit     'type 'berry       'color "red"    'season "spring"     'price 3.99)
   (propertize "blueberry"  'category 'fruit     'type 'berry       'color "blue"   'season "summer"     'price 4.99)
   (propertize "raspberry"  'category 'fruit     'type 'berry       'color "red"    'season "summer"     'price 5.99)
   (propertize "blackberry" 'category 'fruit     'type 'berry       'color "black"  'season "summer"     'price 5.49)
   (propertize "lemon"      'category 'fruit     'type 'citrus      'color "yellow" 'season "year-round" 'price 0.79)
   (propertize "lime"       'category 'fruit     'type 'citrus      'color "green"  'season "year-round" 'price 0.39)
   (propertize "orange"     'category 'fruit     'type 'citrus      'color "orange" 'season "winter"     'price 0.99)
   (propertize "grapefruit" 'category 'fruit     'type 'citrus      'color "pink"   'season "winter"     'price 1.49)
   (propertize "peach"      'category 'fruit     'type 'stone       'color "orange" 'season "summer"     'price 2.49)
   (propertize "plum"       'category 'fruit     'type 'stone       'color "purple" 'season "summer"     'price 2.99)
   (propertize "cherry"     'category 'fruit     'type 'stone       'color "red"    'season "summer"     'price 6.99)
   (propertize "apricot"    'category 'fruit     'type 'stone       'color "orange" 'season "summer"     'price 3.99)
   (propertize "mango"      'category 'fruit     'type 'tropical    'color "orange" 'season "summer"     'price 1.99)
   (propertize "pineapple"  'category 'fruit     'type 'tropical    'color "yellow" 'season "year-round" 'price 3.99)
   (propertize "banana"     'category 'fruit     'type 'tropical    'color "yellow" 'season "year-round" 'price 0.59)
   (propertize "papaya"     'category 'fruit     'type 'tropical    'color "orange" 'season "year-round" 'price 2.49)
   (propertize "watermelon" 'category 'fruit     'type 'melon       'color "green"  'season "summer"     'price 0.59)
   (propertize "cantaloupe" 'category 'fruit     'type 'melon       'color "orange" 'season "summer"     'price 2.99)
   ;; Vegetables
   (propertize "carrot"     'category 'vegetable 'type 'root        'color "orange" 'season "year-round" 'price 0.99)
   (propertize "beet"       'category 'vegetable 'type 'root        'color "purple" 'season "fall"       'price 1.49)
   (propertize "radish"     'category 'vegetable 'type 'root        'color "red"    'season "spring"     'price 0.79)
   (propertize "spinach"    'category 'vegetable 'type 'leafy       'color "green"  'season "spring"     'price 2.99)
   (propertize "kale"       'category 'vegetable 'type 'leafy       'color "green"  'season "winter"     'price 2.49)
   (propertize "lettuce"    'category 'vegetable 'type 'leafy       'color "green"  'season "summer"     'price 1.99)
   (propertize "broccoli"   'category 'vegetable 'type 'cruciferous 'color "green"  'season "year-round" 'price 2.99)
   (propertize "cauliflower" 'category 'vegetable 'type 'cruciferous 'color "white" 'season "fall"       'price 3.99)
   (propertize "tomato"     'category 'vegetable 'type 'nightshade  'color "red"    'season "summer"     'price 2.49)
   (propertize "eggplant"   'category 'vegetable 'type 'nightshade  'color "purple" 'season "summer"     'price 3.49))
  "Produce candidates (fruits + vegetables) for the VOMPECCC walkthrough.")

Thirty propertized strings, two completion categories (fruit, vegetable), ten types (six botanical + four vegetable), and four additional properties. For the rest of this post, produce candidate means one of these propertized strings: a plain Emacs string at the surface (the produce name, if you will) with its remaining fields as text properties.

3.1. Why a propertized string?

The post is going to lean on one specific claim: the candidate is the unit of currency that flows between every layer of the substrate. When we say "every package consumes the same currency without knowing about each other," we mean the propertized string above is what gets used by the built-in Emacs substrate and the VOMPECCC packages. The shape we chose for my-produce is what makes the thesis cash out.

It is worth pausing on, because the same data could plausibly have been a list of plists, an alist of cons cells, a hash table from name to record, or a programmed completion function, etc…. and completing-read accepts all of those as collections. No VOMPECCC package constrains the shape further, so strictly speaking, any shape that produces strings would work. The question is what each shape costs the consumer code, and the answer is relevant to the rest of this post.

1. Properties survive the round trip. When completing-read returns the chosen candidate, it returns the exact propertized string you put in. Properties intact. Your Embark action receives "apple" with all its text properties; your transformer receives "apple" with type pome still attached; the exporter receives the full set. The entire candidate-as-currency story rests on this: domain data and candidate identity are the same object. You hand the framework a propertized string, and you get a propertized string back, and you can read whatever properties you stamped on without ever leaving the candidate.

2. Text properties are the framework's integration channel. Three concrete examples from the packages below:

Vertico applies face text properties for display.
Consult writes a multi-category text property to thread per-candidate types through Embark's dispatcher.
Embark's built-in transformer reads multi-category off the candidate.

These packages were designed assuming candidates are strings with rich text properties. The two framework-owned properties (face and multi-category) coexist on the same string object alongside our category, type, color, season, price, because a propertized string supports arbitrary properties without conflict. An alist or hash-table shape would force you to translate to strings somewhere on the way into the framework, and that breaks the integration, or at least makes it more difficult.

3. No sidecar state. The plausible alternative is plain strings plus a hash table mapping name → record. It works, but introduces:

A second piece of state to keep in sync with the candidate list.
A (gethash cand my-records) step in every annotator, action, transformer, and exporter. This is 'lookup' or 'rehydration'. Best avoided, and I can only think of this being useful if a candidate has a huge number of mostly unneeded properties, which is rare in practice.
A bug class around duplicate names: the hash table can't disambiguate, and the candidate string by itself carries no other identifying information.

Propertized strings collapse this into "the candidate is the record." Each propertize call mints a fresh string object whose properties are bound to that exact instance.

What is not uniquely required. Some things look more constrained than they are.

The property name category is not required by the framework. No VOMPECCC package reads our category text property; we discussed this above, and our filter helper and exporter are the only consumers. We could rename it to kind or class and only our own code would change. category was chosen for alignment with Emacs's vocabulary and the completion ecosystem's conventions, not for compatibility.
Flat properties vs. one multi-data bag is not required either. This corpus uses individual properties because the records are shallow and the property bag stays small, so every consumer asks one get-text-property question and gets one answer. In codebases like spot, where each candidate is a Spotify track or playlist with dozens of nested fields, the convention is to attach the full record under a single multi-data property and let consumers reach into the plist for deep fields. Both routes meet the substrate at the same hook.
Human readability is not required. The candidate string is just an identifier as far as completing-read is concerned. You could put a UUID and have the annotator render the human name as a prefix. Most packages use the string as the visible name because it is simpler, not because they have to.

The shape, in one sentence. A list of propertized strings is the shape that lets every VOMPECCC layer participate without your code translating between a "candidate" representation (what the framework sees) and a "record" representation (what your annotator, action, and transformer need). Every other shape forces that translation somewhere. Candidate-as-currency means: don't translate. Pass the same object end to end.

4. Phase 0: Resetting to Stock reset setup

If you are reading this post in your own Emacs, your config may already have VOMPECCC packages enabled, which would muddy this demo of built-in completion. Run this block first to peel them off so the baseline really is the baseline.

;; Reset completion-styles and category configuration to Emacs defaults.
(setq completion-styles '(basic partial-completion emacs22))
(setq completion-category-defaults nil)
(setq completion-category-overrides nil)

;; Drop any custom Orderless wiring so dispatchers and matching styles don't leak in.
(when (boundp 'orderless-style-dispatchers)
  (setq orderless-style-dispatchers nil))
(when (boundp 'orderless-component-separator)
  (setq orderless-component-separator " "))
(when (boundp 'orderless-matching-styles)
  (setq orderless-matching-styles '(orderless-literal orderless-regexp)))

;; Disable every VOMPECCC mode the post will switch back on layer by layer.
(when (bound-and-true-p vertico-prescient-mode) (vertico-prescient-mode -1))
(when (bound-and-true-p prescient-persist-mode) (prescient-persist-mode -1))
(when (bound-and-true-p vertico-mode) (vertico-mode -1))
(when (bound-and-true-p marginalia-mode) (marginalia-mode -1))

After this block, completing-read should behave the way Emacs ships out of the box: a *Completions* buffer instead of a vertical list, prefix-only and partial-completion matching, no annotations, no contextual actions, and no 'frecency'. Phase 1 below demonstrates exactly that, and every subsequent phase adds one layer back.

5. Phase 1: The Baseline (Stock `completing-read`) baseline

Before we pull in a single VOMPECCC package, it is worth seeing what the built-in Emacs completion already gives us. completing-read is a function in the Emacs standard library: it prompts the user for an input string, filters candidates based on that string, and then returns the chosen string. That is the entire contract.

(completing-read "Pick something: " my-produce)

When this block runs, the minibuffer opens with the prompt Pick something: = and a blinking cursor. Nothing else is visible at first. Press =TAB and a *Completions* buffer pops open above the minibuffer, laying all thirty produce names across columns. Type a prefix like pe and press TAB again; the *Completions* buffer shrinks to the two produce items whose names start with those letters (peach and pear). Once you pick an item (either by arrowing to it in *Completions* or typing its full name), you accept it with RET and the chosen string echoes into the message area.

This works, but it is visually and ergonomically primitive. Right now we are lacking display control for our candidate list, fuzzy matching, metadata display and filtering, preview, and any way of doing anything with the chosen item except receive its name.

Every phase that follows places layers of the VOMPECCC stack around this function without changing the function itself.

Every phase that follows places layers of the VOMPECCC stack around this function without changing the function itself.

6. Phase 2: Vertico — Display Control vertico display

Vertico only does one thing; it just gives us control over how candidates are displayed in the minibuffer. It does not filter, sort, annotate, or act on anything. Any code that calls completing-read; whether it's yours, Emacs's, a third-party package's; is rendered according Vertico's display settings if it is enabled.

(vertico-mode 1)

That is the entire integration! Re-evaluate the Phase 1 block:

(completing-read "Pick something: " my-produce)

This time the *Completions* buffer never appears. Instead, the minibuffer lays out candidates horizontally (my default display style for Vertico). The prompt still sits at the bottom, but to it's right is a flat array of all thirty produce items, one per line, with the first one (apple) highlighted as the current selection. C-n (or C-j in my config) walks the highlight to the right through pear, strawberry, blueberry, and so on through the list; C-p (or C-k in my config) walks it left. RET accepts whichever candidate is currently highlighted. The candidate list filters incrementally whenever we type a letter: typing a single p on the empty prompt collapses it to the 12 items whose names contains p, and each additional character narrows further in real time, with the selection snapping to the first surviving candidate.

Notice our completing-read function call did not change, and, critically, we did not pass Vertico the candidates. Vertico hooked into the minibuffer-setup pipeline at a lower level, and Emacs routes candidates to it. This is critical because this means Vertico now gives us candidate display control everywhere completing-read is used, without us havign to anything except enable vertico mode!

7. Phase 3: Orderless — Multi-Component Matching orderless filtering

Vertico gave us a better view, but the matching is still the default combination of basic, partial-completion, and emacs22. These styles handle prefix and hyphen-segmented matches, but we lack a way to type more than one independent fragment, do any flex matching, negation, or any way to filter against candidate metadata.

Orderless is a completion style: it plugs into the completion-styles variable and changes how the input string is matched against candidates during completing-read. Orderless in practice reveals its namesake: it lets us split the input on a separator character, and return candidates that contain every component, in any order.

(setq orderless-component-separator ",")

(setq orderless-matching-styles '(orderless-regexp)
      completion-styles '(orderless basic)
      completion-category-defaults nil
      completion-category-overrides '((file (styles basic partial-completion))))

;; A small `tab' shim style: TAB completion only, no fall-through.
;; In-buffer completion (Corfu, the in-buffer counterpart from Post 2)
;; uses it; minibuffer prompts ignore it and pass straight through to Orderless.
(add-to-list 'completion-styles-alist
             '(tab completion-basic-try-completion ignore
                   "Completion style which provides TAB completion only."))

(setq completion-styles '(tab orderless basic))

Note: The basic fallback matters because a handful of Emacs features (TRAMP host completion, for example) require prefix-style matching that Orderless does not handle; basic catches those.

A few notes on the configuration we set up:

orderless-matching-styles is the chain Orderless uses against any input component that no dispatcher has claimed, and setting it to orderless-regexp is my personal recommendation.
The file-category override (defined in completion-category-overrides) is an idiomatic exception so that ~/d/s expands to ~/Documents/source/.
The separator is set to a comma because Orderless's default is a space, and spaces are valuable inside candidate strings because search candidates (and their annotations) often contain whitespace. Reassigning the separator to a rarely-occurring character (,) keeps spaces available as part of any component you might want to match.
The tab style at the head of completion-styles is a one-line concession to in-buffer completion, because Corfu uses it for plain TAB completion in code buffers, but know that the minibuffer prompts ignore it and fall through to Orderless.

Re-run the produce prompt:

(completing-read "Pick something: " my-produce)

You see Orderless in action when you type more than one component separated by commas. Typing a,e narrows the list to every item containing both an a and an e somewhere, in either order (Order-less, remember? 😜). Each comma-separated component is an independent filter, and the intersection (in the set algebra sense) of their matches is what survives in the candidate list display.

Individual components can override the default matching style through Orderless's style dispatchers, which are single-character affixes that tell Orderless to treat that component in a special way. Out of the box, Orderless ships orderless-affix-dispatch as the default dispatcher, mapping ~ to flex, ! to negation, & to annotation matching, , to initialism, and a few others. Two of those defaults are awkward in our setup: , is already serving as our component separator, so it can't double as a dispatcher prefix; and we want the annotation prefix to support a flex variant, which the affix-alist can't express because each entry maps a single character to a single style. Both reasons motivate replacing the defaults with hand-rolled versions tuned to our preferred prefix vocabulary.

We'll use a customized dispatcher set for the rest of this post.

Each dispatcher is a function of three arguments (pattern, index, total) that inspects a component and, if its dispatcher character appears at either end, returns (STYLE . PATTERN-WITHOUT-AFFIX) as so Orderless knows which matching style to apply. Returning nil passes the component to the next dispatcher in the chain, or to the default style if none match. Accepting the character as either prefix or suffix mirrors the built-in orderless-affix-dispatch and means you don't have to remember which end the trigger goes on, or preempt the matching style before you type out a component. ~bna and bna~ both flex-match.

;; Each dispatcher accepts the dispatcher character as either a
;; PREFIX or a SUFFIX of the component, mirroring the built-in
;; `orderless-affix-dispatch'.

(defun my/orderless-dispatcher-initialism (pattern _index _total)
  "Initialism-match a component starting OR ending with a backtick."
  (cond
   ((string-prefix-p "`" pattern)
    `(orderless-initialism . ,(substring pattern 1)))
   ((string-suffix-p "`" pattern)
    `(orderless-initialism . ,(substring pattern 0 -1)))))

(defun flex-if-twiddle (pattern _index _total)
  "Flex-match a component starting OR ending with `~'."
  (cond
   ((string-prefix-p "~" pattern)
    `(orderless-flex . ,(substring pattern 1)))
   ((string-suffix-p "~" pattern)
    `(orderless-flex . ,(substring pattern 0 -1)))))

(defun annotation-if-at (pattern _index _total)
  "Annotation-match `@P' or `P@'.
Flex-annotation-match `@~P', `~P@', `@P~', or `P~@' --- the inner
`~' may sit at either end of the inner pattern."
  (let ((rest
         (cond
          ((string-prefix-p "@" pattern) (substring pattern 1))
          ((string-suffix-p "@" pattern) (substring pattern 0 -1)))))
    (when rest
      (cond
       ((string-prefix-p "~" rest)
        (let ((re (mapconcat (lambda (c) (regexp-quote (char-to-string c)))
                             (string-to-list (substring rest 1)) ".*")))
          `(orderless-annotation . ,re)))
       ((string-suffix-p "~" rest)
        (let ((re (mapconcat (lambda (c) (regexp-quote (char-to-string c)))
                             (string-to-list (substring rest 0 -1)) ".*")))
          `(orderless-annotation . ,re)))
       (t `(orderless-annotation . ,rest))))))

(defun without-if-bang (pattern _index _total)
  "Exclude a literal match for a component starting OR ending with `!'.
A bare `!' is a no-op (matches every candidate)."
  (cond
   ((equal "!" pattern) '(orderless-literal . ""))
   ((string-prefix-p "!" pattern)
    `(orderless-without-literal . ,(substring pattern 1)))
   ((string-suffix-p "!" pattern)
    `(orderless-without-literal . ,(substring pattern 0 -1)))))

;; `annotation-if-at' precedes `flex-if-twiddle' on purpose:
;; with suffix support, a compound like `@PATTERN~' would otherwise
;; fire flex on the trailing `~' before annotation could claim the
;; leading `@'.  Annotation must get first crack.
(setq orderless-style-dispatchers
      '(my/orderless-dispatcher-initialism
        annotation-if-at
        flex-if-twiddle
        without-if-bang))

Four dispatchers, each demonstrated against the candidate list:

Try the prompt again with these style dispatchers in place.

(completing-read "Pick something: " my-produce)

The annotation dispatcher is the most interesting of the four because it shows that some dispatchers compose. The leading @ picks a slot (annotation rather than name); the inner ~ switches the match style on whatever it's already pointing at. Nothing in Orderless's library knows about @~ as a compound prefix. We wrote that composition ourselves, in a few lines (annotation-if-at).

Note we won't be able to see the annotation dispatcher in action until we add annotations in the Marginalia section, so bear with me!

Orderless stays out of the way. The only thing that changed about our completion setup by introducing Orderless is how Emacs matches your input against the candidate list changed, because we effectively swapped in a different completion style through completion-styles.

Vertico didn't need to know about Orderless. Orderless didn't need to know about Vertico. They compose because Emacs routes their concerns through separate hooks.

To drive the point home, what we did not do matters architecturally: Vertico and Orderless are agnostic to one another. They leverage independent Emacs built-ins (completing-read rendering and completion-styles respectively), and they compose because Emacs natively routes their concerns through these separate channels. You can swap in any other minibuffer candidate display UI (Icomplete-vertical, Mct, fido-vertical-mode), or drop it entirely, and Orderless will still work. You can swap in any other completion style and Vertico will still work.

8. Phase 4: Marginalia — Annotations marginalia annotations

We can filter tightly now, but in spite of the rich metadata attached to each produce candidate, we can't see anything about a candidate except its name. If you're deciding between peach and apricot, relevant information like price, color, season, etc… is already on the candidate's text properties, but Vertico is only showing us the string itself. Marginalia is the package that promotes candidates into informed choices by displaying their metadata as right-aligned columns next to each candidate name.

The trick that makes Marginalia (and every subsequent VOMPECCC package) possible is the convention already established by the list of produce items: the candidate is its name as a string, with its full record's fields stamped on as text properties. completing-read is satisfied because the candidate is a plain string; the rest of the substrate is satisfied because the properties are right there.

A note on scope before we start: plain completing-read can only carry one completion category at a time, and Marginalia dispatches its annotator off that prompt-level category. The corpus has two categories (fruit and vegetable); to keep this phase honest, we narrow the picker to just fruits for now. Phase 5 will lift this restriction with Consult's multi-source mechanism.

That narrowing is one line of Lisp, but worth pausing on. Every later phase (the Consult sources in Phase 5, the async variant in Phase 8) will partition the corpus by category in the same way, so we factor it out once and read the routing key off the candidate itself rather than off of some separate lookup table. This is the candidate-as-currency convention in miniature: a routing question is answered by reading a text property:

(defun my-produce-of-category (cat)
  "Return candidates from `my-produce' whose `category' is CAT."
  (cl-remove-if-not
   (lambda (cand) (eq (get-text-property 0 'category cand) cat))
   my-produce))

We still need to tell the prompt itself what completion category this is, because Marginalia dispatches its annotator off the prompt's metadata, not off per-candidate text properties. The candidate stamping we did in the corpus is for our own code (the actions, the transformer, the exporter) to read; the framework looks at prompt metadata. The lightest way to set the metadata is completion-extra-properties, a property list that overrides the completion metadata for the duration of one completing-read call:

(defun my-pick-fruit ()
  "Pick a fruit by name."
  (interactive)
  (let ((completion-extra-properties '(:category fruit)))
    (message "You picked: %s"
             (completing-read "Fruit: " (my-produce-of-category 'fruit)))))

The foundational pattern — a completion function that responds to (action 'metadata) with (metadata (category . fruit)) — is still available and is what libraries like Consult build on. However, for a one-off picker without Consult, completion-extra-properties is equivalent and cleaner. Why is this even needed? Because plain completing-read over a list of strings has no way to communicate a category to Marginalia: the framework reads the prompt's completion metadata, and our list of strings doesn't ship any. As soon as we move to Consult in Phase 5, the source-level :category key takes over and the extra-properties step disappears entirely, which is exactly why packages like spot never need this dance. Every spot prompt is a Consult prompt. Our Phase 4 picker is the awkward case precisely because it is deliberately the barest possible call, and a demonstration of a Consult-less completion setup for our produce picker.

The annotator itself is the heart of this phase. It takes a candidate string, reads its text properties directly, and hands a list of columns to marginalia--fields, which does the alignment, per-field truncation, and face application:

(defun my-annotate-produce (cand)
  "Annotate a produce candidate CAND with type, color, season, and price."
  (marginalia--fields
   ((symbol-name (get-text-property 0 'type cand))
    :truncate 13 :face 'marginalia-type)
   ((get-text-property 0 'color cand)  :truncate 10 :face 'marginalia-string)
   ((get-text-property 0 'season cand) :truncate 12 :face 'marginalia-date)
   ((format "$%.2f" (get-text-property 0 'price cand))
    :truncate 8  :face 'marginalia-number)))

Note that I am not writing any layout code at all. marginalia--fields handles padding, alignment, and face application; my job is only to declare which fields go in which columns. Annotating the candidates in this way enables Orderless's @ dispatcher to filter by our produce's metadata, so @berry, @citrus, @root become legitimate filter prefixes.

Registration for the fruit category is one add-to-list against Marginalia's annotator registry, plus enabling the marginalia-mode:

(add-to-list 'marginalia-annotators
             '(fruit my-annotate-produce none))
(marginalia-mode 1)

The registry entry is (CATEGORY ANNOTATOR1 ANNOTATOR2 ... none), where each tail symbol is an annotator marginalia-cycle (M-A) can rotate to in-session. We list two states for our category: our custom annotator, then none (annotations off). This matches spot's convention and gives a clean toggle on M-A. Marginalia's own built-in entries also include a builtin symbol in the chain (which is a fallback that defers to whatever annotation-function the prompt's metadata declares natively) but for a category nobody else knows about (like fruit), there is no built-in to defer to, so leaving it out keeps the cycle to two visibly-different states instead of three.

Run the picker:

(my-pick-fruit)

When (my-pick-fruit) runs, the prompt opens as it did before, but every one of the fruit candidates is now followed by a horizontally aligned set of columns: a type word (pome, berry, citrus, …), a color word (red, yellow, blue, green, …), a season (spring, summer, winter, year-round), and a dollar-formatted price ($0.59, $3.99, $6.99).

Stylistically, each column is padded to a fixed width and rendered in its own face, so the four fields read as distinct groups rather than running together with a delimiter. Where Phase 3 showed strawberry, this phase shows:

strawberry berry red spring $3.99

The list is legible at a glance, and what's more, you can usefully compare peach against apricot on price and season without typing anything. Scanning for cheap in-season fruit, for example, is made easy in this way.

Typing against annotation text is where Marginalia crosses from cosmetic to compositional. Typing yellow at the prompt matches nothing, because yellow is in the annotation column, not the candidate name, and Orderless is still matching against names only. But prefix that same component with @, as in @yellow, and the annotation dispatcher we wired up in Phase 3 tells Orderless to match this particular component against the annotation text instead of the candidate string. The list snaps to exactly the three yellow-colored fruits in the corpus.

To drive home the point that the VOMPECCC packages work independently of one another, Orderless knew nothing about Marginalia, and vice-versa. The @ dispatcher simply matches against whatever is in the "annotation slot" of the current candidate, and that slot happens to contain the words Marginalia stamped there.

The compound variant from Phase 3 cashes in here too: @~sm triggers the flex branch of annotation-if-at, flex-matching the characters s and m against annotation text. Only summer contains them in order, so the list collapses to the summer fruits.

Annotation components compose the same way regular components do. Typing @summer,@red on the empty prompt narrows first to summer fruits, then to the subset of those that are also red. The list collapses to raspberry and cherry, the two red summer fruits in the corpus. You can reach for a fruit by its properties without ever remembering its name. Post 2 called this "an unusually large leverage gain for what feels like a cosmetic layer".

The architectural observation here is that the @ dispatcher is not a Marginalia feature. It is an Orderless feature (a dispatcher we wrote) that happens to work because Marginalia exposes annotations through the same completion-metadata slot Orderless reads from. Swap Marginalia for any other annotator (say, a leaner one you write yourself that only shows price) and the @ filter still works. With an alternative annotation provider, Orderless would just filter against whatever that other annotator produces.

8.1. The recommended alternative to Marginalia: inline annotations

The Marginalia readme is explicit on a point worth surfacing before we lock this pattern in. For completion commands you control, the author recommends putting the annotator directly in the completion metadata via affixation-function, not in marginalia-annotators. Marginalia exists primarily to annotate other people's commands, and most of the time this is the built-in Emacs prompts and third-party packages whose authors didn't ship annotations themselves. When you control the call site, as we are here with our fruit picker, you can attach the annotator alongside the category in completion-extra-properties, and that is the recommended default.

The replacement is one function and one extra property. affixation-function receives the list of currently visible candidates and returns (CANDIDATE PREFIX SUFFIX) triples, which Vertico (or any completing-read UI) renders. We have to do our own column padding now: marginalia--fields was the convenience that absorbed it, but the upside of doing things the recommended way is that we eliminate the Marginalia dependency for this prompt:

(defun my-affixation-produce (cands)
  "Return (CAND PREFIX SUFFIX) per candidate, columns padded for alignment."
  (let ((width (apply #'max 0 (mapcar #'length cands))))
    (mapcar
     (lambda (cand)
       (let* ((pad  (make-string (- (1+ width) (length cand)) ?\s))
              (cols (concat
                     (propertize (format "%-13s" (symbol-name (get-text-property 0 'type cand)))
                                 'face 'completions-annotations)
                     (propertize (format "%-10s" (get-text-property 0 'color cand))
                                 'face 'completions-annotations)
                     (propertize (format "%-12s" (get-text-property 0 'season cand))
                                 'face 'completions-annotations)
                     (propertize (format "$%-7.2f" (get-text-property 0 'price cand))
                                 'face 'completions-annotations))))
         (list cand "" (concat pad cols))))
     cands)))

(defun my-pick-fruit-builtin ()
  "Pick a fruit using only built-in annotation machinery."
  (interactive)
  (let ((completion-extra-properties
         (list :category 'fruit
               :affixation-function #'my-affixation-produce)))
    (message "You picked: %s"
             (completing-read "Fruit: " (my-produce-of-category 'fruit)))))

The shape is the same as the Marginalia version (propertized candidates and a property list bound around the call) but with one extra entry. :affixation-function delivers the annotator directly, where the Marginalia version had only :category and let the marginalia-annotators registry lookup pick the annotator.

To prove this is independent of Marginalia, turn the mode off and run the new picker:

(marginalia-mode -1)
(my-pick-fruit-builtin)

The four columns still appear. Vertico renders, Orderless filters, and the annotation slot is filled by my-affixation-produce. @yellow still works, too, because Orderless's annotation dispatcher reads from whatever populates that slot!

This actually strengthens the unix-style nature of the VOMPECCC set rather than diluting it. affixation-function in the completion metadata is an Emacs primitive. Marginalia is one consumer of that slot: a registry that picks an annotator per category and writes it into the slot at completing-read time. Our hand-rolled affixation-function is a different consumer of the same slot, delivering the annotator inline.

Re-enable Marginalia and re-run the original picker:

(marginalia-mode 1)
(my-pick-fruit)

Annotations are back, served by Marginalia's registry-driven version. The two implementations are interchangeable from the prompt's point of view, and only the provenance of the annotator differs. When to reach for which becomes a question of who controls the command. For built-in Emacs prompts and third-party commands you can't edit, Marginalia is your only entry point. For your own commands, the inline affixation-function is closer to the data, has zero dependency, and is the route the Marginalia author recommends.

The rest of this post continues with Marginalia in place. Both routes (the Marginalia registry and the inline affixation-function) can be threaded through the Consult sources in Phase 5. The takeaway from this aside is that the inline route exists, that it is the recommended default for a completion command you fully control, and that it composes with Vertico, Orderless, and the rest of the completion substrate exactly the way the other VOMPECCC packages do.

That being said, I will use the Marginalia registry approach for the rest of this post because you will most often see Marginalia style annotations if you adopt VOMPECCC, and they look nicer with Marginalia's formatting.

9. Phase 5: Consult — Multi-Source with Narrowing consult sources narrow

Phase 4 was a single prompt over a fruit-only subset, which was enough to demo Marginalia, but it left the corpus's vegetables out and gave us no way to scope the prompt without typing. What if we want one prompt that holds everything (all categories) in my-produce and lets us flip between fruits and vegetables (and back to all of it) with a single keystroke.

Consult fixes this through its multi-source mechanism: consult--multi takes a list of sources, unifies their candidates into a single prompt, and sets up per-source narrowing keys. Each source declares its own name, its own narrow key, its own completion category, and its own items.

The dispatch story in Phase 5 is the same as in Phase 4: the candidate's completion category is whatever the candidate carries. In Phase 4 we read category off the only candidate type the picker held (a fruit). In Phase 5 each source produces candidates of one category (fruit for the fruit source, vegetable for the vegetable source) and the source-level :category matches the value the data already declared on every candidate. The framework reads the value out of the candidate. The spot post uses the same double-stamping pattern, and the per-candidate text property is the authoritative truth, and the source-level :category keeps Consult's metadata in sync.

Each candidate carries five text properties: category (fruit or vegetable), type, color, season, and price, and is read directly off the candidate by Marginalia, Embark, the annotator, and every action we're about to write.

Here we define two Consult sources (1 per category) each with its own scoped :history variable so previously-selected fruits and previously-selected vegetables don't get mixed together in any one history list:

(defvar my-consult-history-fruit nil
  "History scoped to the fruit Consult source.")

(defvar my-consult-history-vegetable nil
  "History scoped to the vegetable Consult source.")

(defvar my-consult-source-fruit
  `(:name     "Fruits"
    :narrow   ?f
    :category fruit
    :history  my-consult-history-fruit
    :items    ,(lambda () (my-produce-of-category 'fruit)))
  "Consult source for fruits.")

(defvar my-consult-source-vegetable
  `(:name     "Vegetables"
    :narrow   ?v
    :category vegetable
    :history  my-consult-history-vegetable
    :items    ,(lambda () (my-produce-of-category 'vegetable)))
  "Consult source for vegetables.")

A Consult source plist's most important keys:

:items is the candidate stream. A function that returns a list of candidates, called lazily when the prompt opens. Ours is synchronous because the produce list is local, but for a remote API you would swap :items for :async and consult--dynamic-collection instead. Phase 8 walks through that variant against a faithfully-mocked produce API, and the spot post discusses the consumer-side cost when multiple sources share one endpoint.
:narrow ?f binds the character that scopes the prompt to just this source. Pressing f SPC at the prompt hides every non-fruit candidate.
:category fruit is the completion category that propagates onto every candidate from this source, not via our category text property but via Consult's own multi-category text property, which Consult writes from this very key. Marginalia and Embark consult that multi-category channel to pick the right annotator and the right keymap per candidate. We set this key to match the data's category property by hand, so the two declarations stay aligned.
:history my-consult-history-fruit is a per-source history list. Selecting a candidate from this source appends it to this variable (and only this variable), which means the fruit picker can keep its own history and Vertico's M-p / M-n cycle through a list that is meaningfully scoped instead of polluted with every minibuffer interaction in the session. This per-source scoping is also what makes a per-prompt history-recall command (something like consult-history) useful, which we discuss right after.
:name is the header shown above this source's candidates in the unified list.

Two Marginalia registry entries, one per category:

(dolist (cat '(fruit vegetable))
  (add-to-list 'marginalia-annotators
               `(,cat my-annotate-produce none)))

Then the consult command:

(defun consult-produce-picker ()
  "Pick produce with multi-source Consult completion."
  (interactive)
  (consult--multi
   (list my-consult-source-fruit
         my-consult-source-vegetable)
   :prompt "Produce: "))

Run it:

(consult-produce-picker)

When (consult-produce-picker) runs, the prompt opens with the thirty produce items grouped under two bold header lines in the vertical list: Fruits and Vegetables, each followed by the candidates belonging to that source. Every annotation column from Phase 4 is preserved because the annotator is registered against both categories and Consult has tagged each candidate with the right one.

The new affordance by consult is "narrowing", the ability to scope the prompt to a single source with one keystroke. Pressing f followed by SPC hides every non-fruit candidate: the twenty fruits become the entire list, and a small indicator in the prompt header shows the narrow state. Pressing DEL clears the narrow and restores the full thirty-item view. v SPC narrows to vegetables.

The features from earlier phases still apply inside a narrowed view, and this is where the independence of VOMPECCC's constituents really shows. With the list narrowed to fruits, typing @berry further filters to the four berries via the type column we added to the annotator; @red filters to red fruits; ~bry flex-matches the berry suffix of the remaining candidates; !blue excludes anything containing blue. Orderless, Vertico, and Marginalia are all still doing exactly what they did in Phase 4, and they could care less that the candidate source is now two Consult sources instead of one list.

Note we have another classifying property in each candidate. The type column in the annotator means @berry, @citrus, @root, @cruciferous are all valid one-component filters on the prompt, and they compose with the source narrow, so f SPC @citrus gives you exactly the four citrus fruits. The framework keeps type as a searchable axis instead of a narrowing axis.

The amount of code we wrote for the narrowing, grouping, and per-source history is pretty close to zero. I like Consult's declarative API in this way: we declared; Consult did.

9.1. Recalling prior queries with `consult-history`

Now that fruit selections land in my-consult-history-fruit and vegetable selections land in my-consult-history-vegetable, two further capabilities become available almost for free.

The first is the built-in cycle: M-p and M-n walk through the active prompt's history, and because we scoped per source, those cycles only contain entries you actually picked from this source.

The second is more powerful: consult-history, a Consult command that reads the active history variable, presents its entries in a recursive minibuffer with full Orderless+Vertico+Marginalia goodness, and inserts the chosen entry into the original prompt. The conventional binding is in minibuffer-local-map:

(setq enable-recursive-minibuffers t)
(keymap-set minibuffer-local-map "C-r" #'consult-history)

The enable-recursive-minibuffers setting is a prerequisite: consult-history opens a new minibuffer prompt while another is already active, and Emacs's default is to refuse that. Most VOMPECCC configurations turn it on already.

Demo 1: recall a previous selection. Run (consult-produce-picker) and pick cherry. Run it again, and at the empty prompt press C-r. A second minibuffer opens listing the active source's history; cherry is at the top. Pick it (or flex-match ~chy) and cherry is inserted into the original prompt — RET confirms it.

This is the everyday case: the items you reach for repeatedly are one keystroke and one history-pick away on every subsequent run. Since the history is per-source, narrowing first with f SPC or v SPC scopes C-r to just that source's history.

Demo 2: recall a complex Orderless query. Selections in history are useful, but the bigger win is recalling queries, for example, something like the complex multi-component Orderless filters you spent twenty seconds composing.

This is a behavior of consult history that is not so obvious. The trick is that, by default, completing-read adds whatever it returns to the history variable, and what it returns is the selected candidate. To make the typed query the return value instead, press M-RET (vertico-exit-input) at the prompt. This commits the literal minibuffer contents rather than the highlighted candidate, regardless of whether :require-match is on.

Run the picker, narrow with f SPC, and type summer,!blue,@red. Instead of pressing RET to pick a fruit, press M-RET. The minibuffer closes and the returned string is the literal summer,!blue,@red, and that is what lands in my-consult-history-fruit.

Run the picker again, narrow with f SPC, and hit C-r. summer,!blue,@red is at the top of history. Pick it, and the query is restored in the prompt, ready to be tweaked or RET-confirmed against the same filtered set.

Demo 3: save typed input on every exit. If you'd rather not have to remember M-RET, and you're willing to accept some history pollution, a minibuffer-exit-hook can capture the typed input alongside the selection on every exit:

(defun my-save-typed-input-to-history ()
  "Add minibuffer input to history before exit, alongside the selection."
  (when-let* ((hist minibuffer-history-variable)
              ((symbolp hist))
              ((not (eq hist t)))
              (input (minibuffer-contents-no-properties))
              ((not (string-empty-p input))))
    (add-to-history hist input)))

(add-hook 'minibuffer-exit-hook #'my-save-typed-input-to-history)

With the hook in place, every exit pushes the current contents of the minibuffer to history. RET on raspberry after typing summer,!blue,@red now adds both summer,!blue,@red and raspberry to history. C-r shows both. The cost is that history gets longer, including incomplete queries you abandoned mid-typing. But consider you also have the fully feature ICR experience in consult-history, so in my opinion, this is a non-issue.

Indeed, architecturally, history is one more consumer of the same Emacs primitive every other phase has been consuming. completing-read takes a HIST argument and updates that variable on selection, and Consult's per-source :history key just threads that argument per source. consult-history reads the variable. The minibuffer-exit-hook reads the buffer's typed contents. M-RET changes what gets returned from the prompt and therefore what gets stored.

10. Phase 6: Embark — Actions embark actions

We can select a produce item, but we still can't do anything with it.

So far the picker's job has ended at returning a string. Embark is the package that adds a layer of category-contextual actions on top of any completion prompt and provides a keyboard-driven context menu whose contents depend on what kind of candidate is highlighted.

It's useful to think of Embark as similar to a left-click or 'context menu' in traditional UIs.

We'll define the minimum set of actions needed to demonstrate Embark's three headline features:

embark-act on a single candidate (the basic case): an inspect action that pops a buffer with the item's full plist.
embark-act-all on every visible candidate (multi-cardinality): an add-to-cart action that appends to a *Cart* buffer, which we will invoke against every currently visible item at once.
Per-category keymap dispatch (context-sensitivity): vegetables get a roast action that fruits don't; citrus fruits get a juice action that other fruits don't. These are specializations side by side, by two different mechanisms in Embark: the vegetable specialization rides on the Consult source's :category key (forwarded to Embark via Consult's multi-category channel), while the citrus specialization rides on an Embark transformer we write that reads the candidate's type property.

10.1. The Actions

Each action is a regular interactive command that takes the candidate string as its argument. Embark passes the current candidate when the user triggers the action.

(defun my-inspect-produce (cand)
  "Pop a buffer showing the text properties carried by produce CAND."
  (interactive "sProduce: ")
  (let ((props (text-properties-at 0 cand))
        (buf (get-buffer-create "*Produce Inspect*")))
    (with-current-buffer buf
      (erase-buffer)
      (insert (format ";; %s\n" cand))
      (pp props (current-buffer))
      (goto-char (point-min))
      (emacs-lisp-mode))
    (display-buffer buf)))

(defun my-add-to-cart (cand)
  "Append produce CAND to the *Cart* buffer."
  (interactive "sProduce: ")
  (let ((price (get-text-property 0 'price cand)))
    (with-current-buffer (get-buffer-create "*Cart*")
      (goto-char (point-max))
      (insert (format "- %-12s ($%.2f)\n" cand price)))
    (message "Added %s to cart" cand)))

(defun my-make-juice (cand)
  "Juice the citrus fruit CAND."
  (interactive "sFruit: ")
  (message "🍹 Juicing %s!" cand))

(defun my-roast-vegetable (cand)
  "Roast the vegetable CAND."
  (interactive "sVegetable: ")
  (message "🔥 Roasting %s!" cand))

Each action reads whatever properties it needs off the candidate, and then does something domain-specific. No Embark machinery leaks into the action body, and Embark's only job is to invoke the action with the right candidate.

10.2. The Keymaps

Embark actions are bound in per-category keymaps. We define one general map per top-level category (one for fruits, one for vegetables), and then we define a specialized citrus map that inherits from the fruit map and adds j (for juice 🍹):

(defvar-keymap my-fruit-general-map
  :parent embark-general-map
  :doc "Embark actions applicable to any fruit."
  "i" #'my-inspect-produce
  "a" #'my-add-to-cart)

(defvar-keymap my-vegetable-general-map
  :parent embark-general-map
  :doc "Embark actions applicable to any vegetable."
  "i" #'my-inspect-produce
  "a" #'my-add-to-cart
  "r" #'my-roast-vegetable)

(defvar-keymap my-fruit-citrus-map
  :parent my-fruit-general-map
  :doc "Embark actions for citrus (fruit actions + juicing)."
  "j" #'my-make-juice)

:parent embark-general-map gives us the built-in defaults (copy-as-kill, describe, insert, etc.) on top of our domain-specific actions. :parent my-fruit-general-map on the citrus map means citrus candidates inherit i and a from the fruit general map and add j on top.

10.3. The transformer: refining `fruit` to `fruit-citrus`

We have two dispatch problems in this phase, and they look symmetric on the surface:

Fruit vs. vegetable. Each candidate already knows whether it is a fruit or a vegetable — the source declared it, and Consult propagated that source-level :category onto each candidate via the multi-category text property. We want Embark to pick my-fruit-general-map for fruits and my-vegetable-general-map for vegetables.
Citrus refinement. Within fruits, we want citrus candidates to additionally get the j juice action via my-fruit-citrus-map. This is a refinement below the source category.

The corpus already keeps two clean axes for these: category for top-level kind (fruit or vegetable) and type for fine-grained classification (pome, berry, citrus, …). We don't want to declare citrus as a third completion category — that would collapse the two axes back into one, force the data's category field to mean both "fruit-vs-vegetable" and "this particular kind of fruit", and the next refinement (say, expensive citrus) would force yet another category symbol. The right tool is Embark's transformer mechanism: keep the framework's category vocabulary flat (just fruit and vegetable), and specialize below that vocabulary by reading additional fields off the candidate.

A transformer is a function attached to a category in embark-transformer-alist. When Embark is about to dispatch on a candidate, it looks up the prompt's category in that alist; if it finds a transformer, it calls the transformer once with the original type and target. The transformer returns a refined (TYPE . TARGET) cons, and Embark dispatches on that refined type.

Now the load-bearing detail: Embark applies the transformer exactly once. Look at embark.el's dispatch path and you'll see (if-let (transform (alist-get type embark-transformer-alist)) ...) — a single if-let, no recursion, no chain. The transformer for the original prompt type fires, returns a refined type, and Embark dispatches on that refined type without consulting the alist a second time.

This is consequential when Consult is in the picture. consult--multi sets the prompt's completion-metadata category to multi-category (not fruit or vegetable) and stamps each candidate with a multi-category text property holding (SOURCE-CATEGORY . CAND). Embark ships a built-in transformer registered on multi-category (embark--refine-multi-category) that extracts the source category from that property and returns (fruit . CAND) or (vegetable . CAND). But that's the only transformer Embark will run. If we naively wrote a fruit transformer and registered it on fruit, it would never fire in our prompt, because the prompt's category is multi-category and Embark only consults the alist once, against that original key.

So in a multi-category prompt, the multi-category transformer is the only integration point for any refinement below the source level. We replace Embark's built-in with our own that does both jobs in a single pass: the same source-category extraction (delegated to the built-in helper), plus our citrus refinement on top.

(defun my-multi-category-transformer (type cand)
  "Refine `multi-category' candidates with citrus refinement layered on.
Embark applies the prompt-category transformer exactly once, so any
per-source refinement must happen inside this single function.  We
delegate to Embark's built-in `embark--refine-multi-category' for the
source-category extraction, then refine `fruit' to `fruit-citrus' when
the candidate's `type' property is `citrus'."
  (let ((refined (embark--refine-multi-category type cand)))
    (if (and (eq (car refined) 'fruit)
             (eq (get-text-property 0 'type cand) 'citrus))
        (cons 'fruit-citrus (cdr refined))
      refined)))

(setf (alist-get 'multi-category embark-transformer-alist)
      #'my-multi-category-transformer)

Then we register one keymap per target type. Every fruit gets the general fruit map, citrus gets the specialized one (via our transformer's refinement), and every vegetable gets the vegetable map:

(add-to-list 'embark-keymap-alist '(fruit        . my-fruit-general-map))
(add-to-list 'embark-keymap-alist '(fruit-citrus . my-fruit-citrus-map))
(add-to-list 'embark-keymap-alist '(vegetable    . my-vegetable-general-map))

What about embark-act-all over a candidate set that spans both sources? When all candidates share a refined type (after our transformer runs), Embark dispatches on that unified type — so a fruits-only narrowing dispatches on fruit, and a vegetables-only narrowing dispatches on vegetable. When the set spans sources (e.g., a cross-cutting @summer filter), Embark falls back to the original prompt category, multi-category. We register a fallback keymap so cross-source embark-act-all still has i and a available:

(add-to-list 'embark-keymap-alist '(multi-category . my-fruit-general-map))

This is the integration, end to end. consult--multi sets the prompt category to multi-category and stamps each candidate with a multi-category text property holding the source category. Embark looks up multi-category in embark-transformer-alist and runs our transformer, which extracts the source category (via the built-in helper), then refines fruit to fruit-citrus when the candidate's type property is citrus. Embark dispatches on the refined type, finds the matching keymap in embark-keymap-alist, and opens it. One transformer, three keymap entries plus a fallback — all riding on the per-source :category we declared in Phase 5 and the type field we put on every candidate at the top of the post.

10.4. The Demo

Assuming you have embark-act bound somewhere (the canonical binding is C-.; if you don't, evaluate (keymap-global-set "C-." #'embark-act) first):

(consult-produce-picker)

Let's start by acting on a single candidate. Run the picker, narrow or scroll until apple is highlighted, and press C-.. A small keymap-hint popup appears, listing the action keys available for this candidate: i for inspect, a for add-to-cart, plus everything embark-general-map inherits. Pressing i closes the popup, closes the minibuffer, and pops open a new buffer called *Produce Inspect* showing the apple's text properties pretty-printed: a comment line ;; apple followed by (category fruit type pome color "red" season "fall" price 1.29). Embark invoked my-inspect-produce with the candidate string; our action grabbed the candidate's text-property plist via text-properties-at and handed it to pp.

Now clear the prompt and scroll to lemon. Press C-.. The menu is different this time! i and a are still there, but there is a third entry: j juice. Inside our multi-category transformer, the source-category extraction returns fruit, and then the citrus check sees (get-text-property 0 'type cand) = citrus and refines the dispatch type to fruit-citrus. Embark looks up fruit-citrus in the keymap alist, finds my-fruit-citrus-map (which inherits the i and a bindings from the general map and adds j on top), and presents it after embark-act. Press j and 🍹 Juicing lemon! flashes into the echo area.

Try embark-act on strawberry. The popup is back to just i and a, with no j in sight. A strawberry's type is berry, so the citrus branch of our transformer doesn't fire, the refined type stays fruit, and Embark picks my-fruit-general-map. Now try carrot: the popup is i a r. r roast is there because carrot came from the vegetable source — our transformer extracts vegetable from multi-category, the citrus branch is irrelevant (the source category is not fruit), and Embark dispatches on vegetable.

For the multi-candidate case, start the picker again and narrow to fruits with f SPC, then type @summer to filter to summer fruits within fruits. The list collapses to the summer fruits. Press embark-act-all (the canonical binding is A from the embark-act popup, or C-u C-. directly). Embark prompts for a single action to apply to every visible candidate; press a for add-to-cart. In one keystroke, all ten summer fruits are appended to the *Cart* buffer, one per line, each with its price. You can also select individual candidates with embark-select (which I have bound to C-SPC).

Now clear the narrow and try @summer across the full produce corpus. Hit embark-act-all, press a for add-to-cart. All thirteen go into *Cart*. This is where the multi-category fallback we registered earlier comes in handy, because the candidate set spans both sources, embark dispatches against the multi-category type, and the fallback gives us i and a (the actions defined on every produce item). Type-specific actions like j and r aren't available in this state, which makes logical sense, because a single keystroke can't simultaneously juice a citrus and roast a vegetable.

The same text properties that Marginalia was reading in Phase 4 are what the action functions and the transformer are reading now. Three different packages are cooperating, on three different hooks, off the same candidate, without ever knowing about each other.

10.5. Collect and export

So far the picker has been a selection surface: pick something and act on it.

Embark provides two further commands that promote the candidate list itself into a first-class buffer.

embark-collect snapshots the current candidate set into a fresh *Embark Collect* buffer with the original keymap dispatch still attached to each row. Run the picker, type @summer to narrow to summer items across both sources, then M-x embark-collect (or invoke embark-act with a prefix arg and pick embark-collect). The thirteen summer items land in a buffer that outlives the minibuffer; press embark-act on cherry and the fruit map dispatches; press embark-act on tomato and the vegetable map dispatches. No registration is needed; embark-collect works on any candidate set automatically.

embark-export goes one step further. Where collect produces a generic buffer of strings, export materializes the candidates into the major mode appropriate to their type. File candidates become a Dired buffer; buffer candidates become an Ibuffer; grep results become a wgrep-editable buffer; etc…. For our produce, the natural target is Emacs's built-in tabulated-list-mode.

We register a per-category exporter the same way we registered keymaps in The Keymaps. The exporter takes the list of candidate strings and produces the target buffer:

(defun my-export-produce-tabulated (candidates)
  "Export produce CANDIDATES into a tabulated-list buffer."
  (let ((buf (get-buffer-create "*Produce*")))
    (with-current-buffer buf
      (tabulated-list-mode)
      (setq tabulated-list-format
            [("Name"   14 t)
             ("Cat"     10 t)
             ("Type"   13 t)
             ("Color"  10 t)
             ("Season" 12 t)
             ("Price"   8 t)])
      (setq tabulated-list-entries
            (mapcar
             (lambda (cand)
               (list cand
                     (vector (substring-no-properties cand)
                             (symbol-name (get-text-property 0 'category cand))
                             (symbol-name (get-text-property 0 'type cand))
                             (get-text-property 0 'color cand)
                             (get-text-property 0 'season cand)
                             (format "$%.2f" (get-text-property 0 'price cand)))))
             candidates))
      (tabulated-list-init-header)
      (tabulated-list-print))
    (pop-to-buffer buf)))

(dolist (cat '(fruit fruit-citrus vegetable multi-category))
  (add-to-list 'embark-exporters-alist
               (cons cat #'my-export-produce-tabulated)))

The exporter reaches for the same text properties that the annotator and the actions read from. Once again, the candidate-as-currency convention is being leveraged.

The four registrations are worth a moment. embark-export unifies the candidate set's type by calling our transformer on every candidate and checking that they all produce the same refined type ((cl-every ...) in embark--maybe-transform-candidates). When all candidates are vegetables, our transformer returns vegetable for each, unification succeeds, and Embark dispatches on vegetable. Same for an all-citrus filter (f SPC @citrus → all fruit-citrus) or an all-non-citrus filter. But the obvious case (narrow to fruits with f SPC) gives a mix of citrus and non-citrus, which our transformer refines to two different types (fruit-citrus and fruit). Unification fails, and Embark falls back to the prompt's original category: multi-category. Registering our exporter on multi-category as well makes the export work in that mixed-but-still-produce case.

A trade-off worth being honest about: that multi-category registration is shared with every other consult--multi prompt in the session. In a real package, you'd want to guard the exporter against non-produce candidates, or scope the registration more tightly. For this walkthrough we accept the broad registration and move on.

Run the picker, narrow to fruits with f SPC, then M-x embark-export (or embark-act with prefix arg, then E). A *Produce* buffer pops open in tabulated-list mode:

(consult-produce-picker)

Name           Cat       Type          Color      Season       Price
apple          fruit     pome          red        fall        $1.29
pear           fruit     pome          green      fall        $1.79
strawberry     fruit     berry         red        spring      $3.99
blueberry      fruit     berry         blue       summer      $4.99
raspberry      fruit     berry         red        summer      $5.99
...

Every column is sortable from its header (the trailing t flag in tabulated-list-format turns sortability on per-column); n and p move between rows. Since each row's tabulated-list-id is the original propertized candidate, embark-act on a row still dispatches to the right keymap based on category, including the citrus juicer via the transformer. embark-act on the cherry row offers i a (general fruit); embark-act on lemon offers i a j (citrus, refined by the transformer); embark-act on a row exported from a vegetable narrowing would offer i a r (vegetable). Nothing changes about the per-candidate dispatch just because the candidates moved into a major mode, which is very convenient! This is one of my favourite things about Embark. It works on minibuffer candidates in the all-too-common ICR setting, but it also works on any arbitrary piece of text in Emacs. With Embark, literally everything in Emacs becomes left-clickable in this way.

Cross-cutting filters (e.g., @summer spanning fruits and vegetables) also fall back to multi-category for the same reason (the candidates' refined types differ) so the same registration carries them through. embark-collect remains available as a finer-grained alternative when you want a generic candidate-set buffer rather than a tabulated table.

The architectural take: embark-export is not a Consult feature, not a Marginalia feature, not part of any pipeline our other phases set up. It is an Embark feature that works with any completing-read-driven prompt that has a category and a registered exporter. And the exporter we wrote is one more consumer of the candidate's text properties alongside the annotator (Phase 4), the action functions (this phase), the transformer (this phase), and the per-category keymap dispatch (also this phase). If you ever decide a tabulated list isn't the right export target (maybe a csv-mode or org-mode would be better) swap the exporter function and every other layer of the picker stays exactly where it is.

11. Phase 7: Prescient — Recency and Frequency Sorting prescient sorting

The last concern from the orthogonal six is sorting.

So far, sorting has been incidental. Vertico ships a default sort that draws on minibuffer history, but it ignores frequency entirely and resets when Emacs restarts. Prescient is the dedicated package for this concern: it computes a combined frecency score (recency + frequency) per candidate and hands it to Vertico as the sort function. With prescient-persist-mode the score survives Emacs restarts; even without it, the score updates from the very first selection.

That last point is what makes Prescient demonstrable in a from-scratch walkthrough. The score for a never-selected candidate is zero. Pick a candidate once and its score jumps above zero, putting it at the top of the next prompt. One selection is enough to see the effect.

One wrinkle to acknowledge before the setup. Of the six VOMPECCC packages we are using, Prescient is the only one that bundles two concerns: sorting (the part we want here) and its own filtering style. vertico-prescient-mode toggles both by default — which would replace the Orderless setup from Phase 3 and silently break the custom dispatchers (~, !, backtick, @) we have been relying on for the last four phases. Post 2 flags this same two-concern split and notes the common workaround: keep Orderless for filtering, take Prescient's sort, and disable the filter takeover. That is what we do here:

(setq vertico-prescient-enable-filtering nil)
(vertico-prescient-mode 1)

This is the entire prescient integration. (Adding (prescient-persist-mode 1) would persist scores across Emacs sessions; we leave it off here so the demo's state stays bounded to this single Emacs session.)

This demo is simple. Run the picker once, select an item, then re-run. The item we just picked will be the first in the list.

(consult-produce-picker)

All five layers continue untouched, while a sixth package quietly improves the order in which their candidates land on screen.

12. Phase 8: Async — Going Remote with `consult--dynamic-collection` async consult remote

The picker we have works because the entire produce corpus is local: my-produce is a literal thirty-item list, and each Consult source's :items callback returns its slice synchronously. Real-world sources are usually remote, and the spot post demonstrates this w/r/t the Spotify API. Filtering at the Emacs side stops being viable once the corpus has thousands or millions of entries, and you have to push the query to the server and let the server tell you which candidates match.

Consult ships consult--dynamic-collection for exactly this case. It wraps a completion function so that each keystroke fires a debounced, cancellable query. The function you write only has to answer "given this query string, what are the candidates?" Consult handles the debouncing (default ~200ms via consult-async-input-debounce), the cancellation of stale responses (via while-no-input), and the display refresh.

12.1. Mocking the API

We don't have a real produce service to hit, but we can mock one faithfully enough to demonstrate the pattern. Real search backends (Spotify, GitHub, Algolia, Slack, …) almost always do something fuzzier than literal substring matching, so the mock matches that style. Each character of the query must appear in the candidate's name in order, possibly with gaps in between, case-insensitively. The mock takes a query string, sleeps 😴 to simulate network round-trip, and returns the matches:

(defvar my-mock-api-latency 0.1
  "Simulated API latency in seconds.  Set to 0 to disable the sleep.")

(defvar my-mock-api-call-count 0
  "Counter so we can watch the mock API being hit.")

(defun my-mock-fuzzy-match-p (query name)
  "Return non-nil if NAME flex-matches QUERY (chars in order, case-insensitive)."
  (let ((case-fold-search t)
        (re (mapconcat (lambda (c) (regexp-quote (char-to-string c)))
                       (string-to-list query)
                       ".*")))
    (string-match-p re name)))

(defun my-mock-produce-api (query)
  "Pretend to fetch produce from a remote API matching QUERY.
Sleeps for `my-mock-api-latency' seconds to simulate network round-trip,
then returns the subset of `my-produce' whose names fuzzy-match QUERY."
  (cl-incf my-mock-api-call-count)
  (when (> my-mock-api-latency 0)
    (sleep-for my-mock-api-latency))
  (cl-remove-if-not
   (lambda (cand) (my-mock-fuzzy-match-p query cand))
   my-produce))

A real client would issue an HTTP request, parse JSON, and propertize the response. Ours is a fuzzy regex match over the corpus, gated by sleep-for so latency is observable. The call counter lets us watch the API being hit (or not) as we type.

12.2. A single async source

The completion function takes a query and returns a list of propertized candidates, the same text properties as the synchronous version (category, type, color, season, price all carried directly on each candidate). Only the source has changed. Because my-produce is already a list of propertized strings, the completion function reduces to a category filter on whatever the API returns. We close over cat so each completion category gets its own completion function:

(defun my-async-produce-candidates (cat)
  "Return a completion function that yields CAT-category produce matching QUERY."
  (lambda (query)
    (cl-remove-if-not
     (lambda (cand) (eq (get-text-property 0 'category cand) cat))
     (my-mock-produce-api query))))

The Consult source uses :async rather than :items, wrapping the completion function with consult--dynamic-collection:

(defvar my-consult-history-fruit-async nil)

(defvar my-consult-source-fruit-async
  `(:name     "Fruits (async)"
    :narrow   ?f
    :category fruit
    :async    ,(consult--dynamic-collection
                (my-async-produce-candidates 'fruit)
                :min-input 1)
    :history  my-consult-history-fruit-async)
  "Async Consult source for fruits.")

(defun my-async-produce-picker ()
  "Pick a fruit using an async Consult source."
  (interactive)
  (consult--multi (list my-consult-source-fruit-async)
                  :prompt "Fruit: "))

Run it:

(my-async-produce-picker)

The prompt opens empty; :min-input 1 keeps Consult from firing until you type at least one character. Type b and you will see a moment of latency, and then five fruits whose names contain b (the four berries and banana). Type e more (be), and you will see another fetch, the four berries appear because each one has a b followed by an e somewhere in its name, while banana has no e and drops out.

Empty the prompt and type rapidly: papaya, holding no key for long. Consult's debouncer drops intermediate queries, and in a resource-sparing manner, only the queries you paused on reach the API. When a slow query is mid-flight and your input changes, while-no-input aborts the in-flight computation and restarts on the new input, so stale results never make it to the candidate list. The completion function we wrote is plain synchronous Lisp; all the cancellation, debouncing, and refresh logic are consult--dynamic-collection's problem, not ours.

A small architectural symmetry worth flagging. For Consult's "async command" family of commands (consult-grep, consult-ripgrep, consult-find, and friends) input is additionally split between a backend portion and a local-filter portion via consult-async-split-style. Setting it to 'comma aligns the split character with our orderless-component-separator, so the same , delimits "send this to the server" and "filter the result locally with Orderless." consult--dynamic-collection (the lighter wrapper we used here) skips the split and forwards the whole input to the completion function, but the harmonisation is right there for prompts that want both.

13. The Payoff: Candidates as Shared Currency substrate

Step back and count what each package contributed:

Package	What it gave us	Lines we wrote
Vertico	Display control of candidates	1
Orderless	Multi-component matching, flex, negation, annotation filter dispatch	~3
Marginalia	Four right-aligned metadata columns + annotation-aware matching	~12
Consult	Two sources, unified prompt, per-source narrow keys	~20
Embark	Per-category action keymaps + transformer for citrus refinement + tabular export	~50
Prescient	Frecency sort that promotes recently/frequently picked candidates	2

Roughly 90 lines of VOMPECCC-facing emacs-lisp, and we have a categorised, narrowable, annotated, annotation-matchable, action-bindable, transformer-refined, exportable, frecency-sorted produce picker (that's a mouthful!). There is no UI code anywhere in it! Every line fell into one of two buckets: configuring a VOMPECCC package (add-to-list, setq, defvar-keymap) or declaring our data (the propertized corpus, the annotator, the action bodies, the transformer).

The how of the composition, the question Post 2 gestured at and Post 3 answered for a larger application, is a single convention repeated across the six packages. Each candidate is its name as a string, with its full record's fields stamped on as text properties:

(propertize "apple"
            'category 'fruit       ; our internal routing key (filter, exporter)
            'type     'pome        ; read by our Embark transformer
            'color    "red"        ; annotation column
            'season   "fall"       ; annotation column
            'price    1.29)        ; annotation column

That is the entire integration surface. The exporter and our filter helper read the candidate's category property directly; the annotator reads type, color, season, price; the Embark transformer reads type. Vertico, Orderless, and Prescient do their work on the string itself. Marginalia and Embark dispatch off the prompt's completion-metadata category, which Consult populates from each source's :category key (in turn set to match the data's category property by hand — the candidate-as-currency convention paying its dues by keeping our routing key and Consult's source key in lockstep). When Embark wants to dispatch below the granularity of category, e.g.\ with citrus-only juicing inside the broader fruit category, our transformer reads type off the candidate and refines accordingly. These six packages communicate interoperably through Emacs's completion substrate, with one shared currency: the propertized candidate.

A note on shape. We carry the produce fields as individual text properties because the records are shallow and the property bag stays small. Codebases like spot, where each candidate is a Spotify track or playlist with dozens of nested fields, take a different approach and attach the entire record under a single multi-data property and let consumers reach into the plist for deep fields. Both shapes meet the substrate at the same hook (a propertized candidate whose properties happen to encode a typed record) and the choice between them is purely local to the corpus.

Replace my-produce with GitHub issues, S3 buckets, Slack channels, ten thousand Org headings, a music library, or your ticketing system. The integration surface is unchanged. The corpus reshapes; the annotator reads different fields; the Consult sources partition differently; the Embark keymaps and transformer do different things. Critically, none of the framework code moves. This is the architecture behind spot, consult-gh, consult-notes, consult-omni, and the growing ecosystem of ICR-driven packages that can be assembled from the same substrate without rebuilding any of its layers.

14. What We Didn't Cover further

A handful of VOMPECCC features are worth pointing at, because you will want them eventually and they are all continuations of the same substrate pattern you just saw:

Consult preview. A source's :state key accepts a function that fires on candidate navigation, not just selection. consult-line uses it to scroll the current buffer to the highlighted line; consult-theme applies the theme as you scroll. For a produce picker, :state could pop a "tasting notes" buffer that updates as you move through the list.
More Embark transformers. Phase 6 used a transformer to refine fruit → fruit-citrus based on type. Transformers can refine on any predicate over the candidate's properties — e.g., turn every produce item into produce-expensive if price > 3.00, so you can layer arbitrary fine-grained dispatch on top of the coarse category without inventing new completion categories. There is a huge amount of power there, especially when you understand that Embark's utility expands greatly when you are willing to start typing entities in Emacs, whether they are in the minibuffer or regular buffers.
prescient-persist-mode. Phase 7 enabled vertico-prescient-mode without persistence to keep the demo bounded; in a real configuration, (prescient-persist-mode 1) writes the frecency table to disk so your most-picked candidates stay at the top across Emacs restarts.
Corfu and Cape. In-buffer completion, out of scope for a picker. If you have a programming-language buffer open and you want to complete symbols with the same matching style and annotation columns, Corfu and Cape are how.

Each of these is an incremental add on the same foundational Emacs completion substrate.

15. TLDR tldr

This post built a 30-item produce picker in Emacs by layering six VOMPECCC packages one at a time on top of stock completing-read. Vertico rendered the candidate list vertically with a one-line mode activation; Orderless added multi-component matching via the completion-styles hook plus four custom style dispatchers (~ flex, backtick initialism, ! negation, @ annotation with a @~ flex variant), each accepting its trigger character at either prefix or suffix position; Marginalia added four metadata columns per candidate (type, color, season, price) by reading text properties attached to each candidate string with propertize, and along the way made the annotation text itself searchable through Orderless's @ dispatcher — including the type column, so @berry and @citrus become valid one-component filters; Consult's consult--multi unified the corpus into two categorised sources (fruit, vegetable) under one prompt with per-source narrow keys and per-source :history variables, with each source's :category matching the value the data declares, and consult-history bound to C-r turning those scoped histories into a recall surface for both prior selections and (via M-RET or a minibuffer-exit-hook) prior Orderless queries; Embark attached contextual actions via per-category keymaps (one for fruits, one for vegetables, one specialized for citrus) plus an Embark transformer registered on multi-category that does both jobs in a single pass — because Embark fires the prompt-category transformer exactly once, the multi-category transformer is the one place to put both source-category extraction (delegating to the built-in helper) and our citrus refinement (reading type off the candidate and refining fruit to fruit-citrus) — and an embark-export path that materialises candidates into a sortable tabulated-list-mode buffer; Prescient then hooked Vertico's sort slot to surface recently and frequently picked candidates first, with the rank visibly shifting after a single selection; finally an async variant swapped :items for consult--dynamic-collection over a faithfully-mocked produce API, demonstrating debounced/cancellable remote queries and discussing when the spot-style cache+mutex pattern is load-bearing (multiple sources sharing one endpoint) versus defensive ceremony (single thread, single source). The entire integration surface across the six packages was one propertized candidate carrying its fields as text properties — category as our internal routing key, kept aligned with each Consult source's :category so the framework's own multi-category channel matches; type read by our Embark transformer; the rest for annotation columns — no package calls another's API, none imports another's internals, and swapping my-produce for any other typed corpus would leave every line of the framework configuration unchanged.

Gödel, Escher, Bach, Wallace: the "o's, d's and p's" in Infinite Jest

Charlie Holland — Sat, 25 Apr 2026 22:53:00 GMT

1. About infiniteJest dfw literature

Figure 1: Figure 64 from Douglas Hofstadter's Gödel, Escher, Bach: An Eternal Golden Braid (1979), p. 335.

Content note: This essay necessarily discusses child sexual abuse and incest as implicit elements of Infinite Jest, and includes excerpts from the novel containing explicit language. The argument is speculative and text-based, but engages the subject matter directly. Reader discretion is advised.

Orin Incandenza looks, on first read, like the villain of Infinite Jest. He is cruel to animals and to his own brother; he serially seduces married mothers and abandons them before breakfast; and he retrieves his father's lethal Entertainment cartridge from the corpse's skull, disperses it to his mother's former lovers, and eventually hands the master copy to the terrorists trying to weaponize it. But Infinite Jest constantly dares its readers to subvert first impressions, and character roles blur along with everything else in a novel without a traditional plot arc.

A closer look at Orin's past, and at the last words he utters in the novel, recasts him as something closer to a victim than a villain. His apparent evil, this essay argues, is the recursive (self-feeding) product of childhood trauma, specifically the sexual abuse by his mother, Avril Incandenza. The argument is offered as an explanation, not exoneration: the cruelty Orin inflicts on others remains real, and the people he harms (Mario, his Subjects, Joelle, the recipients of the Entertainment) are not made less harmed by the fact that Orin himself was harmed first.

This essay's novel contribution to the critical literature is a typographic close-reading of one moment in Orin's morning chapter, where Wallace describes a peculiar feature of a Subject's handwritten note: "every single circle – o's, d's, p's, the #s 6 and 8 – is darkened in" (pg. 43). The argument is that the three darkened letters (O, D, P) spell, in Orin's perception, the name Oedipus. This may seem like a reach, but the encoding becomes the smoking gun in the case against Avril Incandenza when you appreciate Wallace's intellectual debt to Douglas Hofstadter and Gödel, Escher, Bach – a debt the essay documents in detail below. GEB is the foundational text in which typographic position carries semantic weight, and Wallace, per his biographer, "actually shoved this book excitedly at people in the eighties." The figure at the top of this essay is GEB's own demonstration of the move: the outer words HOLISM and IONISM are formed of twelve letters whose constituent shapes spell REDUCTIONISM, a word hidden across the morphology of two others. And the figure deepens once one sees the dialogue it sits inside. In GEB's "…Ant Fugue," Hofstadter has the Crab, the Anteater, Achilles, and the Tortoise each look at the same picture and each see a different word:

Crab: Well, what have we here? Oh, I see: it's 'HOLISMIONISM,' written in large letters that first shrink and then grow back to their original size.

Anteater: Well, what have we here? Oh, I see: it's 'REDUCTHOLISM,' written in small letters that first grow and then shrink back to their original size.

Achilles, in turn, sees HOLISM written twice; the Tortoise sees REDUCTIONISM written once. The picture is the same; the perception supplies the word. That is the o/d/p situation in miniature. The Subject's note is the picture; Orin is one of the characters; "Oedipus" is what he sees that nobody else can. Without that key, the o/d/p observation reads as coincidence, but with it, the encoding reads as Wallace marking the page with the signature of an event he did not put on it directly.

2. Orin the Apparent Antagonist infiniteJest orin

Orin is presented as a deplorable character throughout the novel. His introduction sees him being cruel to cockroaches, torturing them by suffocating them under glass tumblers (pg. 45). This is not the only time Orin is seen being remorselessly cruel to animals. Indeed, in his accident with the family dog, S. Johnson, he was unapologetic (n. 269 pg. 1050).

His cruelty to animals is reflected in a general lack of human compassion. Mario, Orin's physically disabled younger brother, often fell victim to Orin's harsh verbal cruelty (pg. 589). He chooses to liaise sexually with only married mothers, an interaction he knows harms not only the women, whom he coldly calls "Subjects", but also their children, who (especially in literature) tend to epitomize innocence (n. 110 pg. 1014-1015).

Even within the realm of this conscious act of familial corruption, Orin maintains cold detachment towards his Subjects, actively hoping they are gone by the time he awakens (pg. 46). Even before this documented mission in pursuing Subjects (see "Speedy Seduction Strategy Number [X]" n. 110 pg. 1007), Orin displayed vanity in his selection of a woman who was of "brainlocking beauty" (pg. 295). Confirming a vain motivation for this relationship, Orin cruelly relinquished Joelle around the time of her disfigurement, the precise circumstances of which the novel leaves deliberately ambiguous (pg. 795).

Finally, in perhaps the epitome of his list of crimes, Orin was the one who retrieved the lethal entertainment master copy from his father's skull, the motivation for this desecration being personal revenge (see Aaron Swartz's What Happened in Infinite Jest?). In perhaps a worse offense, he traded the Entertainment to the AFR for his life after a considerably mild technical interview (pg. 971-972).

Taken together, this evidence would make Orin the villain of Infinite Jest – cruel, vain, vengeful, reckless, and implicated in the book's central catastrophe. But read against his past, and against the specific moment near the novel's end when he breaks, these traits change shape. Two events in his life perform the shift: an abuse buried in Orin's childhood, and a technical interview by the AFR in which that past finally surfaces.

3. The First Event: Avril's Abuse of Orin infiniteJest orin avril

The first of these events is Avril Incandenza's sexual abuse of Orin. The actual occurrence of this event is implicit, and requires significant analysis to deduce. Given its fringe nature, this accusation against Avril comes with a large burden of proof. Plenty of evidence supports it.

The implication of incest between Avril and Orin first arises when Himself and Joelle's potential relationship is being discussed. Himself realizes that Avril was unbothered by the rumored affair between him and Joelle for a specific reason: she was having one of her own. The evidence which led Jim to believe this was the presence of a name written in his car window's steam (n. 80 pg. 999). Himself goes no further with this evidence than to conclude an affair was taking place between Avril and some unnamed partner. The natural curiosity to the reader, then, is the identity of the person in the car with Avril.

The text implies that the partner is Orin, and that Orin has perhaps suppressed the memory due to its traumatic nature. It comes to light (pg. 899) that "Orin alleged in YTMP that when he took the Moms's car in the morning, he sometimes observed the smeared prints of nude human feet on the inside of the windshield." At first glance, it would seem as though Orin is a third party in a potential affair, as he is 'observ[ing]' evidence of its occurrence. But his own behavior when pressed about the affair complicates this reading: n. 80 notes that Orin "would not say who or whether he knew who" was in the Volvo with Avril (n. 80 pg. 999), a conspicuous evasion for a purportedly disinterested observer. Alternative explanations exist – Orin might be protecting the family from a less lurid but still embarrassing revelation – but few of them account for the specific intensity of his avoidance. And Marlon Bain, Orin's closest friend, characterizes him to Hugh Steeply this way: "It is not that Orin Incandenza is a liar, but that I think he has come to regard the truth as constructed instead of reported" (n. 269 pg. 1048).

One might reasonably ask why the Volvo's partner must be Orin rather than John Wayne, Avril's documented student lover, and the subject of established scholarship on her sexual irregularity. The text pushes the answer toward Orin by the specific fact of how Jim learned of the affair: the Volvo anecdote is Orin's own. Orin is the source of the story about the name in the steam; and Orin, uniquely, "would not say who or whether he knew who" was in the car. Orin reporting on his mother's affair with a student teammate has no particular reason to withhold the name, while Orin reporting on his own abuse by his mother has every reason. The Wayne affair is the well-documented surface – the visible scene of Avril with Wayne. The Volvo is a different scene underneath it, and the evidence requires Orin to be the boy in the car with her.

Indeed, if one cross-references the imagery (fogged windows and footprints) used in describing the affair with the imagery used to describe Orin elsewhere, the text invites the identification of Orin as Avril's victim. The evidence is circumstantial, but it accumulates in a specific direction. The identification is a reading the text invites, not a conclusion it hands us.

What follows proceeds on the working hypothesis that Orin was in the Volvo and asks what else in the novel lines up with that reading.

4. Steam and Footprints infiniteJest orin imagery

First, in Orin's introduction, steam is an almost gratuitous motif. The general description of dampness and sweat coupled with repeated references to glass windows echoes the image of the fogged car window. His coffee's steam thinning, a sweat-soaked mustache, the chugging of a Jacuzzi, shimmering heat, mirages, a perfume spritzer, etc… all contribute to the general atmosphere of humidity seen in the car (pg. 43). Orin's technique of killing cockroaches involves inverted glass tumblers, which "gradually steam up with roach-dioxide. The whole thing makes Orin sick" (pg. 45). The image of steam is enhanced by the description of extremely hot water which immediately follows (pg. 45). The section closes with a poignant image: Orin shaving in the shower "wreathed in steam, by feel, shaving upward, with south-to-north strokes, as he was taught" (pg. 49). The closing image also nods implicitly at Himself, the teacher of against-grain shaving. The atmosphere of steam likely brings Orin back to that same atmosphere in the car with Avril, and conjures a misplaced sense of guilt towards his father.

Second, when Orin is the subject in a technical interview, he is placed under a sort of glass tumbler, like the cockroaches he kills. The glass tumbler itself echoes the car: "steam on the sides," and, in possibly this essay's most robust connection to the car scene, smeared footprints. "The glass was too thick to break or to kick his way out, and it felt like he might have possibly broken the leg's foot already trying… There were now smeared footprints on the glass" (pg. 972). These footprints on the glass walls of the tumbler parallel strikingly, in both content and diction, with the footprints Orin "alleged" earlier in the novel.

A skeptical reader will note that steam, glass, and enclosure are motifs Infinite Jest uses broadly. They saturate the Phoenix condo, fill Ennet House, and recur across the Quebec arc. The claim here is not that the imagery is unique to Orin but that its specific conjunction in his introduction, with fog plus footprints plus glass plus the mother-as-Jacuzzi-chugger and father-as-teacher-of-shaving pairing, recapitulates the car scene with a density that reads as patterning rather than accident.

5. Other Evidence for the Affair infiniteJest orin avril

Other evidence supports the incest hypothesis. Pemulis walks in on John Wayne and Avril mid-encounter in Charles Tavis's office:

John Wayne wore a football helmet and light shoulderpads and a Russell athletic supporter and socks and shoes and nothing else. He was down in the classic three-point stance of U.S. football. Inc's incredibly tall and well-preserved mother Dr. Avril Incandenza wore a little green-and-white cheerleader's outfit and had one of deLint's big brass whistles hanging around her neck (pg. 553).

The scene demonstrates that Avril has engaged in sexual contact with a teenage student at the academy she co-founded. It also, once the staging is on the page, reads as a fantasy re-enactment in which Wayne plays Orin (a football player) and Avril plays Joelle (Orin's former cheerleader girlfriend). The football helmet, the brass whistle, the green-and-white outfit, the paper pompoms on the seminar table are too specific a constellation to be coincidence.

The incestuous connection is encouraged by the narrative. Immediately before the scene Pemulis walks in on, Dolores Rusk is in her office down the hall delivering an extended psychoanalytic monologue to Ortho Stice that turns out, for several pages, to be a gloss on the Oedipus complex: "GI Joe typically being cathected as an image of the potent but antagonistic father… the Oedipal phase's desire to control the bowels in order to impress or quote 'win' the mother, of whom the Barbie might be seen as the most obviously reductive and phallocentric reduction of the mother to an archetype of sexual function and availability" (pg. 550). Wallace has placed his most explicit Oedipal exegesis a few feet from the room where Avril and Wayne are role-playing it.

Wayne's exact age during the YDAU narrative-present is one of the novel's deliberate ambiguities. The text places him at 17 or just-18 – he was "the top-ranked junior male in Canada at sixteen" the year before, and the recruitment plan has him going pro "at nineteen" (pg. 259) – and the novel never pins the date down. That ambiguity is itself part of Infinite Jest's broader practice: the text leaves Joelle's disfigurement deliberately ambiguous, leaves the Volvo partner unnamed, leaves Wayne's age on the cusp. If Wayne is 17 the Avril-Wayne affair is statutory rape; if 18, it is institutional grooming by a co-founder of the academy he is enrolled at. Both are harsh indictments of Avril's sexual irregularity. The novel withholds the difference, and the withholding does literary work: what it leaves visible is that Wayne is a teenager under Avril's authority, sexually entangled with her, his relation to consent unresolved. On this reading, Wayne in the Wayne-Avril incident is not the documented adult counterpart to a hidden Orin abuse, but instead is a parallel case. Wayne and Orin are two instances of the same predation, treated by the novel with the same studied ambiguity that keeps either from being unmistakably named.

Avril's note to Orin offers another piece of evidence, which contains obviously sexual diction: "Every floral unit on the grounds has its pistil aprick and petals atremble in a truly shameless fashion, for the bees are about." She closes the letter with the phrase "Proud, as ever, to know you." (n. 110 pg. 1006). A militant grammarian, Avril chooses her phrasing with care, and as a result, the second (sexual) entendre is difficult to read as accidental. Marlon Bain, in a correspondence with Hugh Steeply, revealed that Avril, towards her children, was "the most consummate mind-fucker" (n. 269 pg. 1048). The phrase is Bain's characterization of Avril's psychological dominion over her children, which is not, in itself, evidence of sexual abuse, but it does corroborate the broader pattern of maternal enmeshment on which this reading rests.

Finally, after Himself sees the name written in the window, presumably 'Orin' or simply 'O', he immediately films the scene in the Entertainment which depicts a mother emphatically apologizing to her son (n. 80 pg. 999). Orin's habit of leaving signature marks on partners makes him a more natural candidate for the name-writer than a hypothetical third party. One Subject is characterized in passing as "Not real bright – she thought the figure he'd trace without thinking on her bare flank after sex was the numeral 8, to give you an idea" (n. 110 pg. 1015). The trait characterological: Orin signs his work.

6. O's, D's, and P's: The Oedipus Encoding infiniteJest orin oedipus

The most direct textual figure for what happened to Orin appears in a description of his nightmares. In a paragraph which opens with the phrase "As a nod to Orin's own unhappy youth…", a dream is described in which "…Mrs. Avril M. T. Incandenza's, the Moms's disconnected head attached face-to-face to his own fine head, strapped tight to his face somehow by a wrap-around system of VS HiPro top-shelf lamb-gut string from his Academy racquet's own face. So that no matter how frantically Orin tries to move his head or shake it side to side or twist up his face or roll his eyes he's still staring at, into, and somehow through his mother's face. As if the Moms's head was some sort of overtight helmet Orin can't wrestle his way out of" (pg. 46-47). The face-to-face contact is unmistakably sexual in charge.

A few pages earlier in the same chapter, the narration had turned to the Subject's note, on which Orin believed "The only interesting thing about the script, but also depressing, is that every single circle – o's, d's, p's, the #s 6 and 8 – is darkened in, while the i's are dotted not with circles but with tiny little Valentine hearts, which are not darkened in" (pg. 43). The note, in the particular circles Orin fixates on, suggests the name "Oedipus" not as something the Subject has encoded, but as something Orin is projecting onto a neutral graphic. The morphological hook is real: O, D, and P are the circle-bearing letters of the Oedipal name, and they are precisely the letter-circles Orin's eye lands on. The darkening also includes the numerals 6 and 8, which belong to no word at all, meaning the pattern cannot be the Subject's coded spelling. It is Orin's pattern-matching, his repressed memory surfacing through a visual trigger.

A more parsimonious reading is available: the Subject simply darkens all closed glyphs as a handwriting tic, with no projection required. The projective reading depends on those numerals doing semantic work no tic explains, an argument the essay develops below for the 8 in particular. The Valentine hearts dotting the i's (not darkened in) compound the creepiness of the near-spelling: the hearts occupy the "i" positions of the word, so that a post-coital note from a maternal-figure Subject comes to Orin as "Oedipus" rendered with a heart over the self-referential "I" character. The geometry is more precise than that. "Oedipus" has seven letters, and the single i sits at position four, the exact center of the word. The valentine heart that replaces the i's dot lands at the very middle of the name Orin is reading. This is GEB's foundational move: typographic position doing semantic work, the way Gödel-numbering makes a symbol's place in a string inseparable from its meaning. The sign of romance sits at the center of the Oedipal word, just as Orin's trauma sits at the center of his romantic engagements. This is "depressing" because Orin understands, at whatever level of awareness, that he and the Greek mythological figure Oedipus have the same secret.

A reader might reasonably object at this point that the essay is forcing a physical reading onto a pathology the novel establishes as emotional. Infinite Jest characterizes Avril as controlling, enmeshing, "consummately" manipulative. Every behavior the essay has cited (the smothering, the helmet dream, the Feeding My Man passage, the bees letter) could be read as severe psychological enmeshment without any physical component. The objection is legitimate. The answer here is not that physical abuse is proven but that it is the reading which accounts for the specific shape of the evidence: the fogged-window / nude-feet parallel is a physical detail belonging to a physical event; the "Do it to her!" collapse at the technical interview is a breaking-under-torture response that protects a specific embodied memory rather than a generalized emotional wound; and Orin's repeated evasion about who was in the Volvo points at a particular person rather than an abstract pattern of maternal damage. Emotional enmeshment is a necessary condition for this reading, not a competing one. The essay argues that the enmeshment has a physical dimension the novel suggests rather than confirms.

7. Gödel, Escher, Bach, Wallace infiniteJest hofstadter

The o/d/p reading looks, on its own, like a particular kind of writerly trick: a word hidden in the morphology of other letters, a signified laundered through the shape of the signifier. That trick is not idiosyncratic to Wallace. It belongs to a specific intellectual inheritance, one Wallace took up from Douglas Hofstadter's 1979 Gödel, Escher, Bach: An Eternal Golden Braid (GEB), a book he read with enough zeal that, per his biographer D. T. Max, he "actually shoved this book excitedly at people in the eighties."

Wallace was on record about GEB in his own voice. In a 2003 interview with Dave Eggers for The Believer, he called it "a great book, but it's hard," and added that "I personally don't think Hofstadter does enough teaching of the basic concepts to make his riffs and dialogues come alive for people who didn't have a lot of basic logic and recursion-theory in college" (qtd. in Burn). He was treating GEB as a peer text – engaged enough with its argument to fault its pedagogy, fluent enough in its idiom to use "recursion-theory" as a term of art. The same year, he published Everything and More: A Compact History of Infinity, his pop-math book on Cantor's set theory; and Atlas Books had originally commissioned Wallace to write the volume on Gödel and the Incompleteness Theorems before the topic was reassigned. The publisher, in other words, saw Wallace as the natural author to popularize Gödel, which was exactly the territory GEB had defined a generation earlier.

The provenance stretches across two decades of Wallace's career. D. T. Max's authorized biography records that Wallace borrowed his father's copy of GEB; that Mark Costello, Wallace's Amherst roommate, remembered Wallace while composing Infinite Jest "going on about the 'braid' or 'fugue' shape – disparate elements making a whole"; and that Max himself treats GEB as "a predecessor to Infinite Jest, at least structurally" (Max 312 n. 6). In his 1993 interview with Larry McCaffery, Wallace was already using "recursive mechanism" as his master-term for evaluating self-referential fiction, three years before Infinite Jest's publication (McCaffery, Review of Contemporary Fiction 13.2). Three years later, in a 1996 conversation with Michael Silverblatt on KCRW's Bookworm, he confirmed the Sierpinski gasket (a self-similar fractal) as Infinite Jest's structural model. By 2003, his vocabulary had hardened: in a Boston Globe interview with Caleb Crain, he called Gödel "the devil, for math," described "Cantor's paradox" as the moment that "starts the wheel of self-reference," and tied the character of Pemulis to Gödelian incompleteness as one of the novel's "Antichrists" (Crain 2003). And in his 2004 conversation with Steve Paulson, he looked back on the philosophical terrain of his graduate years as "full of recursion, and involution, and things bending back on themselves, and various incarnations of Gödel's proof, and I think some of that kind of affected me at a spinal level" (qtd. in Burn 133).

The structural connection has support beyond the biographical record. N. Katherine Hayles, in "The Illusion of Autonomy and the Fact of Recursivity" (New Literary History 30.3, 1999), reads Infinite Jest as governed by recursive feedback loops in which entertainment systems entrap characters who cannot achieve autonomy precisely because they are inside the loop. Roberto Natalini's chapter "David Foster Wallace and the Mathematics of Infinity" in A Companion to David Foster Wallace Studies (eds. Boswell and Burn, Palgrave 2013) argues that Wallace drew on Cantorian infinity and Gödelian self-reference as structural and thematic resources throughout his career. Ryan David Mullins, in "Theories of Everything and More: Infinity Is Not the End" (Gesturing Toward Reality, eds. Bolger and Korb, Bloomsbury 2014), develops a "bad infinity / good infinity" reading explicitly indebted to Hofstadter's distinction between vicious regress and productive recursion. Most directly: Ugo Panzani, writing in Lettera Matematica International (Springer 2015), observes that the recursive iteration in Infinite Jest "proceeds to the level of typography", which is the precise level at which the o/d/p reading operates. Cory M. Hudson's 2015 MTSU thesis Gödel, Hofstadter, Wallace: The Gödelian Metalogical Narrative Structure of David Foster Wallace's Infinite Jest then develops the structural isomorphism in detail (Hudson 56-86). The braid, the fugue, and the strange loop are GEB's operative figures, and they become Wallace's formal vocabulary.

But GEB is not only a book about structural recursion; it is, persistently, a book about typography. Hofstadter's dialogues between Achilles and the Tortoise are riddled with letters encoding other letters, words hidden inside numerals, ambigrams, and Gödel-numbering (the technique by which any written statement can be translated into a single integer, so that a formal system can refer to itself through a different surface grammar). The Subject's note in Infinite Jest works in exactly that register. Orin does not read "Oedipus" on the page; he projects it, out of the morphology of circle-letters the Subject wrote for other reasons entirely. That is a Hofstadterian move: the move of finding a meaningful string inside an indifferent one, the move of self-reference laundered through surface innocuousness. When Orin registers the note as "depressing," he is doing the reader's work for us: he is experiencing, as a character, the kind of strange loop GEB taught Wallace to construct.

Figure 2: Hofstadter's "trip-let" construction from Gödel, Escher, Bach (1979) – a single wooden form whose shadows spell G, E, and B when lit from three orthogonal directions. The wood itself is neutral; the letters live in the projection. Orin reads "Oedipus" onto the Subject's circle-letters by the same light: the morphology on the page is indifferent, and the meaning is supplied by the angle from which Orin is looking.

What the record does not yield is direct evidence that Wallace and Hofstadter ever met or corresponded; Hofstadter, for his part, has never publicly commented on Wallace's work. Wallace's father, James Donald Wallace, was a virtue ethicist (Cornell PhD under Norman Malcolm – a prominent Wittgenstein pupil), not a formal-systems philosopher; the household intellectual lineage ran Wittgenstein-via-Malcolm rather than through Hofstadter directly. GEB reached Wallace as a pop-sci stimulus, sitting beside but not displacing the formal-philosophy training he had through his Amherst thesis on modal logic. Nor has any prior scholarship identified the o/d/p encoding specifically. The argument here is original, but grounded in well-prepared soil.

8. Letters Inside Letters infiniteJest hofstadter typography

None of this would matter if the o/d/p encoding were the only such moment in Infinite Jest. It isn't. Wallace is a typographic novelist in the strictest sense: across his thousand pages he encodes meaning in the morphology of letters, in acronyms that spell hidden words, in anagrammed proper names, in phonetic decomposition, and in self-reflexive footnote architecture. The Subject's note is one instance in a consistent practice.

Consider James Incandenza's filmography, listed in n. 24. Wallace gives one of the films the title Möbiu$ Strips, substituting a dollar sign for the s, a single glyph that visually resembles the letter while importing a second register (commerce, pornography) into a topological loop. The technique is the same as the one on the Subject's note: a character whose shape is doing typographic work beyond the level of legibility.
Or consider "O.N.A.N." – the Organization of North American Nations, the supranational body whose acronym, deployed relentlessly throughout the novel, spells "Onanism" (the biblical figure for spilled seed and the term for self-gratification). The reader is being asked to assemble a hidden word from morphological units, which is the o/d/p mechanism applied at the scale of a nation-name.
Or "Pemulis," the drug-dealing E.T.A. student whose name is a perfect anagram of IMPULSE – letters rearranged to encode the character's pathology inside his own name.
Or a credited filmography character named "Hugh G. Rection" – a phonetic decomposition that hides "huge erection" inside an innocuous-looking proper name.

Each of these moves is the o/d/p move, played in a different register.

The practice scales from individual words to the architecture of the text. Infinite Jest, the novel – contains a film called Infinite Jest, the lethal Entertainment whose existence drives the plot (listed in James Incandenza's filmography as versions I-VI, n. 24); the book is named after the artifact at the center of its own world, a structural strange loop in Hofstadter's exact sense.

Pemulis's answering-machine message extends the move into prose: "This is Mike Pemulis's answering machine's answering machine; Mike Pemulis's answering machine regrets being unavailable to take a first-order message… if you'll leave a second-order message…". This is GEB's technical vocabulary deployed inside a character's voicemail. An internal footnote in n. 304 reads "Q.v. Note 304 sub", which is a footnote pointing back at its own note, a bibliographic strange loop. Another Incandenza film is titled The Machine in the Ghost, inverting the Cartesian/Rylean "ghost in the machine"; the narration later quotes its own inversion verbatim ("A machine in the ghost, to quote a phrase"), so that the filmography and the body text cite each other across formal levels.

At the level of proper names, the practice continues. James O. Incandenza's initials spell J.O.I. (joy), the very feeling his lethal Entertainment was intended to deliver and instead poisons. "Orin" is an anagram of "NOIR," and the chapters Orin appears in are the novel's most paranoid, surveillance-soaked, genre-marked sections. Other instances are scattered throughout: Hugh Steeply's drag persona "Helen Steeply" encodes the "Paris and Helen" mythology the Marathe-Steeply dialogues explicitly invoke; Madame Psychosis's call sign "WYYY-109" is named for the fact that 109 is "the largest whole prime on the FM band" (the triple Y also reading as a question – why? why? why?); James Incandenza's production company "Latrodectus Mactans Productions" takes its name from the Latin for the black widow spider, naming his marriage's fate. In each case, Infinite Jest is doing what the Subject's note does: hiding a word inside a word, or a word inside a structure, asking the reader to recognize the embedded meaning by stepping back from the surface text. The Oedipal reading is one instance of a continuous authorial practice.

9. Orin in Translation infiniteJest hofstadter typography

Orin's name itself does similar work, at the level of translation. The strongest reading is Hebrew: Oren (אֹרֶן) means "pine tree," and appears in Isaiah 44:14 in one of the prophet's central attacks on idolatry. The passage describes a man who plants a tree, waters it, and from the same tree carves both fuel for his fire and an idol he proceeds to worship. The prophet's argument is that idolatry consists in worshipping what one has oneself constructed. That is the precise architecture of Orin's life. The football helmet, the amniotic stadium and the Subject-protocol are all built from his own trauma and then submitted to as if external. The Hebrew root names the pattern.

A second derivation, the Irish Odhrán, may supplement the reading. The name belonged to a 6th-century Irish saint, one of Columba's companions at Iona; an apocryphal but persistent strand of his hagiography holds that he was buried alive at the abbey's foundation to consecrate the ground. Whether Wallace had this particular legend in mind is unknowable, but the loose resonance is hard to miss. The Irish derivation, even taken at the level of legend, places a buried boy at the foundation of an institution, which is exactly what the essay has been arguing the Incandenza family is: an institution erected over the buried fact of what was done to its eldest son.

GEB devotes substantial attention to translation across languages, formal systems, and levels of representation. Hofstadter's recurring argument is that meaning lives at the level where these translations preserve structure, not at the level of the surface symbols. The etymology of "Orin" is exactly that kind of cross-system encoding: a name innocuous in English unfolds, under translation, into a thematic key, which visible to the reader who knows the language, and hidden to the one who does not. Wallace, characteristically, has placed the meaning where it can be missed.

10. Eight, Sideways infiniteJest hofstadter typography

There is one more typographic observation worth pausing on, and it returns the essay to the same passage we began with. The Subject's note has its darkened circles – "o's, d's, p's, the #s 6 and 8" – and the essay has so far read those as the morphology of "Oedipus." But the 8 is doing additional work the other glyphs are not. Rotated ninety degrees, "8" becomes "∞." It is the only glyph in the darkened set that is also an ambigram of the symbol for infinity.

The Subject's note, in other words, is doing the same kind of encoding work twice. The letter-circles spell Oedipus. The numerical circle, rotated, spells infinity. Together, the note encodes the Oedipal trauma in its recursive form: not only Orin's mythological status, but the strange-loop structure that keeps him traversing it. GEB is the founding text on strange loops (closed curves that cross themselves, traversed forever, never escaping). ∞ is the strange loop drawn and 8 is the strange loop hidden inside an innocuous numeral.

The same figure shows up on Orin's body. His specific signature mark, "the figure he'd trace without thinking on her bare flank after sex was the numeral 8" (n. 110 pg. 1015), is, in this light, the symbol for infinity inscribed on a Subject's body. Each new Subject receives the shape of recursion. Orin's pursuit of married mothers is, the essay has argued, a recursive trauma, a return to the original maternal scene that can never quite arrive there. The 8 is what that pursuit looks like, drawn idly, on skin, after sex. Wallace's own Everything and More: A Compact History of Infinity (2003) is his sustained engagement with Cantor and Gödel, the mathematics of recursive structures ascending into hierarchies of infinity without ever closing. When Orin traces 8 on a Subject's flank, he is drawing a structure Wallace had spent two years writing a book about. Wallace signs the page, Orin signs the body, and the signature in both cases is the same: the strange-loop figure traced on a stand-in for the original.

11. Recursive Anxiety and Redirected Hostility infiniteJest orin psychopathology

The event of Orin's sexual abuse recasts his villainy in an intuitive way: Orin is a victim of a traumatic childhood experience, and his current and past actions are products of the damage that experience instilled. The humid atmosphere of his introduction instills dread.

For Orin Incandenza, #71, morning is the soul's night. The day's worst time, psychically. He cranks the condo's AC way down at night and still most mornings wakes up soaked, fetally curled, entombed in that kind of psychic darkness where you're dreading whatever you think of (pg. 42).

"Dread" and "entombment" here describe Orin's psychological reaction to trauma. The fact that he "dread[s] whatever [he] think[s] of" speaks to his reasons for repressing, on some level, the entire car incident (this repression is seen when Orin is "alleg[ing]" the "smeared prints of nude human feet" distantly, in the 3rd person). The damage from his childhood abuse manifests as anxiety about being entrapped, under control, suffocated (it is no accident that Avril herself defensively self-describes as "un-smothering"). This is perhaps why Orin gravitates towards football, a sport in which he can escape "… as he'd never escaped himself on the court…". Football gives Orin "… a sense of a presence in the sky…" (pg. 295-296). Football, "the sound of the womb, the roar gathering, tidal, amniotic…", offers him a rebirth (pg. 295).

The anxiety dominates him. The morning passages give the imagery directly: "It's the mornings after the spider-and-heights dreams that are the most painful, that it takes sometimes three coffees and two showers and sometimes a run to loosen the grip on his soul's throat" (pg. 46). The cockroaches in the humid shower symbolize his rekindled entrapment anxiety. To subvert these feelings, he attempts to nullify them by exerting some cruel, god-like, torturous control over them.

What makes the anxiety recursive – in the precise Hofstadterian sense Wallace was already using by 1993, when he called metafiction a "recursive mechanism" that "spirals in on itself" (McCaffery, Review of Contemporary Fiction 13.2) – is that every defense Orin builds against it reproduces the conditions of the original trauma. The avoidance-behavior is itself the trigger. The cockroach scene traces the loop step by step. He tries to suppress the cockroaches (the memory) by running the shower water hot. But, alas, hot water generates steam, and steam is the texture of the fogged-up car window where the abuse occurred. He tries to trap the cockroaches under glass tumblers, but the trapped insects produce "roach-dioxide" that fogs the tumbler walls. This is the same fogged-glass signature. Every escape route returns him to the trauma. "The whole thing makes Orin sick" (pg. 45) is not surprise; it is the recognition that the trap is closed.

The same loop runs through Orin's fear of heights. Every elevation he achieves; whether in career, public visibility, or his punter's contract with Arizona; raises the height from which he will eventually tumble into the morning dread. Climbing is escape, but with Shakespearian tragicness, the higher he climbs, the more terrifying is his descent.

These worst mornings with cold floors and hot windows and merciless light – the soul's certainty that the day will have to be not traversed, but sort of climbed, vertically, and then that going to sleep at the end of it will be like falling, again, off something tall and sheer (pg. 46).

Orin also fights his anxiety more directly, whether consciously or not. His abuse of Mario is probably an arrow thrown obliquely towards his abuser, Avril, given how close Mario and Avril are; and then the S. Johnson incident was probably driven by that same logic, given how close Avril was to the dog. Presumably, the reason Orin resented Avril for forgiving the S. Johnson incident (pg. 1014) was that he had hoped it would crush her. Here, Avril reveals how deftly she 'fucks the mind'.

Orin's destructive relationship with the married-mother Subjects is another example of his attempt to control what is controlling him. That is, he targets maternal figures in an attempt to silence the control his own mother exerted over him. His callousness towards them (his desire that they be gone by the morning) is issued because they remind him directly of Avril: they ask "what exactly is the story with the foggy inverted tumblers on the bathroom floor, commenting on his night-sweats… the ones who have this thing about they call it Feeding My Man…" (pg. 46). This reminiscence of Avril is likely the reason Orin deludedly sees things like "Oedipus" ("o's, d's, p's") encoded into his Subject's note.

Perhaps Orin's biggest crime was the retrieval and dispersal of the Entertainment to his mother's previous sexual partners and his ensuing grant of the master copy to the AFR. Orin didn't do this to avenge his father's suicide; Jim and Avril "hadn't been intimate with each other, i.e. conjugally, for quite some time" (n. 80 pg. 999), so an affair wouldn't have driven Jim to kill himself. Rather, his targeting of his mother's previous sexual partners was probably an attempt to seek retribution for his own imagined complicity in what his mother had done to him. This reading departs from Swartz's, which posits the father as the target of Orin's revenge, but it better accounts for the specificity of the recipients: not Avril's enemies or Himself's rivals generally, but the men Avril slept with. Although this was reckless – catastrophically, if not apocalyptically, reckless, given the Entertainment's nuclear properties – it is psychologically intelligible from someone plagued by an intense and recursive anxiety whose source (the abuse by his mother) is the very thing at which the recklessness was aimed. Intelligibility is not absolution; the people the Entertainment was meant to reach were endangered regardless of why.

12. The Helmet infiniteJest orin psychopathology

There is a puzzle in Orin's psyche the essay should pause on. Orin's central trauma (the one his nightmares stage and his syntax disowns) is the experience of being enclosed by his mother. The helmet dream is the explicit version: "Mrs. Avril M. T. Incandenza's, the Moms's disconnected head attached face-to-face to his own fine head, strapped tight to his face… As if the Moms's head was some sort of overtight helmet Orin can't wrestle his way out of" (pg. 46-47). And yet Orin, every game, voluntarily straps on a football helmet. The trauma's exact structure, a tight enclosure of his own head, is the structure of his profession.

The puzzle resolves itself when you consider who is doing the strapping. The Avril-helmet of the dream is something done to him: he cannot wrestle his way out, the verb attached is passive, and the leather string around his face is the work of an external agent. The football helmet is the opposite kind of object: he puts it on, by his own hand, before each game, and removes it when he chooses. Counterphobia, in the vocabulary Dolores Rusk uses with Ortho Stice, is the defense by which one reproduces the structure of the feared thing under conditions of personal control, and then repeating the trauma to master it. Orin's helmet is counterphobic in exactly that sense because he has built a career out of the gesture of voluntarily closing the maternal enclosure around his head, and unbuckling it when he is done.

The football helmet sits, moreover, inside a larger chosen womb. The essay has already cited DFW's word for the stadium: "the sound of the womb, the roar gathering, tidal, amniotic" (pg. 295). Football is a controlled re-entry into the maternal space. Helmet, stadium, crowd, and team are nested enclosures, each of which is chosen, and each of which is protective. Orin has constructed a counter-mother out of professional infrastructure. The original mother smothered him; the new one is amniotic.

Then comes the technical interview. The AFR's glass tumbler is the same shape as the helmet, a tight enclosure of Orin's head and body. But it is unchosen, he cannot remove it, and he can break neither it nor the "leg's foot" trying. What is devastating about the Room 101 (read below) scene is not only that Orin breaks; it is that his entire defensive architecture has been reverse-engineered. The novel has been showing us this counterphobic apparatus all along (the helmet, the stadium, the controlled descent into womb-shape) and the AFR's interrogation chamber is the moment when the apparatus is turned back on him. The helmet that protected him for years is welded shut, and he is inside it, terrified to the point that he is willing to get relief by any means necessary, even if that means the apocalypse.

13. The Second Event: Room 101 infiniteJest orin orwell

Relinquishing the master copy to the AFR, which the reader is led to believe could result in the deaths of millions of innocent people, after a seemingly mild technical interview (see Luria P-—'s eye rolling, pg. 972), seems weak of Orin. However, this is the second event which shifts the perspective of Orin away from him as a villain. A close look at Orin's final words in the novel, "Do it to her! Do it to her!", reveals an echo of what Winston shouts in George Orwell's Nineteen Eighty-Four whilst being tortured in Room 101, the infamous torture chamber from which no one emerges unbroken. This allusion suggests that Orin's interview was not mild at all but calculated; it tapped into his most visceral fears and anxieties.

Being entombed and suffocated in steamed glass brought back vivid memories of his abuse, and the flood of cockroaches signifies a total inundation of his mind with abuse-related anxiety. Orin, like the people in Room 101, is helpless against the technical interviewer's technique. The text marks the moment his repressed memory breaks through: "When Orin had tried to kick his way out was when he'd recognized that the Subject was looking at his eyes rather than into them as previously. There were now smeared footprints on the glass" (pg. 972). Orin realizes he has lost control of the Subject and that he has become the Subject. The footprints on the glass follow immediately, marking the moment his childhood abuse surges back into conscious awareness. Under such duress, Orin's giving in is psychologically intelligible – though intelligibility is not the same as forgiveness.

Like Winston's betrayal of Julia in Nineteen Eighty-Four, his (presumed) betrayal of Joelle is the response of an ordinary person to extraordinary torture, not the act of a super-human evil. That is an explanation, not an exoneration. Joelle is endangered regardless of why he named her. The parallel is not airtight because IJ never specifies who Orin names under torture, or who "her" refers to, but Nineteen Eighty-Four's echo resonant: the man who spent the novel fleeing his mother's abuse breaks, at last, into betraying the one woman who had loved him outside that shadow.

14. Subject, Not Object infiniteJest orin language

DFW was hyper-aware of the difference a word makes. He was trained in analytic philosophy, wrote an undergraduate thesis on modal logic, and taught prose style for a living. His choice of words is deliberate. So it is worth sitting with the word Orin uses for the married women he seduces: not Object, but Subject, always capitalized – "last night's Subject," "the Subject's note," "the Subject," and, when he is on the phone giving step-by-step seduction protocols to a friend, "Picture this. Obtain a ring. As in a wedding band. So you present yourself to the Subject as visibly married" (n. 110 pg. 1007). The standard feminist critique of male sexual behavior is that men objectify women, that they flatten women into their use-value, evacuating their interiority. Orin is not doing that. He is doing something much more strange.

The word "Subject" carries several resonances, each of which inflects what he is doing in a different way.

In research, "the Subject" is the person in an experiment, or someone whose behavior is studied under controlled conditions, and about whom data is gathered.
In grammar, "the Subject" is the agent of a sentence, the entity performing the action. The Object is what is acted upon.
In philosophy (Descartes, Kant, Hegel, phenomenology), "the Subject" is the experiencing self, the locus of consciousness, the counterpart of the Object out there in the world.
In political theory, "subjects" are those under the authority of a sovereign, and are subordinates to a power.

DFW's capitalized "Subject" does all four jobs at once.

Grammatically, Orin makes the women agents, but agents of his own ongoing narrative.
Philosophically, he acknowledges their subjecthood, but drafts it into the service of his own.
Experimentally, he runs a long, iterated study, with each seduction being a fresh run of the same protocol (see the "Speedy Seduction Strategy" series, n. 110), with data gathered and discarded at dawn.
Politically, the women are subjects of his self-reproducing pathology – subordinates to a sovereign whose only real project is working out the shape of his own trauma.

Subjectification, in Orin's hands, turns out to be a subtler and more invasive violation than objectification. To objectify is to deny interiority. To subjectify, in Orin's sense, is to borrow interiority, or to enlist the other person's subjecthood as a prop for your own. The women are treated as full persons, but only insofar as being treated as full persons is useful to the work Orin's psyche is doing on itself.

The logic shows itself most clearly on the note. The Subject's note is a real artifact of her subjecthood (her script, her violet bond, her Valentine hearts) and yet what Orin reads in it is not her at all. He reads Oedipus. He reads himself. The Subject has been drafted, unknowingly, into the mirror he is using to see his own buried memory. The "depressing" feeling he registers is not about her, but rather about what her handwriting has made him recognize in himself. Her full subjecthood is exactly what makes the mirror work. An Object could not reflect him back; only a Subject could.

Then, in the technical interview by the AFR, the direction reverses. Orin, who has spent the novel using women as Subjects, becomes the Subject himself, in the capital-S, technical sense, interrogated behind glass. "When Orin had tried to kick his way out was when he'd recognized that the Subject was looking at his eyes rather than into them as previously" (pg. 972). The Subject on the other side of the glass is Luria P-—, who was once his Subject in the sexual sense; now the surface between them has flipped, and Orin is the one being studied, squeezed for data, held under conditions he did not choose. He has been the Subject the whole time, the subject of his own trauma working itself out through the bodies of other women. The technical interview is merely the scene in which the novel makes the inversion explicit. Every "Subject" Orin ever slept with was, in a sense, a surrogate Orin: the self he could not look at directly, looked at through someone else. The strange loop, in the Hofstadter sense, is that the grammar was right. He was always the Subject of the sentence and the women were the Objects. He just preferred to call them otherwise.

15. The Leg's Foot infiniteJest orin language

DFW's grammar of Orin's body is also marked, and the technical-interview passage is the place where the marking becomes most visible. Look again at the sentence the essay has been quoting:

The glass was too thick to break or to kick his way out, and it felt like he might have possibly broken the leg's foot already trying (pg. 972).

Two things are doing trauma-vocabulary work in this sentence. The first is the modal scaffolding: it felt like plus might have plus possibly is a triple hedge that puts maximum distance between Orin's reporting consciousness and the embodied event. He is not reporting that he hurt his foot, but rather is reporting that it-felt-like-may-have-possibly happened to a foot. The second is the noun phrase "the leg's foot." Not "his leg" or "his foot." Not even "the leg" with "the foot" as a separate noun. The leg owns the foot, and Orin owns nothing. The chain of dispossession runs two removes deep because the leg is alienated from Orin, and the foot belongs to that already-alienated leg.

This is the language of dissociation. Survivors of childhood sexual abuse frequently describe a trauma response in which the body is experienced as not-theirs, watched from outside, and owned by something other than the experiencing self. Wallace renders the dissociation clinically, at the level of syntax. There is no clean I connected to this body in this sentence at all. The pronoun has retreated entirely.

The grammatical retreat is sharper given who Orin is. Orin is a punter. The leg the syntax disowns is the body part on which his entire adult identity is built, the instrument of his career, the locus of his "amniotic" rebirth fantasy in the football passages, and the means by which he had organized his post-trauma life around an escape from his early-morning dread. To watch the novel disown that leg in this scene is to watch Orin lose access to the one part of himself he had organized everything around.

The same syntactic move runs through the morning chapters. He describes "his soul's throat" being under grip (pg. 46). This throat is not owned not by Orin but by his soul, with Orin reporting on the relationship as a third party. The soul's throat, the soul's certainty, the soul's night, the leg's foot: in moments of acute pressure, the grammar reaches for an intermediate possessor (like a soul or a leg) to insert between Orin and the part of him that is suffering. The intermediate noun is the grammatical residue of dissociation; it is the chain of inanimate relations that the body becomes when the self has fled it.

This is also, finally, a problem in the philosophy of mind that Wallace, via Hofstadter, was already preoccupied with. GEB takes its energy from the question of how a self inhabits a physical substrate, or the ghost in the machine, in Ryle's coinage that Wallace inverted in The Machine in the Ghost on the Incandenza filmography. The leg's foot is what the inversion looks like inside Orin's body: a chain of mechanical relations with no clean ghost left to own them. By the technical interview, Orin's strategy of interposing intermediate nouns has run out of room. There is no further owner. He is the Subject at last, but he no longer owns the body the Subject is in. The trauma is what made the leg into "the leg" to begin with. Orin's body alienated itself a long time ago, in another room, with another woman who needed not to be there. The technical interview only forces him to watch the alienation happen in real time.

16. Conclusion infiniteJest orin

Orin's deplorable behavior, on this reading, is the product of his traumatic past and its recursive anxiety. Each of the cruelties the novel attributes to him admits an explanation that does not require inherent evil. The cockroaches are a memory he can neither suppress nor face. S. Johnson and Mario are plausibly indirect targets of hostility he cannot aim at Avril directly. The married-mother Subjects are both a search for his mother and a revenge upon her, which is why he is cold to them at breakfast. Leaving Joelle after her disfigurement was overdetermined – superficially a vanity collapse, but plausibly compounded by the familial echoes her relationship with her father stirred up that day. Dispersing the Entertainment targeted the men Avril slept with, not, as Swartz argues, an avenging of Jim.

Taken together, these behaviors describe a victim as well as an antagonist. The thesis does not exonerate Orin – he does real harm, and the harm is real. It argues only that his role as the catalyst of the post-text conflict is the aftermath of childhood sexual abuse, not the expression of any super-human evil.

What makes the reading possible at all is the o/d/p trick, and what makes the trick legible is GEB. Without Hofstadter, the darkened circles read as coincidence; with him, they read as Wallace doing exactly the kind of work GEB taught him – meaning encoded in the morphology of marks rather than in their assigned content, recoverable only by a reader who knows where to look. The Subject's note is the place where the novel marks its own page with the signature of an event it cannot otherwise put on it. Every other piece of evidence the essay has assembled – the Volvo, the Wayne parallel, the helmet dream, the leg's foot, the Room-101 betrayal – is corroboration of what the o/d/p trick names directly.

17. Glossary glossary

Aaron Swartz: Programmer, activist, and early Infinite Jest critic. His 2009 essay What Happened in Infinite Jest? proposes a reconstruction of the novel's post-text plot. This essay's Event-Two reading explicitly departs from Swartz's father-as-revenge-target account.
AFR: Les Assassins des Fauteuils Rollents ("the Wheelchair Assassins"), the Québécois-separatist terrorist cell pursuing the Entertainment.
Avril: Orin's mother, formally Avril Incandenza (also called "the Moms" or "Mrs. M. T. Incandenza" in the novel). Co-founder of E.T.A., Québécois Catholic immigrant, prescriptivist grammarian. Confirmed in a sexual relationship with E.T.A.'s John Wayne – a relationship established scholarship treats as the primary textual evidence for her sexual irregularity, beneath which this essay argues a deeper layer.
DFW: David Foster Wallace, the author of Infinite Jest and the subject of this essay.
Dolores Rusk: E.T.A.'s staff counselor and on-site psychologist. Conducts therapy sessions in which she expounds, sometimes comically, on psychoanalytic theory; her discussion of the Oedipus complex with Ortho Stice immediately precedes the Pemulis/Avril/Wayne scene.
Entertainment: Shorthand in Infinite Jest for James Incandenza's final, fatally compelling film cartridge – the film whose viewers cannot stop watching.
E.T.A.: Enfield Tennis Academy, the elite tennis school co-founded by Avril and James Incandenza, where most of the novel's E.T.A.-side action takes place.
GEB: Gödel, Escher, Bach: An Eternal Golden Braid, Douglas Hofstadter's 1979 Pulitzer-winning book on self-reference, recursion, and strange loops – a foundational influence on Wallace.
Himself: Family nickname for James O. Incandenza, Orin's father (also "Jim"). Optical physicist, experimental filmmaker, and founder of E.T.A.; creator of the Entertainment cartridge whose effect drives the novel's plot. Kills himself by microwaving his own head before the main narrative opens; the Entertainment's master copy is subsequently retrieved from his skull.
Hofstadter: Douglas Hofstadter (b. 1945), American cognitive scientist and author of Gödel, Escher, Bach (1979). His work on self-reference, recursion, and strange loops is the formal-system framework this essay reads Wallace against.
Hugh Steeply: Office of Unspecified Services operative investigating the Entertainment. Typically works in (unconvincing) female disguise. His correspondence with Marlon Bain supplies the Bain letters this essay quotes.
IJ: Infinite Jest, David Foster Wallace's 1996 novel.
Joelle: Orin's girlfriend of twenty-six months, formally Joelle van Dyne; the so-called "Prettiest Girl Of All Time" (P.G.O.A.T.). After Orin leaves her she becomes muse and lead for James Incandenza's final, lethal film. Disfigured under circumstances the novel leaves deliberately ambiguous; later wears a veil and broadcasts as "Madame Psychosis" on MIT student radio. This essay frames her as Orin's Julia in the Room-101 betrayal structure.
John Wayne: E.T.A.'s top-ranked male tennis player, formerly of Montcerf, Quebec; Avril's secret student lover. In the YDAU narrative-present he is 17 or just-18 – an age the novel leaves deliberately ambiguous. This essay reads him as plausibly a parallel victim to Orin rather than Avril's adult co-conspirator.
Julia: Winston Smith's lover in Nineteen Eighty-Four, betrayed by him under Room-101 torture. This essay casts Joelle as Julia's structural analog in Orin's collapse.
Luria P----: Member of the AFR (full name Luria Perec, of Lamartine, county L'Islet, Quebec). Appears female-presenting as one of Orin's Subjects and then as co-operative at his technical interview; her eye-rolling at the AFR leader's theatrics is the gesture Orin misreads as the interview being "mild."
Mario: The middle Incandenza brother (Mario Incandenza), born with severe congenital disabilities and a documentary-filmmaker's temperament. Avril's favorite – which this essay argues is exactly why Orin's verbal cruelty toward him functions as displaced hostility toward their mother.
Marlon Bain: Orin's closest friend from the E.T.A. tennis years, later debilitated by a psychosomatic hyper-perspiration disorder. His correspondence with Office of Unspecified Services agent Hugh Steeply is the source of the "most consummate mind-fucker" characterization of Avril and the claim that Orin "constructs rather than reports the truth."
Oedipus: Mythological king of Thebes who, fulfilling an oracle, unknowingly killed his father Laius and married his mother Jocasta; source of Freud's "Oedipus complex." This essay argues Orin's fixation on the note's darkened circle-letters o/d/p reflects an inadvertent Oedipal self-recognition.
O.N.A.N.: Organization of North American Nations, the supranational confederation Infinite Jest invents. The acronym, deployed relentlessly throughout the novel, spells "Onanism" – one of Wallace's typographic encodings.
Orin: Orin Incandenza, the eldest of the three Incandenza brothers, a former E.T.A. tennis prodigy who switched to football at Boston University and became a punter (#71) for the Arizona Cardinals. The subject of this essay.
Ortho Stice: ("The Darkness") E.T.A. tennis player ranked #3, from rural Kansas, dressed exclusively in black. Therapy-session interlocutor of Dolores Rusk.
Pemulis: Michael Pemulis, E.T.A. student, mathematical and navigational savant, and the Academy's de facto pharmacist. Hal Incandenza's closest friend. His accidental discovery of John Wayne and Avril mid-encounter in Charles Tavis's office is one of this essay's pieces of evidence.
P.G.O.A.T.: Prettiest Girl Of All Time, Joelle van Dyne's nickname.
S. Johnson: The Incandenza family dog, named after the English lexicographer Samuel Johnson. Killed in an "accident" involving Orin; the circumstances surface in n. 269. This essay reads Orin's indifference to the dog's death as an indirect attack on Avril.
Subjects: Orin's chosen term for the married women he seduces (always capitalized, "the Subject," "last night's Subject"). This essay reads the terminology as deliberately marked: not objectifying but subjectifying – borrowing each woman's interiority as a prop for his own.
Winston: Winston Smith, protagonist of George Orwell's Nineteen Eighty-Four (1949). Broken in Room 101 under the threat of having rats set on his face, he shouts "Do it to her! Do it to her!" – the same phrase Orin shouts at his technical interview, anchoring this essay's Event-Two allusion.
YDAU: Year of the Depend Adult Undergarment, the principal year of Infinite Jest's narrative-present. In the novel's near-future, calendar years are subsidized to corporate sponsors.
YTMP: Year of the Tucks Medicated Pad, one of the subsidized years preceding YDAU.

A VOMPECCC Case Study: Spotify as Pure ICR in Emacs

Charlie Holland — Fri, 24 Apr 2026 04:26:00 GMT

1. About emacs completion

Figure 1: JPEG produced with DALL-E 3

This is the third post in a series on Emacs completion. The first post argued that Incremental Completing Read (ICR) is not merely a UI convenience but a structural property of an interface, and that Emacs is one of the few environments where completion is exposed as a programmable substrate rather than a sealed UI. The second post broke the substrate into eight packages (collectively VOMPECCC), each solving one of the six orthogonal concerns of a complete completion system.

In this post, I show, concretely, what it looks like when you build with VOMPECCC, by walking through the code of spot, a Spotify client I implemented as a pure ICR application in Emacs.

A word I'll use throughout this post to refer to the use of VOMPECCC in spot is shim, and it is worth qualifying that. The whole package is about 1,100 non-blank, non-comment lines of Lisp¹. Roughly 635 of those is infrastructure any Spotify client would need regardless of its UI choices: OAuth with refresh, HTTP transport with error surfacing, a cached search layer, a currently-playing mode-line, a config surface, player-control commands, blah blah blah. The shim is the rest: 493 lines across exactly three files (spot-consult.el, spot-marginalia.el, spot-embark.el) whose entire job is to feed candidates into Consult (source), annotate them with Marginalia (source), and attach actions to them through Embark (source). When I say spot is a shim, I mean those three files, and I'm emphasizing the fact that there is relatively little code. The rest of spot is plumbing that has nothing to do with the completion substrate.

spot implements no custom UI. It has no tabulated-list buffer, no custom keymap for navigation, no rendering code. Every interaction surface; the search prompt, the candidate display, the annotations, and the action menu; is rented from the completion substrate by the 493-line shim.

This post is about the code. Instead of cataloging spot's features (I'll do that when I publish the package to Melpa), I want to show how the code actually hangs together on top of VOMPECCC, with verbatim snippets mapped onto the interaction they produce. If the previous two posts were the why and the what, this one is the how, with a working application to ground the pattern.

2. The Demonstration consult marginalia embark

Before any code, here is the concrete task the video is solving: I am trying to find a J Dilla song whose title I can't remember; all I recall is that the word don't is somewhere in the track name. The entire post revolves around this one video, so it is worth watching before reading on. Everything that follows is a line-by-line breakdown of the code that produces what you are about to see. In the upper right hand side of my emacs (in the tab-bar), you'll see the key-bindings and, more importantly, the commands I am invoking to drive spot. (To make this clip easier to digest, you can play, pause, scrub, view in full screen, or view as "Picture in Picture" use the video controls).

Here is what happens in the clip:

I invoke spot-consult-search and type j dilla. Each keystroke fires an async query against the Spotify Web API, and the result set is streamed into the minibuffer. That is Consult. In my emacs config, Vertico² renders the candidate set vertically so the per-row metadata is legible.
I use Spotify's query parameters to widen the result set per type. Spotify's search endpoint caps results per content type, so I append parameter flags (--type=track --limit=50, etc.) to ask for a fatter haul across tracks, albums, and artists. The candidates are streamed back through Consult exactly as before, just more of them.
I type ,, the consult-async-split-style character, to switch from remote search to local ICR. Everything before the comma continues to be the API query; everything after is a local narrowing pattern that matches against the candidate set already in hand. No further Spotify requests are issued, and each incremental keystroke only filters the rows Consult is already holding.
I type dont (no apostrophe) looking for the song. The default matching is literal, so "dont" doesn't match "Don't". Zero candidates. The corpus contains the song; my pattern just doesn't. (You thought I did this by mistake didn't you 😜? It actually highlights why fuzzy matching is so important.)
I backspace and prefix the query with ~, the Orderless³ dispatcher for fuzzy matching. ~dont now matches "Don't Cry" (and others) because fuzzy matching tolerates the missing apostrophe. The search set is unchanged; I swapped matching styles without re-querying Spotify. This may sound like a small feature, but consider how much a little fuzz widens the match space of your input strings. This is espacially important in an application like Spotify where entity names can be long and difficult to remember.
I append @donuts, the Orderless dispatcher for matching against the Marginalia annotation column rather than the candidate name. That narrows the surviving candidates to tracks whose annotation mentions "donuts" (i.e., tracks on Dilla's Donuts album, my personal favourite), even though the word "donuts" never appears in any track title. The song I was looking for is right there. (note my orderless-component-separator is also ",")
With the track selected, I invoke Embark (embark-act) and press P to play. The P binding dispatches to spot-action--generic-play-uri, which pulls the track's URI off the candidate's multi-data property and sends a PUT to the Spotify player. The song starts playing; no further navigation required.

Three VOMPECCC packages are doing the work: Consult (the async streaming + the split-character handoff to local ICR), Marginalia (the metadata column the @ dispatcher just narrowed against), and Embark (the action menu that allows you to play the track, list the album's other tracks, or add it to a playlist). The whole rest of this post is an argument that the code required to make this happen is pleasantly concise, because none of those capabilities (asynchronous search with narrowing, metadata annotation, annotation-aware fuzzy filtering, or contextual actions) needed to be built. They already exist in the VOMPECCC framework, and spot's only job is to feed them data.

3. Anatomy of spot structure modularity

spot is organized so that each file corresponds to one concern. This is deliberate: the architecture mirrors the modularity of VOMPECCC itself, not because I was trying to be cute (I'm cute enough 👺), but because when your substrate is modular, consuming it modularly is the lowest-friction path.

File	Responsibility	Substrate package	LoC
`spot-auth.el`	OAuth2 authorization + automatic token refresh timer	(none)	65
`spot-generic-query.el`	HTTP request plumbing (sync + async, error surfacing)	(none)	88
`spot-search.el`	Cached search against the Spotify API	(none)	100
`spot-generic-action.el`	Player control commands (play/pause/next/previous)	(none)	51
`spot-mode-line.el`	Currently-playing display	(none)	115
`spot-var.el`	Configuration variables (endpoints, credentials, etc.)	(none)	127
`spot-util.el`	Alist/hash-table conversions, candidate propertize	(the glue)	52
`spot-consult.el`	Seven async Consult sources + `consult--multi` entry	Consult	194
`spot-marginalia.el`	Annotation functions per content type	Marginalia	159
`spot-embark.el`	Keymaps and actions per content type	Embark	140
`spot.el`	`spot-mode`: wires registries + timers in and out	(integration)	37
Total			1128

The breakdown is the whole point of the shim framing. The three substrate-facing files (194 + 159 + 140 = 493 lines) are the part that actually integrates with VOMPECCC. None of that is UI code; there is no UI code in spot. Every pixel the user sees comes from Consult, Marginalia, Embark, or whatever the user has slotted in below them.

One caveat on the 194-line figure for spot-consult.el: roughly 105 of those lines are a 7-way parallel triplet (one source definition, one history variable, and one completion function per Spotify content type), varying only in the narrow key and the :category symbol. A small macro (spot-define-consult-source) would collapse the 105 lines into 7 invocations plus a ~25-line definition, for 30-35 lines total. The honest Consult-facing line count, with redundancy factored out, is closer to 115 than 194, and the whole shim closer to 420 than 493.

The reason I didn't write this macro is because it would muddy the concrete depiction of the VOMPECCC APIs here, and honestly, I tend to avoid over-macroizing as it creates new and confusing APIs over well-established and intuitive APIs.

4. Candidates as Shared Currency candidates

Before looking at any of the three VOMPECCC layers individually, there is one piece of code that makes the entire integration possible. It is a short function, and if you understand it, you understand how Consult, Marginalia, and Embark cooperate without knowing anything about each other.

(defun spot--propertize-items (tables)
  "Propertize a list of hash TABLES for display in completion.
Each table is expected to have `name' and `type' keys.  Names are
truncated for display per `spot-candidate-max-width'; the full
name remains accessible via `multi-data'."
  (-map
   (lambda (table)
     (propertize
      (spot--truncate-name (ht-get table 'name))
      'category (intern (ht-get table 'type))
      'multi-data table))
   tables))

Every candidate that spot hands to Consult is a string (the Spotify item's name) carrying two text properties:

category is one of album, artist, track, playlist, show, episode, or audiobook. Emacs's completion metadata protocol uses this property to route candidates to the right annotator and the right action keymap. Marginalia reads it to pick an annotator; Embark reads it to pick a keymap. The two packages never talk to each other, and yet they agree on every candidate's type, because both are reading the same Emacs-standard property.
multi-data is the raw hash table the Spotify API returned for this item: the full JSON response with every field the API exposes. Marginalia's annotator reads from it to format the margin; Embark's actions read from it to execute playback, to navigate to an album's tracks, to add to a playlist. The candidate is the full record; the name is just the visible handle. The name multi-data is spot's own designation, not a Consult or Marginalia convention (the multi- prefix is unrelated to consult--multi); any symbol would have worked. What is conventional is attaching the domain record to the candidate via propertize in the first place.

Marginalia and Embark never talk to each other. They both read the same text property on the same candidate, and that is enough.

That is the entire integration surface: One string (display name) and two props (category and metadata). Everything else (the async fetching, the narrowing, the annotation columns, the action menu) is handled by VOMPECCC, keyed on those two properties. This is a key take away for those looking to build with VOMPECCC: build your candidates like this and you will have a good time on the mountain.

This is what I meant in the first post when I called completion a substrate rather than a UI. A UI would be "here is a widget, bind data to it." A substrate is "here is a common currency (candidates with standard properties); tools that speak the currency can be mixed freely."

5. Consult: Defining the Search Surface consult async narrowing

Consult is spot's frontdoor. It gives me three things I would otherwise have had to build from scratch: async candidate streaming, multi-source unification with narrowing keys, history, and probably other things I'm forgetting. Here is one of the seven source definitions spot uses:

(defvar spot--consult-source-track
  `(:async ,(consult--dynamic-collection
             #'spot--consult-completion-function-consult-track
             :min-input 1)
    :name "Track"
    :narrow ?t
    :category track
    :history spot--history-source-track)
  "Consult source for Spotify tracks.")

A Consult source is just a plist. The interesting keys are:

:async is the candidate stream. consult--dynamic-collection is the de-facto extension point third-party packages have settled on for async sources, despite the double-dash that conventionally marks it internal⁴. It wraps a function that takes the current minibuffer input and returns a list of candidates. Consult handles the debouncing and the "only recompute when the input changes" logic on its side; my code just has to produce candidates for a given query. :min-input 1 prevents a search on an empty query. This is the two-level async filtering that Consult is designed around: the external tool (Spotify's API, in this case) handles the expensive filtering against its own corpus, and my completion style (Orderless, if I have it) narrows the returned set locally.
:narrow ?t binds the narrowing key. In the video, I could have pressed t SPC when running spot-consult-search, and the session would have been scoped to tracks only, and would have avoided querying the other sources. I didn't implement narrowing; Consult did. I just declared which character maps to which source!
:category track is the property that will propagate onto every candidate from this source. This is the same category property that spot--propertize-items stamps on individual candidates, and it is the hinge that Marginalia and Embark both key off.
:history gives me free persistent search history for this source, isolated from the other sources.

The completion function itself is trivial because all the work happens in spot-search.el:

(defun spot--consult-completion-function-consult-track (query)
  "Return track candidates for QUERY."
  (spot--search-cached-and-locked query spot--mutex spot--cache)
  spot--candidates-track)

Seven of these functions exist, one per content type, all identical except for which global they return. The heavy lifting (the HTTP call, the cache, the propertization) is shared. Each source is effectively a view onto a single search result split by type.

Putting all seven sources together into one interface is also trivial:

(defvar spot--search-sources
  '(spot--consult-source-album spot--consult-source-artist
    spot--consult-source-playlist spot--consult-source-track
    spot--consult-source-show spot--consult-source-episode
    spot--consult-source-audiobook)
  "List of consult sources for Spotify search.")

;;;###autoload
(defun spot-consult-search (&optional initial)
  "Search Spotify with consult multi-source completion.
Optional INITIAL provides initial input."
  (interactive)
  (consult--multi
   spot--search-sources
   :history '(:input spot--consult-search-search-history)
   :initial initial))

This is the command you saw in the video. consult--multi takes the list of sources, unifies their candidates into a single list, and wires the narrowing keys. Seven heterogeneous content types, one prompt, one keystroke to filter to any subset, async throughout, with per-source history.

Without Consult I would need: a separate candidate display, an async debouncer, a narrowing mechanism, per-source history buffers, and some way to visually distinguish content types in a single list.

Compare this to the counterfactual. Without Consult I would need: a separate candidate display, an async debouncer, a narrowing mechanism, per-source history buffers, and some way to visually distinguish content types in a single list. And because Consult uses the standard completing-read contract, every minibuffer feature my Emacs already has (Vertico's display, Orderless's matching, Prescient's sorting) applies to spot with zero integration code.

6. Why the Cache? async ratelimits

I have been brushing past a detail of spot-consult.el that deserves its own section, because it is the honest cost of building on an async-on-every-keystroke substrate. consult--dynamic-collection wires the completion function to the minibuffer such that it is invoked on (a debounced version of) every keystroke the user types. For spot, each invocation issues an HTTP request to Spotify's Web API, receives a mixed-type result set, splits it across the seven global candidate lists, and returns the slice relevant to the calling source. That is the hot path. And the hot path is a rate-limited network call.

Spotify's Web API is rate-limited 🙃. Exact limits are dynamic and not publicly documented in detail, but the envelope is small enough that a rapid-typing ICR session can hit it quickly. Consider the baseline: typing radiohead fires a completion call for each prefix the user's typing pauses on (Consult's consult-async-input-debounce and consult-async-input-throttle collapse runs of keystrokes into a smaller set of actually-issued calls, but realistically that still leaves several distinct prefixes per word). Now add the common real-world pattern of typing too far, backspacing a few characters, and retyping: the same query string is re-issued within the same search session. Without a cache, each repetition burns a request, but with a cache keyed on the raw query string, repeats are actually free (or at least as cheap as a cache hit):

(defun spot--search-cached (query cache)
  "Search for QUERY, using CACHE to avoid duplicate requests."
  (when (not (ht-get cache query))
    (let ((results (spot--propertize-items
                    (spot--union-search-items
                     (spot--search-items query)))))
      (ht-set cache query results)))
  (let ((results (ht-get cache query)))
    (spot--set-search-candidates results)))

The cache is a hash table from query strings to propertized candidate lists. It lives for the life of the Emacs session, so not only backspace-and-retype within one search but also the next search session that hits the same prefix is instant. The memory cost is negligible (a few hundred candidates per query, small hash tables for each) and the request-budget win is real. And if you find yourself listening to the same music over and over, then you'll have snappier results when you go down familiar paths.

Async-on-every-keystroke against a remote corpus is the feature. A query-string cache is the bill.

This is the honest consumer tax of the substrate. The first post sold you on ICR by promising that the interaction scales constantly regardless of how big the underlying corpus gets. That claim depends on async sources that fire on every keystroke against a remote corpus, and that in turn means you as package author inherit rate-limit pressure your users never see. Consult gives you the debouncer, the display, the narrowing keys, and the stale-response discarding on its side of the protocol. The cache is what you owe back on your side when your candidate source is a rate-limited network API rather than a local list, and it is exactly the kind of infrastructure that does not belong in Consult itself (because Consult has no way to know your backend is rate-limited, or which queries are equivalent enough to cache together).

7. Marginalia: Promoting Candidates into Informed Choices marginalia

If you watch the video carefully, each track in the candidate list is followed by a horizontally aligned column of fields: #, artist, a M:SS duration, album name, album type, release date. Each field is rendered to a fixed width in its own face, so numbers and dates and names land as visually distinct columns rather than getting mashed together with a delimiter. Small glyph prefixes (# for counts, ★ for popularity, ♥ for followers) disambiguate otherwise bare numbers. That column is provided by Marginalia, and it comes from one function:

(defun spot--annotate-track (cand)
  "Annotate track CAND with number, artist, duration, album, type, and date.
The track number is prefixed with `#' and duration rendered as M:SS."
  (let ((data (get-text-property 0 'multi-data cand)))
    (marginalia--fields
     ((spot--format-count (ht-get data 'track_number))
      :format "#%s" :truncate 5 :face 'spot-marginalia-number)
     ((spot--annotation-field (spot--first-name (ht-get data 'artists)))
      :truncate 25 :face 'spot-marginalia-artist)
     ((spot--format-duration (ht-get data 'duration_ms))
      :truncate 7 :face 'spot-marginalia-number)
     ((spot--annotation-field (ht-get* data 'album 'name))
      :truncate 30 :face 'spot-marginalia-album)
     ((spot--annotation-field (ht-get* data 'album 'album_type))
      :truncate 8 :face 'spot-marginalia-type)
     ((spot--annotation-field (ht-get* data 'album 'release_date))
      :truncate 10 :face 'spot-marginalia-date))))

The first line is the only plumbing: (get-text-property 0 'multi-data cand) pulls the full Spotify API response off the candidate (exactly the hash table spot--propertize-items stashed earlier), and everything after it is Marginalia's own marginalia--fields macro doing the formatting. marginalia--fields handles the alignment, the per-field truncation, and the face application. The only thing my code does is declare which fields of the Spotify payload go in which columns with which faces. This is another substrate borrow hiding in plain sight: Marginalia registers the annotator and formats its output. I never wrote a single character of alignment, padding, or colourisation logic. The annotator reached into multi-data for its fields, Marginalia's macro did the cosmetic work, and Marginalia never had to know about Spotify's data model.

spot ships seven annotators. Each one is a domain-specific projection of a single Spotify response type onto a display string. Albums surface artist, release date, and track count, artists surface popularity and follower count, shows surface publisher, media type, and episode count; and all this context is really important, especially if you are 'browsing'. The annotators are independent of the search code, independent of the actions code, and independent of each other.

Registering them with Marginalia is three lines of bookkeeping:

(defvar spot--marginalia-annotator-entries
  '((album spot--annotate-album none)
    (artist spot--annotate-artist none)
    (playlist spot--annotate-playlist none)
    (track spot--annotate-track none)
    (show spot--annotate-show none)
    (episode spot--annotate-episode none)
    (audiobook spot--annotate-audiobook none))
  "List of marginalia annotator entries registered by spot.")

(defun spot--setup-marginalia ()
  "Register spot annotators with marginalia."
  (dolist (entry spot--marginalia-annotator-entries)
    (add-to-list 'marginalia-annotators entry)))

The spot--marginalia-annotator-entries list keys on the category symbol (album, artist, and so on), the very same symbols the Consult sources stamp onto their candidates. Marginalia looks up the category of the current candidate in marginalia-annotators, finds the entry, and runs the annotator. No spot code is in that path. I only had to declare the mapping.

This is where one of the most interesting benefits of the second post shows up concretely. That post mentioned that because Marginalia annotations are themselves searchable, Orderless's @ dispatcher lets you match against annotation text. spot did not ship this feature. Orderless and Marginalia did, for free, because I stamped the annotation onto the candidate in the right way.

8. The Four Levels of Narrowing narrowing orderless consult

The walkthrough at the top of this post shows three different characters doing three superficially similar jobs: , (narrow the Spotify result set without issuing a new remote request), ~ (switch to fuzzy matching), and @ (match against the Marginalia annotation column rather than the candidate name). To a reader who has internalized the modularity argument of the series, these are three different packages each owning one lever, but when you see them one after another in a single search prompt, it is easy to assume they are variations on the same theme.

u/Strickinato pointed out on Reddit that step 3 of the walkthrough broke their mental model in a useful way. Their initial read was that , would match against the annotations; which is actually what Orderless's & dispatcher does (remapped to @ in my config). Reasoning through why that expectation was wrong led them to a crisp taxonomy worth reproducing here, lightly adapted, because it names something the walkthrough shows but never quite spells out.

Remote search. Everything before the consult-async-split-style character is the string sent to the external backend; Spotify's Web API, in this case. The backend runs its own search, over its own corpus, under its own matching rules. Nothing in Emacs has seen this corpus; Consult is just the transport. (Step 2 of the demo showed a sub-variant of this: Spotify-specific flags like --type=track --limit=50 are appended to the remote query to reshape how the backend searches, rather than what it searches against. Same level; different lever on the same backend.)
Candidate narrowing. Everything after the split character is matched against the candidates Consult is already holding. No more remote requests fire. Each keystroke filters the in-hand set by candidate name under whatever completion style you have configured (Orderless, flex, basic, whatever). This is the level at which your everyday completion-style intuitions apply; step 3 of the demo switches to this mode the moment I type the comma.
Annotation narrowing. Orderless's orderless-annotation dispatcher (the & character by default, remapped to @ in my config via orderless-affix-dispatch-alist) matches against the Marginalia column rather than the candidate name. Step 6 of the demo is exactly this: @donuts narrows to tracks whose annotation mentions "donuts", even though no track title contains the word. This is the level at which Orderless and Marginalia interoperate without either knowing about the other.
Hidden-metadata narrowing. u/JDRiverRun added a fourth: orderless-kwd exposes keyword-prefixed filters that match against metadata which is not even displayed. Their example: in M-x, type org :doc:table and the candidate list narrows to commands whose docstring mentions "table", even when the docstring never appears on screen. This is the most interesting level to me, because it clarifies that "the candidate" (the visible text) and "what is searchable about the candidate" are two different things, and the substrate lets a package declare which facets of a record are filterable without committing to which facets are visible.

Four levels, four packages cooperating. No one of them implements more than one.

Consult owns the split that separates 1 from 2; the active completion style (Orderless, flex, and so on) owns the matching in 2; Marginalia supplies the content that 3 matches against; orderless-kwd (shipped with Orderless) owns 4. The original confusion ("surely the comma filters annotations too?") is, in hindsight, the sharpest demonstration of the modularity on offer: if one character had been responsible for two of these levels, the substrate would be more tangled, and VOMPECCC's central claim would be weaker.

9. Embark: The Action Layer embark composition

The third leg of spot's tripod is Embark. In the video, pressing the Embark action key on any candidate surfaces a menu of single-letter actions appropriate to that kind of candidate: P plays it, s shows its raw data, t lists its tracks (on albums and artists), + adds it to a playlist (on tracks). Each of those actions is a one-function definition in spot-embark.el, and their binding to candidates is declarative.

The simplest action is play:

(defun spot-action--generic-play-uri (item)
  "Play the Spotify item represented by ITEM."
  (let* ((table (get-text-property 0 'multi-data item))
         (type (ht-get table 'type))
         (offset (cond
                  ((string= type "track") `(("uri" . ,(ht-get* table 'uri))))
                  ((string= type "playlist") '(("position" . 0)))
                  ((string= type "album") '(("position" . 0)))
                  ((string= type "artist") nil)))
         (context_uri (cond
                       ((string= type "track") (ht-get* table 'album 'uri))
                       ((string= type "playlist") (ht-get* table 'uri))
                       ((string= type "album") (ht-get* table 'uri))
                       ((string= type "artist") (ht-get* table 'uri))))
         ...
         (spot-request-async
          :method "PUT"
          :url spot-player-play-url ...))))

Same pattern as the annotators: (get-text-property 0 'multi-data item) pulls the full hash table off the candidate, and the rest is Spotify domain logic. Embark invokes my action with the candidate that was highlighted; my action handles the HTTP.

The keymap wiring is also just bookkeeping:

(defvar-keymap spot-embark-track-keymap
  :parent embark-general-map
  :doc "Keymap for Spotify track actions.")

;; ... one keymap per content type ...

(defvar spot--embark-keymap-entries
  '((album . spot-embark-album-keymap)
    (artist . spot-embark-artist-keymap)
    (playlist . spot-embark-playlist-keymap)
    (track . spot-embark-track-keymap)
    (show . spot-embark-show-keymap)
    (episode . spot-embark-episode-keymap)
    (audiobook . spot-embark-audiobook-keymap)
    ...))

(dolist (map (list spot-embark-artist-keymap spot-embark-album-keymap
                   spot-embark-playlist-keymap spot-embark-track-keymap
                   ...))
  (define-key map "s" #'spot-action--generic-show-data)
  (define-key map "P" #'spot-action--generic-play-uri))

(define-key spot-embark-track-keymap "+" #'spot-action--add-track-to-playlist)
(define-key spot-embark-album-keymap  "t" #'spot-action--list-album-tracks)
(define-key spot-embark-artist-keymap "t" #'spot-action--list-artist-tracks)
(define-key spot-embark-playlist-keymap "t" #'spot-action--list-playlist-tracks)

Again, the key keys off category. Embark looks up the current candidate's category in embark-keymap-alist, finds the matching keymap, opens it. Every layer of this integration is the same trick: a candidate carries a category property, and the substrate routes based on it. All three VOMPECCC packages, working on the same candidates, sharing the same category convention, never importing each other.

9.1. Composition: When an Action Opens Another Search composition chaining

One action in particular is worth reading slowly, because it closes the loop the thought exercise in the first post opened:

(defun spot-action--list-album-tracks (item)
  "Search for tracks on the album represented by ITEM."
  (let* ((table (get-text-property 0 'multi-data item))
         (album-name (ht-get* table 'name))
         (artist-name (ht-get* (nth 0 (ht-get* table 'artists)) 'name)))
    (spot-consult-search
     (concat
      "album:" album-name
      " "
      "artist:" artist-name " -- --type=track"))))

This action runs when I am in a completion session, run Embark on an album candidate, and press t. It extracts the album name and artist from the multi-data, builds a Spotify query using Spotify's field-filter syntax (album:X artist:Y), and calls spot-consult-search again: the same entry point the user invoked initially.

Embark action on a Consult candidate launches a new Consult session, scoped to that candidate. Three lines of Lisp. The whole "chain ICRs to compose workflows" argument from Post 1, made concrete.

Nice!!! What just happened? An Embark action on a candidate produced by a Consult source launched a new Consult session, scoped to the selected candidate, in the same substrate, with the same annotators, and the same available actions. The chaining pattern from the first post ("ICR to pick a thing, which scopes the candidate set for the next ICR") is literally three lines of spot code, because the substrate composes oh so cleanly with itself.

The first post described this as the shell's git branch | fzf | xargs git checkout pattern in miniature. In spot, the pipe is embark-act, and the downstream command is another consult--multi. It is the same compositional shape; the surface it runs on is different.

10. The Integration Point: spot-mode modularity hooks

Both registries (Marginalia's annotator alist and Embark's keymap alist) plus the two background timers (mode-line updates and access-token refresh) get installed and uninstalled in one place:

;;;###autoload
(define-minor-mode spot-mode
  "Global minor mode for the spot Spotify client.
Registers embark keymaps, marginalia annotators, starts the
mode-line update timer, and starts a periodic access-token
refresh timer when enabled.  Cleanly removes all integrations
when disabled."
  :global t
  :group 'spot
  (if spot-mode
      (progn
        (spot--setup-embark)
        (spot--setup-marginalia)
        (spot--start-update-timer)
        (spot--start-refresh-timer))
    (spot--teardown-embark)
    (spot--teardown-marginalia)
    (spot--stop-update-timer)
    (spot--stop-refresh-timer)))

This is the entire integration layer. Toggle the mode, spot's categories appear in Marginalia and Embark and the two timers begin ticking. Toggle it off, they all disappear. No global state mutation escapes the teardown path.

And by the way, a user who never installs Marginalia or Embark still gets a working spot; the setup functions no-op gracefully (all they do is add-to-list against someone else's variable), that user just doesn't get annotations or actions. The "stack what you want, subset what you don't need" property of VOMPECCC propagates through to spot as a consumer: the package is graceful under any subset of VOMPECCC.

11. The Counterfactual: What spot Would Look Like Without VOMPECCC

To see what spot isn't building, look at the negative space.

A pre-VOMPECCC Spotify client (see smudge for an example that predates the modern completion ecosystem) has to build the UI itself: a tabulated-list-mode buffer with its own keymap, its own rendering code, its own pagination, its own selection logic. That approach works and can work well. But the cost is structural: a bespoke UI is a parallel universe of interaction that does not benefit from any completion infrastructure the user has already invested in. You have to learn its bindings, and frustratingly, these don't carry over to any other Emacs tool.

The architecture was entirely reasonable when there was nothing else to build on. The point here is purely structural: once the substrate exists, reinventing the UI on top of it is a strictly larger codebase that delivers a strictly less interoperable experience. spot is about 1,100 lines of Lisp, and its interface, as we've shown, is closer to 420 lines of Lisp. A pre-substrate equivalent is many times that, and much of the delta is code implementing things (display, filtering, selection, action menus) that Consult, Marginalia, and Embark implement once, centrally, for every completion-driven command in the user's Emacs.

This is the gap the first post was pointing at when it distinguished using completion from building on completion. A package that uses completion is a consumer of completing-read. A package that builds on completion assumes the existence of a richer substrate (async sources, categorized candidates, annotator hooks, action keymaps) and contributes into that substrate rather than rebuilding around it.

12. What This Says About the Substrate substrate platform

Three things follow.

First, the cost of building an ICR-driven app collapses once the substrate exists. spot is about 1,100 lines including OAuth, token refresh, HTTP, caching, the mode-line, and the integration glue. The three VOMPECCC files (spot-consult.el, spot-marginalia.el, spot-embark.el) are together under 500 lines, much of it boilerplate per content type. A feature-competitive pre-VOMPECCC Spotify client would easily have been several thousand lines larger.

Second, composition is the feature, not the packages. The list-album-tracks action is the most important ten lines in the repository, not because of what it does (a Spotify query), but because of what it demonstrates: an Embark action on a Consult candidate launching a new Consult session in the same substrate. Every ICR-driven package in your Emacs configuration that shares this substrate composes with every other one. embark-export on a spot result set could, in principle, produce a native mode for Spotify results, the same way it produces Dired from file candidates or wgrep from ripgrep hits. The composability is a property of the substrate, not of any individual package.

Third, the category property is doing an enormous amount of load-bearing work. Three different packages, each knowing nothing about the others, all agree on the right behavior for every candidate because they are keying off the same standardized property 'category. The "text" in the protocol is (candidate . (category . metadata)), and every tool that speaks the protocol interoperates for free.

13. Generalizing the Pattern Beyond Spotify generalization pattern

spot is specifically a Spotify client, but nothing about the recipe it follows is Spotify-specific. Strip the domain out and what remains is a six-step shape that applies to an enormous fraction of the services and data sources you interact with daily:

An API or backend that returns typed items: each item has a type discriminator and a bag of metadata.
A candidate-constructor (the spot--propertize-items analogue) that turns those items into completion candidates with a category text property and a multi-data payload.
A Consult source per type, async, with a narrow key, all unified under a consult--multi entry point.
A Marginalia annotator per type, keyed on category, reading the multi-data payload for its domain metadata.
An Embark keymap per type, keyed on category, binding single-letter actions that operate on the multi-data payload.
A minor mode that installs and uninstalls the three registries together. This one can even be optional, but I recommend doing it.

Any domain that fits that shape can be built the same way. The thought exercise from the first post (which of your daily tools reduces to "pick a thing, act on it" over a typed corpus?) has a lot of concrete answers: issue trackers, cloud consoles, email, chat, package managers, news feeds, knowledge bases, code hosting. Two worked examples are enough to sketch the altitude:

Issue trackers. Types are issue / epic / comment / user, metadata is status / assignee / priority / labels, actions are transition / assign / comment / close.
Code hosting. consult-gh already does the GitHub version. Types are repo / PR / issue / branch / release / user, metadata is state / author / date / counts, actions are clone / checkout / review / merge / close.

Several domains already ship as working packages: consult-gh, consult-notes, consult-omni, consult-tramp, consult-dir, and many others. None of these packages ships a UI; they all (roughly) follow the same six-step recipe spot follows, and each one composes with every other one automatically.

The more interesting exercise is the shape of domains that don't cleanly fit. The pattern starts to strain when items aren't naturally enumerable, or when the right interaction is a canvas rather than a list (a map, a timeline, a dependency graph). Those cases need something more than ICR. What I find remarkable is how often even those interfaces still have an ICR-shaped core (pick a location on the map, pick a node on the graph, pick a frame on the timeline), which could be delegated to the substrate while the custom-UI parts focus on what genuinely needs rendering.

The concrete-enough test I apply to any new Emacs workflow I'm considering building: can I express it as a Consult source, a Marginalia annotator, and an Embark keymap? If yes, the package will be mostly a client of the VOMPECCC API. If no, the package needs custom UI, and I should be deliberate about which parts genuinely do and which parts could still be delegated. spot is the case where the answer is a clean "yes across the board", but I've found that more often than not, the answer is yes for the first draft.

14. Conclusion

This post took a working application and showed what the argument looks like when you cash it in.

If there is one thing I want a reader to take away from the series, it is the reframe. Completion is not a convenience feature you turn on and forget about. It is the primitive on which a surprising fraction of your Emacs interaction either already runs or could run, if you let it. Packages that treat it that way end up smaller, more interoperable, and more amenable to composition than packages that treat it as one feature among many. spot is one example.

The broader claim, which I will leave you with, is that "packages that do one thing" is the lazy reading of the Unix philosophy. The sharper reading is "packages that contribute into a shared substrate." Unix pipes were never interesting because each command was small; they were interesting because every command produced and consumed plain text. VOMPECCC is interesting for the same reason, with candidates-with-properties instead of plain text. spot was easy to write because the substrate is good. Many things in your Emacs configuration could be rewritten today as "ICR applications on the substrate" and would be smaller, cleaner, and more composable as a result.

When you next find yourself thinking "I wish there were a better way to browse X", ask whether it could just be a Consult source, a Marginalia annotator, and an Embark keymap. Surprisingly often, that is the entire package, and all you have to do is feed it data.

15. TLDR

spot is a Spotify client for Emacs that implements no custom UI. About 493 of its ~1,100 lines are the "shim" that feeds candidates into Consult, Marginalia, and Embark via a single text-property pattern (category plus multi-data); the remaining ~635 are plumbing any Spotify client would need regardless of UI. The six-step recipe (typed items → propertize → Consult source per type → Marginalia annotator per type → Embark keymap per type → minor mode) generalizes to issue trackers, cloud consoles, email, chat, knowledge bases, and more, many of which already ship as working packages (consult-gh, consult-notes, consult-omni). The claim the series has been building toward: when the substrate is good, ICR applications collapse to their domain logic, and "packages that contribute into a shared substrate" is the sharper reading of the Unix philosophy.

Footnotes:

As of the version being discussed, the eleven .el files in the repository total about 1,128 non-blank, non-comment lines. Not a large package by any measure.

Vertico is the vertical minibuffer UI you see in the video. It is not part of the spot package; it is a piece of my personal Emacs configuration, one of the VOMPECCC packages the user slots in underneath a consumer like spot. A different user could run spot with fido-vertical-mode, Helm, Ivy, or plain default completing-read; the candidates and their annotations would be unchanged, only the rendering would differ.

Orderless is the completion style that powers the ~ (fuzzy) and @ (annotation) dispatchers in the video. Like Vertico, it is configured in my personal Emacs setup, not shipped with spot. One detail worth calling out: Orderless's default annotation dispatcher is &, not @. I remap it to @ in my own config, so the @donuts you see in the video is specific to my setup; out of the box you would type &donuts to get the same behavior. The dispatcher characters are fully user-configurable, and users on an entirely different completion style (flex, substring, basic) will see different filtering behavior.

⁴

The double-dash convention in Elisp marks a symbol as internal to its package. consult--dynamic-collection is formally one of those. In practice it is the extension point third-party async Consult sources have all settled on, and Daniel Mendler has been careful about signalling breaking changes in the Consult changelog when its shape does shift. spot pins consult > 1.0= for this reason.

VOMPECCC: A Modular Completion Framework for Emacs

Charlie Holland — Fri, 17 Apr 2026 11:17:00 GMT

1. About emacs completion modularity

Figure 1: JPEG produced with DALL-E 3

Completion is not a feature or UI, but instead it is a system composed of at least half a dozen orthogonal concerns that most users never think about separately. The previous post in this series argued that Emacs uniquely exposes completion as a programmable substrate rather than a sealed UI, and that this substrate is what makes Incremental Completing Read (ICR) viable as a primary interaction pattern in Emacs. This post is about the packages that build on that substrate in practice.

VOMPECCC is a loose acronym for eight of them that, together, form a complete, modular, Unix-philosophy-aligned completion framework for Emacs: Vertico, Orderless, Marginalia, Prescient, Embark, Consult, Corfu, and Cape. Each package does one thing, and the key attribute of all eight is that they compose through Emacs's standard completion APIs, meaning any subset works without the others.

I'm writing this post because these packages have recently taken the Emacs community by storm, but I rarely see discussions on how they relate or how they compose together to provide a feature complete ICR system in emacs. These packages implement concretely what the antecedent post argues in the abstract: completion is a substrate, or set of primitives, on top of which users can build rich interfaces for effortlessly interacting with your machine to do almost anything.

2. The Hidden Complexity of Completion complexity design

Even if you've only used Emacs once, you've likely seen its completion features in action. When you press M-x and start typing, a list appears, you pick something, and it runs. But beneath that interaction lies a system of surprising depth. Consider what a fully featured completion experience actually requires:

Candidate display. Where do completion candidates appear? In the minibuffer, vertically? Horizontally? In a separate buffer? In a popup at point? The display layer determines how you scan and navigate candidates, and of course the optimal display is context dependent. Switching buffers might want a vertical list; completing a symbol in code might want a popup near the cursor.

Filtering. You can also think of this as 'matching': how does your input match against candidates? Literal prefix matching is the simplest: find-f matches find-file. But if we want to add some flexibilty (or 'fuzzy matching'), where for examplke ff matches find-file? What about splitting your input into multiple components and matching all of them in any order? What about mixing strategies, for example, where one component matches as a regexp, and another matches as an initialism? Candidate lists can be huge, so we need this set of features as a sort of query language for filtering the candidate list to find what we're looking for.

Sorting. Once you have your filtered candidates, in what order do you see them? Alphabetically? By string length? By how recently you selected them? By frequency of use? A good sorting strategy means the candidate you want is almost always within the first few results. A bad one means scrolling every time.

Annotation. A bare list of candidate names is often insufficient or unhelpful. Often, candidates are of a certain 'type' or 'category' and have rich metadata associated with them. In the M-x example, when selecting a command, you likely want to see its keybinding and docstring. When selecting a file, you likely want to see its size and modification date. When selecting a buffer, you want to see its major mode and file path. Annotations transform a list of strings into a list of informed choices.

Actions. Selecting a candidate (and running some default action) is the most common interaction, but not the only one. In the find-file example, what if you want to delete the file instead of opening it? In the M-x example, what if you want to describe the function instead of running it? A completion system without contextual actions forces you out of the flow: complete, exit, invoke a separate command, etc….

In-buffer completion. Everything above applies to the minibuffer (the prompt at the bottom of the screen). But completion also happens inside buffers: symbol completion while writing code, dictionary words while writing prose, file paths while editing configuration. In-buffer completion has its own display requirements (a popup near the cursor, not the minibuffer) and its own backend requirements (language servers, dynamic abbreviations, file system paths). A truly complete completion system must handle both contexts well.

Completion is not one problem. It is at least six, and most frameworks pretend otherwise.

These six concerns are orthogonal. The way you display candidates has nothing to do with how you filter them; the way you sort them has nothing to do with what actions you can take, etc…. It's actually a useful thought exercise to go through each of the six concerns and appreciate how each is independent from the others. A single-package system can deliver an excellent out-of-the-box experience across all of these, and many have (see Ivy and Helm below). The trade-off is usually that the boundaries between concerns become harder to see, and harder to swap one concern's implementation without disturbing the others.

3. The Monolith Era: Helm and Ivy helm ivy legacy

For the better part of a decade, two incredible frameworks dominated Emacs completion: Helm and Ivy. Both were genuinely transformative, because in my opinion, they proved that Emacs's built-in completion experience was inadequate, and they inspired everything that followed. But both, in retrospect, made the same architectural trade-off: they bundled every concern into a single package with a single API. I have used both packages extensively, as both a package author and a consumer. The benefits were immediate for me, but the costs emerged over time.

3.1. Helm: The Kitchen Sink

Helm traces its lineage to anything.el, created by Tamas Patrovics in 2007. Thierry Volpiatto, a French alpine guide who taught himself programming after discovering Linux in 2006¹, forked it as Helm in 2011 and contributed nearly 7,000 commits over the following decade. Helm became the most downloaded package on MELPA² and the default completion framework in Spacemacs, which drove massive adoption during 2013–2018.

Helm's ambition was impressive but all-encompassing. It provided its own candidate display, filtering, action system, source API (via EIEIO classes), and dozens of built-in commands for things like file finding, buffer switching, grep, and more…. The actions system was comprehensive too — it offered 44+ file actions alone.

Helm showed what great completion could feel like. Its architecture showed what happens when a single maintainer carries every concern alone.

The cost was proportional to Thierry's ambition. Users reported multi-second delays on basic operations after extended use, 100–500ms lag on window popups, and CPU-intensive fuzzy matching that required disabling for large projects. Samuel Barreto's widely cited "From Helm to Ivy" essay called Helm "a big behemoth size package" and reported using only a third of its capabilities.

Most critically, Helm replaced Emacs's completing-read entirely with its own proprietary helm-source API. Every Helm extension was written against this API. None of them could be reused with any other completion system. That was the helm killer for me: if Helm's development stalled — and it did, twice, in 2018 and 2020³ — every downstream package would be stranded.

3.2. Ivy: The Lighter Monolith

Ivy emerged in 2015 as Oleh Krehel's direct reaction to Helm's complexity. Where Helm tried to do everything, Oleh aimed to be more minimalist or at least better factored. The package split its concerns into three logical components: Ivy (the completion UI), Swiper (an isearch replacement), and Counsel (enhanced commands).

In practice, the split was cosmetic. All three lived in a single repository. Counsel was coupled to Ivy's internals. And the core architectural choice was the same as Helm's: Ivy defined its own completion API, ivy-read, and Counsel commands called ivy-read directly rather than completing-read. Code written for Ivy worked only with Ivy.

The ivy-read function grew organically to accept roughly 20 arguments with multiple special cases⁴. As the Selectrum developers noted: "When Ivy became a more general-purpose interactive selection package, more and more special cases were added to make various commands work properly." Users reported performance degradation after extended use, and Ivy broke with Emacs 28 and again with Emacs 30, forcing compatibility polyfills. This is stressful for not only the consumers of Ivy, but also for the maintainers.

When Ivy's original maintainer stepped back, the project entered a period of reduced maintenance. A new maintainer has since taken over and released version 0.15.1, but active feature development has slowed considerably from the 2016–2020 peak.

3.3. The Unix Philosophy Lens

The Unix philosophy, as articulated by Doug McIlroy⁵, is straightforward: "Write programs that do one thing and do it well. Write programs to work together." Viewed through this lens, both Helm and Ivy bundle too many concerns into packages that communicate through proprietary APIs (helm-source, ivy-read) rather than Emacs's native completing-read contract. The result is that extensions and backends written for one framework cannot be reused with another, making an investment in either tool non-transferable.

None of this diminishes what they achieved, by the way. I'm personally a huge Helm and Ivy fan and I've build with them and consumed them directly for years. In my opinion, the legacy of Helm and Ivy is that they showed the community what great completion felt like, and gave a taste of what a fully featured completion system built on the Emacs substrate could be. The question is whether the architecture that delivered those features is the one we want to build on going forward.

The irony is that Emacs already provides the right abstraction.

completing-read is a stable, well-specified API that any UI can render⁶.
completion-styles is a pluggable system for controlling how input matches candidates⁷.
completion-at-point-functions is a standard hook for in-buffer completion backends.

The infrastructure for composable completion has existed for years. It just needed packages that actually used it.

4. The VOMPECCC Framework vompeccc framework

VOMPECCC is not a framework in the traditional sense. There is no single repository, no shared dependency, and no coordinating package. It is eight independent packages, maintained by three different developers, that compose through Emacs's standard APIs to cover every concern of a complete completion system.

Package	Concern	Author
Vertico	Minibuffer display	Daniel Mendler
Orderless	Filtering / matching	Omar Antolin Camarena & Daniel Mendler
Marginalia	Candidate annotations	Omar Antolin Camarena & Daniel Mendler
Prescient	Sorting / ranking	Radon Rosborough
Embark	Contextual actions	Omar Antolin Camarena
Consult	Enhanced commands	Daniel Mendler
Corfu	In-buffer display	Daniel Mendler
Cape	In-buffer backends	Daniel Mendler

The architecture maps cleanly onto the six concerns identified earlier:

                Minibuffer                     Buffer
                ----------                     ------
Display:        Vertico                        Corfu
Filtering:      Orderless          (shared across both)
Sorting:        Prescient          (shared across both)
Annotations:    Marginalia         (shared across both)
Actions:        Embark             (shared across both)
Backends:       Consult                        Cape

Each package targets a single layer, and they all communicate through standard Emacs APIs: completing-read, completion-styles, completion-at-point-functions, annotation functions, and keymaps. No package knows about the others' internals ‼️, and because of this all of them can be replaced without affecting the rest.

5. Vertico: The Display Layer vertico display

Vertico (VERTical Interactive COmpletion) provides a vertical candidate list in the minibuffer. It is roughly 600 lines of code, excluding its extensions.

Vertico's defining characteristic is strict adherence to the completing-read contract. It doesn't filter candidates (that's your completion style's job). It doesn't sort them (that's your sorting function's job). It doesn't annotate them (that's your annotation function's job). It just displays them. Any command that calls completing-read, whether built-in or third-party, automatically gets Vertico's UI with zero configuration.

If you think 1 package for display is overkill, like I originally did before migrating to VOMPECCC, keep reading.

Vertico ships with 13 built-in extensions that modify the display behavior:

Extension	Effect
`vertico-buffer`	Display in a regular buffer instead of the minibuffer
`vertico-directory`	Ido-like directory navigation (backspace deletes path components)
`vertico-flat`	Horizontal, flat display
`vertico-grid`	Grid layout
`vertico-indexed`	Select candidates by numeric prefix argument
`vertico-mouse`	Mouse scrolling and selection
`vertico-multiform`	Per-command or per-category display configuration
`vertico-quick`	Avy-style quick selection keys
`vertico-repeat`	Repeat last completion session
`vertico-reverse`	Bottom-to-top display
`vertico-suspend`	Suspend and restore completion sessions
`vertico-unobtrusive`	Show only a single candidate

The vertico-multiform extension is particularly worth configuring: it lets you set per-command display modes, so consult-line can open in a full buffer while M-x stays in the minibuffer.

Created: April 2021. Stars: ~1,800. Available on: GNU ELPA.

6. Orderless: The Filtering Layer orderless filtering

Orderless is a completion style — it plugs into Emacs's completion-styles variable, the standard mechanism for controlling how user input is matched against candidates. Where built-in styles like basic require prefix matching and flex does single-pattern fuzzy matching, Orderless splits your input into space-separated components and matches candidates that contain all components in any order (Orderless reveals its namesake 😜).

Each component can independently use a different matching method:

Style	Example	Matches
`orderless-literal`	`buffer`	`switch-to-buffer`
`orderless-regexp`	`^con.*mode$`	`conf-mode`
`orderless-initialism`	`stb`	`switch-to-buffer`
`orderless-flex`	`stbf`	`switch-to-buffer`
`orderless-prefixes`	`s-t-b`	`switch-to-buffer`
`orderless-literal-prefix`	`swi`	`switch-to-buffer`

Style dispatchers let you select a matching method per component using affix characters: == for literal, ~ for flex, , for initialism, ! for negation, & to match annotations. The system is fully extensible.

The typical configuration sets completion-styles to '(orderless basic), with partial-completion for the file category so that ~/d/s expands path components like ~/Documents/src. The fallback to basic is deliberate: some Emacs features (TRAMP hostname completion, dynamic completion tables) require a prefix-matching style.

Let's keep beating the dead horse of this post's theme: because Orderless is a standard completion style, it works with any completion UI that uses Emacs's completing-read API: Vertico, Icomplete, the default *Completions* buffer, and even the minibuffer in Emacs's stock configuration.

Quick timeout: for readers getting to this point thinking "Wow Vertico plus Orderless is a power stack, let's keep stacking", you certainly can see things this way, but instead, I encourage you to consider what it would be like to use each package without the others. That will give you a better understanding of how the consituent stars in the VOMPECCC constellation behave independently. And that's the long term ROI you'll get from VOMPECCC. The independence is what makes stacking safe and fortuitous, but it doesn't make it necessary.

Created: April 2020. Stars: ~979. Available on: GNU ELPA.

7. Marginalia: The Annotation Layer marginalia annotations

Marginalia adds contextual annotations to minibuffer completion candidates. The name refers to notes written in the margins of books, and here it means metadata displayed alongside each candidate.

Marginalia detects the category of the current completion (files, commands, variables, faces, buffers, bookmarks, packages, etc.) and selects an appropriate annotator function. The detection works through two mechanisms: marginalia-classify-by-command-name (lookup table keyed by calling command) and marginalia-classify-by-prompt (regex matching against the minibuffer prompt text).

Category	Annotations shown
Command	Keybinding, docstring summary
File	Size, modification date, permissions
Variable	Current value, docstring
Face	Preview of the face styling
Symbol	Class indicator (v/f/c), docstring
Buffer	Mode, size, file path
Bookmark	Type, target location
Package	Version, status, description

marginalia-cycle (typically bound to M-A) lets you cycle between annotation levels: detailed, abbreviated, or disabled entirely. This is useful when annotations are consuming screen space during narrow completions.

Marginalia hooks into Emacs's annotation-function and affixation-function properties in completion metadata. Sorry again to the dead horse I've been wailing on, but yes, this means Marginalia works with any completion UI that respects these properties. It is the framework-agnostic successor to ivy-rich⁸, which provided similar annotations but was Ivy-specific. It's cool to see Oleh and Thierry's visions carry on in these packages!

This was a mind blower to me when I discovered it - one subtle but consequential effect of using Marginalia is that the annotations themselves become searchable. Combined with Orderless's & style dispatcher, your input can match against annotation text as well as candidate names: running M-x and typing window &frame narrows to commands whose name contains "window" and whose docstring contains "frame". The search/matching space extends beyond candidate identifiers into candidate metadata, which is an unusually large leverage gain for what feels like a cosmetic layer. You are no longer constrained to remembering exact names (🤯); you can reach for commands, files, or buffers by properties that were previously invisible to your completion input. This helps to solve for cases where you have a ICR UI, but you don't know exactly what you're looking for. It can also be used to help you 'browse' candidates based on their characteristics as opposed to their names. Honestly my favorite feature of any of the VOMPECCC packages.

Created: December 2020. Stars: ~919. Available on: GNU ELPA.

8. Prescient: The Sorting Layer prescient sorting

Prescient provides intelligent sorting and filtering of completion candidates based on recency and frequency of use. The portmanteau frecency captures the combined metric that drives the ranking.

Orderless and Prescient are often confused with one another: the difference is that while Orderless answers "which candidates match?", Prescient answers "in what order should they appear?"

The sorting is hierarchical:

Recency — most recently selected candidates appear first
Frequency — frequently selected candidates next, with scores that decay over time
Length — remaining candidates sorted by string length (shorter first)

Usage statistics persist across Emacs sessions via prescient-persist-mode, which writes to a save file. This means Prescient learns your habits: if you frequently run magit-status from M-x, it surfaces near the top after a few uses, regardless of where it falls alphabetically.

Prescient ships as a core library plus framework-specific adapters — vertico-prescient and corfu-prescient being the relevant ones for VOMPECCC. A key architectural insight is that both Vertico and Corfu work seamlessly with Prescient.

A common and powerful configuration combines Orderless for filtering with Prescient for sorting. Among the candidates filtered by Orderless, the most recent and frequent ones get promoted to the top.

Prescient also provides its own filtering methods (literal, regexp, initialism, fuzzy, prefix, anchored) with on-the-fly toggling via M-s prefix commands. However, I personally prefer Orderless for filtering and use Prescient purely for its sorting intelligence. I sort of act as if Prescient was cohesive in this way, rather than giving it responsibility for 2 orthogonal features.

Created: August 2017. Stars: ~695. Available on: MELPA.

9. Embark: The Action Layer embark actions

Embark provides a framework for performing context-aware actions on "targets" — the thing at point or the current completion candidate. Think of it as a keyboard-driven right-click context menu that works everywhere in Emacs: in the minibuffer and in normal buffers.

The core command is embark-act. When invoked, Embark determines the type of the target (file, buffer, URL, symbol, command, etc.) and opens a keymap of single-letter actions appropriate to that type:

Target	Example actions
File	Open, delete, copy, rename, byte-compile, open as root
Buffer	Switch to, kill, bury, open in other window
URL	Browse, download, copy
Symbol	Describe, find definition, find references
Package	Install, delete, describe, browse homepage

There are over 100 preconfigured actions across all target types.

Beyond embark-act, Embark provides several other capabilities:

embark-dwim runs the default action without showing the menu
embark-act-all applies the same action to every current candidate (e.g., kill all matching buffers)
embark-collect snapshots current candidates into a persistent buffer
embark-live creates a live-updating collection that refreshes as you type
embark-export exports candidates into the appropriate Emacs major mode: file candidates become a Dired buffer, grep results become a grep-mode buffer (editable with wgrep), buffer candidates become an Ibuffer buffer
embark-become switches to a different command mid-stream, transferring your input

Two of these deserve special attention, because they change what a completion session is.

embark-collect freezes the current candidate set into a standalone buffer that persists after the minibuffer exits. This converts an ephemeral interaction (browse, pick, leave) into something durable (collect, hand off, revisit later). The collected buffer remains an Embark target, so the same keymap of actions applies to each entry. It is the right tool when the candidate list itself is the useful artifact: a shortlist of files to process, a set of buffers you want to act on later, a reference you want to keep open on the side.

embark-export goes one step further: instead of a generic candidate buffer, it materializes a buffer in the native major mode appropriate to the candidate type. File candidates become a Dired buffer, with Dired's decades of filesystem operations available. Grep-style candidates become a grep-mode buffer that wgrep can turn into a multi-file editing session, buffer candidates become Ibuffer, package candidates become the package menu, etc…. Each export targets a major mode purpose-built for the candidate type, so you end up inside the tool that was already the best one for the job, arrived at on demand, from a completion prompt, with no navigation overhead. Few interaction patterns in computing convert generic into specialized this cleanly.

Embark is a difference of kind, not quantity, compared to Helm and Ivy's action systems — because it works everywhere, across all types of objects⁹.

Using embark and consult together we can see a canonical example of this pattern: exporting consult-ripgrep results gives you a wgrep-editable grep buffer, so the workflow — search with Consult, export with Embark, edit with wgrep — compounds three independent packages into a multi-file refactor tool without any of them knowing about the others.

Created: May 2020. Stars: ~1,200. Available on: GNU ELPA.

10. Consult: The Command Layer consult commands

Consult provides 50+ enhanced commands built on completing-read. It is the spiritual successor to Counsel (from the Ivy ecosystem) but designed to work with any completion UI. Where Counsel called ivy-read directly, Consult uses the native contract, which means its commands work with Vertico, Icomplete, fido-mode, or even Emacs's default completion buffer.

Consult's commands span several categories:

Search:

Command	Purpose	Replaces
`consult-line`	Search lines in current buffer	Swiper
`consult-line-multi`	Search across multiple buffers	Swiper-all
`consult-ripgrep`	Async ripgrep search	`counsel-rg`
`consult-grep`	Async grep search	`counsel-grep`
`consult-git-grep`	Git-aware grep	`counsel-git-grep`
`consult-find`	Async file finding	`counsel-find`

Navigation:

Command	Purpose	Replaces
`consult-buffer`	Enhanced buffer switching	`helm-mini`
`consult-imenu`	Flat imenu with grouping	`helm-imenu`
`consult-outline`	Navigate headings with preview	Built-in
`consult-goto-line`	Goto line with live preview	Built-in
`consult-bookmark`	Enhanced bookmark selection	Built-in
`consult-recent-file`	Recent file selection with preview	`counsel-recentf`

Editing and miscellaneous:

Command	Purpose
`consult-yank-from-kill-ring`	Browse kill ring interactively
`consult-theme`	Preview themes before applying
`consult-man`	Async man page lookup
`consult-flymake`	Navigate Flymake diagnostics
`consult-org-heading`	Navigate org headings

Three features make Consult particularly powerful:

Live preview: Most commands show a real-time preview as you navigate candidates. consult-line highlights the matching line in the buffer. consult-theme applies the theme before you select it. consult-goto-line scrolls to the line as you type the number.

Narrowing and grouping: consult-buffer combines buffers, recent files, bookmarks, and project items into a single unified list. Narrowing keys filter to a single source: b SPC for buffers, f SPC for files, m SPC for bookmarks. Custom sources can be added via consult-buffer-sources.

Two-level async filtering: Commands like consult-ripgrep split input at #: everything before it goes to the external tool as the search pattern, everything after it filters the results locally with your completion style. error#handler searches for "error" with ripgrep, then narrows to results containing "handler" using Orderless. Async support is an enormously important feature, because it makes the cognitive cost of search roughly constant with respect to the size of the search space.

Created: November 2020. Stars: ~1,600. Available on: GNU ELPA.

11. Corfu: The In-Buffer Display Layer corfu completion

Corfu (COmpletion in Region FUnction) is simply the in-buffer counterpart to Vertico. Where Vertico handles minibuffer completion display, Corfu handles the popup that appears at point when you complete a symbol while writing code or text. It is roughly 1,220 lines of code.

Corfu's defining architectural choice mirrors Vertico's: it hooks into Emacs's built-in completion-in-region mechanism rather than inventing its own backend system. Any mode that provides a completion-at-point-function (Eglot, Tree-sitter, elisp-mode, etc.) works with Corfu automatically. Any completion-style (basic, partial-completion, orderless) can be used for filtering.

This is the fundamental difference from Company, the incumbent in-buffer completion framework¹⁰. Company uses its own proprietary company-backends API. Company backends don't work with completion-at-point, and Capfs don't work with Company (without an adapter). Anecdotally, I've had many wrestling matches with Company and always found it incredibly difficult to set up properly. Corfu eliminates this split. Doom Emacs recognized this: Company is now deprecated in Doom in favor of Corfu, with plans to remove it post-v3¹¹.

Aspect	Company	Corfu
Backend system	Proprietary	Emacs-native Capfs
Popup technology	Overlays	Child frames
Completion styles	Limited	Any Emacs style
Codebase size	Many files, 3,900+ LOC in main file	Single file, ~1,220 LOC
Created	2009	2021

Corfu ships with seven built-in extensions:

Extension	Purpose
`corfu-echo`	Brief candidate documentation in the echo area
`corfu-history`	Sort by selection history/frequency
`corfu-indexed`	Select candidates by numeric prefix argument
`corfu-info`	Access candidate location and documentation
`corfu-popupinfo`	Documentation popup adjacent to the completion menu
`corfu-quick`	Avy-style quick key selection

Created: April 2021. Stars: ~1,400. Available on: GNU ELPA.

12. Cape: The In-Buffer Backend Layer cape backends

Cape (Completion At Point Extensions) provides a collection of modular completion backends (Capfs) and a powerful set of Capf transformers for composing and adapting them. If Corfu is the frontend (how completions are displayed), Cape is the backend toolkit (what completions are available).

Cape provides 13 completion backends, here are some highlights:

Capf	Purpose
`cape-dabbrev`	Dynamic abbreviation from current buffers
`cape-file`	File path completion
`cape-elisp-block`	Elisp completion inside Org/Markdown blocks
`cape-keyword`	Programming language keyword completion
`cape-history`	History completion in Eshell/Comint

The remaining backends cover dictionary words, emoji, abbreviations, line completion, and Unicode input via TeX, SGML, and RFC 1345 mnemonics.

Cape's Capf transformers are higher-order functions that wrap and modify backends:

cape-capf-super merges multiple Capfs into a single unified source
cape-capf-case-fold adds case-insensitive matching
cape-capf-inside-code / cape-capf-inside-string / cape-capf-inside-comment restrict activation to specific syntactic regions
cape-capf-prefix-length requires a minimum prefix before activating
cape-capf-predicate filters candidates with a custom predicate
cape-capf-sort applies custom sorting

The cape-company-to-capf adapter converts any Company backend into a standard Capf, without requiring Company to be installed. This bridges the two ecosystems: you can use Company-era backends (like company-yasnippet) with Corfu. I don't personally do this, but you can if you want!

Created: November 2021. Stars: ~760. Available on: GNU ELPA.

13. The Subset Property: Use What You Want modularity flexibility

The most important property of VOMPECCC is that you don't need to buy into all eight packages. You can start with one, add another when you feel a gap, and swap any component for an alternative without breaking anything else.

If you're into inverting dependencies, VOMPECCC is your bag, man.

This works because every package communicates through the native Emacs APIs rather than depending on each other's internals. There are no hard dependencies between any of the eight packages. Here is a map of what each package can be replaced with — or simply omitted:

Package	Alternative	Or simply…
Vertico	Icomplete-vertical, Mct, Ido, fido-mode	Default `Completions` buffer
Orderless	Hotfuzz, Fussy, Prescient (filtering mode)	Built-in `flex` or `substring`
Marginalia	(none equivalent)	No annotations (still works)
Prescient	`savehist-mode` + `vertico-sort-override`	Alphabetical sorting
Embark	(none equivalent)	Direct command invocation
Consult	Built-in `switch-to-buffer`, `grep`, etc.	Standard Emacs commands
Corfu	Company, `completion-preview-mode`	Default `Completions` buffer
Cape	Company backends, `hippie-expand`	Mode-provided Capfs

Some practical subset configurations:

Minimal (2 packages): Vertico + Orderless. You get a vertical candidate list with multi-component matching. No annotations, no actions, no enhanced commands — but a dramatically better M-x and find-file experience than stock Emacs.

Comfortable (4 packages): Vertico + Orderless + Marginalia + Consult. Now you have annotations on every candidate and enhanced commands with live preview. This is probably the sweet spot for most users.

Full stack (8 packages): All of VOMPECCC. Complete coverage of both minibuffer and in-buffer completion, with intelligent sorting, contextual actions, and modular backends.

For concrete configuration, the most reliable starting point is each package's own repository — every package linked in the opener ships a comprehensive README with example use-package snippets, and most also provide wikis or info manuals covering more specialized use cases (Vertico's per-command vertico-multiform patterns, Cape's Capf transformer recipes, Embark's keymap customization examples, Consult's custom sources, and so on). Reading those directly is faster than copying a consolidated configuration and then reverse-engineering what each line does, and it scales better as the packages themselves evolve.

14. Growth and Adoption Timeline timeline adoption

The history of Emacs completion frameworks is a progression from monolithic solutions toward composable ones.

Year	Event
1996	Kim F. Storm begins Ido
2007	Ido included in Emacs 22; `anything.el` created (Helm's ancestor)
2011	Volpiatto forks `anything.el` as Helm
2013–2018	Helm's golden era: most-downloaded MELPA package, default in Spacemacs
2015	Krehel creates Ivy/Swiper/Counsel
2016	"From Helm to Ivy" blog post sparks migration; Ivy peaks ~2016–2020
2017	Rosborough creates Prescient
2018	Helm enters bug-fix-only mode (maintainer burnout)
2019	Rosborough creates Selectrum (first `completing-read`-native UI)
2020 Apr	Antolin Camarena creates Orderless
2020 May	Antolin Camarena creates Embark
2020 Sep	Helm development officially stopped
2020 Nov	Mendler creates Consult
2020 Dec	Antolin Camarena & Mendler create Marginalia
2021 Apr	Mendler creates Vertico and Corfu
2021 May	"Replacing Ivy and Counsel with Vertico and Consult" (System Crafters)
2021	Selectrum deprecated in favor of Vertico; Doom Emacs adds Vertico module
2021 Nov	Mendler creates Cape
2022	Doom Emacs switches default completion from Ivy to Vertico
2024	Ivy breaks with Emacs 30; Company deprecated in Doom in favor of Corfu

Helm and Ivy accumulated stars over a longer period; the newer packages are growing faster relative to their age (counts as of early 2026):

Package	Stars	Created	Approx. age
Helm	~3,500	2011	15 years
Ivy/Swiper	~2,400	2015	11 years
Vertico	~1,800	April 2021	5 years
Consult	~1,600	Nov 2020	5 years
Corfu	~1,400	April 2021	5 years
Embark	~1,200	May 2020	6 years
Orderless	~979	April 2020	6 years
Marginalia	~919	Dec 2020	5 years
Cape	~760	Nov 2021	4 years
Prescient	~695	Aug 2017	9 years

The community momentum is clear. Doom Emacs, one of the most popular Emacs distributions, has moved to Vertico + Corfu as its defaults¹². Modern configuration guides almost universally recommend the modular stack¹³. And the upstream Emacs project itself has been integrating ideas from this ecosystem: Emacs 30 added completion-preview-mode, and Emacs 31 is incorporating Mct-inspired features (they love Prot, and for good reason, lol).

15. The Trade-Off: Monolith vs. Composition tradeoffs analysis

Engineering is about trade-offs. The modular approach has real advantages, but it does have costs, so I want to be honest about them:

15.1. Advantages of VOMPECCC

No vendor lock-in. Every package builds on the same native contracts. If any one of the eight packages is abandoned, you replace it. Your other packages continue to work. Contrast this with Helm, where the maintainer's burnout announcement stranded an entire ecosystem of downstream packages.

Independent maintenance. Three different developers maintain the eight packages. Daniel Mendler maintains five (Vertico, Consult, Corfu, Cape, and co-maintains Marginalia), so the overall bus factor is not dramatically higher than a monolith. But the key difference is structural: if Mendler stepped away, the remaining packages would continue to function independently. Omar Antolin Camarena's Embark and Orderless would keep working. Radon Rosborough's Prescient would keep working. Nobody's contribution is stranded by someone else's absence.

Incremental adoption. You start with one package and add more as you discover needs. There is no cliff of initial configuration. You never need to understand all eight before getting value from any one.

Smaller, auditable codebases. Vertico is ~600 lines. Corfu is ~1,220 lines. These are packages you can actually read end to end. Bugs are easier to find and fix in small, focused codebases.

Automatic ecosystem benefits. Because everything uses the native completion protocol, third-party packages benefit for free. Any command that calls completing-read gets your chosen UI, filtering, sorting, annotations, and actions without any integration code.

Future compatibility. Emacs itself continues to improve its built-in completion system. Packages built on the native protocol benefit from those improvements automatically. Packages built on proprietary APIs do not.

15.2. Disadvantages of VOMPECCC

Higher initial discovery cost. A newcomer searching "Emacs completion" finds eight packages instead of one. Understanding the role of each, and which subset to start with, requires more research than "install Helm" or "install Ivy." The conceptual overhead is non-trivial.

Configuration across packages. Eight packages means eight use-package declarations, eight sets of configuration variables, and eight places where something could be misconfigured. Helm's all-in-one approach means one declaration, one set of variables, one source of truth.

Interaction effects. While the packages are independent, some combinations require awareness of how they interact. Combining Orderless with Prescient requires understanding that Orderless handles filtering while Prescient handles sorting. The embark-consult integration package exists because the two packages benefit from knowing about each other in specific workflows.

Less out-of-the-box polish. Helm ships with dozens of purpose-built commands. With VOMPECCC, you compose those workflows yourself. The result is often more powerful, but you build it rather than unwrap it.

Documentation is distributed. Each package has its own README, its own issue tracker, its own wiki. There is no single "VOMPECCC manual." Cross-cutting workflows (search with Consult, export with Embark, edit with wgrep) are documented across multiple repositories.

15.3. When to Choose What

Choose VOMPECCC if:

You value understanding your tools and want to read the source code
You want completion that works identically with built-in and third-party commands
You want to invest incrementally rather than all at once
You care about long-term maintainability and Emacs version compatibility
You want to mix and match components as your needs evolve

Consider Helm if:

You want maximum out-of-the-box functionality with minimal configuration
You prefer a single point of documentation and support
You are comfortable depending on a single package and its API
You need one of Helm's highly specific, purpose-built features (like helm-top or helm-colors) and don't want to replicate them
You think Thierry is a cool dude (he is)

Consider Ivy if:

You are already invested in the Ivy ecosystem with custom ivy-read code
You prefer Ivy's action selection UX
You need Spacemacs's Ivy layer specifically
You think Oleh is a cool dude (he is)

For new configurations today, the community consensus points strongly toward the modular stack. Doom Emacs's switch to Vertico and Corfu, the deprecation of Selectrum, and the ongoing maintenance challenges of both Helm and Ivy have made the direction clear. The question is no longer whether to use the modular approach, but which subset to start with.

16. Conclusion conclusion

I came to this stack the way most people probably do: one package at a time, over the course of a year or so. I started with Vertico and Orderless because my Ivy config had started fighting with Emacs 28 upgrades and I was tired of debugging someone else's ivy-read edge cases. Two packages, ten minutes of configuration, and M-x already felt better. Marginalia came next for me. Once you've seen keybindings and docstrings next to every command, you can't unsee their absence. Consult replaced Counsel, Embark replaced the "type search string, exit completion, run a different command" waltz, and Corfu replaced Company when I realized the same Orderless filtering I'd grown to depend on in the minibuffer wasn't available in my code buffers.

The whole migration happened very incrementally, which was incidental for me, but is the point of this post. I never sat down to "install VOMPECCC." I solved one friction at a time, and each solution composed with the ones I already had. That's the experience the architecture is designed to produce.

Nobody really calls it VOMPECCC in Emacs circles, it is a mnemonic used here for the sake of an article rather than an established term. But the packages it describes have quietly become the default recommendation for modern Emacs completion, adopted by Doom Emacs, recommended by Protesilaos Stavrou¹⁴, documented by System Crafters¹⁵, and built on by a growing ecosystem of third-party packages.

The shift from Helm to Ivy to the modular stack follows a familiar pattern in software: monoliths are convenient until they aren't. Composable tools with clear interfaces outlast the frameworks that try to be everything¹⁶. Emacs figured this out forty years ago, and the modular stack described here is what completion looks like once you treat it as a substrate, the raw material on top of which you build Incremental Completing Read interactions, rather than as a finished product the vendor hands you. Its completion ecosystem just needed a few years to catch up.

17. TLDR tldr

Emacs completion is not one problem but at least six orthogonal concerns: display, filtering, sorting, annotation, actions, and in-buffer completion. For a decade, Helm and Ivy delivered excellent experiences but bundled everything behind proprietary APIs, creating vendor lock-in and maintenance fragility. VOMPECCC names eight independent packages — Vertico, Orderless, Marginalia, Prescient, Embark, Consult, Corfu, and Cape — that each address a single concern and compose through Emacs's native completing-read contract rather than custom APIs. Because no package depends on another's internals, any subset works on its own and any component can be replaced without breaking the rest. The community has moved decisively toward this modular stack, with Doom Emacs switching its defaults to Vertico and Corfu. There are real trade-offs — higher discovery cost and distributed configuration — but the architecture pays off in durability, auditability, and incremental adoption.

18. socials

Footnotes:

Sacha Chua's interview with Thierry Volpiatto (2018) provides a candid account of Helm's history. Volpiatto describes being a mountain guide with no programming background, discovering Linux in 2006, and gradually becoming Helm's sole maintainer. He also discusses the financial unsustainability of maintaining a package used by hundreds of thousands of users as a volunteer.

Helm accumulated over 640,000 downloads on MELPA, making it the most downloaded package on the archive at its peak. MELPA download counts are visible on the MELPA package page. The figure is cumulative since MELPA began tracking downloads in 2013.

Volpiatto's 2020 announcement (GitHub Issue #2386) was definitive: "Helm development is now stopped, please don't send bug reports or feature request, you will have no answers." The issue was locked to collaborators. The Hacker News discussion that followed highlights the difficulty of sustaining large open-source projects without institutional support.

⁴

The ivy-read signature can be inspected in ivy.el on GitHub. The Selectrum README (radian-software/selectrum) provides a detailed comparison of ivy-read with completing-read and explains why the deviation from the standard API created long-term maintainability problems.

⁵

McIlroy's articulation of the Unix philosophy appears in the Bell System Technical Journal's 1978 special issue on Unix (available at archive.org). The full quote is: "Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new 'features'." See also Eric S. Raymond's The Art of Unix Programming, Chapter 1, which elaborates on the philosophy's implications for software design.

⁶

The completing-read API is documented in the Emacs Lisp Reference Manual. The key design insight is that completing-read supports programmatic completion tables — functions that can compute candidates lazily based on the current input — which is essential for large or dynamic candidate sets like TRAMP hosts or LSP symbols.

⁷

Emacs's completion styles system is documented in the GNU Emacs Manual. The variable completion-styles controls which matching strategies are tried, in order, until one produces results. The completion-category-overrides variable allows per-category customization, so file completion can use partial-completion while M-x uses orderless.

⁸

ivy-rich (Yevgnen/ivy-rich) was a popular Ivy extension that added columns of information to Ivy completion candidates — essentially the same concept as Marginalia. The key limitation was that it was structurally coupled to Ivy: if you switched away from Ivy, you lost your annotations. Marginalia solves the same problem through the standard annotation-function API, making it framework-agnostic.

⁹

This characterization comes from Karthinks's "Fifteen Ways to Use Embark", one of the most comprehensive third-party guides to the package. The post demonstrates workflows that were impossible or impractical before Embark: acting on multiple candidates simultaneously, exporting completion results into native Emacs modes, and switching commands mid-stream without losing context.

¹⁰

Company-mode (company-mode/company-mode) was created by Nikolaj Schumacher in 2009 and has been maintained by Dmitry Gutov since 2013. It remains actively maintained with ~2,300 GitHub stars. The architectural critique here is specific to the backend API: company-backends is a separate protocol from completion-at-point-functions, which means backends written for Company don't work with other completion UIs, and vice versa.

¹¹

The Doom Emacs Corfu module was merged in PR #7002 in March 2024. The Discourse discussion explains the rationale: Corfu aligns with Emacs's native completion infrastructure, while Company's proprietary API creates friction with the rest of the modern completion stack.

¹²

Doom Emacs's completion modules are documented at docs.doomemacs.org. The Vertico module includes pre-configured integration with Orderless, Marginalia, Consult, and Embark. The older Ivy and Helm modules remain available but are no longer the recommended default.

¹³

Notable guides recommending the modular stack include: Martin Fowler's "Improving my Emacs experience with completion" (2024), which documents his switch to the Vertico ecosystem; the "Guide to Modern Emacs Completion" by Jonathan Neidel, which walks through the full Vertico/Corfu stack; and Kristoffer Balintona's multi-part "Vertico, Marginalia, All-the-icons-completion, and Orderless" series (2022).

¹⁴

Protesilaos Stavrou's "Emacs: modern minibuffer packages (Vertico, Consult, etc.)" is a ~44 minute video demonstrating the full stack. Stavrou is also the author of Mct (Minibuffer and Completions in Tandem), an alternative approach that reuses the built-in *Completions* buffer with automatic updates. His recommendation of Vertico despite having written a competing package speaks to the strength of the ecosystem.

¹⁵

System Crafters' "Streamline Your Emacs Completions with Vertico" and the companion video "Replacing Ivy and Counsel with Vertico and Consult" (May 2021) were early catalysts for community adoption. David Wilson (System Crafters) documented his own migration from Ivy and provided configuration examples that became widely copied.

¹⁶

The pattern of monoliths giving way to composable architectures is well-documented in software engineering. Fred Brooks described the "second system effect" in The Mythical Man-Month (1975), where the follow-up to a successful lean system tends to be an overdesigned monolith. More recently, the microservices movement explicitly applies the Unix philosophy to distributed systems — with similar trade-offs around discovery cost, operational complexity, and distributed debugging.

Completion is a Substrate, not a UI

Charlie Holland — Tue, 14 Apr 2026 12:22:00 GMT

1. About emacs completion ux

Figure 1: JPEG produced with DALL-E 3

ICR is not a convenience feature. It is a structural change in how the cost of an interaction scales with the size of the underlying data.

The argument I want to make is sharper than it sounds. Incremental completing read (ICR) is not a convenience feature. It is a structural change in how the cost of an interaction scales with the size of the underlying data; it is one of the few interface patterns that genuinely respects how human memory works; and it can fortuitously change how you organize your data, not just how you retrieve it.

A brief thought exercise reveals how a surprisingly large fraction of all software — email, calendars, file browsers, music players, issue trackers, package managers — is, at its core, just two primitives: 1) pick a thing, 2) act on it. That is the exact shape ICR was built for, and most of the visual chrome we drape around those primitives is decoration.

This matters concretely because very few environments expose completion as a programmable substrate¹ you can build ICR experiences with, rather than as a sealed UI you can only consume. In everything else you use, the candidate sources, the matcher, the sorter, the annotator, and the available actions are largely fixed by the vendor or aren't even available. On the other hand, in Emacs and the shell, every layer is independently replaceable. Taking your completion stack seriously is among the highest-leverage things an Emacs user can do, on the same scale as customizing your shell, and for the same reasons. Done right, ICR can dramatically reduce the cognitive overhead of using your computer to do almost anything.

This post opens a short series on ICR. The remaining two posts get concrete: a breakdown of the modular completion framework I use day to day, and a case study of an entire Spotify client that is just an ICR application. The goal of this opening piece is to convince you that ICR is worth your rigor, and to give you the conceptual vocabulary to recognize how much of your own software experience already runs on it.

2. What is Incremental Completing Read? ICR HCI

"Incremental Completing Read" has three load-bearing words:

Read, in the elisp sense: a function that prompts the user and returns a value. The system asks a question, you answer, and then the answer is something other code can do something with.

Completing: the system maintains a candidate set and shows you which candidates currently match your input. You don't type the full answer. You type enough to disambiguate, and the system fills in the rest.

Incremental: the candidate set is recomputed on every keystroke². You don't submit a query and wait for results. Filtering happens between characters, fast enough that the result list feels like an extension of what you're typing.

Combine the three words and you get an interaction that is qualitatively different from either browsing or searching. Browsing scales poorly to large sets — you can scan a list of ten things, not a list of ten thousand. Search-and-submit scales fine in the back end but introduces a feedback gap that breaks flow. ICR fuses the two.

A clarification before going further. In Emacs, the standard-library function named completing-read is not, on its own, incremental. It TAB-completes at the minibuffer and shows a *Completions* buffer on demand. The incremental UX described above is layered on top by a separate generation of frontends like Icomplete, Ido, Ivy, Helm, and the modern Vertico. Throughout this series, "ICR" refers to the pattern (the API plus an incremental frontend), not to any single function. This separation matters because it makes the Emacs completion stack pluggable, and this separation is the subject of the next post in the series.

3. The ubiquity of ICR ux

Think about all the places you already use ICR. Here's a partial inventory:

The browser URL bar narrows history and bookmarks as you type.
Search engines suggest queries character by character.
Spotify, Apple Music, and YouTube surface tracks, artists, and videos as you fill in the search box.
Amazon's product search shows partial matches and category filters live.
IDEs offer symbol completion, file navigation, and command palettes. Think VS Code's Cmd-Shift-P, JetBrains' "Search Everywhere," GitHub's file finder, Sublime Text's "Goto Anything."
Shell users reach for fzf to fuzzy-find files, branches, processes, and command history.
Slack jumps to channels by typing fragments of the name.
Even mobile keyboards suggest the next word as you tap³!

These look like different tools, but when you think about it they are the same interface. Each one accepts a stream of keystrokes, runs an incremental query against a sometimes enormous candidate set, and surfaces the best matches in real time, as you type. Across all these apps, your interaction pattern is the same: you type fragments, watch a candidate list list narrow, and then pick from what survives the narrowing.

ICR has become the lingua franca of navigation.

The pattern is so ubiquitous that its absence now feels strange to me. File pickers that only show a tree, settings panels with no search box, and configuration UIs where you have to remember the menu hierarchy all force me to slow down and then manually browse through candidate sets to find what I'm looking for. These feel like artifacts of an earlier era — the era before incremental completing read became a common default for how humans navigate sets of named things. Today, it feels like ICR has become the lingua franca of navigation.

4. A thought exercise: how much of computing fits inside ICR? composition shell HCI

If you take anything away from this post, let it be what follows in this section. This realization is what makes Emacs legible to its power users:

We've seen where ICR shows up in the previous section, but where else can we use it? Run an inventory of the interfaces you use daily, and for each one, ask: at its core, is this just pick a thing from a set, then do something to it?

Email: pick a message; reply, archive, forward, delete.
Calendar: pick an event; accept, reschedule, open.
File browser: pick a file; open, rename, delete, move.
Issue tracker: pick an issue; assign, comment, close.
Music player: pick a track; play, queue, save.
Package manager: pick a package; install, remove, inspect.
Git client: pick a branch; checkout, merge, rebase, delete.
Cloud console: pick a resource; start, stop, configure, destroy.

The list grows uncomfortably long. It turns out that a surprising fraction of all interactions with your sofware uses the same two primitives: a source of candidates and a set of actions you can perform on a set of selected candidate. Most of the visual chrome we drape around these primitives is decoration.

It turns out that a surprising fraction of all interactions with your sofware uses the same two primitives: a source of candidates and a set of actions you can perform on a set of selected candidate. Most of the visual chrome we drape around these primitives is decoration.

Now that you've seen the light, your next move is to ask whether you can chain these. Consider navigating files in a project: ICR to pick a project, which scopes the candidate set to its files; ICR to pick a file, which scopes the actions to its file type; ICR to pick an action, which produces a new candidate set, and so on…. An interaction model built from selecting and acting can be composed into arbitrarily complex workflows, the same way any other small set of orthogonal primitives can.

Shell users already know this composition story well. For most shell users, fzf drives ICR and produces selections. Pipes feed those selections into commands. Commands produce new selections which can be piped back into fzf for more ICR, and so on…. git branch | fzf | xargs git checkout is the pattern in miniature: a candidate source, a selector, an action, all chained. fd | fzf | xargs $EDITOR is the same shape with a different source. Build a few dozen of these one-liners and you have a personal interface to your filesystem, your version control history, your processes, your network, without anyone shipping you that interface. That's powerful!

The interesting, and frustrating, observation is how rare this is composability and feature-richness is where ICR interfaces exist. Spotify will never let you redefine what "select a track" can do. Gmail's search cannot pipe its selected results into your own actions. Some environments come closer than others — Neovim's Telescope, Raycast's extension API, VS Code's QuickPick — but in each of them at least one of the layers (the matcher, the sorter, the annotator, the action set) is fixed by the vendor. Few environments expose every layer, and only Emacs and the shell expose them independently, so that you can swap one without disturbing the others.

This is the difference between using ICR and building ICR, and it is what makes Emacs and the shell uniquely powerful for anyone who works inside them all day. Personally, this is the main reason why I live in Emacs and the shell.

5. The cognitive cost argument cognitiveStrain

Software engineers have a precise vocabulary for talking about how algorithms scale: time complexity, space complexity, big-O notation. The corresponding field for how interfaces scale is human-computer interaction (HCI), which has its own established vocabulary — Hick-Hyman's Law, Fitts's Law, working-memory load, recognition vs. recall — but engineers rarely reach for it. The argument that follows borrows from both sides, because ICR is best understood through both angles: an algorithmic property (constant-time filtering against an arbitrary corpus) producing an HCI property (constant-cost selection regardless of corpus size).

Consider the simple act of finding a file. In a tree-based file browser, the cognitive effort grows with the size of the file system. Five files in a folder is trivial, but five hundred files spread across a hierarchy is much more cognitively taxing. You have to remember where the file lives, click through directories, scan lists, scroll, and move your cursor to the selection. Add another order of magnitude — half a million files in a project — and the file browser has effectively ceased to function as a tool for finding things. Cognitively, this approach scales worse than linearly.

Now do the same task with ICR. You hit your file-finder binding, type a fragment of the name you remember, watch the list narrow to a handful of plausible matches, and pick one. The experience is the same whether your project contains fifty files or fifty thousand. The interface does not get harder to use as the candidate set grows.

ICR breaks the linkage between the size of the world and the difficulty of finding something in it.

It is tempting to call this O(1) cognitive complexity, by analogy to algorithmic complexity⁴. The point is straightforward: the cost of finding something via ICR is independent of the size of the candidate set, and that independence is what the big-O analogy is reaching for. ICR breaks the linkage between the size of the world and the difficulty of finding something in it.

There is also a literature analogue worth naming. Hick-Hyman's Law⁵ models the time required for a forced choice as roughly proportional to log₂(n+1), where n is the number of equally likely alternatives. A flat menu of ten thousand commands is a Hick-Hyman nightmare; the user pays a logarithmic-in-n decision cost on every selection. ICR sidesteps the law by collapsing n before the choice step happens. By the time the user is selecting from the visible candidate panel, n is already small, typically less than half a dozen in my experience, and the per-selection decision cost is bounded by panel size rather than corpus size. We can calmly let the corpus grow without bound and we can trust that the time-to-pick stays roughly constant.

This is why ICR is not just an ergonomic nicety. It bends the curve. Most interface improvements buy you a constant factor, like a faster animation, a clearer label, or a better-organized menu. ICR changes the curve itself, and anything that changes the curve dominates the things that only change the constant, given enough data.

The corollary is that ICR's value is asymmetric across users. If your projects are tiny and your address book is short, you may never feel the difference. However, if like me you are an Emacs user with a sprawling notes directory, two decades of email, half a dozen languages installed, and a thousand interactive commands, ICR is the difference between a usable system and an unusable one. The bigger your world, the more you'll want to bend the curve.

A really key thing for me personally is the alleviation of any anxiety about the aforementioned search spaces growing. Regardless of the underlying magnitude of my emails, news articles, code repositories, music libraries, etc…, the ease of finding what I'm looking for in any given workflow is roughly constant.

6. Recognition, recall, and the third option psychology

Human-computer interaction research has long distinguished recognition (picking the right item from a presented list) from recall (producing the right item from memory)⁶. Recognition is famously easier, and this is why menus exist, why icon-based interfaces won, why "tip of my tongue" is a complaint about recall failure rather than recognition failure.

ICR sits in a strange and useful place between easy recognotion and hard recall. You don't have to recall the full item, but instead you only have to recall a fragment of it. And you don't have to recognize it from a large fixed presented list because the list narrows (often to a single candidate) in response to whatever fragment you produced. The interface meets you halfway.

This matters because the cognitive load of pure recall and the visual load of pure recognition both grow with set size. Recalling one item out of ten thousand is harder than recalling one out of ten. Recognizing one item in a list of ten thousand is harder than recognizing one in a list of ten. The hybrid form ICR offers — partial recall, then narrowing recognition — degrades much more gracefully. It is one of the few interaction primitives that gets its leverage from how human memory actually works rather than fighting it.

Cognitive psychology has a name for this hybrid: cued recall⁷. The user-typed fragment is a retrieval cue: the system uses it to materialize a small candidate set and the remainder of the task is recognition over that set. ICR is the UI instantiation of cued recall, with the screen serving as an externalized cue-to-candidate index. This is a well establish cognitive primitive, but it is rare to see an interface deploy it as deliberately as a well-tuned completion stack does.

The hybrid form ICR offers — partial recall, then narrowing recognition — degrades much more gracefully.

The best completion frameworks lean into this further. They learn your patterns. Recently selected items rise. Frequently selected items rise. The fragment you produce maps to the candidate you usually pick, not the candidate that happens to alphabetize first. The interface adapts to you. Over months, this turns into something close to muscle memory: you type a few characters and the right answer is already at the top, because that's where it has been for the last hundred selections.

7. Flat over nested: how ICR reshapes how you organize organization knowledgeManagement

The downstream effect is not just on retrieval. ICR changes the math on how you should structure your data in the first place.

In a world without ICR, hierarchy is a pretty good coping strategy. Tree-structured folders, deeply nested categories, "taxonomies" — these exist because flat lists become unscannable past a certain size. If finding things requires browsing, then organizing into a navigable tree is necessary work, but that work has real and compounding costs. You have to invent the taxonomy up front, before you know what you'll eventually want to file. Then you have to remember it later. The biggest nightmare for me personally is that with hierachies and taxonomies, I have to live with the fact that many items legitimately belong in two categories at once, yet the file system or knowledge management system forces you to pick one. I know people who are good at breaking out of this choice paralysis, but I know from experience that I am not one of them. And you incur an operational cost on every save, because every new item is a small classification problem.

The argument for nesting was always "I cannot scan a flat list of ten thousand items." ICR replies: "you do not need to scan it."

With ICR, hierarchy becomes optional. The argument for nesting was always "I cannot scan a flat list of ten thousand items." ICR replies: "you do not need to scan it." A flat directory plus tags plus links is sufficient, because ICR makes any individual item findable in a few keystrokes regardless of how many neighbors it has.

It is worth being precise about what ICR replaces and what it doesn't. Hierarchy does at least two distinct jobs. One is retrieval: helping you find a thing. The other is explanation: encoding kind-of and part-of relationships, conferring landmark structure on a space, making the shape of a domain legible at a glance. Cognitive psychology has long identified the latter as load-bearing. Eleanor Rosch's work on basic-level categories⁸ showed that hierarchical taxonomies map onto how humans actually carve up the world, and Thomas Malone's classic study of how people organize their physical desks⁹ found that "filing" (hierarchical, classified) and "piling" (flat, recency-ordered) coexist for good reasons: piles support fast access to active material and files support reasoning about the shape of what you have. ICR substitutes cleanly for hierarchy's retrieval function. It does not substitute for the explanatory function. When the relationships between things are themselves the point — a code architecture, a course curriculum, a legal taxonomy — a tree is still doing real work that no completion stack will replace¹⁰.

The sleight of hand to avoid is treating "ICR makes hierarchy optional" as "hierarchy is bad." The honest, narrower claim is this: in domains where hierarchy was load-bearing only as a search affordance, ICR lets you drop it and reclaim its costs.

This is the architectural premise of denote, Protesilaos Stavrou's Emacs note-taking package. denote stores notes in a single mostly-flat directory, and although the package supports subdirectory "silos", Stavrou explicitly argues against using them as a primary organizing principle. Notes relate to each other through filename-encoded tags and explicit hyperlinks. The package leans entirely on completion to find things, and that works because finding things in a flat namespace via ICR is instantaneous. The same idea shows up in tools like Obsidian and in older personal-knowledge systems. These systems abandon of hierarchy because they trust that search interfaces to scale to larger search spaces.

Emacs itself works this way at a much larger scale. One of my all-time favorite quirks is that every interactive command lives in a single flat namespace. A mature configuration easily exposes ten thousand of them (a quick smash of M-x on my Emacs produces over 13,000 interactive commands). Nothing about this is overwhelming to me though, because I never see the full list. I just type M-x and a fragment of what I want, and the relevant commands surface. A hierarchical menu system covering ten thousand commands would be unusable; a flat namespace plus M-x is unremarkable.

In Emacs you can get this flat-list style ICR even where there are rigid hierarchies. This is critical when physical hierarchies or taxonomies are necessary (like in code repositories), but the user still wants to navigate the content without engaging with the hierarchy or taxonomy. For example, when I'm trying to find a file via ICR, I find myself reaching for something like project-find-file (show me all files in a project in a flat list) over something like find-file (let me traverse the directories one level at a time until I find my leaf).

As we've already seen, the ICR pattern generalizes really well. Any structure you build to make scanning easier is a structure ICR makes redundant. Even where these structures need to exist, ICR can still help you get around the rigidity and opacity of that structure. Once you trust your completion stack, you can shed the hierarchies you built and maintain, and you can triumphantly reclaim the cognitive and operational overhead that those hierarchies were costing you.

8. Why ICR matters more in Emacs than anywhere else emacs

The thought exercise above hands us the answer to a question this post has been circling: of the environments where ICR is genuinely programmable, why focus a series on Emacs rather than on the shell?

The shell case is well-trodden territory; Unix users have been chaining fzf and pipes for years, the design space is mostly explored, and shell users are typically introduced to the notion of ICR the second they start learning how to configure their prompt. The Emacs case is younger, deeper, and less well documented — and it is the focus of this series, so it is worth zooming in on the specific ways Emacs exposes completion as a substrate. Emacs is also less popular, so there is an air of proselytism to this post 😜.

In Emacs, every layer of the ICR interaction is pluggable. completing-read is a function in the standard library. The display is pluggable. The matching strategy is pluggable. The sorting is pluggable. The annotations are pluggable. The actions you can take on a selected candidate? Pluggable! This is all discussed in my subsequent post on the VOMPECCC composite framework.

In Emacs, every layer of the interaction is a place where you can substitute behavior, and every layer has a small ecosystem of competing implementations to choose from.

Most editors give you a completion UI. Emacs gives you a completion substrate. The difference is what you can build on top.

This is what separates Emacs from the editors that come closest. Most give you a completion UI; Emacs gives you a completion substrate. From an HCI standpoint, what is unusual about Emacs is not the completion interaction itself — the visible behavior is broadly similar to Telescope, QuickPick, or Raycast — but that the layers HCI usually treats as monolithic (matcher, sorter, annotator, action set, display surface) are exposed as independent surfaces. Those other tools let you produce candidates and bind actions, but the matcher, the sorter, the annotator, and the display they hand you are largely fixed. Recently, the Emacs community has done a lot of work towards making all of these pieces independently swappable, and the resulting compositional space is qualitatively bigger. This is the reason the Emacs completion ecosystem is one of the most interesting parts of the software. Every well-designed Emacs package eventually becomes, in part, a completing-read application: a thoughtful choice of candidate source, plus annotations, plus actions, plus a UI that is already familiar because it is the same UI you use for everything else. The cost of adding a new "thing the user can pick from a list" is close to zero, and the resulting interaction inherits all of the user's existing muscle memory.

Don't treat completion as a built-in convenience you don't have to think about. Emacs ships with a working completing-read out of the box, and many users never look further. This is a tragic error on the same scale as never customizing your shell. A serious Emacs user should treat the completion stack the way a serious shell user treats prompt and history setup: as a thing worth investing in, arguably the driving HCI paradigm in the Emacs paltform. Every other piece of the system gets better when this one is good:

ICR is a simple concept, but it has really profound effects on I use Emacs. Better completion makes file finding faster. Faster file-finding changes how I organize my data. Better symbol completion changes how aggressively I refactor. Better command completion changes which commands I remember exist¹¹. Better candidate annotations change which choices I can make confidently. In addition to saving me cognition, keystrokes, and time, ICR raises the upper bound on how much of Emacs I can fluently use.

9. Where this series goes

This was all very woo-woo and hand wavy, but the next two posts get concrete.

The middle post is on VOMPECCC, a name for a loose constellation of eight Emacs packages — Vertico, Orderless, Marginalia, Prescient, Embark, Consult, Corfu, and Cape — that together compose a complete, modular completion framework along Unix-philosophy lines. Each package does one thing, and, boy, does it do it well. Most importantly, Each communicates through Emacs's standard completion APIs, making it possible for any subset of these packages to work with or without the others. That post is a technical breakdown for developers who want to either adopt the whole stack or pick the pieces that solve their specific problems.

The final post is on spot, a Spotify client built as a pure ICR application: search Spotify's catalog through consult, view catalogue metadata inline with with marginalia, and act on them with embark. It builds nothing of its own at the UI layer because it doesn't need to. Every UI primitive it requires is already there, courtesy of the framework the previous post describes. spot is a useful case study in what becomes possible when you stop treating completion as a default and start treating it as a programmable substrate.

Three posts, one argument: incremental completing read is one of the highest-leverage interaction patterns in computing, Emacs gives you uniquely deep control over it, and that control is worth using. The rest of the series is about the practical 'how'.

10. tldr

This post argues that Incremental Completing Read (ICR) — the pattern where a candidate list narrows in real time as you type — is not a convenience feature but a structural change in how interface cost scales with data size. ICR is composed of three ideas: read (prompt the user and return a value), completing (maintain and display a candidate set), and incremental (recompute matches on every keystroke). Together they produce an interaction qualitatively different from both browsing and searching.

The pattern is already ubiquitous across software you use daily — browser URL bars, search engines, music players, IDE command palettes, and shell tools like fzf all implement it. A surprising fraction of all computing boils down to two primitives: pick a thing from a set, then act on it, and these primitives compose into arbitrarily complex workflows through chaining, the way shell pipes do.

From a cognitive-science perspective, ICR breaks the linkage between corpus size and the difficulty of finding something in it. While tree-based browsing degrades with scale and Hick-Hyman's Law penalizes large choice sets, ICR collapses the visible candidate count before the choice step, keeping per-selection cost roughly constant regardless of how large the underlying data grows. ICR also occupies a unique position between recognition and recall — you supply a partial cue, the system materializes a small candidate set, and the rest is easy recognition. Cognitive psychology calls this cued recall, and well-tuned completion stacks lean into it further by learning your selection history.

Beyond retrieval, ICR reshapes how you organize data in the first place. Hierarchy was always a coping strategy for unscannable flat lists; ICR makes flat lists scannable, so hierarchies built purely as search affordances become redundant. This is the design premise behind tools like denote and Emacs's own flat M-x command namespace.

Finally, the post explains why Emacs is the focus of this series: unlike every other environment, Emacs exposes the matcher, sorter, annotator, display, and action set as independently replaceable layers, making completion a programmable substrate rather than a sealed UI. The next two posts get concrete — one on the modular VOMPECCC completion framework, and one on a Spotify client built as a pure ICR application.

Footnotes:

I use "substrate" in the sense borrowed from biology and platform engineering: a foundational layer that other things are built on, acted upon, or composed out of. In biology, an enzyme acts on a substrate; in hardware, transistors are fabricated on a silicon substrate; in platform engineering, applications run on a compute substrate like Kubernetes. In all three, the substrate is primitive, malleable, and compositional — the raw material from which or on which higher-level things are built. Applied here: Emacs hands you completion as raw pluggable parts (matcher, sorter, annotator, action, display) rather than as a finished dish. The implicit contrast is completion-as-UI: a product you consume, where the vendor has already picked every layer for you.

The obvious objection: what if the candidate set is too enormous to materialize up front? Think a grep over a large codebase, or a query against a remote API. Emacs handles this through async completion sources — consult-ripgrep is the canonical example. Each keystroke debounces and spawns a ripgrep process whose streaming output becomes the incremental candidate set; the user sees narrowing results without ever holding the full corpus in memory. The pattern generalizes: any candidate source that can be expressed as a streaming query (ripgrep, git log, a database cursor, a REST endpoint) slots into the same ICR interaction. Corpus size stops being a constraint on the interface.

This actually doesn't even require an initial search string. I have a bad joke about the iMessage word-prediction being the original ChatGPT — if you could use a chuckle, I highly suggest opening up iMessage and spamming the next predicted word and observing the sheer nonsense that comes out.

⁴

Strictly speaking, big-O describes the runtime of an algorithm, not the perceived effort of a human using a tool, and the user-facing cost of ICR is not literally constant — recalling a fragment, scanning the survivors, and choosing among them all consume real cognitive resources. The defensible claim, and the one big-O notation is reaching for, is independence from the size of the candidate set. Whether you call that "asymptotically constant cognitive cost," "sublinear effort," or just "the same work regardless of scale," the underlying observation is the same.

⁵

William E. Hick, "On the rate of gain of information," Quarterly Journal of Experimental Psychology 4(1), 1952, 11–26; and Ray Hyman, "Stimulus information as a determinant of reaction time," Journal of Experimental Psychology 45(3), 1953, 188–196. The law: choice reaction time scales as roughly k·log₂(n+1) for n equally likely alternatives. ICR's effect is to keep n (the size of the visible candidate panel) small and roughly constant even as the underlying corpus grows arbitrarily.

⁶

Jakob Nielsen, "10 Usability Heuristics for User Interface Design" (1994, periodically updated by the Nielsen Norman Group). Heuristic #6 is "Recognition rather than recall": interfaces should minimize the user's memory load by making elements, actions, and options visible, rather than requiring users to retrieve them from memory.

⁷

Endel Tulving and Zena Pearlstone, "Availability versus accessibility of information in memory for words," Journal of Verbal Learning and Verbal Behavior 5(4), 1966, 381–391. The original demonstration that retrieval cues dramatically improve recall over uncued conditions, even when the underlying item is equally "available" in memory. Tulving's framing of cued recall as a distinct mode — intermediate between free recall and recognition — is the one ICR most closely instantiates.

⁸

Eleanor Rosch, Carolyn B. Mervis, Wayne D. Gray, David M. Johnson, and Penny Boyes-Braem, "Basic objects in natural categories," Cognitive Psychology 8(3), 1976, 382–439. The basic-level finding: human categorization is not arbitrary across hierarchies but anchored at a particular middle level (chair, dog, car) that maximizes informativeness. Hierarchies are not just retrieval scaffolds; they reflect how humans naturally carve up the world.

⁹

Thomas W. Malone, "How do people organize their desks? Implications for the design of office information systems," ACM Transactions on Office Information Systems 1(1), 1983, 99–112. The classic study identifying "files" (hierarchical, classified) and "piles" (flat, recency-ordered) as coexisting strategies, each well-suited to different parts of the same workflow.

¹⁰

The counterargument here would be that tags and hyperlinks would give you the same thing, but the point here is that often times a PHYSICAL hierarchy, like the organization of files in a directory, is needed and will be unavoidable.

¹¹

I find it interesting that alleviating the burden of memory of a large search space actually improves my memory for the things that are actually important.

Live Life on the Edge: A Layered Strategy for Testing Data Models

Charlie Holland — Tue, 07 Apr 2026 08:17:00 GMT

1. About dataModelling testing orgMode literateProgramming

Figure 1: JPEG produced with DALL-E 4o

Data models live everywhere in a modern system: function signatures, bounded-context boundaries, database schemas, event payloads on the wire, etc…. And for good reason – the model isn't just a schema – it's an executable specification of how the system works. The criticality of data modelling has led to its ubiquity, and you will find a daunting proliferation of models throughout your software system, especially if you work in an enterprise where bias towards classic integration patterns urge developers to exhaustively model every payload and interface in the system. I call this the 'Model Everywhere Problem'.

But if models are so great, why is their pervasiveness a 'problem'?

Consider that a modest data model – a dozen fields, a few enums and optionals – has thousands of structural states. This set of a permissible instances is the model's 'state space', and large state spaces put demand on your testing suite (state space correlates with number of test cases).

On every engineering team I've worked on, I've noticed that these state spaces are almost never tested exhaustively, and instead only a few hardcoded instances of a model's possible instance are used for testing. Tragically, this causes avoidable issues once the production system begins processing real data with untested edge cases. This a problematic testing gap, and this is why the state space of a model – not just its happy path of a golden test instance – is the right unit to reason about when you write tests.

[the state space] of a model – not just its happy path – is the right unit to reason about when you write tests.

Using python as an example language, this post walks through a three-layer strategy that closes that gap, and – importantly – where each layer earns its keep and where it doesn't:

Polyfactory – automates structural partition coverage (every enum value, every optional state) without exploding into a Cartesian product
Hypothesis – probes value-level edge cases (boundary floats, unicode, NaN) with shrinking
icontract – enforces cross-field invariants that types and serializable schemas can't express

None of these tools are new. Hypothesis has been around since 2013; the ideas behind icontract (Design by Contract) date to Eiffel in 1986; equivalence partitioning and pairwise testing have been standard since Myers' Art of Software Testing. The contribution in this blog post is the layering pattern: when to reach for which tool, applied to a real scientific data model.

Versions used in this post: Python 3.11, Pydantic 2.x, Polyfactory 2.x, Hypothesis 6.x, icontract 2.x.

2. The Combinatorial Explosion Problem testing mathematics

Even modest models have enormous structural state spaces. Consider a realistic Pydantic model for a spectroscopy reading:

2.1. Growth Analysis

class SpectroscopyReading(BaseModel):
    # Required fields
    reading_id: str
    instrument_id: str

    # Optional fields
    wavelength_nm: Optional[float] = None
    temperature_K: Optional[float] = None
    pressure_atm: Optional[float] = None
    notes: Optional[str] = None

    # Enums
    sample_type: SampleType = SampleType.EXPERIMENTAL  # 3 values
    status: ReadingStatus = ReadingStatus.PENDING  # 4 values: PENDING, VALIDATED, FLAGGED, REJECTED
    instrument_mode: InstrumentMode = InstrumentMode.STANDARD  # 5 values: STANDARD, HIGH_RES, FAST, CALIBRATION, DIAGNOSTIC

    # Booleans
    is_validated: bool = True
    requires_review: bool = False
    is_replicate: bool = False

Now let's compute the combinations:

Field	States
reading_id	1
instrument_id	1
wavelength_nm	2
temperature_K	2
pressure_atm	2
notes	2
sample_type	3
status	4
instrument_mode	5
is_validated	2
requires_review	2
is_replicate	2

\[ \text{Combinations} = 1 \times 1 \times 2^4 \times 3 \times 4 \times 5 \times 2^3 = 16 \times 60 \times 8 = 7,680 \]

A handful of realistic fields produces 7,680 combinations. And this is just structural – we haven't even considered value-level edge cases (negative wavelengths, sub-absolute-zero temperatures, NaN concentrations) yet.

2.2. A Caveat: Nobody Tests the Cartesian Product

Each tool answers a question the previous one couldn't.

Before going further, the obvious objection: 7,680 combinations is not 7,680 tests you need to write. Equivalence partitioning (Myers, 1979) and combinatorial / pairwise testing (NIST has decades of work on $t$-way coverage) tell us that most "combinations" share a code path, and that 1-way and 2-way coverage catch the overwhelming majority of interaction bugs. The 7,680 number is the state space a tester has to reason about, not the number of cases to enumerate.

The point of the tools below is not brute force. Polyfactory's coverage() is essentially automated 1-way (every value of every field is exercised once); Hypothesis adds value-level probing where partition boundaries actually matter; icontract adds the cross-field rules that no equivalence partition can express. Each tool answers a question the previous one couldn't.

3. Property-Based Testing with Polyfactory testing polyfactory

Polyfactory is a library that generates mock data from Pydantic models (and other schemas). Instead of hand-writing test fixtures, you define a factory and let polyfactory generate valid instances.

3.1. Basic Usage: The Build Method

The build() method creates a single instance with randomly generated values that satisfy your model's constraints:

from polyfactory.factories.pydantic_factory import ModelFactory
from pydantic import BaseModel
from typing import Optional
from enum import Enum

class SampleType(str, Enum):
    CONTROL = "control"
    EXPERIMENTAL = "experimental"
    CALIBRATION = "calibration"

class Sample(BaseModel):
    sample_id: str
    experiment_id: str
    concentration_mM: Optional[float] = None
    sample_type: SampleType = SampleType.EXPERIMENTAL
    is_validated: bool = True

class SampleFactory(ModelFactory):
    __model__ = Sample

# Generate a random valid sample
sample = SampleFactory.build()
print(sample)

# Override specific fields
control_sample = SampleFactory.build(sample_type=SampleType.CONTROL, is_validated=True)

sample_id='aqgvWnszGSMJWogQRmWa' experiment_id='zPxKVxoDzwanDbZmhDNL' concentration_mM=None sample_type=<SampleType.CALIBRATION: 'calibration'> is_validated=False

Every call to build() gives you a valid instance. This is already powerful for unit tests where you need realistic test data without hand-crafting it.

3.2. Systematic Coverage: The Coverage Method

Here's where polyfactory really shines. The coverage() method generates multiple instances designed to cover all the structural variations of your model:

# Generate instances covering all structural variations
for sample in SampleFactory.coverage():
    print(f"type={sample.sample_type}, conc={'set' if sample.concentration_mM is not None else 'None'}, valid={sample.is_validated}")

type=SampleType.CONTROL, conc=set, valid=True
type=SampleType.EXPERIMENTAL, conc=None, valid=True
type=SampleType.CALIBRATION, conc=set, valid=False

The coverage() method systematically generates instances, but notice something important: we only got 3 instances, not the 12 we calculated earlier. This is by design.

3.2.1. How coverage() Actually Works

Polyfactory's coverage() uses a lockstep algorithm rather than a full Cartesian product. Here's how it works:

Each field gets a CoverageContainer that holds all possible values for that field (enum members, True=/=False for booleans, value=/=None for optionals)
All containers advance in parallel on each iteration – the first instance picks the first value from every container, the second instance picks the second from every container, and so on. Containers shorter than the longest one wrap around
Iteration stops when the "longest" container has been fully consumed – meaning every individual value of every field has been seen at least once

This produces a representative sample that guarantees:

Every enum value appears at least once
Both True and False appear for boolean fields
Both present and None states appear for optional fields

But it does not guarantee every combination is tested. In our 3 instances:

sample_type	concentration_mM	is_validated
CONTROL	set	False
EXPERIMENTAL	None	True
CALIBRATION	set	False

All enum values are covered. Both optional states (set/None) appear. Both boolean states appear. But we didn't test CONTROL with is_validated=True, for example. This is the deliberate trade-off: coverage() guarantees every individual value of every field is exercised, but misses interaction bugs that only manifest with specific combinations. For validation logic where fields are processed independently, that's enough. For complex interactions, supplement with targeted cases or reach for Hypothesis.

3.3. A Practical Example

Let's say we have a function that determines analysis priority based on sample attributes:

def determine_priority(sample: Sample) -> str:
    """Determine analysis priority based on sample type and validation status."""

    # Calibration samples are always high priority
    if sample.sample_type == SampleType.CALIBRATION:
        return "high"

    # Unvalidated samples need review first
    if not sample.is_validated:
        raise ValueError("Sample must be validated before analysis")

    # Control samples with known concentration get medium priority
    if sample.sample_type == SampleType.CONTROL and sample.concentration_mM is not None:
        return "medium"

    return "normal"

None

We can test this exhaustively using coverage():

import pytest

def test_priority_all_sample_variations():
    """Test priority determination across all sample variations."""
    results = []
    for sample in SampleFactory.coverage():
        if not sample.is_validated:
            try:
                determine_priority(sample)
                results.append(f"FAIL: {sample.sample_type.value}, validated={sample.is_validated} - expected ValueError")
            except ValueError:
                results.append(f"PASS: {sample.sample_type.value}, validated={sample.is_validated} - correctly raised ValueError")
        elif sample.sample_type == SampleType.CALIBRATION:
            priority = determine_priority(sample)
            if priority == "high":
                results.append(f"PASS: {sample.sample_type.value}, validated={sample.is_validated} -> {priority}")
            else:
                results.append(f"FAIL: {sample.sample_type.value} expected 'high', got '{priority}'")
        else:
            priority = determine_priority(sample)
            if priority in ["high", "medium", "normal"]:
                results.append(f"PASS: {sample.sample_type.value}, validated={sample.is_validated} -> {priority}")
            else:
                results.append(f"FAIL: {sample.sample_type.value} got invalid priority '{priority}'")
    return results

# Run the test and display results
print("Testing priority determination across all sample variations:")
print("-" * 60)
for result in test_priority_all_sample_variations():
    print(result)
print("-" * 60)
print(f"All variations tested!")

With a simple call to SampleFactory.coverage(), this single test covers every structural combination of our model. If we add new enum values or optional fields later, the test automatically expands to cover them.

3.4. The Reusable Fixture Pattern

Here's where things get powerful. We can create a reusable pytest fixture that applies this coverage-based testing pattern to any Pydantic model:

import pytest
from typing import Type, Iterator, TypeVar
from pydantic import BaseModel
from polyfactory.factories.pydantic_factory import ModelFactory

T = TypeVar("T", bound=BaseModel)

def create_factory(model: Type[T]) -> Type[ModelFactory[T]]:
    """Dynamically create a factory for any Pydantic model."""
    return type(f"{model.__name__}Factory", (ModelFactory,), {"__model__": model})

@pytest.fixture
def model_coverage(request) -> Iterator[BaseModel]:
    """
    Reusable fixture that yields all structural variations of a model.

    Usage:
        @pytest.mark.parametrize("model_class", [Sample, Measurement, Experiment])
        def test_serialization(model_coverage, model_class):
            for instance in model_coverage:
                assert instance.model_dump_json()
    """
    model_class = request.param
    factory = create_factory(model_class)
    yield from factory.coverage()

# Now testing ANY model is trivial:
@pytest.mark.parametrize("model_class", [Sample, SpectroscopyReading, Experiment])
def test_all_models_serialize(model_class):
    """Every model variation must serialize to JSON."""
    factory = create_factory(model_class)
    for instance in factory.coverage():
        json_str = instance.model_dump_json()
        restored = model_class.model_validate_json(json_str)
        assert restored == instance

This pattern is massively scalable. Add a new model to your codebase? Just add it to the parametrize list and you instantly get full structural coverage. The investment in the pattern pays dividends as your codebase grows.

4. Value-Level Testing with Hypothesis testing hypothesis

Polyfactory handles structural variations, but what about value-level edge cases? What happens when wavelength_nm is 0, or negative, or larger than the observable universe? This is where Hypothesis comes in.

Hypothesis is a property-based testing library. Instead of specifying exact test cases, you describe properties that should hold for any valid input, and Hypothesis generates hundreds of random inputs to try to break your code.

4.1. The @given Decorator

The @given decorator tells Hypothesis what kind of data to generate:

from hypothesis import given, strategies as st, settings

@given(st.integers())
@settings(max_examples=10)  # Limit for demo
def test_absolute_value_is_non_negative(n):
    """Property: absolute value is always >= 0"""
    assert abs(n) >= 0

@given(st.text())
@settings(max_examples=10)  # Limit for demo
def test_string_reversal_is_reversible(s):
    """Property: reversing twice gives original"""
    assert s[::-1][::-1] == s

# Run the tests and show output
print("Running Hypothesis tests:")
print("-" * 60)
try:
    test_absolute_value_is_non_negative()
    print("PASS: test_absolute_value_is_non_negative - all generated integers passed")
except AssertionError as e:
    print(f"FAIL: test_absolute_value_is_non_negative - {e}")

try:
    test_string_reversal_is_reversible()
    print("PASS: test_string_reversal_is_reversible - all generated strings passed")
except AssertionError as e:
    print(f"FAIL: test_string_reversal_is_reversible - {e}")
print("-" * 60)

Hypothesis will generate ~100 integers/strings per test run, including edge cases like 0, negative numbers, empty strings, unicode, etc.

4.2. The Chaos Hypothesis Unleashes

Hypothesis doesn't just generate "normal" test data – it actively tries to break your code with the most cursed inputs imaginable. Real-world string inputs are reliably worse than you imagine.

@given(st.text())
def test_sample_notes_field(notes: str):
    """What could go wrong with a simple notes field?"""
    sample = Sample(
        sample_id="test-001",
        experiment_id="exp-001",
        notes=notes  # Oh no.
    )
    process_sample(sample)

None

Hypothesis will helpfully try:

notes""= – The empty string. Classic.
notes"\\x00\\x00\\x00"= – Null bytes. Because why not?
notes"🧪🔬🧬💉"= – Your sample notes are now emoji. The lab notebook of the future.
notes"a" * 10_000_000= – Ten million 'a's. Hope you're not logging this.
notes"\\n\\n\\n\\n\\n"= – Just vibes (and newlines).
notes"ñoño"= – Unicode normalization enters the chat.
notes"🏳️‍🌈"= – A single "character" that's actually 6 code points (flag + variation selector + ZWJ + rainbow). Grapheme clusters: surprise!

Your function either handles these gracefully or you discover bugs you never knew you had. Usually the latter.

4.3. Combining Hypothesis with Pydantic

The real power comes from combining Hypothesis with our data models. Hypothesis has a from_type() strategy that can generate instances of Pydantic models:

from hypothesis import given, strategies as st
from hypothesis import settings

@given(st.from_type(Sample))
@settings(max_examples=20)  # Reduced for demo output
def test_sample_serialization_roundtrip(sample: Sample):
    """Property: serializing and deserializing preserves data"""
    json_str = sample.model_dump_json()
    restored = Sample.model_validate_json(json_str)
    assert restored == sample

# Run and show output
print("Testing Sample serialization roundtrip with Hypothesis:")
print("-" * 60)
try:
    test_sample_serialization_roundtrip()
    print("PASS: All 20 generated Sample instances serialized correctly")
except AssertionError as e:
    print(f"FAIL: {e}")
except Exception as e:
    print(f"ERROR: {type(e).__name__}: {e}")
print("-" * 60)

This test generates random valid Sample instances and verifies that JSON serialization works correctly for all of them.

4.4. Custom Strategies for Domain Constraints

Sometimes we need more control over generated values. In scientific domains, this is critical – our data has physical meaning, and randomly generated values often violate physical laws.

Let me show you what I mean with spectroscopy data:

from hypothesis import given, strategies as st, assume

# Strategy for wavelengths (must be positive, typically 200-1100nm for UV-Vis)
valid_wavelength = st.floats(min_value=200.0, max_value=1100.0, allow_nan=False)

# Strategy for temperature (above absolute zero, below plasma)
valid_temperature = st.floats(min_value=0.001, max_value=10000.0, allow_nan=False)

# Strategy for concentration (non-negative, physically reasonable)
valid_concentration = st.one_of(
    st.none(),
    st.floats(min_value=0.0, max_value=1000.0, allow_nan=False)  # millimolar
)

# Strategy for pressure (vacuum to high pressure, in atmospheres)
valid_pressure = st.floats(min_value=0.0, max_value=1000.0, allow_nan=False)

# Composite strategy with inter-field constraints
@st.composite
def spectroscopy_reading_strategy(draw):
    """Generate physically plausible spectroscopy readings."""
    wavelength = draw(valid_wavelength)
    pressure = draw(valid_pressure)

    # Domain constraint: at very low pressure, temperature readings are unreliable
    # (this is a real thing in vacuum spectroscopy!)
    # Draw temperature *conditionally* on pressure rather than drawing-then-filtering,
    # so we don't burn Hypothesis's example budget on rejected draws.
    if pressure < 0.01:
        temperature = draw(st.floats(min_value=100.0, max_value=10000.0, allow_nan=False))
    else:
        temperature = draw(valid_temperature)

    return SpectroscopyReading(
        reading_id=draw(st.text(min_size=1, max_size=50).filter(str.strip)),
        instrument_id=draw(st.sampled_from(["UV-1800", "FTIR-4600", "Raman-532"])),
        wavelength_nm=wavelength,
        temperature_K=temperature,
        pressure_atm=pressure,
        sample_type=draw(st.sampled_from(SampleType)),
        is_validated=draw(st.booleans())
    )

@given(spectroscopy_reading_strategy())
def test_reading_within_physical_bounds(reading: SpectroscopyReading):
    """Property: all readings must be physically plausible"""
    if reading.wavelength_nm is not None:
        assert reading.wavelength_nm > 0, "Negative wavelength is not a thing"
    if reading.temperature_K is not None:
        assert reading.temperature_K > 0, "Below absolute zero? Bold claim."

The key insight here is that scientific data has semantic constraints that go beyond type checking. A float can hold any value, but a wavelength of -500nm or a temperature of -273K is physically impossible. Custom strategies let us encode this domain knowledge.

4.5. Shrinking: Finding Minimal Failing Cases

One of Hypothesis's killer features is shrinking. When it finds a failing test case, it automatically simplifies it to find the minimal example that still fails. Instead of a failing case like:

SpectroscopyReading(reading_id='xK8jP2mQrS...', wavelength_nm=847293.7, temperature_K=9999.9, ...)

Hypothesis will shrink it to something like:

SpectroscopyReading(reading_id='a', wavelength_nm=1101.0, temperature_K=0.0, ...)

This makes debugging much easier – you immediately see that wavelength_nm=1101.0 (just outside our UV-Vis range) is the problem, not the giant random string.

4.6. What Hypothesis Actually Probes

The reason Hypothesis finds bugs naive random sampling misses isn't volume – it's targeting. Under the hood, st.floats() biases its draws toward values that historically break code: boundary values (min, max, just inside, just outside), zero, negative zero, the smallest positive subnormal, inf, -inf, and NaN when allowed. st.text() biases toward the empty string, single characters, surrogate pairs, and combining marks. Each strategy carries a "this is what bugs look like in this domain" prior.

Combine that with shrinking and you get the property-based testing loop: explore aggressively, fail fast, then minimise the failure to something a human can read in one line. Naive uniform random gives you neither.

4.7. When Hypothesis Isn't the Right Tool

Hypothesis is not 'free'. Specific cases where it earns its keep less:

Stateful workflows with expensive setup. If each example needs a fresh database, an HTTP fixture, or a multi-second container, 100 examples per test blows your CI budget. Use targeted cases or @reproduce_failure for regression pinning instead.
Impure code with hidden state. Shrinking assumes failures are reproducible from the shrunk input alone. If the failure depends on global mutable state, you get confusing minimised cases that don't actually fail in isolation.
Properties you can't actually state. "The function should return the right answer" is not a property. If the only oracle you have is another implementation, you have differential testing, not property testing – and that's a different (still useful) technique.
When a typed total function would do. A pure function with a tight signature and equivalence partitioning may not need a property at all. Don't reach for Hypothesis as a status symbol.

5. The Testing Gap: When Models Aren't Enough testing gaps

We've covered structural combinations with polyfactory and value-level edge cases with Hypothesis. This is powerful, but there's still a gap: runtime invariants that can't be expressed in the type system.

Consider this example from analytical chemistry:

class CalibrationCurve(BaseModel):
    readings: list[CalibrationPoint]
    r_squared: float
    slope: float
    intercept: float

    @field_validator('r_squared')
    @classmethod
    def validate_r_squared(cls, v):
        if not 0 <= v <= 1:
            raise ValueError('R² must be between 0 and 1')
        return v

None

Pydantic validates that r_squared is between 0 and 1. But what about this invariant?

The r_squared must be calculated from the actual readings using the slope and intercept.

This is a cross-field constraint – it depends on the relationship between multiple fields. And it's not just about validation at construction time. What if r_squared gets calculated incorrectly in our curve-fitting logic?

5.1. Scientific Logic Errors

Consider this function:

def recalculate_curve(curve: CalibrationCurve, new_reading: CalibrationPoint) -> CalibrationCurve:
    """Add a new calibration point and recalculate the curve."""
    all_readings = curve.readings + [new_reading]
    slope, intercept, r_squared = fit_linear_regression(all_readings)

    # BUG: accidentally swapped slope and intercept
    return CalibrationCurve(
        readings=all_readings,
        r_squared=r_squared,
        slope=intercept,  # BUG: wrong assignment!
        intercept=slope   # BUG: wrong assignment!
    )

None

This code has a subtle bug: the slope and intercept are swapped. Each field individually is a valid float, so Pydantic validation passes. But any concentration calculated from this curve will be wildly wrong.

Our Pydantic validation passes because each field is individually valid. Our Hypothesis tests might not catch this because they test properties at the data structure level, not scientific invariants.

5.1.1. Why Not Pydantic Validators?

You might be thinking: "Can't we add a @model_validator to Pydantic that checks if r_squared matches the fit?" Technically, yes:

class CalibrationCurve(BaseModel):
    # ... fields ...

    @model_validator(mode='after')
    def validate_r_squared_consistency(self) -> Self:
        # Check that r_squared matches the actual fit
        calculated_r2 = compute_r_squared(self.readings, self.slope, self.intercept)
        if abs(self.r_squared - calculated_r2) > 0.001:
            raise ValueError("R² doesn't match the fit")
        return self

But this approach has a significant drawback: custom validators don't serialize to standard schema formats¹.

In data engineering, your Pydantic models often need to export schemas for:

Avro (schema registries for Kafka)
JSON Schema (API documentation, OpenAPI specs)
Protobuf (gRPC services)
Database DDL (SQLAlchemy models, migrations)

These formats support type constraints and basic validation (nullable, enums, numeric ranges), but they have no way to represent arbitrary Python code like "R² must be computed from readings using least-squares regression."

Embedding complex validation logic in your model validators means:

The schema your consumers see is incomplete – it shows the fields but not the invariants
Other systems can't validate data independently – they must call your Python code
Schema evolution becomes fragile – changes to validation logic don't appear in schema diffs

By keeping Pydantic models "schema-clean" (only expressing constraints that can be serialized) and putting cross-field rules runtime contracts (see below), you at least keep your serialized schema honest about what it does and doesn't enforce.

This is where Design by Contract comes in.

6. Design by Contract with icontract testing icontract

icontract brings Design by Contract (DbC) to Python. DbC is a methodology where you specify:

Preconditions: What must be true before a function runs
Postconditions: What must be true after a function runs
Invariants: What must always be true about a class

If any condition is violated at runtime, you get an immediate, informative error.

6.1. Preconditions with @require

Preconditions specify what callers must guarantee:

import icontract

@icontract.require(lambda curve: len(curve.readings) >= 2, "Need at least 2 points to fit a curve")
@icontract.require(lambda new_reading: new_reading.concentration >= 0, "Concentration must be non-negative")
def recalculate_curve(curve: CalibrationCurve, new_reading: CalibrationPoint) -> CalibrationCurve:
    """Add a new calibration point and recalculate the curve."""
    all_readings = curve.readings + [new_reading]
    slope, intercept, r_squared = fit_linear_regression(all_readings)

    return CalibrationCurve(
        readings=all_readings,
        r_squared=r_squared,
        slope=slope,
        intercept=intercept
    )

None

If someone calls recalculate_curve with only one reading, they get an immediate ViolationError explaining which precondition failed.

6.2. Postconditions with @ensure

Postconditions specify what the function guarantees to return:

import icontract

@icontract.ensure(lambda result: 0 <= result.r_squared <= 1, "R² must be between 0 and 1")
@icontract.ensure(
    lambda curve, result: len(result.readings) == len(curve.readings) + 1,
    "Result must have exactly one more reading"
)
@icontract.ensure(
    lambda result: result.slope != 0 or all(abs(r.response - result.intercept) < 1e-9 for r in result.readings),
    "Zero slope only valid if all responses equal intercept"
)
def recalculate_curve(curve: CalibrationCurve, new_reading: CalibrationPoint) -> CalibrationCurve:
    """Add a new calibration point and recalculate the curve."""
    all_readings = curve.readings + [new_reading]
    slope, intercept, r_squared = fit_linear_regression(all_readings)

    return CalibrationCurve(
        readings=all_readings,
        r_squared=r_squared,
        slope=slope,
        intercept=intercept
    )

None

Now if our function produces an invalid result – even if it passes Pydantic validation – we catch it immediately.

6.3. Class Invariants with @invariant

For data models, class invariants are particularly powerful. They specify properties that must always hold:

import icontract
from pydantic import BaseModel
import numpy as np

def r_squared_matches_fit(self) -> bool:
    """Invariant: R² must be consistent with actual readings and coefficients."""
    if len(self.readings) < 2:
        return True  # Can't verify with insufficient data
    concentrations = np.array([r.concentration for r in self.readings])
    responses = np.array([r.response for r in self.readings])
    predicted = self.slope * concentrations + self.intercept
    ss_res = np.sum((responses - predicted) ** 2)
    ss_tot = np.sum((responses - np.mean(responses)) ** 2)
    calculated_r2 = 1 - (ss_res / ss_tot) if ss_tot > 0 else 1.0
    return abs(self.r_squared - calculated_r2) < 0.001  # Allow for floating point

@icontract.invariant(lambda self: len(self.readings) >= 2, "Calibration needs at least 2 points")
@icontract.invariant(r_squared_matches_fit, "R² must match actual fit quality")
class CalibrationCurve(BaseModel):
    readings: list[CalibrationPoint]
    r_squared: float
    slope: float
    intercept: float

    class Config:
        arbitrary_types_allowed = True

None

Now any CalibrationCurve instance that violates our scientific invariant will raise an error immediately – whether it's created directly, returned from a function, or modified anywhere in the system.

6.4. A Complete Example

Let's put it all together with a realistic example from a quality control workflow:

import icontract
from pydantic import BaseModel, field_validator
from typing import Optional
from enum import Enum
from datetime import datetime
import numpy as np

class QCStatus(str, Enum):
    PENDING = "pending"
    VALIDATED = "validated"
    FLAGGED = "flagged"
    REJECTED = "rejected"
    APPROVED = "approved"

class CalibrationPoint(BaseModel):
    concentration: float
    response: float
    replicate: int = 1

    @field_validator('concentration')
    @classmethod
    def validate_concentration(cls, v):
        if v < 0:
            raise ValueError('Concentration must be non-negative')
        return v

def r_squared_is_consistent(self) -> bool:
    """Invariant: R² must match the actual fit."""
    if len(self.readings) < 2:
        return True
    conc = np.array([r.concentration for r in self.readings])
    resp = np.array([r.response for r in self.readings])
    pred = self.slope * conc + self.intercept
    ss_res = np.sum((resp - pred) ** 2)
    ss_tot = np.sum((resp - np.mean(resp)) ** 2)
    calc_r2 = 1 - (ss_res / ss_tot) if ss_tot > 0 else 1.0
    return abs(self.r_squared - calc_r2) < 0.001

def approved_has_good_r_squared(self) -> bool:
    """Invariant: approved curves must have R² >= 0.99."""
    if self.status == QCStatus.APPROVED:
        return self.r_squared >= 0.99
    return True

@icontract.invariant(lambda self: len(self.readings) >= 2, "Need at least 2 calibration points")
@icontract.invariant(r_squared_is_consistent, "R² must match actual fit quality")
@icontract.invariant(approved_has_good_r_squared, "Approved curves need R² >= 0.99")
class CalibrationCurve(BaseModel):
    curve_id: str
    analyst_id: str
    readings: list[CalibrationPoint]
    slope: float
    intercept: float
    r_squared: float
    status: QCStatus = QCStatus.PENDING
    reviewer_notes: Optional[str] = None
    created_at: datetime

    class Config:
        arbitrary_types_allowed = True


# Function with contracts
@icontract.require(lambda curve: curve.status == QCStatus.PENDING,
                   "Can only validate pending curves")
@icontract.ensure(lambda result: result.status in [QCStatus.VALIDATED, QCStatus.FLAGGED],
                  "Validation must result in validated or flagged status")
def validate_curve(curve: CalibrationCurve) -> CalibrationCurve:
    """Validate a calibration curve based on R² threshold."""
    new_status = QCStatus.VALIDATED if curve.r_squared >= 0.99 else QCStatus.FLAGGED
    return CalibrationCurve(
        curve_id=curve.curve_id,
        analyst_id=curve.analyst_id,
        readings=curve.readings,
        slope=curve.slope,
        intercept=curve.intercept,
        r_squared=curve.r_squared,
        status=new_status,
        reviewer_notes=curve.reviewer_notes,
        created_at=curve.created_at
    )


@icontract.require(lambda curve: curve.status == QCStatus.VALIDATED,
                   "Can only approve validated curves")
@icontract.require(lambda reviewer_notes: reviewer_notes and reviewer_notes.strip(),
                   "Reviewer notes required for approval")
@icontract.ensure(lambda result: result.status == QCStatus.APPROVED,
                  "Curve must be approved after approval")
@icontract.ensure(lambda result: result.reviewer_notes is not None,
                  "Reviewer notes must be set")
def approve_curve(curve: CalibrationCurve, reviewer_notes: str) -> CalibrationCurve:
    """Approve a validated calibration curve."""
    return CalibrationCurve(
        curve_id=curve.curve_id,
        analyst_id=curve.analyst_id,
        readings=curve.readings,
        slope=curve.slope,
        intercept=curve.intercept,
        r_squared=curve.r_squared,
        status=QCStatus.APPROVED,
        reviewer_notes=reviewer_notes,
        created_at=curve.created_at
    )

None

With this setup:

You cannot create a CalibrationCurve that violates any invariant
You cannot call validate_curve on a non-pending curve
You cannot call approve_curve without reviewer notes
If any function returns an invalid CalibrationCurve, you get an immediate error

6.5. Combining Everything

The real power comes from combining all three approaches. Here's a complete test file that demonstrates all three techniques working together:

"""
Integration tests demonstrating Polyfactory, Hypothesis, and icontract together.

This file is tangled from post-data-model-testing.org and can be run with:
    pytest test_data_model_integration.py -v
"""
from typing import Optional
from enum import Enum
from datetime import datetime

import numpy as np
import icontract
import pytest
from pydantic import BaseModel, field_validator
from polyfactory.factories.pydantic_factory import ModelFactory
from polyfactory import Use
from hypothesis import given, strategies as st, settings


# =============================================================================
# DOMAIN MODELS (with icontract invariants)
# =============================================================================

class QCStatus(str, Enum):
    PENDING = "pending"
    VALIDATED = "validated"
    FLAGGED = "flagged"
    REJECTED = "rejected"
    APPROVED = "approved"


class CalibrationPoint(BaseModel):
    concentration: float
    response: float
    replicate: int = 1

    @field_validator('concentration')
    @classmethod
    def validate_concentration(cls, v):
        if v < 0:
            raise ValueError('Concentration must be non-negative')
        return v


def r_squared_is_consistent(self) -> bool:
    """Invariant: R² must match the actual fit."""
    if len(self.readings) < 2:
        return True
    conc = np.array([r.concentration for r in self.readings])
    resp = np.array([r.response for r in self.readings])
    pred = self.slope * conc + self.intercept
    ss_res = np.sum((resp - pred) ** 2)
    ss_tot = np.sum((resp - np.mean(resp)) ** 2)
    calc_r2 = 1 - (ss_res / ss_tot) if ss_tot > 0 else 1.0
    return abs(self.r_squared - calc_r2) < 0.001


def approved_has_good_r_squared(self) -> bool:
    """Invariant: approved curves must have R² >= 0.99."""
    if self.status == QCStatus.APPROVED:
        return self.r_squared >= 0.99
    return True


@icontract.invariant(lambda self: len(self.readings) >= 2, "Need at least 2 calibration points")
@icontract.invariant(r_squared_is_consistent, "R² must match actual fit quality")
@icontract.invariant(approved_has_good_r_squared, "Approved curves need R² >= 0.99")
class CalibrationCurve(BaseModel):
    curve_id: str
    analyst_id: str
    readings: list[CalibrationPoint]
    slope: float
    intercept: float
    r_squared: float
    status: QCStatus = QCStatus.PENDING
    reviewer_notes: Optional[str] = None
    created_at: datetime

    class Config:
        arbitrary_types_allowed = True


# =============================================================================
# DOMAIN FUNCTIONS (with icontract pre/post conditions)
# =============================================================================

@icontract.require(lambda curve: curve.status == QCStatus.PENDING,
                   "Can only validate pending curves")
@icontract.ensure(lambda result: result.status in [QCStatus.VALIDATED, QCStatus.FLAGGED],
                  "Validation must result in validated or flagged status")
def validate_curve(curve: CalibrationCurve) -> CalibrationCurve:
    """Validate a calibration curve based on R² threshold."""
    new_status = QCStatus.VALIDATED if curve.r_squared >= 0.99 else QCStatus.FLAGGED
    return CalibrationCurve(
        curve_id=curve.curve_id,
        analyst_id=curve.analyst_id,
        readings=curve.readings,
        slope=curve.slope,
        intercept=curve.intercept,
        r_squared=curve.r_squared,
        status=new_status,
        reviewer_notes=curve.reviewer_notes,
        created_at=curve.created_at
    )


@icontract.require(lambda curve: curve.status == QCStatus.VALIDATED,
                   "Can only approve validated curves")
@icontract.require(lambda reviewer_notes: reviewer_notes and reviewer_notes.strip(),
                   "Reviewer notes required for approval")
@icontract.ensure(lambda result: result.status == QCStatus.APPROVED,
                  "Curve must be approved after approval")
def approve_curve(curve: CalibrationCurve, reviewer_notes: str) -> CalibrationCurve:
    """Approve a validated calibration curve."""
    return CalibrationCurve(
        curve_id=curve.curve_id,
        analyst_id=curve.analyst_id,
        readings=curve.readings,
        slope=curve.slope,
        intercept=curve.intercept,
        r_squared=curve.r_squared,
        status=QCStatus.APPROVED,
        reviewer_notes=reviewer_notes,
        created_at=curve.created_at
    )


# =============================================================================
# POLYFACTORY FACTORIES
# =============================================================================

class CalibrationPointFactory(ModelFactory):
    __model__ = CalibrationPoint
    # Constrain concentration to non-negative values (matching Pydantic validator)
    concentration = Use(lambda: ModelFactory.__random__.uniform(0, 1000))


class CalibrationCurveFactory(ModelFactory):
    __model__ = CalibrationCurve

    @classmethod
    def build(cls, **kwargs):
        # Generate readings that produce a valid fit
        readings = kwargs.get('readings') or [
            CalibrationPointFactory.build(concentration=float(i), response=float(i * 2.5 + 1.0))
            for i in range(5)
        ]
        # Calculate actual fit parameters
        conc = np.array([r.concentration for r in readings])
        resp = np.array([r.response for r in readings])
        slope, intercept = np.polyfit(conc, resp, 1)
        pred = slope * conc + intercept
        ss_res = np.sum((resp - pred) ** 2)
        ss_tot = np.sum((resp - np.mean(resp)) ** 2)
        r_squared = 1 - (ss_res / ss_tot) if ss_tot > 0 else 1.0

        return super().build(
            readings=readings,
            slope=slope,
            intercept=intercept,
            r_squared=r_squared,
            **{k: v for k, v in kwargs.items() if k not in ['readings', 'slope', 'intercept', 'r_squared']}
        )


# =============================================================================
# TESTS
# =============================================================================

class TestPolyfactoryCoverage:
    """Tests using Polyfactory's systematic coverage."""

    def test_qc_workflow_all_combinations(self):
        """Test QC workflow with polyfactory coverage - structural edge cases.

        Note: We iterate over QCStatus values manually because CalibrationCurve
        has complex invariants (R² consistency, minimum readings) that coverage()
        can't satisfy automatically. This demonstrates intentional structural
        coverage of the state machine.
        """
        tested_statuses = []

        for status in QCStatus:
            # Build a valid curve with this status
            curve = CalibrationCurveFactory.build(status=status)
            tested_statuses.append(status)

            if curve.status == QCStatus.PENDING:
                validated = validate_curve(curve)
                assert validated.status in [QCStatus.VALIDATED, QCStatus.FLAGGED]

                if validated.status == QCStatus.VALIDATED:
                    approved = approve_curve(validated, "Meets all QC criteria")
                    assert approved.status == QCStatus.APPROVED
                    assert approved.reviewer_notes is not None

        # Verify we tested all status values
        assert set(tested_statuses) == set(QCStatus)


class TestHypothesisProperties:
    """Property-based tests using Hypothesis."""

    @given(st.builds(
        CalibrationPoint,
        concentration=st.floats(min_value=0, max_value=1000, allow_nan=False),
        response=st.floats(min_value=0, max_value=10000, allow_nan=False),
        replicate=st.integers(min_value=1, max_value=10)
    ))
    @settings(max_examples=50)
    def test_calibration_point_concentration_non_negative(self, point: CalibrationPoint):
        """Hypothesis: concentration must be non-negative."""
        assert point.concentration >= 0

    @given(st.builds(
        CalibrationPoint,
        concentration=st.floats(min_value=0, max_value=1000, allow_nan=False),
        response=st.floats(min_value=0, max_value=10000, allow_nan=False),
        replicate=st.integers(min_value=1, max_value=10)
    ))
    @settings(max_examples=50)
    def test_calibration_point_response_is_finite(self, point: CalibrationPoint):
        """Hypothesis: response values are finite numbers."""
        assert np.isfinite(point.response)


class TestIcontractInvariants:
    """Tests verifying icontract catches invalid states."""

    def test_contracts_catch_invalid_r_squared(self):
        """Verify contracts catch scientifically invalid R² values."""
        readings = [
            CalibrationPoint(concentration=1.0, response=2.5),
            CalibrationPoint(concentration=2.0, response=5.0),
        ]

        # Try to create a curve with fake R² that doesn't match the data
        with pytest.raises(icontract.ViolationError) as exc_info:
            CalibrationCurve(
                curve_id="cal-001",
                analyst_id="analyst-1",
                readings=readings,
                slope=2.5,
                intercept=0.0,
                r_squared=0.5,  # Wrong! Actual R² is ~1.0
                created_at=datetime.now()
            )
        assert "R² must match actual fit quality" in str(exc_info.value)

    def test_contracts_require_minimum_readings(self):
        """Verify contracts require at least 2 calibration points."""
        with pytest.raises(icontract.ViolationError) as exc_info:
            CalibrationCurve(
                curve_id="cal-002",
                analyst_id="analyst-1",
                readings=[CalibrationPoint(concentration=1.0, response=2.5)],  # Only 1!
                slope=2.5,
                intercept=0.0,
                r_squared=1.0,
                created_at=datetime.now()
            )
        assert "Need at least 2 calibration points" in str(exc_info.value)

    def test_validate_requires_pending_status(self):
        """Verify validate_curve requires pending status."""
        readings = [
            CalibrationPointFactory.build(concentration=float(i), response=float(i * 2.5 + 1.0))
            for i in range(5)
        ]
        conc = np.array([r.concentration for r in readings])
        resp = np.array([r.response for r in readings])
        slope, intercept = np.polyfit(conc, resp, 1)

        curve = CalibrationCurve(
            curve_id="cal-003",
            analyst_id="analyst-1",
            readings=readings,
            slope=slope,
            intercept=intercept,
            r_squared=1.0,
            status=QCStatus.VALIDATED,  # Not pending!
            created_at=datetime.now()
        )

        with pytest.raises(icontract.ViolationError) as exc_info:
            validate_curve(curve)
        assert "Can only validate pending curves" in str(exc_info.value)

Now we run the tests with pytest:

cd ~/projects/lab-data && poetry run pytest test_data_model_integration.py -vvvv -q --disable-warnings --tb=short 2>&1

============================= test session starts ==============================
platform darwin -- Python 3.11.6, pytest-9.0.2, pluggy-1.6.0 -- ~/projects/lab-data/.venv/bin/python
cachedir: .pytest_cache
hypothesis profile 'default'
rootdir: ~/projects/lab-data
configfile: pyproject.toml
plugins: Faker-37.11.0, hypothesis-6.142.3
collecting ... collected 6 items

test_data_model_integration.py::TestPolyfactoryCoverage::test_qc_workflow_all_combinations PASSED [ 16%]
test_data_model_integration.py::TestHypothesisProperties::test_calibration_point_concentration_non_negative PASSED [ 33%]
test_data_model_integration.py::TestHypothesisProperties::test_calibration_point_response_is_finite PASSED [ 50%]
test_data_model_integration.py::TestIcontractInvariants::test_contracts_catch_invalid_r_squared PASSED [ 66%]
test_data_model_integration.py::TestIcontractInvariants::test_contracts_require_minimum_readings PASSED [ 83%]
test_data_model_integration.py::TestIcontractInvariants::test_validate_requires_pending_status PASSED [100%]

======================== 6 passed, 3 warnings in 1.40s =========================

6.6. Caveats with icontract

An honest caveat: icontract has the same opacity problem as @model_validator. An @invariant is arbitrary Python – it does not serialize to Avro, JSON Schema, or Protobuf either. Moving the logic out of Pydantic doesn't make it visible to downstream consumers; it just stops it from polluting the schema export. If a downstream service in another language needs to enforce "R² matches the fit", you still have to re-implement it there (or push the check into a shared validation service). This is a real limit of any in-process invariant approach – the alternative is consumer-driven contract testing (Pact and friends), which is a different toolchain entirely and out of scope here.

And a runtime cost. @invariant checks run on every method call on the instance, not just construction. The r_squared_is_consistent check below does a numpy polyfit on every invocation; on a hot path (a Kafka consumer processing thousands of messages per second) this is a real cost. Note that python -O does not help here – icontract raises ViolationError unconditionally and does not piggyback on assert. The right knobs are icontract's own enabled argument on each contract, the ICONTRACT_SLOW environment variable for gating expensive checks, or building two configurations of your application. Either way: if you switch contracts off in prod, your "runtime safety net" is only a test-time safety net, and you need to be honest with yourself about that.

6.7. Alternatives to runtime contract enforcement

Alternatives worth weighing. Before reaching for runtime contracts, three other approaches deserve a serious look:

Schema-first with codegen. Treat Avro/Protobuf/JSON Schema as the source of truth and generate Pydantic (or your language's equivalent) from it. Cross-system drift becomes structurally impossible because there's only one definition. This is the right answer when your data crosses many language boundaries. Its weakness is exactly the one this post is about: schema languages can't express cross-field invariants either, so you still need something for "R² must match the fit."
Consumer-driven contract testing (Pact and friends). Push the enforcement to the boundary between services rather than inside any one of them. This is the right answer when the question is "do producer and consumer agree?" It's the wrong answer when the question is "is this single object internally coherent?", which is what we have here.
In-process invariants (icontract, @model_validator, plain assertions in __init__). Cheapest to add, lives next to the data, and – as discussed above – invisible to anything outside your Python process.

These are not mutually exclusive. A mature system typically has schema-first definitions at the wire, CDC tests at the service boundaries, and in-process invariants for the rules that live entirely inside one bounded context. This post is about that last layer.

7. Conclusion summary

The example here is a calibration curve, but the pattern is not domain-specific. Anywhere a data model carries a rule the type system can't express, the same three layers apply:

An Order where discount < subtotal=, tax is a function of subtotal - discount, and total is the sum. Pydantic accepts any three floats; only a cross-field check rejects the inconsistent invoice.
An OAuthToken where the granted scopes must be a subset of the client's allowed_scopes, and expires_at > issued_at. Each field is structurally fine in isolation.
An inventory StockMovement where on_hand_after = on_hand_before + delta. Off-by-one in a service layer produces a "valid" object that silently corrupts every downstream report.

In each case the bug looks the same as the calibration-curve bug: every field passes its own validator, the JSON serialises cleanly, and the wrongness only shows up when you ask whether the fields agree with each other. That is the bug class this stack is for.

The three layers, each catching a different class:

Technique	Catches	When
Polyfactory	Structural combinations	Test generation
Hypothesis	Value-level edge cases	Test execution
icontract	Cross-field invariants	Runtime

Three independent failure modes, three independent tools. Start with polyfactory's coverage() for structural completeness. Add Hypothesis for value-level probing. Use icontract for invariants that can't be expressed in types – the swapped slope and intercept, the discount > subtotal, the StockMovement that doesn't add up.

8. tldr

TLDR: A modest Pydantic model – a dozen fields with a few enums and optionals – has 7,680 valid structural shapes. Your tests probably cover four of them. This post is a three-layer pattern for closing that gap – and an honest accounting of where each layer does and doesn't earn its keep.

Polyfactory's coverage() automates 1-way structural partition coverage so you stop hand-writing fixtures for "every enum value × every nullable state". Hypothesis adds value-level probing – boundary floats, NaN, unicode – and shrinks failing cases to minimal examples. icontract enforces cross-field invariants (like "R² must match the actual fit") that no type system or serializable schema can express.

The worked example is a scientific calibration curve, with all three tools running in a real pytest file you can copy. The post is also explicit about the limits: equivalence partitioning has been standard since the 1970s, @invariant has the same schema-opacity problem as @model_validator, and runtime contracts cost real CPU on hot paths.

Footnotes:

Data standards are the connective tissue of cross-system integration, and in my experience the right default is to use them all the way down – as the source of truth, not as a downstream artefact. You don't necessarily write the schema files by hand; they can be generated from Python (e.g. from Pydantic models). But if you go that route, it is essential that every constraint your in-memory model enforces also appears in the exported schema. Anything that doesn't survive serialisation is a constraint your downstream consumers cannot see.

Pattern Inheritance: A Fork-Based Strategy for Scaling Service Standards

Charlie Holland — Tue, 07 Apr 2026 03:56:00 GMT

1. About platformEngineering architecture templates

Figure 1: JPEG produced with DALL-E 4o

Your payments team patches a JWT library CVE on Thursday. Your inventory team patches the same CVE on Monday. Your notifications team hasn't noticed yet. All three services started life as a git clone of the same internal template, and the day after the clone, they stopped sharing anything at all.

This post is about the workflow I'd reach for to stop that happening: a three-tier fork hierarchy – community template, org fork, team forks – that lets a platform team push security and infrastructure changes downstream through ordinary git fetch and git merge, the way a subclass picks up a base-class fix. I'll also cover why I'd reach for it over the obvious alternatives (cruft, internal packages, monorepos), because that's the first question anyone reading this should ask.

2. The Problem: Service Proliferation Without Standards architecture platformEngineering

Every growing engineering organization hits the same inflection point¹. A second team needs to build an API service. Then a third. Then a tenth.

Without intervention, each team makes its own choices about project structure, dependency management, database access patterns, authentication middleware, health check endpoints, logging configuration, error handling, and deployment manifests. The resulting landscape looks something like this:

graph TD
    subgraph "Without Standards"
        T1[Team Alpha] -->|builds from scratch| S1[Service A
SQLAlchemy sync
custom logging
no health checks]
        T2[Team Beta] -->|builds from scratch| S2[Service B
raw asyncpg
structlog
custom auth middleware]
        T3[Team Gamma] -->|builds from scratch| S3[Service C
Tortoise ORM
stdlib logging
JWT auth]
        T4[Team Delta] -->|builds from scratch| S4[Service D
SQLModel
loguru
API key auth]
    end

Every service works. None of them work the same way. The consequences compound:

Onboarding cost: Engineers moving between teams have to relearn fundamental code patterns.
Operational burden: SREs can't write generic runbooks when every service has different logging, health checks, and failure modes.
Security surface: Each team independently solves authentication, input validation, and secrets management – and each implementation has its own bugs.
Upgrade paralysis: When a critical dependency needs patching (say, a CVE in your database driver), there's no single place to make the fix. You're patching N services with N different integration approaches.

The usual response is to write an internal wiki page titled "How to Build a FastAPI Service." That doesn't work. Documentation decays², and even when engineers read it, translating prose into working code introduces drift on day one. You want running code, not running prose.

3. The Running Example: FastAPI + Async Postgres fastAPI postgres asyncio

To make this concrete, let's work with a stack that's extremely common in modern Python shops: a FastAPI service backed by PostgreSQL, with asynchronous database access for performance³.

This seemingly simple stack requires a surprising number of interlocking decisions. The table below reflects opinionated defaults for this particular stack – your org may reasonably choose differently, but the point is that each choice constrains the others:

Concern	Options	Opinionated default
Async DB driver	`asyncpg`, psycopg3 (async mode), `aiopg`	asyncpg (fastest, most mature)
ORM / query builder	`SQLAlchemy` 2.0 async, SQLModel, Tortoise ORM, raw SQL	SQLAlchemy 2.0 (ecosystem, flexibility)
Migrations	`Alembic` (async-aware), aerich, manual SQL	Alembic
Connection pooling	`SQLAlchemy` built-in async pool, pgBouncer sidecar	Both (app-level + infra-level)
Config management	`pydantic-settings`, env vars, Vault, AWS SSM	pydantic-settings + Vault
Testing	`pytest` + `httpx` + `testcontainers`	pytest-asyncio + httpx.AsyncClient

Getting each of these right takes iteration. Getting them all right together, in a way that's coherent and production-ready, takes substantially more. This is the kind of compound problem where you should be reaching for someone else's working answers, not building your own.

4. Templates Exist, but Cloning Strands You cookiecutter templates

The open source community has already solved the general version of this problem. full-stack-fastapi-template (maintained by FastAPI's author) ships SQLModel, Alembic, async SQLAlchemy, JWT auth, pydantic-settings, Docker Compose, and pytest infrastructure in a single repo. The Cookiecutter ecosystem offers parameterized variants like cookiecutter-fastapi. Pick one of these and you've skipped a couple of months of dependency-archaeology and connection-pool tuning.

The catch is what you get the day after you adopt it. git clone and cookiecutter generate both produce a snapshot: a point-in-time copy of the template's state with no live link back to its origin.

graph LR
    subgraph "Clone / Generate (Point-in-Time Snapshot)"
        direction LR
        Template[Community Template
v1.0] -->|clone / generate| TeamRepo[Team's Service]
        Template -->|v1.1: security fix| Nowhere1[❌ Not inherited]
        Template -->|v1.2: perf improvement| Nowhere2[❌ Not inherited]
        Template -->|v1.3: new best practice| Nowhere3[❌ Not inherited]
    end

When the community template later fixes a vulnerability in its auth middleware, swaps in a faster async driver, or improves its connection pool defaults, none of it reaches you. Every improvement requires someone on your team to notice, understand, and manually port it. In practice, that never happens. The template was useful on day one and forgotten on day two.

4.1. "Why Not Just Use cruft, or Internal Packages?"

This is the right first question, and it deserves an answer before I go any further.

cruft solves the snapshot problem by recording the template version a project was generated from and offering cruft update to apply later template diffs as a patch. It's a real improvement over cookiecutter generate, and for a single layer of inheritance (community template → service) it's simpler than what I'm about to describe. Where cruft starts to creak is at the second layer: when your organization wants to express opinions on top of the community template that every service then inherits. cruft doesn't model "fork of a fork" naturally, and patch-based updates are less forgiving than three-way merges when conflicts get gnarly. If you only need one layer of inheritance, use cruft and stop reading.

Internal packages (acme-fastapi-core, acme-observability) are the right answer for runtime concerns: middleware, auth wiring, observability hooks, database session helpers. Anything that can live behind a function call should live behind a function call. But packages don't ship project structure – they don't give you a Dockerfile, a CI pipeline, a directory layout, an Alembic config, deployment manifests, or the boilerplate that wires the packages together. Most mature platform teams end up doing both: a fork hierarchy for the scaffold, packages for the runtime behaviour. This post is about the scaffold half.

Monorepos sidestep the problem entirely by removing the boundaries that allowed drift in the first place. If you already have working monorepo tooling, you probably don't need this post. If you don't, adopting Bazel or Pants to solve a template-drift problem is a heavy detour.

With those out of the way: here's the fork story.

5. Why Fork, Not Clone git versionControl

A fork preserves a relationship; a clone severs it. When you fork a repository⁴ you get a copy with full history, a remote reference back to the original, and the ability to git fetch upstream and git merge as the upstream evolves. That upstream remote is the entire mechanic this post relies on.

The mental model is loose object-oriented inheritance⁵: your fork inherits from upstream, you override specific files, and you manually choose when to absorb base-class changes. The "manual" part is a feature – automatic propagation of breaking changes into production infrastructure would be terrifying.

6. The Three-Tier Fork Hierarchy architecture platformEngineering

Here's the architecture I recommend. It has three tiers:

graph TB
    subgraph Tier1["Tier 1: Community Upstream"]
        Upstream[Community Template
e.g. tiangolo/full-stack-fastapi-template
Battle-tested patterns]
    end

    subgraph Tier2["Tier 2: Organization Fork"]
        OrgFork[Org Gold Standard
e.g. acme-corp/fastapi-service-template
Org opinions applied]
    end

    subgraph Tier3["Tier 3: Team Forks"]
        TeamA[Team Alpha Fork
payments-service]
        TeamB[Team Beta Fork
inventory-service]
        TeamC[Team Gamma Fork
notifications-service]
    end

    Upstream -->|"fork + customize"| OrgFork
    OrgFork -->|"fork per service"| TeamA
    OrgFork -->|"fork per service"| TeamB
    OrgFork -->|"fork per service"| TeamC

    Upstream -.->|"upstream sync"| OrgFork
    OrgFork -.->|"upstream sync"| TeamA
    OrgFork -.->|"upstream sync"| TeamB
    OrgFork -.->|"upstream sync"| TeamC

6.1. Tier 1: Community Upstream

This is the open source template you've chosen as your foundation. You don't modify it directly. It represents the community's best understanding of how to build this type of service⁶.

A warning before going further: a fork chain is also a supply chain, and the same mechanism that propagates security fixes downstream propagates malicious or buggy commits with equal efficiency. Treat the choice of upstream like the choice of any other production dependency. Concretely, before adopting an upstream:

Check that the project has more than one active maintainer, a recent release cadence, and evidence that someone reviews PRs. A scaffold maintained by one person on weekends is a single point of failure for your fleet.
Pin to signed tags, not upstream/main. Require commit signature verification at the Tier 2 boundary so an upstream account compromise can't ride a git fetch straight into your services.
Subscribe the org fork to the upstream's GitHub Security Advisories and OSV feeds. Many projects ship security fixes silently in point releases without filing a CVE.
Run pip-audit / osv-scanner on every Tier 2 merge. An SBOM generated at this boundary is the only honest record of what you actually shipped to teams. An ORG_CHANGES.md manifest documents intent; an SBOM documents reality.

6.2. Tier 2: Organization Fork (The Gold Standard)

This is where your platform team applies organizational opinions on top of the community template. This fork is maintained by your platform or infrastructure team and represents your org's "blessed" way to build a service of this type.

Typical org-level customizations include:

Authentication: Swap JWT for your org's OIDC provider or service mesh auth.
Observability: Add your org's OpenTelemetry configuration, custom metrics, and tracing headers.
Secrets management: Integrate with Vault, AWS Secrets Manager, or whatever your org uses.
CI/CD: Replace generic GitHub Actions with your org's pipeline templates.
Deployment manifests: Add Kubernetes manifests, Helm charts, or Terraform modules that match your infrastructure.
Compliance: Add security scanning, license checking, and audit logging requirements.
Internal libraries: Wire in your org's shared Python packages for common concerns.

The platform team's job is to keep this fork synchronized with upstream while maintaining the org's customizations⁷.

6.3. Tier 3: Team Forks (Concrete Services)

Individual teams fork the org's gold standard to create their specific services. A team building a payments service forks acme-corp/fastapi-service-template into acme-corp/payments-service, then adds their domain-specific models, routes, and business logic.

Teams get the org's opinions "for free" and can focus entirely on their domain problem. When the platform team pushes an improvement to the gold standard (say, upgrading the OpenTelemetry SDK or fixing a connection pool misconfiguration), teams can pull that change into their fork with a standard git merge.

7. Setting Up the Hierarchy git howTo

7.1. Step 1: Fork the Community Template

On GitHub, fork the community template into your org's namespace:

tiangolo/full-stack-fastapi-template → acme-corp/fastapi-service-template

Then clone your org fork locally:

git clone git@github.com:acme-corp/fastapi-service-template.git
cd fastapi-service-template
git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git
# Disable accidental pushes to upstream
git remote set-url --push upstream no_push
git remote -v
# origin    git@github.com:acme-corp/fastapi-service-template.git (fetch)
# origin    git@github.com:acme-corp/fastapi-service-template.git (push)
# upstream  git@github.com:fastapi/full-stack-fastapi-template.git (fetch)
# upstream  no_push (push)

7.2. Step 2: Create an Org Customization Branch Strategy

This is a critical decision⁸. I recommend maintaining two long-lived branches in the org fork:

upstream-mirror: Tracks the upstream template exactly. Never commit org changes here.
main: Contains the org's customizations on top of upstream.

# Create the mirror branch from upstream's main, NOT from your customized main
git fetch upstream
git checkout -b upstream-mirror upstream/main
git push origin upstream-mirror

# main branch is where org customizations live
git checkout main

When you want to sync with upstream:

# Update the mirror
git checkout upstream-mirror
git fetch upstream
git merge upstream/main
git push origin upstream-mirror

# Merge upstream changes into org's main
git checkout main
git merge upstream-mirror
# Resolve conflicts, keeping org customizations where intentional
git push origin main

The upstream-mirror ranch gives you a clean diff between "what upstream looks like" and "what our org version looks like." This is invaluable for understanding exactly what your org has changed.

For simple, infrequent syncs, GitHub's "Sync fork" button and the gh repo sync CLI command offer lighter-weight alternatives. These work well when the org fork has minimal divergence, but for forks with significant customizations you'll want the mirror-branch workflow above to keep a clear audit trail.

7.3. Step 3: Apply Org Customizations

Now apply your org's opinions to main. The single most important rule: keep the diff between your fork and its upstream as small as possible. Every line you change in a file that upstream also changes is a future merge conflict. Before modifying an upstream file, ask: "Can I achieve this by adding a new file instead?" Often you can. A new org_middleware.py that's imported by the entrypoint is better than editing the middleware directly.

Some specific guidelines:

Prefer additive changes over modifications. Adding new files (a deploy/ directory, an internal_libs/ package, a .github/workflows/ci.yml) is low-conflict. Modifying files that upstream also modifies (main.py, requirements.txt, Dockerfile) is high-conflict.

Use configuration layers. Instead of editing settings.py directly, create an org_settings.py that imports and extends the base settings. This isolates your changes from upstream's evolution of the settings module.

Document every divergence. Maintain an ORG_CHANGES.md file that catalogs what you've changed and why. When merge conflicts arise, this document tells you whether the conflict is in code you intentionally modified. A typical manifest looks like:

## Org Customizations

### Authentication (modified: app/core/security.py)
- Replaced JWT auth with OIDC integration via org's identity provider
- Added service-to-service mTLS validation

### Observability (added: app/observability/)
- OpenTelemetry auto-instrumentation with custom span attributes
- Structured logging via [[https://www.structlog.org/en/stable/][structlog]] with org-standard fields

### CI/CD (replaced: .github/workflows/)
- Upstream GitHub Actions replaced with GitLab CI
- Added SAST scanning, container scanning, license compliance

### Database (modified: app/core/db.py)
- Connection pool max_size increased from 10 to 50
- Added read-replica routing for GET endpoints

This document is your merge conflict playbook. When upstream changes app/core/security.py and you get a conflict, you check the manifest: "We intentionally replaced this with OIDC. Ignore upstream's changes to the JWT implementation, but check if they've changed anything else in this file."

7.4. Step 4: Team Forks

A note on mechanics: GitHub will not let you fork acme-corp/fastapi-service-template into another repo in the same org via the fork button – a given upstream can only have one fork per namespace. In practice, teams create a new empty repo (acme-corp/payments-service), then seed it from the org template using git clone --bare and git push --mirror, and finally add the org template as a long-lived remote. You lose GitHub's fork-network UI for the Tier 2 → Tier 3 hop, but the git-level inheritance relationship is identical.

# One-time seeding of a new service repo from the org template
git clone --bare git@github.com:acme-corp/fastapi-service-template.git
cd fastapi-service-template.git
git push --mirror git@github.com:acme-corp/payments-service.git
cd .. && rm -rf fastapi-service-template.git

# Then clone the new service repo and wire up the org-template remote
git clone git@github.com:acme-corp/payments-service.git
cd payments-service
git remote add org-template git@github.com:acme-corp/fastapi-service-template.git
git remote set-url --push org-template no_push

Teams should similarly maintain an org-template-mirror branch and merge into main:

git checkout -b org-template-mirror
git fetch org-template
git merge org-template/main
git push origin org-template-mirror

git checkout main
git merge org-template-mirror

7.5. How Changes Flow

With the hierarchy in place, improvements flow downstream through the fork chain. Here's what different types of changes look like in practice:

graph LR
    subgraph "Change Propagation"
        direction LR
        U[Community
Template] -->|"1. Publishes
security fix"| O[Org Fork]
        O -->|"2. Platform team
validates + merges"| OP[Org Main ✅]
        OP -.->|"3. Teams pull
from org-template"| S1[payments-service ✅]
        OP -.->|"3. Teams pull
from org-template"| S2[inventory-service ✅]
    end

7.5.1. Scenario: Upstream Security Fix

The community template patches a vulnerability in its authentication middleware.
Your platform team fetches upstream, merges into upstream-mirror, then merges into main.
The platform team validates the fix works with org customizations and pushes to main.
Teams fetch from org-template and merge into their services.

Total effort: one careful merge by the platform team + N trivial merges by service teams. Without the fork chain, you'd need N independent teams to each discover, understand, and port the fix.

7.5.2. Scenario: Org-Wide Observability Upgrade

The platform team upgrades the OpenTelemetry SDK and adds new custom spans to the org fork.
Teams fetch and merge from org-template.
Every service gets improved observability without any team doing custom work.

7.5.3. Scenario: Team-Specific Feature

A team adds domain-specific models, routes, and business logic. These changes live entirely in the team's fork and never propagate upward. The fork hierarchy doesn't interfere – the team just has additional files that don't exist in the org template.

8. Gotchas That Break Fork Compatibility pitfalls

The fork-based approach works well when changes are additive. It gets painful when upstream or org changes are incompatible with downstream forks. Here are the specific gotchas that can break the inheritance chain:

8.1. File Renames and Moves

Renames are the most common source of painful merge conflicts. If upstream renames app/core/config.py to app/settings/config.py, and your org fork has modifications to the original app/core/config.py, Git may not detect this as a rename-with-modification⁹. Instead, you'll see the old file deleted and a new file created, with your org's changes silently lost.

Mitigation: When merging upstream changes that include renames, always diff the deleted file against the new file manually. Use git diff –find-renames with a low similarity threshold to help Git detect renames:

git merge -X find-renames=40 upstream-mirror

8.2. Dependency Version Conflicts

Upstream pins sqlalchemy==2.0.30 in their requirements.txt. Your org fork has pinned sqlalchemy==2.0.25 because 2.0.30 has a regression with your custom dialect. Three months later, upstream bumps to sqlalchemy==2.1.0 with breaking API changes.

The danger escalates with lock files (poetry.lock, requirements.txt with hashes). Lock file conflicts are virtually impossible to resolve by hand¹⁰.

Mitigation: don't try to "layer" lock files – pip and poetry resolvers don't compose two requirement files cleanly, and -r base.txt followed by overrides will silently produce unsatisfiable resolutions. Instead, pick one of two honest strategies:

Single resolved lock file owned by the org fork. The org fork edits pyproject.toml directly to express its constraints (upper bounds on critical libs, swapped-in internal packages) and re-runs the resolver after every upstream merge. Yes, this means pyproject.toml and the lock file are high-conflict zones, but it's the only approach that produces a coherent dependency graph.
Constraints file. Keep upstream's requirements.txt unmodified and ship a separate constraints.txt that pip install -c constraints.txt -r requirements.txt consumes. Constraints don't add dependencies, only bound them, so they don't fight the resolver.

Run pip-audit (or osv-scanner) on every upstream merge so security regressions surface in the Tier 2 PR, not in production.

8.3. Entrypoint and Startup Sequence Changes

The application entrypoint (main.py, app/__init__.py, or wherever the FastAPI app instance is created) is a high-conflict zone. Both upstream and your org fork need to modify this file – upstream to add framework features, your org to wire in custom middleware, startup hooks, and shutdown handlers.

If upstream refactors the startup sequence (e.g., moving from a module-level app = FastAPI() to a factory function create_app()), every downstream fork that has modified the entrypoint will face a complex merge.

Mitigation:

Use a lifecycle hooks pattern. Define well-known hook functions (on_startup(), on_shutdown(), configure_middleware()) in separate files that the entrypoint imports. Upstream owns the entrypoint; your org owns the hook implementations.
If upstream doesn't support this pattern, propose it upstream. This is a legitimate contribution that benefits everyone.

8.4. Database Migration Conflicts

Alembic migrations have a linear dependency chain: each migration references the previous one's revision ID¹¹. If upstream adds migration abc123 and your org fork adds migration def456, both claim to be the "head." Alembic calls this a "multiple heads" situation and refuses to run until you create a merge migration. (This is the same Alembic we chose in the decision table above – a great tool, but one that demands careful coordination across fork tiers.)

At the team fork level, every team has domain-specific migrations that diverge from the org template's migrations, compounding the problem further.

Mitigation: this is the case where you should break the inheritance. Each service owns its own database, so migration history is fundamentally per-service and shouldn't be inherited at all. The org template should ship migration infrastructure (the alembic.ini, env.py, naming conventions, CI checks for multiple heads) but ship zero migration revision files. Treat the alembic/versions/ directory as team-owned from day one and add it to the merge-conflict-prevention checklist alongside CI files. If you genuinely have org-wide tables (a shared audit log, a tenancy table), publish them as a library the team imports, not as inherited migrations.

8.5. CI/CD Pipeline Divergence

CI/CD pipelines tend to be heavily customized at every level of the hierarchy. Upstream has generic GitHub Actions. Your org replaces them with GitLab CI. Teams add service-specific test stages.

If upstream restructures their CI (renaming jobs, changing the workflow file layout), the merge into your org fork touches files you've completely replaced.

Mitigation:

Place CI files in a separate, clearly-namespaced directory. If upstream uses .github/workflows/, put your org's CI in .ci/ or .gitlab/. This eliminates conflicts entirely because you're adding files, not modifying upstream's.
Alternatively, .gitignore upstream's CI files in your org fork and maintain your own.

8.6. Docker and Infrastructure File Conflicts

Dockerfile, docker-compose.yml, and Kubernetes manifests are modified at every tier. Upstream sets up a basic multi-stage build. Your org adds security scanning layers, internal registry references, and specific base images. Teams add service-specific build arguments and sidecar containers.

Mitigation:

Use Docker Compose extends or override files: docker-compose.yml (upstream) + docker-compose.org.yml (org overrides) + docker-compose.team.yml (team overrides).
For Dockerfiles, consider a base image strategy: the org publishes a base image with org-specific layers, and team Dockerfiles use FROM acme-corp/python-service-base:latest instead of modifying the upstream Dockerfile.

8.7. Python Import Path Changes

If upstream renames the top-level Python package (e.g., app → fastapi_app), every file in every downstream fork that imports from app breaks. This is a cascading failure across the entire hierarchy.

Mitigation:

This is one case where talking to upstream matters. If you're building an org's infrastructure on top of a template, consider opening an issue or PR that establishes the top-level package name as a stable API.
If you can't prevent it, maintain a thin compatibility shim (app/__init__.py that re-exports from fastapi_app) in the org fork to give teams time to migrate. Remove the shim after a transition period.

9. General Challenges and How to Address Them challenges

Beyond specific gotchas, there are broader organizational and technical challenges that arise when implementing pattern inheritance.

9.1. Merge Conflict Accumulation

The longer you wait between upstream syncs, the harder they get. If you sync monthly, you're merging a month of upstream changes against a month of org changes. Conflicts that would have been trivial in isolation become tangled messes when batched.

The fix is cadence. Set a regular sync schedule – weekly or biweekly – and treat it like any other maintenance task. Automate the fetch and attempt the merge in CI. If it succeeds cleanly, auto-merge. If it conflicts, create a PR for human review. The key is detecting divergence early, even if you don't resolve it immediately.

graph LR
    subgraph "Sync Cadence"
        direction LR
        W1[Week 1
3 upstream commits
easy merge ✅] --> W2[Week 2
5 upstream commits
easy merge ✅]
        W2 --> W3[Week 3
2 upstream commits
1 conflict ⚠️]
        W3 --> W4[Week 4
4 upstream commits
easy merge ✅]
    end

Compare this to syncing quarterly, where you'd face 14 upstream commits in a single merge with compounding conflicts.

9.2. Fork Drift and Staleness

Drift looks like a social problem – teams fork the org template, build their service, never sync again, and six months later the fork is frozen at the version from the day they started¹². The service still runs, so nobody notices.

Frame it as a vulnerability management problem instead, because that's what it actually is. A stale Tier 3 fork is a service silently carrying every CVE that's been patched in the org template since the last sync. "47 commits behind" is a number that no engineer will act on; "missing 3 advisories from the last 60 days, including a high-severity auth bypass" is.

Solutions:

Advisory-aware staleness detection: a CI job that doesn't just count missing commits but cross-references them against the org template's changelog and the upstream's GHSA / OSV feed. Surface security-relevant gaps independently from the general freshness number.
Freshness SLO with escalation: set a policy ("no team fork more than N weeks behind stable", "zero open security-channel releases") and enforce it by opening a tracking issue with an owner – not a dashboard nobody reads, and not a CI warning that scrolls past.
Sync sprints as a fallback for general-cohort drift, but never as the only mechanism for security drift.

A GitHub Action to automate staleness detection looks like this:

# .github/workflows/upstream-sync-check.yml
name: Check Upstream Sync
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am
  workflow_dispatch:

jobs:
  check-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Fetch upstream
        run: |
          git remote add upstream https://github.com/tiangolo/full-stack-fastapi-template.git
          git fetch upstream
      - name: Check divergence
        run: |
          BEHIND=$(git rev-list --count HEAD..upstream/main)
          if [ "$BEHIND" -gt 0 ]; then
            echo "::warning::Org fork is $BEHIND commits behind upstream"
          fi

Run the same pattern on team forks, checking against the org template.

9.3. Governance: Who Decides What Goes in the Org Fork?

Because the org fork is shared infrastructure for every team, a bad change – a poorly configured middleware, a broken migration, a dependency bump with a subtle regression – can propagate to every service that syncs.

Clear ownership and review processes are essential:

Dedicated owners: The platform team owns the org fork. Changes require review from at least one platform engineer, with branch protection and signed commits enforced. Two-person review for anything touching auth, crypto, or session lifecycle.
Change classification: Not every upstream change needs to be merged. Evaluate each upstream release for relevance and risk, and tag releases accordingly (security / patch / minor / major).
Changelog: Maintain a changelog that translates upstream changes into org-relevant context. "Upstream upgraded SQLAlchemy to 2.1. This changes how async sessions are created. If you've customized session creation, see migration guide."
Semantic commit prefixes: Prefix commits to distinguish org customizations from upstream merges (org: vs upstream:). When a merge conflict shows up, you immediately know whether the conflicting change is one you own or one you inherited.

9.3.1. Tiered rollout, not "a canary"

A single low-traffic canary service is enough to prove the template still boots; it is not enough to prove a connection-pool resize, a TLS change, or an OpenTelemetry SDK bump will survive a high-QPS payments service. Roll Tier 2 changes out in cohorts:

Cohort 0 – canary. A real but low-traffic service the platform team owns. Soak for 24 hours minimum.
Cohort 1 – low-criticality services. Internal tools, batch jobs, anything not in the customer request path. Soak for several days.
Cohort 2 – general fleet. Most services. Auto-merge PRs against team forks.
Cohort 3 – Tier 0 services. Auth, payments, identity, anything paged on. Manual change-review only, never auto-merged.

Define rollback criteria up front (error rate, latency p99, saturation) and tie them to your existing SLO monitoring. A bad merge that already shipped to Cohort 1 shouldn't require human judgement to roll back from Cohort 2.

9.3.2. Release channels and rollback

Have the org fork ship tagged releases, not a moving main target, and have teams pin to tags. Steal Debian's pattern: a stable channel with monthly tags, and a security channel for cherry-picked CVE fixes against the last stable tag. This decouples freshness from stability – a team can stay on stable v2.3 for a quarter and still receive v2.3.1-security.1 when an upstream auth fix lands.

Rollback is the part most fork-based-template posts skip and it is the part that bites hardest. Once a team has merged a bad org-template release and layered a week of domain code on top, git revert is non-trivial and may conflict with that domain code. Two practices make this survivable:

Feature-flag risky template changes. If the org fork swaps the connection pool implementation, gate it on an env var so a rollback is a config change, not a merge.
Document an emergency revert procedure per release. "If you need to roll back v2.4.0, here is the exact merge commit to revert and the known conflicts you'll see." Do this work once at release time, not at 3am during an incident.

9.4. The "Too Customized to Merge" Problem

Sometimes a team's service diverges so far from the template that merging org-template updates becomes more work than it's worth. The payments service has rewritten the entire database layer to use event sourcing. The notifications service has replaced FastAPI's routing with a custom message broker integration. At this point, the fork relationship is a liability, not an asset.

This is fine, and it should be a normal part of the lifecycle, not a stigmatised escape hatch. Not every service needs to stay on the fork. When a service has genuinely unique requirements that make it architecturally different from the template, detach it:

# Remove the org-template remote
git remote remove org-template

# Delete the mirror branch
git branch -D org-template-mirror

To make detachment a normal part of service lifecycle rather than a stigmatized escape hatch, define clear criteria:

If merging org-template updates has required manual conflict resolution in more than 50% of the last 10 syncs, consider detaching.
If the service has replaced more than 30% of the template's files with custom implementations, consider detaching.
If the service's architecture has diverged from the template's assumptions (different database, different auth model, different deployment target), detach.

Explicitly detaching is better than maintaining a fiction of inheritance that creates merge conflicts without delivering value. The fork hierarchy should be opt-in, not mandatory.

9.5. Testing at the Tier 2 Boundary

The critical gap is the org fork's CI. Upstream tests the template in isolation; team forks test their service. Without strong tests at Tier 2, broken upstream merges silently propagate to every team. In addition to the obvious unit and integration tests, write contract tests that exercise the interfaces team forks depend on – startup hooks, middleware ordering, session lifecycle – so a refactor that quietly changes a hook contract fails in a Tier 2 PR rather than in a team's production deploy.

10. Alternatives to Pattern Inheritance alternatives

Forking is not the only way to solve the "consistent service patterns" problem. Here are the main alternatives, with trade-offs:

10.1. Monorepo with Shared Libraries

Instead of forks, put all services in a single repository with shared libraries for common patterns:

monorepo/
├── libs/
│   ├── fastapi-common/     # Shared middleware, auth, config
│   ├── db-common/          # SQLAlchemy setup, session management
│   └── observability/      # OpenTelemetry, logging
├── services/
│   ├── payments/
│   ├── inventory/
│   └── notifications/
└── templates/
    └── service-scaffold/   # Cookiecutter for new services

Pros: Atomic changes across services and libraries, no merge conflicts, single CI pipeline, easy refactoring.

Cons: Requires monorepo tooling (Bazel, Pants, Nx)¹³, CI complexity scales with repo size, teams lose autonomy over their release cycle, doesn't inherit from community templates.

Best for: Organizations with strong platform teams and existing monorepo infrastructure.

10.2. Template Generators with Post-Generation Updates

Tools like cruft (built on top of Cookiecutter) solve the "snapshot problem" by tracking which template version was used to generate a project and offering an update mechanism¹⁴:

# Generate project from template
cruft create https://github.com/acme-corp/fastapi-template

# Later, update to latest template version
cruft update

cruft update computes the diff between the template version you generated from and the current version, then applies that diff to your project.

Pros: No Git fork management, works with any Cookiecutter template, clear diffing between template versions.

Cons: Updates are one-way (no pushing changes back to the template), conflicts are handled at the file level (less granular than Git), doesn't compose into a multi-tier hierarchy as naturally.

Best for: Organizations that want template inheritance without the Git overhead.

10.3. Internal Developer Platforms (Backstage, Port, Humanitec)

Platforms like Backstage provide service scaffolding as a feature of a broader developer portal:

Service catalog with templates
One-click service creation from "golden path" templates
Built-in CI/CD integration
Plugin ecosystem for org-specific features

Pros: Higher-level abstraction, UI-driven, integrates service creation with service management, good for organizations with many non-expert users.

Cons: Heavy infrastructure (Backstage itself is a significant service to maintain)¹⁵, templates are still snapshots (no inheritance), vendor-specific if using a commercial platform.

Best for: Large organizations (500+ engineers) with dedicated platform teams.

10.4. Package-Based Composition

Instead of inheriting an entire project template, publish your patterns as installable packages:

# In your service's requirements.txt
acme-fastapi-core==2.3.0    # Auth, middleware, config
acme-db-common==1.5.0        # SQLAlchemy setup, migrations base
acme-observability==3.1.0    # OpenTelemetry, structured logging

Teams install these packages and compose their service from them:

from acme_fastapi_core import create_app, configure_auth
from acme_db_common import get_async_session, Base
from acme_observability import setup_tracing

app = create_app()
configure_auth(app)
setup_tracing(app)

Pros: Versioned dependencies with semantic versioning, teams can pin to specific versions, no merge conflicts, standard package management.

Cons: Requires extracting patterns into well-designed APIs (significant upfront investment), doesn't provide project structure (only runtime patterns), teams still need a scaffold for the "rest" of the project.

Best for: Organizations with mature platform teams that can invest in library design.

10.5. Comparison Matrix

Approach	Inherits from community	Multi-tier	Merge overhead	Upfront investment	Best scale
Fork hierarchy	Yes	Yes	Medium	Low	5-50 services
Monorepo	No	N/A	None	High	50+ services
cruft / template generators	Partial	No	Low	Low	5-20 services
Internal developer platform	No	No	None	Very high	100+ engineers
Package composition	No	N/A	None	High	20+ services

The fork hierarchy occupies a sweet spot: low upfront investment, inherits from community work, and scales to a meaningful number of services before the merge overhead becomes a bottleneck. For most mid-sized engineering organizations (50-500 engineers, 5-50 services on a common stack), it's the right starting point¹⁶.

These approaches aren't mutually exclusive. Mature organizations often combine package-based composition for runtime patterns (auth, observability, database utilities) with a fork hierarchy for project structure (directory layout, CI pipelines, deployment manifests, Dockerfile conventions). The fork gives you the scaffold; the packages give you the runtime behavior.

11. Conclusion conclusion

A fork hierarchy is a tax you pay weekly so that the next CVE in your auth library is one merge for your platform team and N trivial merges for service teams, instead of N independent rediscoveries followed by N different fixes. It only pays off if you're honest about the conditions: pin to signed upstream tags, ship tagged Tier 2 releases with rollback playbooks, treat fork drift as a vulnerability-management failure rather than a social one, and let services detach when they've outgrown the template. Get those right and the workflow earns its keep. Skip them and you've just built a slow vendoring pipeline with extra steps.

12. TLDR platformEngineering templates

Generate a TLDR for this document that will be displayed at the top of the static-site version of this document. Include internal org links to headings in this document where relevant. Org links look like this, regardless of the level of nesting: Footnotes. Do not use any bullets for the explanation, but you can use line breaks to help with readability. Be verbose and describe as many sections as possible. Don't forge the org links! The links should be evenly dispersed in the text you produce. CRITICAL – you must get the link format correct. The template for the ref part of the link is simply an asterisk with the header name. Do not include tags in the links

Most engineering organizations eventually face a consistency crisis: dozens of services, each built differently, each carrying its own opinions about authentication, logging, database access, and deployment. This post introduces pattern inheritance — a three-tier fork hierarchy that turns open-source community templates into living, evolvable organizational standards.

The core problem is service proliferation without standards. When every team builds from scratch, you get compounding costs in onboarding, operations, security, and upgrades. The natural instinct is to write documentation, but documentation decays. What you actually need is running code that embodies your standards.

Using a FastAPI + async Postgres stack as a concrete example, the post shows how a seemingly simple technology choice requires dozens of interlocking decisions — async driver, ORM, migrations, connection pooling, config management, and testing — that are difficult to get right in isolation. The open-source community has already solved much of this through battle-tested templates like tiangolo's full-stack-fastapi-template and various Cookiecutter scaffolds, but cloning or generating from these templates creates a point-in-time snapshot that immediately begins drifting from its source.

The key insight is that forking preserves a relationship between your code and its origin, while cloning severs it. A fork maintains an upstream remote that enables standard Git operations — fetch and merge — to pull improvements downstream over time. The mental model is inheritance in the object-oriented sense: you override specific behaviors while continuing to receive updates to the base implementation.

The recommended architecture is a three-tier fork hierarchy: Tier 1 is the community upstream template you never modify directly; Tier 2 is your organization fork where your platform team applies org-wide opinions like OIDC authentication, OpenTelemetry configuration, Vault integration, and custom CI/CD pipelines; Tier 3 consists of team forks where individual services add their domain-specific business logic. Improvements at any tier flow downstream through standard Git merges.

The post provides a detailed step-by-step setup guide, including a mirror-branch strategy that maintains a clean upstream-mirror branch for tracking the community template exactly, while main carries organizational customizations. A critical principle runs throughout: keep your diff small, prefer additive changes over modifications, and document every divergence in an ORG_CHANGES.md manifest that serves as your merge conflict playbook.

Several specific gotchas can break fork compatibility: file renames that Git fails to detect, dependency version conflicts (especially in lock files), entrypoint and startup sequence refactors, database migration conflicts caused by Alembic's linear revision chain, CI/CD pipeline divergence, Docker and infrastructure file conflicts, and Python import path changes. Each gotcha comes with concrete mitigation strategies — from layered dependency files and lifecycle hook patterns to Alembic branch labels and Docker Compose override files.

Beyond the technical gotchas, the post addresses broader organizational challenges. Merge conflict accumulation is solved through regular sync cadence — weekly or biweekly — because small, frequent merges are always easier than large, infrequent ones. Fork drift and staleness is the biggest social risk, addressed through automated staleness detection via CI jobs, org-wide sync sprints, and freshness SLOs. Governance requires dedicated platform team ownership, change classification, staged rollouts via canary services, and semantic commit prefixes. The post also honestly addresses the "too customized to merge" problem, providing clear criteria for when a service should detach from the fork hierarchy entirely. Finally, testing at the Tier 2 boundary is essential — particularly robust CI on the org fork, which acts as the immune system for your entire service fleet.

The post concludes with a thorough evaluation of alternatives — monorepos with shared libraries, template generators like cruft, internal developer platforms like Backstage, and package-based composition — presented in a comparison matrix. The fork hierarchy occupies a sweet spot of low upfront investment and community inheritance that suits most mid-sized organizations with 5–50 services on a common stack, and it composes well with package-based approaches for runtime behavior.

Footnotes:

This inflection point often arrives earlier than you'd think. At startups, it can happen at 15-20 engineers. At larger companies spinning up new product lines, it happens the moment a second team adopts the same tech stack.

There's a well-known pattern in engineering orgs where internal documentation is enthusiastically written during a "documentation sprint," links are shared in Slack, and within six months the docs are out of date and actively misleading. The half-life of an internal wiki page that isn't enforced by automation is roughly 3-6 months.

The async requirement is non-trivial. Synchronous database access in a FastAPI service blocks the event loop, which under load means a single slow query can stall every concurrent request. Getting async right involves understanding asyncpg's connection pool semantics, SQLAlchemy's async session lifecycle, and the subtle ways await points interact with transaction boundaries.

⁴

Note that GitHub Free and Team plans cannot fork a public repository into a private one. GitLab allows changing fork visibility. If you need a private org fork of a public template, the workaround is git clone + manual remote setup – you lose GitHub's fork-tracking UI, but the git-level upstream relationship is preserved.

⁵

The analogy isn't perfect. In OOP, a subclass automatically inherits method changes from its parent at compile/runtime. In fork-based inheritance, you must explicitly merge. This is actually a feature – automatic inheritance of breaking changes in production infrastructure would be terrifying. The manual merge step is your review gate.

⁶

If upstream goes dormant, the org fork effectively becomes the new upstream. This is actually fine – you've already been applying org opinions, so you just stop syncing. The main loss is community-sourced improvements and bug fixes. Monitor upstream activity and have a plan for the eventuality.

⁷

If your organization doesn't have a platform or infrastructure team, this role can be filled by a rotating "template maintainer" responsibility, similar to how some teams rotate on-call duties. What matters is that someone is explicitly accountable for the org fork's health.

⁸

An alternative to the two-branch strategy is to use tags on the upstream remote's commits. Some teams prefer git fetch upstream && git merge upstream/main directly into their main branch without a mirror. This works but makes it harder to see a clean diff of "our changes vs. upstream" since the merge history interleaves org and upstream commits. The mirror branch keeps these concerns separated.

⁹

Git's rename detection uses a similarity heuristic. By default, it considers a file renamed if the new file is at least 50% similar to the deleted file. When your org fork has heavily modified a file, the similarity drops below this threshold and Git treats it as a delete + create rather than a rename. The rename-threshold flag lowers this bar.

¹⁰

The correct approach to lock file conflicts is almost always: accept one side entirely (usually upstream's), then regenerate the lock file with your dependency overrides applied. Never attempt a three-way merge on a lock file – the format isn't designed for it and the result will be subtly corrupted.

¹¹

This is Alembic-specific, but the same class of problem exists with any linear migration system: Django migrations, Flyway, Liquibase. The general solution is always some form of migration namespacing or branching.

¹²

This mirrors a well-studied pattern in open source: "fork and forget." Studies of GitHub forks show that the vast majority of forks never sync with upstream after the initial fork. The same dynamic plays out inside organizations unless you actively counteract it.

¹³

Google (Bazel), Meta (Buck), and Twitter (Pants) all invested enormous engineering effort into making monorepos work at scale. Without that level of build system investment, monorepos tend to degrade into "monoliths with directory boundaries" where CI takes 45 minutes and a bad commit blocks every team.

¹⁴

cruft stores a .cruft.json file in your project that records the template URL, the commit hash it was generated from, and the template variables used. Running cruft update diffs between the recorded commit and the template's current HEAD, then applies the diff as a patch. It's clever, but patches are less forgiving than Git merges when conflicts arise.

¹⁵

Backstage is itself a React application with a PostgreSQL backend, a plugin architecture, and its own deployment requirements. The irony of needing to deploy and maintain a complex service just to help teams deploy and maintain their services is not lost on most platform engineers who've tried it.

¹⁶

These aren't hard boundaries. The "best scale" column reflects where each approach's trade-offs are most favorable. A fork hierarchy can work at 100+ services if you invest in tooling, and a monorepo can work at 5 services if you're already using monorepo tooling for other reasons. Choose based on your existing infrastructure and team capabilities, not just service count.

Schema Diagrams: Bidirectional Visualization for the Schema Languages That Need It Most

Charlie Holland — Tue, 03 Mar 2026 08:29:00 GMT

1. About schemaVisualization dataModelling

Figure 1: JPEG produced with DALL-E 4o

If you've ever worked with a relational database, you've almost certainly seen an entity-relationship diagram (ERD). Maybe it was generated by DataGrip or pgAdmin, or maybe someone drew it in Lucidchart. In any event, the point is you actually saw the data model. You could point at boxes, trace lines, and say "this table references that one."

Now think about the last time you reviewed an Avro schema. If you're like most engineers, you opened a JSON file, scrolled through hundreds of lines of deeply nested objects, and mentally assembled the structure in your head. No boxes. No lines. Just JSON. I'd be surprised if most readers have actually seen visualizations of the models composed by Avro schemas.

This gap – between the rich visual tooling that SQL databases have enjoyed for decades and the near-complete absence of equivalent tooling for schema languages like Avro – is what Schema Diagrams aims to close, you can try out at that link, or you can view the source at schema-diagrams on GitHub. It's a diagrams-as-code tool that renders interactive entity-relationship diagrams from Avro schemas, with bidirectional sync between the code editor and the visual canvas. Edit the code, the diagram updates. Edit the diagram, the code updates. Everyone works on the same artifact.¹

This post is a companion to my earlier post on schema language selection, which explored which schema language to choose. This post asks a different question: once you've chosen, how do you actually see what you've built?

2. The Visualization Gap schemas toolingGap

Avro schemas are defined as JSON. This is a reasonable serialization choice – JSON is ubiquitous, parsable everywhere, and schema registries speak it natively. But it's a terrible authoring format for complex data models.

Consider a moderately complex schema: a User record with nested Address, PaymentMethod, and OrderHistory types, each referencing further records and enums. In raw .avsc JSON, this might look like 300 lines of nested objects, arrays, and union types. The structural relationships – which records reference which, what the cardinality is, where the enums live – are buried in syntax².

This creates real problems:

PR reviews become rubber stamps. When a schema change is a diff of 50 lines of JSON, reviewers skim rather than analyze. Subtle issues – an accidental field removal, a type change that breaks backward compatibility, a new nullable union that downstream consumers don't handle – slip through.
Onboarding stalls. A new engineer joining a team with 40 Avro schemas across a Kafka-based architecture faces weeks of spelunking through .avsc files to build a mental model of the data domain. With SQL, they'd open an ERD and have the big picture in minutes.
Cross-team communication breaks down. When a data engineer needs to explain a schema to a product owner or data analyst, they have two options: hand them the raw JSON (useless) or manually draw a diagram in Lucidchart (labor-intensive, extremely error prone, and immediately stale).
Duplicate schemas proliferate. Without a visual map of existing types, teams create new schemas that partially duplicate existing ones. In large organizations, this leads to dozens of slightly different Address or Timestamp definitions scattered across registries. This undermines the effort to reach a single source of truth and avoid model drift, as explained in my post on schema language selection.

SQL databases solved these problems eons ago. You can point any of thirty-plus tools at a database, and within seconds you have an ERD showing every table, column, relationship, and constraint. The schema languages powering modern event-driven systems – the schemas that are the API contracts between services – have nothing comparable.

3. The State of Schema Visualization Tooling marketAnalysis

The landscape splits along two axes: which schema language is supported, and whether the tool is one-directional (code → diagram) or bidirectional (code ↔ diagram). The findings are sobering.

3.1. SQL ERD: The Gold Standard

SQL has been around since the 1970s, and its visual tooling reflects that maturity. Over thirty actively maintained tools exist:

Free web-based: dbdiagram.io (with its DBML diagram-as-code format), DrawDB, DrawSQL, ChartDB, ERDPlus, QuickDBD
Commercial: Lucidchart, Vertabelo, SQLDBM, DataGrip, Navicat
Open-source CLI: SchemaSpy, SchemaCrawler, tbls, ERAlchemy

Many of these support true bidirectional workflows. DBML, the language behind dbdiagram.io, lets you write schema definitions in a concise DSL, generate visual diagrams, and export DDL for multiple database engines. The round-trip is seamless: design visually, export code; import code, refine visually.

AI-powered options are emerging too – ChartDB includes an AI agent for generating schemas, and Eraser.io can generate ERDs from natural language. This is what mature tooling ecosystems look like.

3.2. Avro: The Tooling Desert

The total number of visualization tools I've been able to identify: roughly six.

Hackolade Studio (~$700/year per seat) – The most capable option. It supports forward-engineering (diagram → .avsc) and reverse-engineering (.avsc → diagram), generates ERD-style views, and integrates with Confluent Schema Registry. But it's a proprietary desktop application, not a diagram-as-code tool, and the price point puts it out of reach for many teams.

You can see the tree, but you can't see the forest.

bol.com Avro Schema Viewer (free, open source) – A web-based hierarchical tree viewer for .avsc files. It renders schemas as expandable/collapsible trees with URL-based navigation. It's useful for browsing, but it's read-only and doesn't produce relationship diagrams. You can see the tree, but you can't see the forest.
schema-uml (free, open source) – A Python tool that converts .avdl and .proto files into UML diagrams via Graphviz. One-directional: schema → diagram. No editing, no round-trip.
Javro (free) – An Avro schema editor with autocomplete and JSON preview. Focused on authoring, not visualization. No diagram output.
Schema Registry UIs (Lenses, Confluent Cloud) – Show schemas as raw JSON with version history. No diagram view, no relationship visualization.

That's it. Six tools, two of which are commercial, and only one of which offer bidirectional diagram-as-code editing. Compare thirty-plus for SQL, with multiple free bidirectional options, AI integration, and active communities. The gap is staggering³.

3.3. Protobuf and JSON Schema

The other major schema languages fare somewhat better, but still lag far behind SQL.

Protocol Buffers benefit from Google's ecosystem. proto-gen-md-diagrams (from Google Cloud Platform) generates Markdown documentation with embedded Mermaid UML diagrams from .proto files. protobuf-uml-diagram and protobuf2uml provide additional UML generation. Protobuf's .proto format is also inherently more readable than Avro's JSON schema, which reduces (but doesn't eliminate) the need for visualization.

JSON Schema has the broadest visualization ecosystem among non-SQL formats: JSON Crack (graph visualization of any JSON), Atlassian's JSON Schema Viewer, IntelliJ plugins, and even a GSoC 2025 project specifically focused on interactive graphical schema viewing.

But even JSON Schema visualization is nowhere near SQL's maturity. And critically, across all three non-SQL formats, the category of bidirectional diagram-as-code tools is essentially empty.

3.4. The Missing Category: Bidirectional Diagram-as-Code

This is the core insight. The tools that exist for Avro (and Protobuf, and JSON Schema) fall into two categories:

Viewers – one-directional tools that render a schema as a diagram or tree. Useful for understanding, but the output is a dead end. You can't edit the diagram and have the changes flow back to your schema code.
Editors – authoring tools with autocomplete and validation, but no visual output. You're still staring at text.

What's missing is the third category: tools where the code and the diagram are the same artifact, kept in sync bidirectionally. In the SQL world, DBML and dbdiagram.io pioneered this. In the architecture diagramming world, this is exactly what CN Diagrams does for architecture diagrams.

Schema Diagrams brings this same bidirectional paradigm to schema visualization. Write Avro JSON or IDL in the code editor, see the diagram update in real time. Click a field in the diagram to rename it, and the code updates. The code is the diagram, and the diagram is the code.

4. How Schema Diagrams Works features

Schema Diagrams provides several capabilities designed to make Avro schemas tangible. You can try it directly at Schema Diagrams.

4.1. Bidirectional Editing

The Monaco editor (the same engine behind VS Code) and the Svelte Flow canvas stay synchronized. Add a field in the code, it appears as a row in the corresponding entity node. Click a field name in the diagram to rename it, and the code updates. Change a field's type via the visual dropdown, and the JSON or IDL reflects the change.

This eliminates the choice between maintainability and accessibility. Engineers version-control the schema code through pull requests. Data analysts and product owners explore and propose changes through the visual interface. Both are editing the same artifact.

4.2. Dual Format Support

Schema Diagrams supports both major Avro representations:

Avro JSON (.avsc) – the format that Schema Registries consume, and the format most Avro tooling produces. Verbose but ubiquitous.
Avro IDL (.avdl) – the human-readable interface definition language. More concise, closer to how engineers think about types.

Format detection is automatic. Paste a JSON schema, and the tool recognizes it. Switch to IDL, and it parses that instead. Both formats are first-class citizens⁴.

4.3. Automatic Layout and Inline Validation

Schema Diagrams uses ELK (Eclipse Layout Kernel) to position entity nodes automatically. There's no manual arrangement required – the layout algorithm handles node positioning, edge routing, and spacing. This is a deliberate design choice: the diagram's layout is deterministic based on the schema structure, which means it stays consistent as schemas evolve. For example, you won't see a complete shuffling of node and edge postitions when changing the name of a schema or field.

The Monaco editor provides inline validation with squiggly underlines and error markers at specific line/column positions. Syntax errors, missing fields, and type resolution failures surface immediately as you type – no waiting for a separate compilation or validation step.

4.4. Relationship Discovery

The tool automatically detects and visualizes relationships between schema types:

Reference edges (blue) – when a field's type is another named record
Nested record edges (purple) – when a record is defined inline within another
Join edges (orange, dashed) – explicit cross-schema relationships declared via @join annotations in IDL or x.join metadata in JSON

Each edge includes cardinality labels (1:1, 1:N, N:1, N:N), making the data model's topology immediately visible. Records can be collapsed to reduce visual clutter while maintaining relationship visibility – useful when working with schemas that have dozens of fields.

5. Benefits productivity collaboration

5.1. Cross-Persona Accessibility

The bidirectional sync is not just a technical feature – it's an organizational one. Data engineers author schemas in IDL or JSON. Data analysts read the diagram. Product owners can understand the data model without parsing nested JSON. Governance teams audit schema structures visually. Everyone contributes in their preferred medium, and everyone stays in sync.

This matters especially in organizations practicing data mesh, where data products are owned by domain teams rather than a central data platform. The schema is the product's interface, and that interface needs to be readable by consumers who may not share the producer's technical background.

5.2. Schema Reviews That Work

Pull request reviews of .avsc files are notoriously unproductive. A 50-line JSON diff tells you what changed syntactically, but not what it means structurally. Did we add a new entity? Change a relationship? Break backward compatibility?

Paste both versions into Schema Diagrams and the structural changes become immediately visible. The visual representation surfaces the intent of the change, making reviews faster and more thorough.

5.3. Faster Onboarding

New team members joining a Kafka-based architecture with dozens of Avro topics can explore schemas visually rather than reading raw JSON files one by one. The diagram reveals the data domain's structure at a glance – which records reference which, where the enums live, what the cardinalities are – providing an overview that would otherwise take days to assemble mentally.

5.4. Schema Evolution Awareness

Avro's schema evolution rules – backward compatibility, forward compatibility, full compatibility – are powerful but difficult to reason about from raw JSON alone. While Schema Diagrams is not a full evolution validator, the visual representation makes structural changes between schema versions obvious, helping teams catch potential issues before they reach production.

6. Beyond Avro extensibility protobuf jsonSchema

The architectural pattern behind Schema Diagrams – parse schema → build graph model → automatic layout → bidirectional sync – is fundamentally schema-agnostic. The parser produces an intermediate representation of entities, fields, and relationships. The layout engine and visual editor don't care whether those entities came from Avro, Protobuf, or JSON Schema.

The current focus is Avro because the need is most acute there – it has the weakest visualization tooling relative to its widespread use in streaming data platforms. But the framework is designed to be extensible. Protocol Buffers, JSON Schema, Thrift, and even GraphQL SDL could all be supported by adding a parser that produces the same intermediate graph representation.

The vision is a single tool where teams can visualize any schema format with the same bidirectional editing experience, regardless of which serialization technology their platform uses.

7. Getting Started bootstrap ai

The fastest path to a useful diagram is simple: paste a schema into the editor at Schema Diagrams and watch the diagram appear. Built-in example schemas (simple records, deeply nested hierarchies) provide starting points if you want to explore the tool before bringing your own data.

For teams with existing schemas spread across a Schema Registry, AI assistance can accelerate the process. LLMs are remarkably good at reading structured formats like JSON and IDL, and they can help consolidate, clean up, or annotate schemas before visualization. The workflow is straightforward:

Export schemas from your Schema Registry (Confluent CLI, REST API, etc.)
Ask an AI agent to consolidate related schemas, add @join annotations for cross-schema relationships, or convert between JSON and IDL
Paste the result into Schema Diagrams
Refine visually – renames, type adjustments, and field additions happen directly on the canvas

This isn't as transformative as AI-bootstrapping an entire architecture diagram from a codebase (as described in the CN Diagrams post), because schemas already exist as structured text. But it meaningfully lowers the barrier to getting a comprehensive visual overview of a data domain that might span dozens of .avsc files.

8. Contributing openSource

Schema Diagrams is open source under the MIT license. The source code is available at github.com/chiply/schema-diagrams.

8.1. Tech Stack

For those interested in contributing, Schema Diagrams is built with:

SvelteKit (Svelte 5) – Application framework with runes for reactivity
Svelte Flow (@xyflow/svelte) – Interactive node/edge diagram canvas
ELK (elkjs) – Automatic graph layout engine
Monaco Editor – VS Code's editor component for schema authoring
TypeScript throughout
Vercel – Deployment platform

8.2. How to Contribute

Contributions are welcome in several forms:

Bug Reports: If something doesn't work as expected, open an issue with steps to reproduce. Include your browser and any error messages from the console.

Feature Requests: Have an idea for improvement? Open an issue describing the use case and proposed solution. New parser support (Protobuf, JSON Schema) is a particularly impactful area.

Pull Requests: Fork the repository, create a feature branch, and submit a PR. Please include tests for new functionality and ensure existing tests pass.

Documentation: Improvements to README, examples, or inline comments are valuable contributions that don't require deep code knowledge.

The project is early-stage, and there's significant opportunity to shape its direction. Parser contributions for additional schema formats would be especially welcome.

9. Conclusion

Schema visualization shouldn't be a luxury reserved for SQL databases. The schema languages powering modern event-driven architectures – Avro, Protobuf, JSON Schema – define the contracts between services, the shape of data flowing through pipelines, and the interfaces of data products. Those contracts deserve the same visual tooling that ERDs have provided for relational databases for decades.

Schema Diagrams is an attempt to close that gap, starting with the format that needs it most. Avro's JSON verbosity, its deep nesting, its implicit relationships – these aren't flaws in the format, but they do make visualization essential rather than optional. And by building on the bidirectional sync paradigm, the tool serves not just the engineer who writes the schema, but every persona in the organization who needs to understand it.

Try it at Schema Diagrams. Browse the source at github.com/chiply/schema-diagrams. If you build something interesting or have feedback, I'd love to hear about it.

10. tldr

Schema Diagrams is an open-source tool that brings bidirectional, diagram-as-code visualization to Apache Avro schemas – closing a gap that SQL ERD tools filled decades ago. The problem is straightforward: Avro schemas are defined as deeply nested JSON, and the tooling for visualizing them is nearly nonexistent. While SQL has thirty-plus ERD tools (many free, many bidirectional), Avro has roughly six – two commercial, the rest read-only viewers or one-directional generators. No bidirectional diagram-as-code tool existed for Avro.

Schema Diagrams fills this gap with a Monaco editor (VS Code's engine) synchronized bidirectionally with a Svelte Flow canvas. Edit Avro JSON or IDL in the code editor, and the ERD updates in real time. Click fields in the diagram to rename them, change types, or add new fields, and the code updates. The tool supports both .avsc JSON and .avdl IDL with automatic format detection, uses ELK for deterministic automatic layout, and renders relationship edges with cardinality labels.

The payoff is organizational: engineers version-control schemas through PRs while analysts and product owners explore visually – everyone works on the same artifact. Schema reviews become structural rather than syntactic, onboarding accelerates, and cross-team communication improves. The architecture is schema-agnostic – Protobuf, JSON Schema, and other formats could reuse the same engine. Try it at the Schema Diagrams page or explore the source at github.com/chiply/schema-diagrams.

Footnotes:

This is the same bidirectional sync paradigm behind CN Diagrams, my architecture diagramming tool. The core insight is the same: when code and visuals are the same artifact, you don't have to choose between maintainability and accessibility.

Avro IDL (.avdl) is significantly more readable than the JSON representation, and Schema Diagrams supports both. But in practice, most Schema Registry tooling and most Avro codegen pipelines work with .avsc JSON, so that's what engineers end up reading and reviewing.

There's an irony here. Avro was designed specifically for data exchange – it's a schema-first format built for interoperability between systems. Yet the tooling for understanding those schemas across teams is almost nonexistent. The format that most needs cross-persona visualization has the least of it.

⁴

Automatic format detection sounds simple, but it matters more than you might think. In practice, engineers switch between JSON and IDL constantly – JSON for registry interactions, IDL for human authoring. A tool that requires you to specify the format adds friction. One that figures it out adds flow.

brushup: Theme-Aware Dynamic Color Palette for Emacs

Charlie Holland — Sun, 01 Mar 2026 19:49:00 GMT

1. About emacs theming colorPalette

Figure 1: JPEG produced with DALL-E 4o

Emacs theming has a dirty secret: most face customizations are written against one theme and silently break against every other. You pick colors that look right in your dark theme, switch to something light for a change of scenery, and suddenly half your UI is unreadable. brushup generates a dynamic color palette from your current theme's foreground and background, so your face customizations work everywhere.

2. The Problem: Theme-Dependent Styling theming problem

Say you've customized org-mode headings, your modeline, or some niche package's faces. You hardcode hex values because they look good in your current theme:

(set-face-attribute 'org-level-1 nil :foreground "#a0b0c0")
(set-face-attribute 'my-custom-face nil :background "#1a1a2e")

These colors assume a dark background. Switch to a light theme and #1a1a2e is nearly invisible against a white background, while #a0b0c0 loses all its contrast. The usual workaround is to write conditional logic:

(if (eq (frame-parameter nil 'background-mode) 'dark)
    (set-face-attribute 'org-level-1 nil :foreground "#a0b0c0")
  (set-face-attribute 'org-level-1 nil :foreground "#3a4a5a"))

This doubles your configuration for every face you touch and still only handles two themes. If you use three or four themes across different times of day or contexts, the branching gets unwieldy fast. What you actually want is a way to say "give me a color that's 30% of the way from the background toward the foreground" and have that resolve correctly regardless of the theme.

3. How brushup Works emacs architecture

brushup reads two colors from your current theme: the default foreground and the default background. From these, it generates a parametric gradient, a series of intermediate colors stepping from one toward the other. The result is twelve palette variables: six foreground gradients (brushup-fg-1 through brushup-fg-6, stepping from the foreground toward the background) and six background gradients (brushup-bg-1 through brushup-bg-6, stepping from the background toward the foreground).

You describe your color intent in relative terms, and the palette resolves it against whatever theme is active.

The gradient step size is controlled by brushup-gradient-step (default: 7%). Each level moves that percentage further along the lightness axis. brushup-fg-1 is a subtle shift, barely distinguishable from the raw foreground. brushup-fg-6 is a dramatic shift, nearly halfway to the background.

brushup also detects whether your theme is dark or light using a luminosity calculation on the background color, exposing the result as brushup-dark-p. This means you never need to check background-mode yourself.

When brushup-mode is enabled, the package hooks into enable-theme-functions. Every time you load or switch themes, brushup re-generates the entire palette and re-evaluates all registered styles. You describe your color intent in relative terms, and the palette resolves it against whatever theme is active.

4. The Palette theming reference

Here's the full set of palette variables:

Variable	Description
`brushup-fg`	Raw theme foreground
`brushup-bg`	Raw theme background
`brushup-fg-1` to `brushup-fg-6`	Foreground gradient (1=subtle, 6=strong shift toward bg)
`brushup-bg-1` to `brushup-bg-6`	Background gradient (1=subtle, 6=strong shift toward fg)
`brushup-bg-1_0`	Very subtle background shift (solaire-like effect)
`brushup-dark-p`	`t` if current theme is dark

The gradient levels map naturally to common styling needs:

Level 1-2: Subtle emphasis. Comments, inactive modeline text, de-emphasized UI elements.
Level 3-4: Moderate contrast. Secondary headings, sidebar text, annotations.
Level 5-6: Strong contrast. Borders, separators, high-visibility indicators.

5. Demo: Switching Themes emacs demonstration

Here's what it looks like when you switch themes with brushup active. Every registered face customization re-evaluates instantly.

6. The Style System emacs configuration

brushup doesn't apply colors directly. Instead, you register forms in brushup-styles, a list of expressions that get evaluated whenever the palette updates. Each form can reference any palette variable:

(add-to-list 'brushup-styles
  '(set-face-attribute 'org-level-1 nil :foreground brushup-fg-3))

(add-to-list 'brushup-styles
  '(set-face-attribute 'line-number nil
     :foreground brushup-fg-5
     :background brushup-bg-1))

When the theme changes, brushup regenerates the palette values, then walks the list and evaluates each form. Errors in individual forms are caught and reported without stopping the rest, so a broken customization won't take down your entire UI.

6.1. use-package Integration

brushup registers a custom :brushup keyword with use-package, so you can co-locate your style registrations with the packages they customize:

(use-package magit
  :ensure t
  :brushup
  (add-to-list 'brushup-styles
    '(set-face-attribute 'magit-section-heading nil
       :foreground brushup-fg-2)))

The :brushup keyword defers evaluation until the package loads, then registers the forms. This keeps theme-dependent styling next to the package configuration it belongs with.

7. Getting Started emacs installation

brushup is on GitHub. Install with elpaca, straight.el, or manually, then enable brushup-mode.

(use-package brushup
  :ensure (:host github :repo "chiply/brushup")
  :config
  (brushup-mode 1))

If you're already maintaining a pile of theme-conditional face settings, brushup is a good excuse to delete them. Replace the hardcoded hex values with palette variables, register them as styles, and let the gradient do the work.

magneto: Composable Window Management for Emacs

Charlie Holland — Sun, 01 Mar 2026 19:49:00 GMT

1. About emacs windowManagement composition

Figure 1: JPEG produced with DALL-E 4o

Window management in Emacs is either too simple or too opinionated. split-window-right and split-window-below are basic primitives that require manual sequencing. purpose and shackle give you declarative rules but take away direct control. What I wanted was something in between: a small grammar of composable operations where I set the parameters I care about and let the system handle the plumbing. magneto is that grammar. Press a key to enter compose mode, set any combination of source action, destination, cursor placement, and buffer action, then press RET to execute.

2. The Window Management Problem emacs problem

Here's a common sequence: you're looking at a file and you want to open a related file in a vertical split to the right, keeping your cursor on the original. In vanilla Emacs:

(split-window-right)       ; split
(other-window 1)           ; move to new window
(find-file "related.el")   ; open file
(other-window -1)          ; move back

Every combination of source, destination, cursor, and buffer action is a separate function you'd need to write or find.

Four commands, and you need to remember the sequence. Want to copy the current buffer instead of opening a new file? Different sequence. Want to split below instead of right? Different sequence. Want the cursor to stay in the new window? Omit the last step. Every combination of source, destination, cursor, and buffer action is a separate function you'd need to write or find.

magneto collapses this combinatorial explosion into a single composable flow. Instead of four sequential commands, you press your magneto key, then press modifiers to set whatever differs from the defaults, then execute. The number of keystrokes scales with how much you're customizing, not with the inherent complexity of the operation.

3. Composable Operations emacs architecture

magneto operations have four independent dimensions:

Dimension	Question	Default
Source Action	What happens to the origin window?	move
Destination	Where does the buffer go?	fill existing
Cursor Placement	Where does your cursor end up?	follow (`o`)
Buffer Action	What buffer appears in the destination?	switch-buffer

Each dimension has its own keys. You press any combination of them in any order before executing with RET. Any dimension you don't set uses its default. This means the simplest magneto operation (just RET with all defaults) is equivalent to switch-to-buffer in the current window. But adding one or two keys before RET gives you dramatically different behavior.

4. Source Actions emacs source

The source action controls what happens to the origin window after the buffer lands in its destination.

Key	Action	Behavior
`m`	Move	Delete the origin window (buffer leaves the original spot)
`c`	Copy	Keep the origin window (buffer is now visible in two places)
`p`	Pull	Show the previous buffer in the origin window

Move is the default and matches the most common intent: relocate a buffer. Copy is useful when you want a reference view alongside an editing view of the same context. Pull is a refinement of move, the buffer leaves, but instead of the window disappearing, it shows whatever was there before.

5. Destination Actions emacs destination

The destination controls where the buffer ends up.

5.1. Splits

Key	Direction
`V`	Split above
`v`	Split below
`H`	Split left
`h`	Split right

Uppercase keys create the split on the "before" side (above, left); lowercase on the "after" side (below, right).

5.2. Side Windows

Key	Position
`t`	Top side
`b`	Bottom side
`l`	Left side
`r`	Right side

Side windows use Emacs's display-buffer-in-side-window, which means they resist delete-other-windows and stay pinned to their edge. Uppercase variants (T, B, L, R) control slot ordering when you have multiple side windows on the same edge.

5.3. Fill Existing Window

Key	Action
`0`	Select an existing window via ace-window

Fill doesn't create a new split. It routes the buffer into a window you pick interactively. This is the default destination, so pressing RET immediately prompts you to pick a window (or uses the current one if there's only one).

6. Cursor Placement emacs cursor

Key	Behavior
`o`	Follow: cursor moves to the destination window
`O`	Stay: cursor remains in the origin window

This is the difference between "open this file over there and keep working here" and "open this file over there and go to it." A small distinction that eliminates a other-window call in half your workflows.

7. Buffer Actions emacs buffers

The buffer action controls what appears in the destination window.

Key	Action	Description
`w`	Buffer (consult)	Switch via `magneto-buffer-command` (customizable, defaults to `switch-to-buffer`)
`f`	Find file	Call `find-file` interactively
`x`	Execute command	Run an extended command
`C-b`	Switch buffer	Built-in `switch-to-buffer` directly

Set magneto-buffer-command to #'consult-buffer if you use consult:

(setq magneto-buffer-command #'consult-buffer)

8. Demo: Basic Composition emacs demonstration

Composing a few simple operations: split right with a file, copy to a split below, move to an existing window.

9. Demo: Side Windows emacs demonstration

Pinning buffers to edges using side window destinations.

10. Demo: Pre-selecting with Ace-Window emacs demonstration

Pre-selecting a destination window before composing the rest of the operation.

magneto uses ace-window's visual overlay to let you pick a window. The keys a, s, d in the compose keymap pre-select the first, second, or third window by ace-window ordering. This lets you set the destination before you've even decided what to put in it.

11. Embark Integration embark composition

magneto includes an optional embark integration module (magneto-embark.el) that routes embark actions through magneto's compose system. The idea: when you act on an embark candidate, you often want to control where the result ends up. Without magneto, embark opens files in the current window. With magneto, you can send them to a split, a side window, or a pre-selected ace-window target.

magneto-embark-bind-keys scans all registered embark keymaps and generates magneto-routed versions of relevant actions (find-file, consult-bookmark, goto-grep, etc.). These are bound under s-o in each embark keymap. So where you'd normally press f in embark to open a file, pressing s-o f opens it through magneto's compose flow instead.

12. Demo: Embark Workflows emacs demonstration

Routing embark actions through magneto to control destination windows.

13. Workflow Examples emacs workflows

13.1. Expand a Layout

You're reading a file. You want to open a test file to the right and keep your cursor where you are.

Keys: magneto-compose h O f RET (then pick the file)

Breakdown: h (split right), O (stay at origin), f (find-file), RET (execute).

13.2. Side-by-Side Comparison

You want the same buffer in two windows, scrolled to different positions.

Keys: magneto-compose c h RET

Breakdown: c (copy, keep original), h (split right), RET (execute). The buffer is now in both windows. For independent scroll positions, use M-x magneto-make-indirect first to create an indirect buffer clone.

13.3. REPL Setup

You want a shell in a bottom side window that persists across delete-other-windows.

Keys: magneto-compose b x RET (then type shell)

Breakdown: b (bottom side window), x (execute-command), RET (execute). The shell opens in a persistent bottom panel.

14. Customization Reference emacs configuration

All defaults are customizable:

Variable	Default	Description
`magneto-default-source-action`	`"move"`	Default source behavior
`magneto-default-destination-action`	`"f"`	Default destination (fill)
`magneto-default-select-action`	`"o"`	Default cursor placement (follow)
`magneto-default-action-action`	`"switch-buffer"`	Default buffer action
`magneto-buffer-command`	`#'switch-to-buffer`	Command for buffer switching
`magneto-default-destination-window`	`nil`	Pre-selected ace-window target

15. Getting Started emacs installation

magneto is on GitHub. It requires Emacs 29.1+ and depends on avy and ace-window.

(use-package magneto
  :ensure (:host github :repo "chiply/magneto")
  :bind ("s-m" . magneto-compose)
  :custom
  (magneto-buffer-command #'consult-buffer))

For embark integration:

(use-package magneto-embark
  :after (magneto embark)
  :config
  (magneto-embark-bind-keys))

Bind magneto-compose to a comfortable key, press it, and start composing. The which-key popup (if you use which-key) shows all available modifiers. Press RET when you're ready. Start with the defaults and add modifiers as you learn the grammar.

repeatable-lite: Make Any Prefix Command Repeatable

Charlie Holland — Sun, 01 Mar 2026 19:49:00 GMT

1. About emacs keybindings productivity

Figure 1: JPEG produced with DALL-E 4o

Emacs loves prefix keys. C-x, C-c, C-c w, C-c p … the deeper your configuration goes, the longer your prefixes get. The problem is that many commands you'd want to call repeatedly sit behind these prefixes: window navigation, text scaling, buffer cycling. You end up typing the same prefix over and over. repeatable-lite fixes this in about 230 lines. Wrap a command with repeatable-lite-wrap and after the first invocation, the prefix stays active. Press the final key again to repeat. Press anything else to exit.

2. The Prefix Problem emacs problem

Say you've bound window navigation to C-c w h/j/k/l:

(global-set-key (kbd "C-c w h") #'windmove-left)
(global-set-key (kbd "C-c w l") #'windmove-right)
(global-set-key (kbd "C-c w j") #'windmove-down)
(global-set-key (kbd "C-c w k") #'windmove-up)

You want to move two windows left. That's C-c w h C-c w h, eight keystrokes for two moves. Navigate through a four-window layout and you're pressing C-c w four times. The prefix is supposed to organize your keybindings, but under repetition it becomes dead weight.

The prefix is supposed to organize your keybindings, but under repetition it becomes dead weight.

Emacs has repeat-mode (built-in since Emacs 28), which solves this for built-in commands. But it requires you to define repeat-map keymaps manually for every group of commands, and it doesn't integrate with which-key to show what's available. hydra and transient are more powerful but heavier, with their own configuration DSLs and display systems. repeatable-lite sits in the gap: one macro, automatic which-key integration, no configuration language.

3. How It Works emacs implementation

The API is a single macro: repeatable-lite-wrap. It takes a function name and returns a new command that:

Calls the original function.
Re-activates the prefix keymap.
Shows which-key with all available keys in that prefix.
Reads the next key and dispatches it:
- If it's bound in the prefix keymap, execute it and loop.
- If it's C-h, show help and continue.
- If it's C-u, accumulate prefix arguments and continue.
- If it's anything else, exit the loop and feed the key back to normal command dispatch.

(global-set-key (kbd "C-c w h") (repeatable-lite-wrap windmove-left))
(global-set-key (kbd "C-c w l") (repeatable-lite-wrap windmove-right))
(global-set-key (kbd "C-c w j") (repeatable-lite-wrap windmove-down))
(global-set-key (kbd "C-c w k") (repeatable-lite-wrap windmove-up))

Now C-c w h h h moves three windows left, six keystrokes saved. And because which-key appears immediately after the first command, you can see all the other keys in the C-c w prefix without memorizing them.

3.1. Which-Key Integration

repeatable-lite configures which-key for optimal display during the repeatable loop. It saves your current which-key settings, enables persistent popup mode, and sets aggressive idle timers (0.1 seconds) so the guide appears instantly. When you exit the loop, all settings are restored to their previous values.

This means which-key acts as a live reference while you're in the repeatable state. You don't need to remember every key in the prefix, you just need to know one, and the popup shows you the rest.

5. Getting Started emacs installation

repeatable-lite is on GitHub. It requires Emacs 30.1+ (which-key is built-in since 30.1).

(use-package repeatable-lite
  :ensure (:host github :repo "chiply/repeatable-lite")
  :config
  (repeatable-lite-mode 1))

Then wrap any commands you want to make repeatable. Here's a fuller example using general.el:

(general-define-key
 "C-c w h" (repeatable-lite-wrap windmove-left)
 "C-c w l" (repeatable-lite-wrap windmove-right)
 "C-c w j" (repeatable-lite-wrap windmove-down)
 "C-c w k" (repeatable-lite-wrap windmove-up)
 "C-c w =" (repeatable-lite-wrap enlarge-window-horizontally)
 "C-c w -" (repeatable-lite-wrap shrink-window-horizontally))

Every command under C-c w becomes repeatable. Type the prefix once, then just the final key. When you're done, press anything outside the keymap and you're back to normal.

spot: A Spotify Client Built on Consult, Embark, and Marginalia

Charlie Holland — Sun, 01 Mar 2026 19:49:00 GMT

1. About emacs spotify completion

Figure 1: JPEG produced with DALL-E 4o

There are a few Spotify clients for Emacs. Most of them predate the modern completion ecosystem, so they build their own UI from scratch: custom buffers, custom keymaps, custom rendering. spot takes a different approach. It's built entirely on consult, embark, and marginalia, which means searching, acting on results, and reading metadata all use the same interfaces you already know.

2. Why Another Spotify Client spotify motivation

smudge (formerly spotify.el) is the most established Emacs Spotify client. It works, but it renders results in a custom tabulated-list buffer. You search, wait for a buffer to pop up, navigate it with its own keybindings, and act on items through its own action system. This is a parallel universe of interaction that doesn't benefit from any of the completion infrastructure you've invested in.

spot doesn't have its own UI idioms to learn. The UI is consult + embark + marginalia.

If you use vertico or selectrum for completion, embark for contextual actions, and marginalia for annotations, you already have a sophisticated interaction model. spot plugs into that model directly. Search results appear in your minibuffer completion framework. Metadata shows up as marginalia annotations. Actions are embark actions. There's nothing new to learn, just Spotify data flowing through tools you already use.

3. Architecture emacs design

spot is modular by design. Each concern lives in its own file:

spot-auth.el: OAuth2 authorization code flow with token refresh
spot-search.el: Mutex-guarded, cached search with argument parsing
spot-consult.el: Seven async consult sources (albums, artists, tracks, playlists, shows, episodes, audiobooks)
spot-marginalia.el: Annotation functions per content type
spot-embark.el: Action keymaps per content type
spot-mode-line.el: Currently-playing display with smart update timing

The search layer deserves a note. spot uses a mutex to serialize concurrent search requests and caches results by query string. This matters because consult's async sources fire searches as you type, and Spotify's API has rate limits. Without the mutex, rapid keystrokes could produce interleaved results or hit rate limits. The cache prevents redundant API calls when you backspace and retype.

3.1. OAuth2 Flow

Spotify requires OAuth2 for most API operations. spot handles the authorization code grant flow: it opens the Spotify authorization URL in your browser, you log in and approve, then paste the authorization code back into Emacs. The access token is stored in memory for the session, and spot refreshes it automatically when it expires. You set spot-client-id and spot-client-secret from a Spotify Developer application.

M-x spot opens a consult--multi search across all seven content types. As you type, spot searches the Spotify API asynchronously and populates completion candidates. Each content type has a narrowing key:

Key	Content Type
`a`	Albums
`A`	Artists
`p`	Playlists
`t`	Tracks
`s`	Shows
`e`	Episodes
`b`	Audiobooks

Narrowing works the way consult narrowing always works: press the narrowing key to filter to a single content type, or leave it open to see everything.

Queries also support Spotify's field filter syntax via -- separator. For example, radiohead -- --type=album restricts the API query to albums only, which is more efficient than fetching everything and narrowing client-side.

5. Demo: Search and Playback spotify demonstration

Here's a search session showing multi-source results, marginalia annotations, and playback control.

6. Marginalia Annotations marginalia metadata

Each content type has its own marginalia annotator that pulls relevant metadata from the Spotify API response. Here's what you see in the completion margin for each type:

Type	Annotations
Albums	Artist, release date, track count
Artists	Popularity score, follower count
Tracks	Track number, artist, duration, album, release date
Playlists	Track count
Shows	Publisher, media type, episode count, description
Episodes	Release date, duration, description
Audiobooks	Publisher, narrator, author, description

This is pure marginalia integration. The annotators register themselves when spot-mode is enabled and unregister when it's disabled. If you don't use marginalia, spot still works, you just don't see the extra metadata.

7. Embark Actions embark actions

spot defines embark keymaps for every content type. When you press your embark-act key on a completion candidate, you get actions appropriate to that type:

Key	Action	Available On
`P`	Play	All types
`s`	Show raw JSON data	All types
`t`	List tracks	Albums, artists, playlists
`+`	Add to playlist	Tracks only

Listing an album's tracks, for example, opens a new consult search narrowed to that album's tracks. From there you can play individual tracks, inspect them, or add them to a playlist, all through the same embark action system.

8. Mode Line emacs modeline

When spot-mode is enabled, the mode line shows the currently playing track, artist, and album. The display updates on a 30-second timer, with smart scheduling that calculates the time remaining in the current track to minimize unnecessary API calls. The currently-playing text is displayed in Spotify green (#1db954) by default.

9. Player Controls spotify playback

spot provides standard player commands, all operating through Spotify Connect:

(spot-player-play)      ; Resume playback
(spot-player-pause)     ; Pause playback
(spot-player-next)      ; Skip to next track
(spot-player-previous)  ; Skip to previous track

There's also spot-add-current-track-to-playlist, which prompts you to select from your playlists (via consult, naturally) and adds whatever is currently playing.

10. Getting Started emacs installation

spot is on GitHub. It requires Emacs 29.1+ and depends on consult, embark, marginalia, ht, and dash.

(use-package spot
  :ensure (:host github :repo "chiply/spot")
  :config
  (setq spot-client-id "your-client-id"
        spot-client-secret "your-client-secret")
  (spot-mode 1))

You'll need to create a Spotify Developer application at https://developer.spotify.com/dashboard and set the redirect URI to http://localhost:8080/callback. On first use, run M-x spot-authorize to complete the OAuth2 flow. After that, M-x spot and start typing.

touchtype: A Progressive Touch Typing Trainer for Emacs

Charlie Holland — Sun, 01 Mar 2026 19:49:00 GMT

1. About emacs typing education

Figure 1: JPEG produced with DALL-E 4o

There are plenty of typing tutors on the web. keybr.com is one of the best, a progressive trainer that unlocks keys one at a time as your speed and accuracy improve. But it runs in a browser, and if you spend most of your day in Emacs, context-switching to a browser tab for typing practice is enough friction to skip it entirely. touchtype brings that progressive training model into Emacs, along with 12 additional training modes, detailed statistics, and support for alternative keyboard layouts.

2. Why Build a Typing Tutor in Emacs emacs motivation

The obvious question. There are two practical answers.

First, friction kills habits. If practicing typing requires opening a browser, navigating to a URL, and breaking your editing flow, you'll do it less. An M-x touchtype that's always one command away makes it trivially easy to slot in a quick session between tasks.

An M-x touchtype that's always one command away makes it trivially easy to slot in a quick session between tasks.

Second, Emacs users type Emacs. A web-based trainer gives you prose and maybe some generic code snippets. touchtype has a dedicated code mode with 42 real snippets across 8 languages (Python, Rust, Go, JavaScript, TypeScript, Emacs Lisp, Shell, SQL, C), and it respects your Emacs keybindings. Backspace, word-delete (M-DEL, C-backspace), and even Evil mode bindings all work as expected. You're practicing in the same environment you'll be typing in.

3. Progressive Training emacs algorithm

Progressive mode is the flagship training mode, directly inspired by keybr.com. It starts you on just two keys, f and j, the home-row index fingers. You practice pseudo-words made from those two characters until your speed and accuracy cross a confidence threshold, then a third key unlocks. Then a fourth. You work through the entire keyboard one key at a time, in an order that spirals outward from the home row.

3.1. Confidence Scoring

Each key has a confidence score between 0.0 and 1.0, calculated from both speed and accuracy:

target_ms        = 60000 / (target_wpm * 5)
avg_ms           = total_ms / hits
speed_confidence = min(1.0, target_ms / avg_ms)
accuracy         = hits / (hits + misses)
confidence       = accuracy * speed_confidence

Both dimensions must be high for full confidence. A key you type quickly but inaccurately won't unlock the next one, and neither will a key you type accurately but slowly. The unlock threshold is touchtype-unlock-threshold (default: 0.80).

A new key unlocks only when every currently unlocked key meets the threshold. This prevents rushing: you can't advance by nailing the new key while your old keys decay.

3.2. Pseudo-Word Generation

touchtype generates practice words using an English bigram frequency table, a 26x26 matrix of character transition weights. Generation works as a weighted random walk:

Pick a starting character, weighted by total outgoing bigram frequency.
Sample the next character from that character's bigram row, filtered to the currently allowed alphabet.
Terminate with probability that increases exponentially with word length (naturally producing 4-7 character words).
Inject the focused character (the most recently unlocked key) at a random position with 40% probability.

This produces words that feel like English, they follow natural letter patterns, even though they aren't real words. The focused character injection ensures you get enough practice on new keys without making every word feel artificial.

3.3. Focus Character Rotation

After each line, touchtype picks a "focus character" to emphasize:

70% of the time: the most recently unlocked key (deliberate practice on the new key).
30% of the time: a random key below the confidence threshold (remediation for weak keys).

This rotation ensures that newly unlocked keys get concentrated practice while weak older keys aren't forgotten.

3.4. Unlock Orders by Layout

The unlock order depends on your keyboard layout, spiraling outward from the home row by English letter frequency:

Layout	Order
QWERTY	`fjdkslahetniourGcmpbywvxqz`
Dvorak	`uhetonasidrljgcmfpbkwvyxqz`
Colemak	`neiostahrdlufywpgmcbkvxjqz`
Workman	`nehtosaidrljgcmfpbkwvyxqz`
Custom	User-provided via `touchtype-custom-unlock-order`

4. Training Modes emacs modes

touchtype has 13 training modes. Progressive is the headline, but the others cover different practice needs.

4.1. Word-Based Modes

Mode	Description
Progressive	Keys unlock one-at-a-time; pseudo-words from unlocked alphabet
Full Words	4,258 real English words, filtered to unlocked keys
Common Words	Top N most frequent words (default: 100)
Letters	All 26 lowercase letters, pseudo-words from full alphabet
Letters + Numbers	Full alphabet + digits 0-9
Letters + Numbers + Symbols	+ punctuation: `.,;'!?-`
Custom	User-provided text (prompt, region, or buffer)

4.2. N-gram Drills

Mode	Description
Bigram Drill	100 common English bigrams, repeated on a line
Trigram Drill	100 common English trigrams
Tetragram Drill	100 common English tetragrams
N-gram Mixed	Random mix of bi/tri/tetragrams per line

Each drill isolates a specific motor pattern. Bigram drills target two-finger transitions (th, he, in). Tetragram drills build four-character muscle memory for common word fragments (tion, ight, that).

4.3. Special Modes

Mode	Description
Narrative	Random passages from 20 Project Gutenberg classics (cached locally)
Code	42 real code snippets across 8 languages

Narrative mode downloads and caches books from Project Gutenberg, then serves random 400-character passages that land on word boundaries. The book list includes Pride and Prejudice, Alice's Adventures in Wonderland, Sherlock Holmes, Frankenstein, Moby Dick, and 15 others. You can add any valid Gutenberg ID to touchtype-narrative-book-list.

Code mode draws from a curated set of snippets: Python (8), Rust (7), Go (5), JavaScript/TypeScript (6), Emacs Lisp (4), Shell (4), SQL (4), and C (5). It includes the full printable ASCII range (chars 32-126), so you practice brackets, operators, and indentation, not just alphanumerics.

5. The Session Experience emacs interface

A touchtype session runs in a dedicated buffer with a clean, distraction-free layout:

                        (blank padding, ~1/3 screen height)

already typed line      (completed: purple=correct, red=wrong)
already typed line

current target text_    (active: gray=untyped, purple=correct, red=wrong)

upcoming preview text   (preview lines, gray, read-only)
upcoming preview text

Net: 42  Gross: 45  Acc: 96%  Consistency: 85%
Time: 1:23  Words: 15/30  Corrections: 3  Mode: progressive  Keys: fjdksl

Completed lines scroll up above the active line. Preview lines (configurable via touchtype-preview-lines, default: 2) let you read ahead. The status line at the bottom updates live with net/gross WPM, accuracy, consistency, elapsed time, word count, correction count, current mode, and (in progressive mode) the unlocked key set.

5.1. Pace Caret

Enable touchtype-pace-caret to show a ghost cursor that moves at your target WPM. It's a visual indicator of whether you're ahead of or behind your target pace, without the pressure of a countdown timer.

5.2. Session Types

Sessions can be word-count based or timed:

Word-count: Default 30 words. Presets: short (15), medium (30), long (60), marathon (120). Set with M-x touchtype-set-session-length or a C-u N prefix argument.
Timed: Default 60 seconds via M-x touchtype-timed. The timer starts on your first keypress, not when the buffer opens. Idle gaps longer than touchtype-idle-threshold (default: 10 seconds) are excluded from WPM calculations.

6. Demo: Progressive Session emacs demonstration

A progressive session from start to key unlock.

7. Demo: Narrative Mode emacs demonstration

Typing a passage from a Project Gutenberg classic.

8. Demo: Code Mode emacs demonstration

Practicing a Rust code snippet with brackets, operators, and indentation.

9. Error Modes emacs configuration

touchtype offers three error behaviors, controlled by touchtype-error-mode:

Mode	Behavior
Normal	Errors highlighted in red but cursor advances. Backspace to correct or continue.
Stop on Letter	Cursor won't advance until the correct character is typed. Forces immediate correction.
Stop on Word	Cursor advances within a word, but you can't cross the word boundary (space) until all errors in the current word are corrected via backspace.

Normal mode is the default and matches how most typing tests work. Stop-on-letter is the most strict, useful for building accuracy at the expense of speed. Stop-on-word is a middle ground that lets you attempt the whole word before requiring corrections.

10. Session End Summary emacs statistics

When a session ends, touchtype displays a comprehensive summary with expandable sections:

10.1. Speed and Accuracy

Net WPM: (total_chars / 5 - uncorrected_errors) / minutes
Gross WPM: (total_chars / 5) / minutes
Net/Gross CPM: Characters per minute (wpm * 5)
Accuracy: Percentage, ignoring corrected mistakes
Raw Accuracy: True first-attempt accuracy, including corrections in the denominator

10.2. Session Metrics

Time: Elapsed excluding idle periods (mm:ss)
Characters: Total keypresses including errors
Corrections: Backspace count
Uncorrected Errors: Mistakes left unfixed
Consistency: Coefficient of variation of per-line WPM, subtracted from 100%
WPM Sparkline: A Unicode bar chart (▁▂▃▄▅▆▇█) showing per-line WPM with min-max range
Streak: Current daily practice streak
Total Time: Cumulative across all sessions

10.3. Expandable Weak Sections

The summary includes collapsible sections for your weakest letters, bigrams, trigrams, and tetragrams. Press RET on any section header to expand it. Weakest letters show the top 10 by confidence (expandable to all 26). N-gram sections show the top 5, expandable to 50. This tells you exactly what to focus on in your next session.

If you set a new personal best for that mode's net WPM, a banner announces it.

11. Demo: Statistics View emacs demonstration

The full statistics view with trends and per-letter confidence.

12. Statistics and Persistence emacs statistics

M-x touchtype-stats-view shows a comprehensive dashboard:

Overall summary: Total sessions, total words, average WPM, average accuracy, streak, cumulative practice time.
Per-letter confidence chart: All 26 letters sorted weakest-to-strongest with a visual bar chart (20 characters wide, 0.0-1.0 scale).
Weakest bigrams: Top 10 (minimum 5 hits) with confidence bars.
Weakest trigrams and tetragrams: Top 10 each.
WPM trend: Last N sessions with direction indicator (^ improving, v declining, - stable).
Accuracy trend: Same format.
Session history: Tabular format with date, WPM, accuracy, mode, word count.
Personal bests: Best WPM and accuracy per mode.

All statistics persist to ~/.emacs.d/touchtype-stats.el as s-expressions. The file is auto-created on first use.

12.1. Export

M-x touchtype-export writes your data to JSON or CSV. The JSON export includes sessions, per-letter stats with confidence scores, streak, and total practice time. The CSV export is a simple table of sessions (date, WPM, accuracy, mode, words).

13. Customization Reference emacs configuration

13.1. Training Parameters

Variable	Default	Description
`touchtype-target-wpm`	40	Target WPM for confidence scoring
`touchtype-unlock-threshold`	0.80	Confidence threshold for key unlock
`touchtype-session-length`	30	Words per session
`touchtype-session-duration`	60	Seconds for timed sessions
`touchtype-error-mode`	`'normal`	Error handling behavior
`touchtype-idle-threshold`	10	Seconds before gap excluded from WPM
`touchtype-word-length-min`	4	Minimum pseudo-word length
`touchtype-word-length-max`	8	Maximum pseudo-word length
`touchtype-common-words-count`	100	Top N words for common-words mode

13.2. Display

Variable	Default	Description
`touchtype-preview-lines`	2	Preview lines shown below active
`touchtype-pace-caret`	`nil`	Show ghost cursor at target WPM

13.3. Layout and Persistence

Variable	Default	Description
`touchtype-keyboard-layout`	`'qwerty`	Layout (qwerty/dvorak/colemak/workman/custom)
`touchtype-custom-unlock-order`	`nil`	Custom unlock order string
`touchtype-stats-file`	`~/.emacs.d/touchtype-stats.el`	Statistics file path
`touchtype-stats-history-length`	20	Sessions retained for trends

13.4. Narrative Mode

Variable	Default	Description
`touchtype-narrative-cache-dir`	`~/.emacs.d/touchtype/`	Cache directory for books
`touchtype-narrative-passage-chars`	400	Characters per passage
`touchtype-narrative-book-list`	20 Gutenberg IDs	Books to sample from

14. Getting Started emacs installation

touchtype is on GitHub. It requires Emacs 29.1+ with no external dependencies.

(use-package touchtype
  :ensure (:host github :repo "chiply/touchtype"))

Start with M-x touchtype-progressive for the flagship progressive mode, or M-x touchtype to pick a mode interactively. Prefix any mode command with C-u N to set the session length (e.g., C-u 60 M-x touchtype-progressive for a 60-word session). Check your progress with M-x touchtype-stats-view and export with M-x touchtype-export.

Five Years of COVID-19 Data: Variants, Hospitalizations, Vaccines, and What Wastewater Tells Us Now

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About publicHealth dataviz covid

Figure 1: JPEG produced with DALL-E 4o

Few events in modern history have generated as much real-time public data as COVID-19. This post draws on four federal datasets – variant proportions, hospital admissions, vaccination progress, and wastewater surveillance – to tell the story of five years of a virus reshaping American life, from emergence through endemicity.

2. TLDR tldr

The COVID-19 pandemic has been one of the most intensively documented public health events in history. CDC's public data APIs capture the full arc: five waves of distinct variant lineages, a hospitalization record that dwarfed any recent respiratory disease season, the fastest vaccine rollout in American history (with significant state-level variation), and a new permanent surveillance infrastructure built on wastewater. As of early 2026, wastewater monitoring shows SARS-CoV-2 activity is present but well below pandemic peaks. The virus didn't disappear — it became endemic, and public health built tools to watch it.

3. Introduction: COVID-19 as a Data Story analysis

Few events in modern history have generated as much real-time public data as COVID-19. At the pandemic's height, public health agencies at every level — federal, state, and local — were publishing case counts, test positivity rates, hospitalization figures, vaccine uptake, variant sequences, and wastewater viral loads, often daily. Some of that infrastructure has since been wound down. But what remains in the CDC's public APIs tells a coherent story about five years of a virus reshaping American life.

This post draws on four distinct federal datasets that remain active and publicly accessible:

Variant Proportions (CDC): Genomic surveillance tracking which SARS-CoV-2 lineage dominates circulating sequences each week, starting in January 2021 and updated continuously through today.
Hospital Admissions (CDC): Weekly adult COVID-19 admissions reported by hospitals to HHS/CDC, from August 2020 through October 2024 when mandatory reporting ended.
Vaccination Progress (CDC): Dose administration and completion rates by state and nationally, from the first shots in December 2020 through the formal end of the federal vaccination data program in May 2023.
Wastewater Surveillance (CDC NWSS): SARS-CoV-2 viral signal detected at wastewater treatment plants nationwide, from mid-2020 to the present — the only dataset that continues tracking COVID-19 activity in real time.

Together these four data streams let us trace the pandemic from emergence through endemicity.

4. The Variant Succession dataviz variants

One of the defining features of SARS-CoV-2 has been its capacity for rapid evolutionary change. CDC's genomic surveillance program tracks the proportion of sequenced specimens attributed to each circulating lineage each week. The result is a clear visual record of variant succession — each new dominant strain displacing the last, often within weeks.

Several structural patterns emerge from the variant timeline:

Alpha and Delta were sequential. Alpha (B.1.1.7, first identified in the UK) became dominant in the US through spring 2021 before Delta (B.1.617.2, first identified in India) displaced it almost entirely by July 2021. Delta was more transmissible than any prior variant; it drove the summer and fall 2021 wave and remained dominant until a single event changed everything.
Omicron was a discontinuity. The emergence of B.1.1.529 (Omicron) in late November 2021 wasn't just a variant transition — it was a reset. Omicron displaced Delta in a matter of weeks, achieving dominance faster than any prior variant. But unlike Delta, which produced severe disease in unvaccinated populations at rates comparable to the original strain, Omicron showed substantially reduced severity per infection (partly due to its different cell tropism, partly due to widespread prior immunity). The trade-off: it was dramatically more contagious, and it produced the largest single hospitalization wave of the pandemic.
Omicron fragmented into subvariants. After the initial BA.1/BA.1.1 wave, Omicron didn't recede — it diversified. BA.2, BA.2.12.1, BA.4, and BA.5 emerged in rapid succession through 2022, each outcompeting its predecessor. By late 2022, BQ.1 and BQ.1.1 took over; by early 2023, XBB.1.5 dominated; through 2023-2024, EG.5, HV.1, JN.1, KP.2, KP.3, and XEC followed. The post-Omicron era has been characterized by continuous churn among subvariants, none achieving quite the dramatic emergence of the original Omicron wave.
The current era: XFG. As of February 2026, the XFG lineage (a recombinant descendent of Omicron) accounts for the largest share of sequenced specimens, alongside XFG.2.5.1 and XFG.1.1. The pattern has become stable: a new Omicron-descendent subvariant achieves dominance every few months, drives a modest uptick in activity, and gives way to the next. This is how seasonal respiratory viruses behave.

The variant chart illustrates something important about pathogen evolution under population immunity: selective pressure favors immune evasion over severity. Each successive Omicron subvariant became better at evading prior immunity but didn't revert to Delta-level severity. The virus found a stable evolutionary niche — high transmissibility, periodic immune escape, manageable (for most) disease burden.

5. The Hospitalization Record dataviz hospitals

Variant proportions tell us about the virus. Hospital admissions tell us about the impact on people.

The hospitalization data runs from August 2020 through October 2024, when the federal government ended mandatory hospital reporting requirements. Several features of this record are striking:

The Omicron BA.1 wave was the largest hospitalization event of the pandemic. In mid-January 2022, weekly adult COVID-19 admissions in the US peaked at levels roughly double the prior record (the winter 2020-21 wave). This is counterintuitive given that Omicron caused less severe disease per infection — but the sheer number of infections was so large that even a lower hospitalization rate produced record admissions. The US hospital system was significantly strained, with staff quarantines and patient surges occurring simultaneously.
The winter 2020-21 wave was the first severe wave. Before vaccines, before any widespread immunity, the original strain drove a sustained winter surge that overwhelmed hospitals across the Sun Belt, Midwest, and Northeast in sequence. This wave established the baseline for what COVID-19 could do to a fully susceptible population.
Delta drove a sharp, sustained summer surge in 2021. Unlike prior waves, which tracked seasonality (rising in winter, falling in summer), Delta spread aggressively through an unvaccinated population during the summer of 2021. Southern states with lower vaccination rates were hit first and hardest. The Delta wave killed approximately 130,000 Americans between June and November 2021 — a toll concentrated heavily among the unvaccinated.
Post-Omicron waves have been progressively smaller. Each subsequent wave (BA.4/5 in summer 2022, XBB.1.5 in winter 2022-23, JN.1 in winter 2023-24) has produced lower peak hospitalizations than its predecessor. This reflects accumulated immunity from prior infection and vaccination, improved treatments (antivirals, updated vaccines), and possible reduced inherent severity of circulating strains. The JN.1 wave in late 2023 / early 2024 — the last full wave captured in this dataset — produced roughly one-tenth the hospitalizations of the Omicron BA.1 peak.
Mandatory reporting ended October 2024. The federal requirement for hospitals to report COVID-19 admissions to HHS expired, creating a gap in national surveillance. Wastewater data (covered below) now serves as the primary ongoing signal for COVID-19 activity.

6. The Vaccination Campaign dataviz vaccines

The COVID-19 vaccine rollout was, by any historical measure, extraordinary. Within one year of a novel pathogen being identified, multiple safe and effective vaccines were authorized, manufactured at scale, and administered to hundreds of millions of Americans.

The national vaccination timeline shows three distinct phases:

The initial sprint (December 2020 – June 2021). Vaccines were authorized for emergency use and administered to priority groups (healthcare workers, long-term care residents, the elderly) before broadening to all adults in April 2021. The pace was remarkable — at peak velocity in April 2021, the US was administering over 3 million doses per day. By June 2021, roughly 45% of the population had received at least one dose.
The plateau (July 2021 – on). First-dose uptake plateaued sharply in mid-2021. The remaining unvaccinated population proved more resistant to vaccination — a combination of hesitancy, access barriers, and political polarization. Despite significant public health campaigns, employer mandates, and ongoing Delta-related mortality that disproportionately affected the unvaccinated, the national fully-vaccinated rate plateaued near 70% for primary series completion.
Boosters and bivalent doses. The booster program launched in fall 2021, primarily targeting those 65+ and immunocompromised. An updated bivalent booster targeting Omicron BA.4/5 was authorized in September 2022, but uptake was substantially lower than the primary series — reflecting both waning urgency (Omicron was less severe) and vaccination fatigue. The CDC stopped tracking vaccine data after May 2023 as the federal vaccination program wound down.

6.1. State-Level Variation dataviz maps

The national averages obscure enormous variation between states.

The spread in peak primary-series vaccination rates across states is striking — a gap of more than 30 percentage points separated the most and least vaccinated states. Several patterns are consistent with other health and political geography data:

New England led. Vermont, Massachusetts, Connecticut, and Maine achieved the highest vaccination rates, with more than 80% of their populations completing a primary series. These states combined high trust in public institutions, dense urban healthcare access, and early employer and institutional mandates.
Mountain West and Deep South lagged. Wyoming, Idaho, Mississippi, and Alabama had the lowest vaccination rates, often below 55%. These states also experienced higher per-capita COVID-19 mortality, reflecting the direct consequence of the protection gap.
The metro-rural divide within states was sharper than the state-level data suggests. A state like Georgia appears near the middle of the distribution, but its rural counties show vaccination rates in the 30-40% range while Atlanta metro approaches 80%. County-level data reveals geography that state aggregates obscure.
The gap had real mortality consequences. Studies published throughout 2021-2023 consistently showed that unvaccinated adults were 5-10x more likely to be hospitalized with COVID-19 and 10-15x more likely to die during Delta. The state variation in vaccination rates translated directly into preventable deaths.

The vaccination data program formally ended in May 2023. The federal COVID-19 vaccine tracking infrastructure — which produced daily granular data at county level throughout the pandemic — no longer exists in its original form.

7. Wastewater: The Ongoing Signal dataviz wastewater

With case counts discontinued in 2023 and hospital reporting ended in 2024, the primary ongoing source of real-time COVID-19 tracking is wastewater surveillance.

SARS-CoV-2 is shed in human feces regardless of whether someone has symptoms or has sought testing. Wastewater treatment plants — which aggregate sewage from thousands to millions of people — serve as passive surveillance systems. The CDC's National Wastewater Surveillance System (NWSS) collects viral load measurements from hundreds of sites nationwide and converts them to percentile scores: 0 means the lowest viral signal ever recorded at that site, 100 means the highest.

The wastewater trend shows several features not visible in hospitalization data (which ended in late 2024):

The JN.1 wave (winter 2023-24) was clearly visible. Wastewater percentiles spiked nationally in December 2023 and January 2024, consistent with the last major wave captured in the hospitalization data. The peak was substantial but well below the Omicron BA.1 winter (when some sites recorded their all-time highest signals).
A summer 2024 wave appeared. Consistent with the KP.3/XEC variant transitions, wastewater showed an uptick in summer 2024 — a pattern that was barely visible in the (by then curtailed) hospital data but clearly detectable in sewage.
Activity has remained at low but non-zero levels. As of early 2026, the national median wastewater percentile sits well below the 50th percentile — meaning most sites are detecting viral levels below their historical midpoint. COVID-19 is present but not producing the surges of the acute pandemic phase.
Wastewater leads clinical data by 4-7 days. One of wastewater surveillance's key advantages is its lead time over clinical testing or hospitalization data. When viral shedding rises in sewage, emergency department visits and hospitalizations typically follow within a week. This makes it a useful early-warning system for resource planning.

7.1. COVID Activity by State dataviz maps

The state-level map shows the most recent four weeks of wastewater activity, expressed as each state's median site percentile.

Geographic variation in wastewater activity reflects both true differences in viral transmission and differences in site coverage. States with very few reporting wastewater treatment plants (often rural states like Wyoming, Montana, or North Dakota) have less reliable state-level estimates, since a single large urban WWTP can dominate the state median. Densely monitored states like California, Illinois, and New York have hundreds of reporting sites, making their state-level estimates much more stable.

The Sunbelt states — Florida, Texas, Arizona — have historically shown elevated summer wastewater signals, likely reflecting indoor congregating driven by heat. Northeast and Midwest states often show higher winter signals. The current map captures a snapshot; the national trend chart above shows how this changes over time.

8. What COVID Data Looks Like Now analysis endemic

Five years after the first US COVID-19 deaths, the data tells a story of transition from pandemic to endemic:

The surveillance landscape has changed. The dense, multi-layer data infrastructure of 2021-2022 — daily case counts by county, hospital occupancy by state, seven-day test positivity, daily vaccination records — has largely been dismantled. What remains is leaner but more sustainable: continuous wastewater monitoring, periodic genomic sequencing, influenza-season syndromic surveillance integrated with COVID-19.

Immunity has fundamentally reshaped the disease burden. The CDC estimated that by early 2022, roughly 75% of Americans had been infected at least once. Combined with vaccination, population-level immunity against severe disease is high. This doesn't prevent infection — Omicron subvariants evade neutralizing antibodies effectively — but it dramatically reduces hospitalization and death rates per infection compared to the pre-immune era.

The seasonal pattern has asserted itself. COVID-19 now behaves more like influenza or RSV than like a novel pandemic pathogen: a predictable winter surge (driven partly by seasonal behavior, partly by waning immunity), a smaller summer bump, and relatively quiet spring and fall periods. This regularity allows healthcare systems to plan rather than react.

The population most at risk has narrowed. During Delta, an unvaccinated 40-year-old with no comorbidities faced meaningful risk of severe disease. Today, for the same person with prior infection and vaccination history, COVID-19 carries risk more comparable to a bad flu year. The remaining high-risk populations — adults over 75, immunocompromised individuals, those with multiple chronic conditions — still benefit substantially from updated vaccines and antiviral treatment, but the population-wide burden has shifted.

Long COVID remains an open chapter. The datasets analyzed here do not capture long COVID prevalence, which CDC surveys have estimated at anywhere from 6% to 11% of ever-infected adults experiencing persistent symptoms. This represents tens of millions of Americans and remains one of the least well-quantified ongoing consequences of the pandemic.

9. Data and Methods data methodology

All data from publicly accessible CDC APIs, no authentication required.

Variant proportions: CDC Nowcast variant proportions (jr58-6ysp). Filtered to usa_or_hhsregion = "USA" for national estimates. Variants with peak share below 5% grouped as "Other." Data current through February 2026. Proportions are model-smoothed estimates; raw sequencing counts shown in confidence intervals (not displayed here).
Hospitalizations: CDC Hospital Respiratory Data (aemt-mg7g). Filtered to jurisdiction = "USA" for national aggregate. Field: total_admissions_adult_covid_confirmed (confirmed adult COVID-19 admissions in the reporting week). Data runs August 2020 – October 2024 when mandatory reporting ended.
Vaccination: CDC COVID-19 Vaccinations in the United States, Jurisdiction (unsk-b7fc). National data filtered to location = "US"; state data filtered to two-letter state codes. Fields: administered_dose1_pop_pct, series_complete_pop_pct, additional_doses_vax_pct, bivalent_booster_pop_pct. Data runs December 2020 – May 2023.
Wastewater surveillance: CDC NWSS Public SARS-CoV-2 Wastewater Metric Data (2ew6-ywp6). The percentile field represents each site's current viral level ranked against its own historical distribution (0=lowest ever, 100=highest ever). State-level estimates computed as median percentile across reporting sites. National trend computed as median percentile across all sites reporting in each biweekly window, restricted to windows with at least 75 reporting sites. Wastewater data current through September 2025.
Charts: Generated using Plotly and Python from the raw API data. All source code available in the site's GitHub repository.

Drug Pricing Transparency: What Medicare Pays Per Day

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare medicare drugs pricing dataviz

Figure 1: JPEG produced with DALL-E 4o

Americans pay more for prescription drugs than any other country. This post uses CMS Medicare Part D spending data – covering ~3,600 drugs from 2019 to 2023 – to visualize where $276 billion in annual drug spending goes, which drugs cost the most per day, and how prices have changed over five years.

2. TLDR tldr

Medicare Part D spent $276 billion on prescription drugs in 2023. The top 10 drugs alone — led by Eliquis at $18.3 billion — accounted for 26% of all spending. The most expensive drug by daily cost runs over $850/day. GLP-1 drugs like Ozempic and Trulicity now represent a $34+ billion category and are growing fast. Price growth varies wildly: some drugs have compounded at 10%+ annually while others have dropped.

3. Introduction cms partd drugs pricing

Americans pay more for prescription drugs than any other country. Part of the reason is opacity: drug prices are negotiated in private between manufacturers, pharmacy benefit managers, and insurers. But one major payer — Medicare Part D — publishes its spending data annually. The result is the most comprehensive public window into what the US actually pays for drugs.

The CMS Medicare Part D Spending by Drug dataset covers every drug with sufficient Medicare claims (roughly 3,600 brand and generic drugs), with annual spending, claim counts, beneficiary counts, and average costs per fill. It covers 2019–2023, providing a five-year view that captures the pandemic disruption, the GLP-1 explosion, and ongoing price escalation in specialty drugs.

Total 2023 spending: $276 billion across all Part D drugs. For context, that's more than the entire federal discretionary budget for education, transportation, and energy combined.

4. The Landscape: Where the Money Goes dataviz treemap

Each block represents one drug, sized by total 2023 Medicare Part D spending. Color shows the 5-year compound annual growth rate in price per dosage unit — red means fast price growth, blue means prices have declined.

A few things stand out in the landscape:

Eliquis dominates. The blood thinner apixaban (Eliquis) is Medicare's single largest drug expense at $18.3 billion — nearly twice the second-place drug. Its patent has been challenged but held; a wave of generic competition is expected in coming years.
Blood thinners and diabetes drugs are the biggest categories. Eliquis, Xarelto, Jardiance, Farxiga, and the GLP-1 drugs collectively account for a disproportionate share of total Part D spending.
Many large drugs have steady price growth. The orange-to-red tint on drugs like Humira, Eliquis, and Trulicity reflects consistent price increases compounding at 5–10% annually over five years.
Some drugs have seen prices fall. Blue-tinted drugs include some generics and drugs that faced biosimilar or generic competition during this period.

5. The Most Expensive Drugs Per Day dataviz cost

"Cost per day" cuts through confusing per-unit pricing to give an intuitive sense of what a drug actually costs to take. This shows the 40 highest daily-cost drugs in Medicare Part D, restricted to drugs with at least 50,000 claims.

The most expensive drug by daily cost is Vyndamax (tafamidis), a treatment for transthyretin amyloid cardiomyopathy — a rare heart condition — at roughly $860/day. Stelara (ustekinumab), a biologic for psoriasis and Crohn's disease, runs about $850/day. Both are biologics: large-molecule drugs that are expensive to manufacture and face limited competition.

For context:

The most expensive drugs on this list are almost exclusively biologics or specialty oncology drugs
Many GLP-1 drugs (Ozempic, Trulicity, Mounjaro) appear in the mid-tier — expensive but not at the extreme top end
Blood thinners (Eliquis, Xarelto) dominate total spending due to massive volume despite moderate daily cost

6. Spending Trajectories: Five Years of Growth dataviz trends

How has spending evolved from 2019 to 2023 for the top drugs?

The most dramatic story is Ozempic (semaglutide). Barely a rounding error in 2019 Part D spending, it reached $9.2 billion by 2023 — entirely driven by volume, as GLP-1 prescriptions exploded first for diabetes management and then for weight loss. Jardiance and Farxiga (SGLT-2 inhibitors) show similar trajectories.

Eliquis has grown steadily throughout, driven by both price increases and aging-population volume growth in atrial fibrillation. Revlimid (lenalidomide, for multiple myeloma) peaked and then declined as generic competition entered after 2022.

Humira (adalimumab) shows an unusual pattern: total spending held roughly flat even as biosimilar competition should have reduced it, because the branded version maintained pricing while biosimilar uptake was slower than expected.

7. Price vs. Volume: The Two Levers of Drug Spending dataviz scatter

Total drug spending is driven by two factors: price per unit and volume of prescriptions. This scatter shows how both changed from 2022 to 2023. Drugs in the upper-right quadrant are becoming more expensive to treat and being used more — a double driver of spending growth.

The upper-right quadrant — price up and volume up — is where policymakers focus. GLP-1 drugs (Ozempic, Mounjaro) appear here with explosive volume growth, though their price per unit has been more controlled. Blood thinners sit near the center: modest price increases, stable or slowly growing volume.

Drugs in the upper-left (volume up, price down) often reflect generics entering the market or manufacturer rebates increasing. The lower-right (price up, volume down) may indicate drugs losing market share as alternatives emerge, but still raising prices on their remaining users.

8. The Policy Context analysis policy

The Inflation Reduction Act (IRA) of 2022 gave Medicare the authority to negotiate drug prices directly for the first time in its history. The first round of negotiations covered 10 drugs, including Eliquis and Xarelto, with negotiated prices taking effect in 2026. The second round expanded the list.

The data here shows why this matters: these drugs represent tens of billions in annual Medicare spending, and their prices have compounded upward for years in a market where Medicare previously had no negotiating power. The projected savings from negotiation are modest relative to total spending — but the precedent is significant.

For GLP-1 drugs, the policy debate is different. These drugs have demonstrated clinical benefit not just for diabetes but for cardiovascular outcomes and obesity-related conditions. The question isn't whether prices are too high in isolation, but how Medicare balances access (these drugs could benefit tens of millions of beneficiaries) against budget impact at scale.

9. Data and Methods data cms methodology

All data from the CMS Medicare Part D Spending by Drug dataset (2019–2023).

Coverage: Drugs with sufficient Medicare Part D claims to meet CMS's minimum reporting threshold (10+ prescribers, 11+ beneficiaries per year). Approximately 3,600 drugs included.
"Overall" rows: The dataset includes one row per drug per manufacturer, plus an "Overall" aggregate row. All analysis here uses the "Overall" rows.
Cost per day: Calculated as average spending per claim divided by 30 (assumes a 30-day supply per claim, a standard Part D fill). This is an approximation; some drugs have different supply durations.
Price change: Chg_Avg_Spnd_Per_Dsg_Unt_22_23 is the year-over-year change in weighted average spending per dosage unit (2022→2023). The 5-year CAGR covers 2019→2023.
Volume change: Change in total claims count from 2022 to 2023.
Minimum thresholds: The cost-per-day chart requires ≥50,000 annual claims; the scatter requires ≥100,000 to reduce noise from low-volume drugs.

The GLP-1 Revolution: How a Diabetes Drug Became the Fastest-Growing Drug Category in Medicare History

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare medicare drugs dataviz

Figure 1: JPEG produced with DALL-E 4o

Medicare Part D spending on GLP-1 drugs grew from $2.3 billion in 2019 to roughly $27 billion by 2024. This post traces that explosion through CMS spending data, beneficiary counts, state-level adoption maps, and FDA adverse event reports – showing how a diabetes drug became the fastest-growing drug category in Medicare history.

2. TLDR tldr

In 2019, Medicare Part D spent $2.3 billion on GLP-1 diabetes drugs — primarily Trulicity. By 2024, that number had grown to roughly $27 billion, with nearly 4 million Medicare beneficiaries on one of these drugs. Ozempic alone costs Medicare more annually than all opioids combined. The explosion is driven almost entirely by volume — the cost per dose has stayed roughly flat — and it is still accelerating. Mounjaro (tirzepatide) is growing faster than Ozempic ever did, and Wegovy/Zepbound (the obesity-indication formulations) have barely begun to penetrate Medicare coverage. The FDA adverse event database has absorbed more tirzepatide reports in 3 years than semaglutide accumulated in 7, suggesting the pace of adoption is genuinely without precedent in recent pharmaceutical history.

3. What Are GLP-1 Drugs? background mechanism

GLP-1 stands for glucagon-like peptide-1, an incretin hormone produced in the gut after meals. Its job is to signal the pancreas to release insulin, slow gastric emptying so nutrients absorb more gradually, and tell the brain that you've eaten enough. In healthy individuals, GLP-1 surges after meals and dissipates quickly — its half-life is roughly two minutes. GLP-1 receptor agonists (GLP-1 RAs) are synthetic molecules designed to bind the same receptors but survive much longer in circulation, producing a sustained hormonal signal that controls blood sugar and suppresses appetite.

The first GLP-1 RA approved in the US was exenatide (Byetta) in 2005 — delivered twice daily by injection and requiring significant patient effort. The category remained a niche diabetes treatment for over a decade: effective but complicated, and competing against established oral options (metformin, sulfonylureas) and insulin. The breakthrough came from a simpler formulation.

Ozempic's arc is the story of the category. Semaglutide (Novo Nordisk) was approved by the FDA in December 2017 as a once-weekly subcutaneous injection for type 2 diabetes. Clinical trials showed not only strong blood sugar control but unexpected weight loss — 10-15% body weight reduction in some patients — and, crucially, reduced cardiovascular events in a high-risk population. Those cardiovascular outcomes data (from the SUSTAIN-6 trial) made Ozempic the first GLP-1 with a proven heart disease benefit, dramatically expanding the patient population that could justify its use.

The next pivotal moment was Ozempic's cultural emergence. By 2022, social media was saturated with accounts of dramatic weight loss from the drug — often from people taking it off-label without a diabetes diagnosis. The #Ozempic hashtag generated billions of views. Celebrities were rumored to be using it. Supply chains strained. The drug had escaped its original clinical context and become a cultural phenomenon.

Then tirzepatide arrived. Mounjaro (tirzepatide, Eli Lilly) was approved in May 2022 for type 2 diabetes. It is a dual agonist — activating both the GLP-1 receptor and the GIP (glucose-dependent insulinotropic polypeptide) receptor. Clinical trial data suggested 20-22% mean body weight reduction, substantially above semaglutide's ceiling. Its SURPASS trial program showed better A1c and weight reduction than Ozempic in head-to-head comparisons. The drug entered Medicare Part D with 54,000 beneficiaries in 2022. By 2024, it had 895,000 — a 16× increase in two years.

Approval timelines for the major drugs in the class:

Drug	Brand	Indication	FDA Approval
Exenatide	Byetta	T2D	2005
Liraglutide	Victoza	T2D	2010
Liraglutide	Saxenda	Obesity	2014
Dulaglutide	Trulicity	T2D	2014
Semaglutide	Ozempic	T2D	2017
Semaglutide	Rybelsus	T2D (oral)	2019
Semaglutide	Wegovy	Obesity	2021
Tirzepatide	Mounjaro	T2D	2022
Tirzepatide	Zepbound	Obesity	2023

The T2D and Obesity brands are often the same molecule at different doses and with different regulatory pathways. This distinction matters enormously for insurance coverage.

4. The Spending Explosion dataviz spending cms

This chart shows gross Medicare Part D spending on GLP-1 drugs from 2019 through 2024.

The shape is unmistakable. In 2019, the entire GLP-1 category cost Medicare $2.3 billion — dominated by Trulicity (dulaglutide), which was then the market leader. By 2023, spending had reached $22 billion, with Ozempic accounting for $9.2 billion alone. The 2024 full-year figures push the total to approximately $27 billion, with Ozempic ($13.0B), Mounjaro ($6.3B), and Trulicity ($5.5B) as the top three.

To put $27 billion in context:

It exceeds the total Medicare Part D spending on all cancer drugs in 2019
It is more than the entire federal budget for the Environmental Protection Agency (~$9B) or the National Science Foundation (~$9B)
Medicare spent more on Ozempic alone in 2024 than on Humira (adalimumab, long the most expensive drug in the US) at its peak

The growth is not a plateau. The 2025 Q1-Q2 partial year shows Ozempic at $7.6B and Mounjaro at $5.7B in just the first half — both tracking above their 2024 full-year rates. The trajectory has not bent.

What's driving the spending? The answer is almost entirely volume, not price. Average spend per beneficiary on Ozempic has remained roughly $6,000-$7,000 per year (gross, before rebates). The extraordinary growth comes from the number of people on the drug — which increased from roughly 70,000 Medicare beneficiaries in 2019 to nearly 2 million in 2024, a 28× increase.

5. The Patient Surge dataviz beneficiaries

The beneficiary chart shows just how fast adoption has been. Trulicity had the most Medicare users in 2019-2021 — its patient base was built gradually over five years of diabetes treatment. Ozempic overtook it in beneficiary count by 2022 despite launching years later, driven by higher demand and more aggressive prescribing. Mounjaro's trajectory is steeper than either: launched mid-2022, it reached 895,000 beneficiaries in 2024 with its first full calendar year barely completed.

Wegovy's beneficiary count remains small in Medicare — only 53,000 in 2024 — for a policy reason. Medicare Part D is prohibited by statute from covering drugs "used for weight loss." Because Wegovy is FDA-approved for chronic weight management (not diabetes), Medicare couldn't cover it until the Inflation Reduction Act and subsequent regulatory action clarified that obesity itself is a disease condition. The 2024 PREVENT trial data showing Ozempic reduced major cardiovascular events by 20% in people with obesity (not just diabetes) created a new pathway: Medicare now covers semaglutide for patients with obesity and established cardiovascular disease. But coverage for obesity alone without a comorbidity remains unresolved. Zepbound faces the same situation — only 245 Medicare beneficiaries in all of 2024.

This gap between diabetes-indication and obesity-indication coverage represents the policy frontier. Tens of millions of Americans with obesity could benefit from these drugs. If Medicare were to cover GLP-1s broadly for obesity, estimates of the budget impact range from $35 billion to $145 billion per year.

7. The Price Question: Cost Per Beneficiary dataviz pricing

One common narrative about GLP-1 growth is that pharma companies have been raising prices aggressively. The per-beneficiary data complicates that picture.

Average spending per beneficiary has remained remarkably stable. Ozempic has held roughly $6,000-$7,000 per beneficiary per year throughout 2020-2024. Mounjaro launched higher (~$8,500 in 2022, reflecting higher doses and higher list price) but has moderated as patient volumes grew. Rybelsus runs substantially cheaper (~$4,500) as an oral daily pill.

This stability in per-patient cost means that list price increases have been modest relative to the volume growth. The Inflation Reduction Act (IRA) capped annual Medicare Part D out-of-pocket costs and restructured plan design to require drug manufacturers to provide rebates; this has kept effective per-beneficiary costs roughly flat even as gross spending has exploded with volume.

The gross figures ($12,000/year for Ozempic is the US list price for cash-paying patients without insurance) are not what Medicare pays. Medicare negotiates through Part D plans and receives manufacturer rebates that can reduce net cost by 40-60%. The actual Medicare expenditure per Ozempic beneficiary is likely closer to $3,000-$4,000 per year — still substantial, but very different from the list price.

The IRA's drug price negotiation provisions specifically target drugs with high Medicare spending, no generic competition, and long patent life. Ozempic and Mounjaro are prime candidates for future negotiation rounds. The first 10 negotiated drugs (from 2023) saved an estimated $6 billion. The potential savings from negotiating GLP-1 prices would dwarf that.

8. Where Are GLP-1s Prescribed? dataviz geography

The geographic distribution of GLP-1 beneficiaries is heavily driven by state population — California, Texas, Florida, and New York dominate in raw beneficiary count. But the interesting variation is in the rate of adoption relative to Medicare enrollment.

Several patterns emerge:

Southern states have high absolute volumes, consistent with higher rates of type 2 diabetes (the South has the nation's highest diabetes prevalence, particularly in the "Diabetes Belt" stretching from the Carolinas through the Gulf states).
Western states show moderate-to-high GLP-1 use relative to their Medicare populations, partly reflecting the density of endocrinology practices and more aggressive prescribing culture in certain urban centers.
Rural states often show high rates of diabetes but lower GLP-1 adoption — a gap driven by both provider access (fewer endocrinologists, more reliance on primary care for diabetes management) and coverage barriers (high deductibles, prior authorization burdens that deter prescribing).

The gap between diabetes prevalence and GLP-1 prescribing is one of the less-discussed aspects of the story. Roughly 30 million Americans have type 2 diabetes. About 2 million Medicare beneficiaries are on semaglutide. Even assuming all are diabetic and all are elderly, only a fraction of the eligible population is receiving the drug. The headroom for further volume growth — even before the obesity indication — is substantial.

9. The Adverse Event Profile dataviz safety faers

No drug category grows this fast without accumulating an adverse event record. The FDA's Adverse Event Reporting System (FAERS) captures voluntary reports from patients, physicians, and manufacturers — not clinical trial data, but real-world post-market surveillance.

9.1. Reports Are Exploding Alongside Prescriptions subsection

The FAERS report count mirrors the prescription growth but with a striking asymmetry: tirzepatide has accumulated far more adverse event reports in 3 years than semaglutide accumulated in 7. In 2025 alone (through mid-February), tirzepatide has generated ~62,000 reports versus ~26,000 for semaglutide. Part of this reflects the faster rate of adoption — Mounjaro reached a million prescriptions per month faster than Ozempic did. But part reflects the drug's novelty: when patients and physicians have less experience with a drug, they are more likely to submit reports for events they might not flag for an established drug.

The FAERS database is a reporting system, not an incidence register — a high report count doesn't mean tirzepatide is less safe than semaglutide. It means patients are using it in large numbers, often in new clinical contexts (weight loss without diabetes), and that the signal-detection machinery is working.

9.2. How the Reaction Profiles Compare subsection

The butterfly chart shows the reaction profile for each drug, normalized per 1,000 FAERS reports. The shape is remarkably similar — both drugs share the same core mechanism (GLP-1 receptor activation slows gastric emptying), so the dominant adverse event category for both is gastrointestinal: nausea, vomiting, diarrhea, constipation, and upper abdominal pain.

A few differences stand out:

Tirzepatide reports a higher rate of injection site reactions (pain, hemorrhage, erythema, bruising). This likely reflects its newer formulation and patient population — fewer patients have experience with injectable medications, and more are injecting for weight loss rather than a decades-long diabetes management routine.
Semaglutide shows a higher rate of "impaired gastric emptying" as a directly named reaction — tirzepatide patients may be experiencing the same effect but describing it differently (as nausea or constipation rather than the clinical term).
Metabolic signals (weight decreased, blood glucose changes) appear on both. Weight loss is a feature of these drugs, but it appears as an "adverse event" in FAERS when patients report unexpected or excessive weight loss.
Psychiatric signals are present but small. Depression, anxiety, and suicidal ideation appear in the FAERS data for both drugs. The FDA added warnings about these in 2023 after an EMA signal review; subsequent analyses have generally found no causal link, but the signals remain under surveillance.
Gallbladder disease (cholelithiasis, cholecystitis) is more prominent in semaglutide data. Rapid weight loss — any cause, not just GLP-1s — increases gallstone risk. Clinical trials showed gallbladder events occurred in 2-3% of semaglutide-treated patients versus ~1% in placebo. This is a known, labeled risk.

The drug discontinuation rate is the most practically relevant safety signal. Both drugs have high dropout rates in real-world data — roughly 50% of patients discontinue within a year. The primary driver is GI side effects in the first 4-8 weeks of dose escalation. Patients who tolerate the initial escalation period tend to stay on the drug long-term, and the GI side effects diminish substantially once a maintenance dose is reached.

10. The Drug Adoption Heatmap dataviz comparison

The heatmap compresses the adoption story into a single view. Each cell shows how many Medicare beneficiaries were on each drug in each year, and what that cost. The pale cells are near-zero adoption (Mounjaro before 2022, Wegovy throughout). The dark cells show the concentration of use — Ozempic in 2024 stands alone as a near-$13B program with nearly 2 million beneficiaries.

Trulicity tells a different story: a large, stable patient base that grew slowly and is now beginning to shrink as Mounjaro and Ozempic have displaced it for new prescriptions. The transition from an older drug (Trulicity) to a newer, more effective one (Ozempic/Mounjaro) is how pharmaceutical markets normally work — but the speed and scale are unusual.

11. The Policy Battleground analysis policy

The policy questions around GLP-1s are not abstract budget debates — they determine who can access drugs that could potentially reduce heart attacks, strokes, kidney failure, and premature death at a population scale.

11.1. The Obesity Coverage Gap

The Medicare prohibition on coverage for weight-loss drugs is a statutory artifact from 2003, when GLP-1s didn't exist. The relevant drugs at the time were largely ineffective stimulants and appetite suppressants with poor safety records. The law made sense in that context. It doesn't in the context of semaglutide, which has demonstrated cardiovascular mortality reduction in randomized trials.

In 2024, CMS expanded coverage for Wegovy (semaglutide) for Medicare beneficiaries with established cardiovascular disease. This covered roughly 3.6 million beneficiaries. The next tier — coverage for obesity alone, without a comorbidity — would cover an estimated 40+ million Medicare beneficiaries. The Congressional Budget Office estimated such a change would cost $35 billion over 10 years under certain assumptions, though advocacy groups contest those projections.

The Medicaid picture is even more fragmented. Each state decides independently whether to cover GLP-1s for obesity. As of early 2026, fewer than half of states cover obesity-indication GLP-1s through Medicaid. The result is a profound access disparity along income lines — the people most likely to have obesity and type 2 diabetes (lower-income, less likely to have premium employer insurance) are least likely to have coverage for the most effective treatments.

11.2. The Price Negotiation Frontier

The IRA gave Medicare the authority to negotiate drug prices for a targeted list of high-spending, high-expenditure drugs. The second round of negotiations (effective 2026) includes several drugs with GLP-1-adjacent relevance. The third and fourth rounds are widely expected to include Ozempic and Mounjaro, given that:

Ozempic is now the single most expensive drug in Medicare Part D by total expenditure
Semaglutide has no generic equivalent and patent protection extends into the late 2020s
Mounjaro is on a similar trajectory and entered Medicare spending discussions within its first year of eligibility

Negotiated prices for the first 10 drugs ranged from 38% to 79% discounts from list price. Even a 40% reduction in Ozempic's Medicare net cost would save several billion dollars annually at current volumes — and current volumes are still growing.

11.3. The Compounding Problem

The drug shortage during 2022-2024 created a secondary market: compounding pharmacies began producing semaglutide and tirzepatide at dramatically lower prices ($100-$400/month vs $900-$1,300/month for brand-name). The FDA initially allowed compounding during the shortage period under the 503B compounding pharmacy framework. As shortages were resolved, the FDA moved to restrict compounding of these drugs, triggering legal challenges from compounding pharmacies and patient advocacy groups.

FAERS data supports concern about compounded GLP-1 quality — the reporting odds ratio for suicidality in compounded semaglutide reports is substantially higher than for brand-name, though this likely reflects confounding (patients who use compounded drugs are a different population) rather than pharmacological difference. Dosing errors in compounded products have been documented more frequently, likely reflecting variability in formulation and patient self-administration without clinical titration support.

11.4. What Happens When These Drugs Go Generic?

Liraglutide (Victoza/Saxenda) came off patent in 2023. Generic dulaglutide (Trulicity) is expected to be more broadly available by 2026. Semaglutide's patents are contested — Novo Nordisk has over 70 patents covering formulation, delivery, and use; generic manufacturers are challenging many of them. The first generic semaglutide could theoretically reach the US market by 2026-2027 under the most optimistic patent challenge scenarios, though 2030 is a more consensus estimate.

When these drugs do go generic, the cost dynamics will change dramatically. Metformin — the standard-of-care oral diabetes medication — now costs $4 per month at major pharmacies. Generic GLP-1s won't reach that floor immediately, but they could plausibly reach $50-$100/month within five years of generic entry, compared to $1,000+/month today. The access implications are enormous.

12. The Broader Signal: What GLP-1s Tell Us About Drug Innovation analysis

The GLP-1 story is not primarily a story about diabetes drugs. It is a story about what happens when a drug unexpectedly becomes effective for a condition (obesity) that affects roughly 40% of the American population, has limited existing pharmaceutical treatments, and for which payers have historically refused to cover medications.

Several features of this story are genuinely new in pharmaceutical history:

Efficacy that created demand. Most blockbuster drugs achieve high sales through marketing and insurance coverage. GLP-1s created their own demand — social media, celebrity culture, and visible results among early adopters drove patients to seek prescriptions in ways that outpaced pharma marketing budgets. The Ozempic viral moment was not manufactured by Novo Nordisk.

CV outcomes data changing coverage. The expansion of GLP-1 coverage from "diabetes management" to "cardiovascular risk reduction" to (partially) "obesity" follows clinical trial results, not lobbying. The SUSTAIN-6, LEADER, SELECT, and SURPASS-CVOT trials produced mortality reduction data that made it progressively harder for payers to deny coverage on efficacy grounds.

The manufacturing constraint. This class of drugs requires biological manufacturing processes (unlike small-molecule pills) and complex formulation. Both Novo Nordisk and Eli Lilly have each spent billions of dollars on manufacturing capacity expansion. The supply chain is still constrained. This creates an unusual situation where a drug is simultaneously in shortage and generating record revenue — not because of pricing strategy, but because demand outstripped manufacturing capacity at any price.

The obesity treatment paradigm shift. For thirty years, the medical consensus on obesity treatment was behavioral (diet, exercise, lifestyle modification). The failure rate of behavioral intervention alone is high — around 80-90% of patients regain lost weight within 5 years. The GLP-1 clinical data has forced a re-evaluation. If 20% mean weight loss can be sustained pharmacologically, with mortality reduction data to match, the treatment paradigm shifts from "treat the behaviors" to "treat the underlying hormonal dysregulation." This reframing has wide-ranging implications for how obesity is understood, coded, covered, and treated.

13. Data and Methods data cms methodology

Medicare Part D annual spending (2019-2023): CMS Medicare Part D Spending by Drug (dataset ID: 7e0b4365-fd63-4a29-8f5e-e0ac9f66a81b). Annual data with per-year breakdowns for spending, claims, beneficiaries, and average per-unit/per-claim/per-beneficiary costs. "Overall" manufacturer rows used for aggregate drug-level analysis.

Medicare Part D quarterly spending (2024-2025): CMS Medicare Quarterly Part D Spending by Drug (dataset ID: 4ff7c618-4e40-483a-b390-c8a58c94fa15). Provides 2024 Q1-Q4 annual totals and 2025 Q1-Q2 partial year data. "Overall" manufacturer rows used.

State-level prescribing: CMS Medicare Part D Prescribers by Geography and Drug (dataset ID: c8ea3f8e-3a09-4fea-86f2-8902fb4b0920). State-level beneficiary counts aggregated across Ozempic, Mounjaro, Trulicity, and Rybelsus.

FDA adverse events: OpenFDA Drug Adverse Event API (FAERS). Annual report counts by generic drug name (patient.drug.openfda.generic_name). Reaction profiles normalized per 1,000 total reports to enable cross-drug comparison. Administrative/process terms excluded from reaction comparison.

Spending figures are gross, before manufacturer rebates. Medicare Part D plans negotiate confidential rebates with drug manufacturers; actual Medicare expenditure is lower than gross spending, typically by 40-60% for brand-name drugs. The true net Medicare cost is not publicly reported.
2025 data is partial: Quarterly dataset includes 2025 Q1-Q2 (approximately January-June 2025). Full-year 2025 is not yet available.
FAERS reports are not incidence data: The FAERS database captures voluntary adverse event reports from patients, physicians, and manufacturers. High report counts reflect high usage and high media attention, not necessarily higher risk relative to other drugs. The FDA uses FAERS for signal detection, not causality determination.

HAI Scoreboard: Hospital-Acquired Infection Rates

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare hospitals infections dataviz

Figure 1: JPEG produced with DALL-E 4o

Every year, about 1 in 31 hospitalized patients acquires an infection they didn't have when they were admitted. This post visualizes CMS hospital-acquired infection data across ~4,789 US hospitals, exploring where hospitals fall on national benchmarks and what that means for patients choosing where to receive care.

2. TLDR tldr

Around 4,789 US hospitals report hospital-acquired infection (HAI) data to CMS. Only 211 hospital-infection pairs (less than 1%) are rated "Worse than the National Benchmark" — but the data reveals real variation between hospitals. MRSA bacteremia shows the lowest rates (most hospitals perform well) while C. difficile is the most prevalent HAI by patient volume. The most important finding: your hospital's infection rating is searchable, and it varies enough to matter.

3. Introduction cms hospitals infections dataviz

Every year, about 1 in 31 hospitalized patients in the US acquires an infection they didn't have when they were admitted. These healthcare-associated infections (HAIs) — infections contracted in hospitals, nursing facilities, or during outpatient procedures — account for roughly 100,000 deaths annually and billions of dollars in excess healthcare costs.

CMS collects and publishes HAI data for all Medicare-participating hospitals through its Hospital Compare program. Hospitals report six major infection types: Central Line-Associated Bloodstream Infections (CLABSI), Catheter-Associated Urinary Tract Infections (CAUTI), two types of Surgical Site Infections (SSI), MRSA bacteremia, and Clostridium difficile (C. diff). Each is measured using the Standardized Infection Ratio (SIR): the number of observed infections divided by the number predicted based on national baseline rates and patient mix. A SIR of 1.0 means your hospital's rate exactly matches the national average. Below 1.0 is better; above 1.0 is worse.

This post explores where hospitals fall on those benchmarks — and what that means for patients choosing where to receive care.

4. How Hospitals Compare to National Benchmarks dataviz benchmark

For each of the six infection types, this chart shows what percentage of hospitals are rated Better, the Same as, or Worse than the national benchmark.

Several patterns emerge:

"Not Available" dominates. The largest share of hospital-infection combinations lacks a valid SIR rating — often because the hospital had too few procedures or patient-days to produce a statistically reliable estimate. A hospital with no SIR is not necessarily a safe hospital; it may simply be too small to be measured.
Most rated hospitals are within the normal range. Among hospitals with a valid benchmark rating, the majority fall into "No Different than National Benchmark."
"Worse" is rare but real. Hospitals rated worse than the national benchmark are a small minority, but they exist across all six infection types. CAUTI (urinary tract infections) and C. diff show the most "Worse" ratings in absolute terms, partly because they are the most common HAIs by volume.
SSI categories show the most "Better" ratings. Surgical site infection rates have improved substantially over the past decade as surgical technique and antibiotic prophylaxis have improved; many hospitals now perform better than historical baselines.

5. State-Level Performance dataviz choropleth

Percentage of hospital-infection pairs rated "Worse than the National Benchmark," by state.

The geographic pattern is noisy — HAI rates are hospital-specific, and state averages can be driven by a handful of hospitals in each direction. That said, a few patterns are consistent with other quality measures:

States with higher overall hospital quality ratings (from CMS Hospital General Information) tend to have lower rates of HAI "Worse" designations.
Some states show elevated rates of worse-than-benchmark infections, which may reflect older facilities, different patient populations, or reporting differences.
The "Not Available" category (excluded from this percentage) is higher in rural states with many small critical-access hospitals, which may make state comparisons misleading.

6. MRSA vs. C. diff: Two Key Infections dataviz scatter

Each point is a hospital. The x axis shows its C. diff SIR; the y axis shows its MRSA SIR. The reference lines at 1.0 mark the national average. Color reflects the hospital's overall benchmark rating across all six infection types.

MRSA and C. diff are often cited as the most consequential HAIs because they are drug-resistant or treatment-difficult, and they spread easily in healthcare settings. A few observations:

Most hospitals cluster near the origin (SIR < 1 for both), meaning the average hospital performs better than the historical baseline — a sign of genuine improvement in infection prevention over the past decade.
Outliers in the upper-right are concerning. Hospitals with high SIR scores for both MRSA and C. diff simultaneously face a systemic challenge — it isn't random variation in one metric, but a pattern suggesting infection prevention gaps.
Green dots (Better overall) tend to cluster below the median for both infections. Hospitals that perform better than benchmark across the board tend to have MRSA and C. diff rates below the national average too — suggesting that overall infection prevention culture matters more than individual measure management.

7. Hospitals With the Highest Average Infection Rates dataviz rankings

These 20 hospitals have the highest average SIR scores across all reported infection types (minimum 3 reported measures). These are hospitals where observed infections consistently exceed the predicted rate.

Several important caveats for interpreting this list:

Patient mix affects SIRs. The Standardized Infection Ratio is designed to adjust for patient complexity, procedure volume, and type of ICU — but no adjustment is perfect. Hospitals treating the most complex, immunocompromised patients may show elevated SIRs even with good care.
Small hospitals can have noisy SIRs. A hospital with 5 predicted infections and 8 observed has a SIR of 1.6 — but that's based on small numbers. CMS has minimum thresholds, but some outliers still reflect statistical noise.
This list is a starting point, not a verdict. CMS's full Hospital Compare tool allows patients to see individual infection ratings plus the detailed confidence intervals and footnotes that explain data limitations.

The takeaway: before a planned procedure, it's worth checking your hospital's HAI ratings — not to make a binary good/bad judgment, but to have an informed conversation with your care team about infection prevention practices.

8. What Patients Can Do analysis

The HAI data is public and searchable through CMS's Care Compare tool. For planned surgeries or procedures, patients can:

Look up their hospital's infection ratings at medicare.gov/care-compare — search by hospital name, see each HAI measure.
Ask about specific prevention protocols. For surgical cases: does the hospital use SCIP (Surgical Care Improvement Project) protocols? For MRSA: is pre-admission MRSA screening standard practice?
Ask about CLABSI bundles. The evidence-based "central line bundle" (hand hygiene, barrier precautions, chlorhexidine skin antisepsis, optimal catheter site selection, daily review of catheter necessity) has been shown to reduce CLABSI rates by up to 70%. Hospitals that follow it consistently should be able to confirm this.
Consider volume. Hospitals that perform more of a given procedure tend to have lower complication rates, including infection rates. A center that does 400 hip replacements per year has likely optimized its infection prevention workflow more than one that does 40.

The data exists to make these conversations possible. Hospitals that perform well on HAI metrics tend to have a culture of measurement and improvement — which correlates with better outcomes broadly.

9. Data and Methods data cms methodology

All data from the CMS Healthcare-Associated Infections - Hospital dataset, current as of April 2024–March 2025.

Hospitals covered: 4,789 unique hospitals with at least one HAI measure reported.
Measures: Six SIR measures — HAI₁_SIR (CLABSI), HAI₂_SIR (CAUTI), HAI₃_SIR (SSI Colon), HAI₄_SIR (SSI Abdominal Hysterectomy), HAI₅_SIR (MRSA), HAI₆_SIR (C. diff).
Benchmark comparison: CMS assigns each hospital-measure pair to one of four categories based on whether the SIR is statistically Better, No Different, or Worse than the national benchmark, or Not Available (insufficient data).
State map: Percentage of hospital-measure pairs rated "Worse than the National Benchmark" among all rated pairs (excluding "Not Available"). Only 2-character state codes included (territories excluded).
Scatter chart: Restricted to hospitals with valid MRSA and C. diff SIR scores; SIR values above 10 excluded as outliers affecting chart scale.
Worst-performing hospitals: Average SIR across all reported measures; requires ≥3 measures with a numeric SIR. Color coding based on the number of "Worse than National Benchmark" designations across all six measures.

Healthcare Deserts: Where America Can't See a Doctor

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare publicHealth dataviz

Figure 1: JPEG produced with DALL-E 4o

If you get sick in Boston, you have a choice of specialists within walking distance. If you get sick in rural Mississippi, you might drive two hours to see a primary care doctor. This post visualizes HRSA shortage area data to map where the healthcare deserts are, how severe they are, and where safety-net clinics try to fill the gaps.

2. TLDR tldr

Roughly 100 million Americans live in a federally designated health professional shortage area — a place with too few primary care doctors, dentists, or mental health providers to meet basic need. This post visualizes that shortage using live HRSA data: where the deserts are, how severe they are, who goes without, and where the safety-net clinics try to fill the gaps.

3. Introduction healthcare hrsa dataviz publicHealth

If you get sick in Boston, you have a choice of specialists within walking distance. If you get sick in rural Mississippi, you might drive two hours to see a primary care doctor — if you can get an appointment at all.

This isn't a market failure in the usual sense. It's a structural one. Rural areas, low-income urban neighborhoods, and tribal lands have too few health care providers relative to population because those providers can earn more money elsewhere. The federal government has been tracking this gap since the 1970s through a designation called a Health Professional Shortage Area (HPSA).

As of 2025, roughly 6,500 primary care HPSAs, 7,000 dental HPSAs, and 6,000 mental health HPSAs are active across the United States. Together they affect an estimated 100 million people. Every chart on this page draws from the HRSA HPSA dataset, updated daily.

3.1. What is an HPSA? methodology

A Health Professional Shortage Area is a formal designation by the Health Resources & Services Administration (HRSA) indicating that a geographic area, specific population (e.g., low-income), or facility (e.g., a prison) has insufficient health professionals to meet demand. Designations are separated into three disciplines:

Primary Care — general practitioners, family medicine, internal medicine, OB/GYN, pediatrics
Dental Health — dentists and related providers
Mental Health — psychiatrists, psychologists, licensed clinical social workers

Each designation carries a shortage score from 0 to 25, where higher scores indicate greater severity. The score incorporates population-to-provider ratio, infant mortality rates, poverty levels, and travel distance to the nearest source of care.

4. The Map: Where the Deserts Are maps dataviz geography

This map shows the count of active HPSA designations per state. Use the buttons below the map to toggle between care types. Note that one state can contain many distinct shortage areas — a rural county, a low-income urban population, and a correctional facility are each counted separately.

A few patterns are immediately visible. Texas and California lead in raw counts partly because of their size and population — but also because each contains enormous internal variation. Rural West Texas is a different universe from Houston. Watts in Los Angeles is medically underserved while Beverly Hills is not.

Proportion matters more than raw count, but the absolute numbers reveal how many distinct shortage designations coexist within a single state — each representing a community that officially does not have enough providers.

5. Primary Care Deserts primaryCare dataviz

Primary care shortages are the most common and, in some ways, the most consequential. Without a primary care provider, patients delay preventive care, miss chronic disease management, and end up in emergency departments for conditions that should never require one. Diabetes goes uncontrolled. Hypertension goes undiagnosed. Cancers are caught late.

The shortage in primary care is structural: medical schools produce roughly the same number of physicians each year, but the economics of specialty medicine make primary care increasingly unattractive as a career. A cardiologist in a major city earns two to three times what a family practice doctor earns in rural Appalachia — and the rural doctor also faces professional isolation, limited resources, and a patient population with higher disease burden.

5.1. The prescriber ratio metrics

HRSA designates a geographic area as a primary care shortage area when the population-to-provider ratio exceeds 3,500:1. In some of the worst-designated areas, that ratio exceeds 30,000:1 — meaning one physician for every 30,000 patients. The national target is under 1,000:1. Emergency departments in urban teaching hospitals typically see one physician per 1,500–2,000 patients per year.

6. Dental Deserts: A Silent Crisis dental dataviz

Dental care is often treated as a luxury — something separate from "real" medicine and therefore outside the scope of public concern. That framing has consequences. Oral disease is the most common chronic condition in childhood. Untreated tooth decay leads to infections that can become life-threatening. Adults with untreated dental disease lose work days, job opportunities, and eventually teeth, which affects nutrition and overall health.

Dental shortages are heavily rural and heavily correlated with income. Most private dentists set up practices in areas with higher incomes and better insurance coverage. Medicaid covers dental care for children but often not adults, and Medicaid reimbursement rates are so low that many dentists don't accept it even where coverage nominally exists.

7. Mental Health: The Deepest Desert mentalHealth dataviz

Of the three categories, mental health has the most severe and most geographically concentrated shortage. The U.S. has a nationwide deficit of approximately 6,000 psychiatrists, and the shortage is worst in precisely the places where mental illness rates are highest: rural communities with economic distress, high rates of substance use, and social isolation.

In some states, entire counties have no licensed psychiatrist at all. Telehealth has partially filled this gap — the COVID-19 pandemic forced a rapid expansion of remote mental health services — but access to reliable broadband remains a barrier in the same rural areas with the worst provider shortages.

The shortage score distribution below shows how the mental health shortage differs from primary care and dental: a higher proportion of mental health HPSAs have scores in the severe range (15–25), indicating that where mental health shortages exist, they tend to be extreme.

The concentration of high scores in mental health reflects several reinforcing factors: the shortage started earlier, grew faster, and involves a workforce that takes longer to train (psychiatrists complete four years of residency after medical school). Psychologists, licensed clinical social workers, and counselors help fill the gap, but HRSA's ratio thresholds for designation still reflect a very real scarcity.

8. By the Numbers dataviz states

8.1. Underserved population by state states

This chart shows the estimated underserved population by state — that is, the number of people who live in a designated shortage area. The bars are stacked by care type.

California, Texas, Florida, and New York lead partly because of size, but also because each contains large low-income urban populations with inadequate provider coverage. Note that a person can be counted in multiple stacks — living in a primary care shortage area and a mental health shortage area simultaneously.

8.2. The worst individual shortage areas worstAreas

Individual HPSA designations vary enormously in the population they cover. A single geographic HPSA designation in a dense urban area — covering, say, a low-income neighborhood in Los Angeles — might affect 200,000 people. A rural HPSA in Wyoming might cover 800.

This chart shows the 20 individual HPSA designations with the largest estimated underserved populations, colored by shortage score.

The pattern here is striking: the largest shortage areas tend to be urban low-income population designations, not rural geographic ones. These areas have the population but not the providers — because providers have no economic incentive to serve Medicaid-heavy, low-income patient panels.

9. The Safety Net: Where FQHCs Fill the Gaps safetyNet fqhc dataviz maps

The main federal response to shortage designations is the Federally Qualified Health Center program. FQHCs are community health clinics that receive federal grants and enhanced Medicaid reimbursement in exchange for serving all patients regardless of ability to pay. They charge on a sliding fee scale — $0 for the very poorest patients.

Nearly 18,000 active FQHC sites operate across the country, serving roughly 30 million patients annually. They are concentrated in shortage areas by design — HRSA gives priority for FQHC grants to areas with active HPSA designations.

But look at where the gaps in the FQHC map are: large stretches of the rural Mountain West, the Plains states, and the rural South have almost no FQHC coverage. These are places where the shortage exists but the safety net was never built. In some counties, there is simply no federally supported primary care option at all.

9.1. What an FQHC actually does fqhcDetail

FQHCs are required by law to provide:

Primary care — adult medicine, pediatrics, OB/GYN
Dental care — preventive, restorative, emergency
Mental health — behavioral health integration, counseling
Pharmacy — through the 340B drug pricing program, enabling steeply discounted medications
Case management — coordinating care for patients with complex needs
Enabling services — transportation, translation, outreach

This makes FQHCs closer to a full medical home than a simple clinic. They are also required to have governing boards on which a majority of members are patients — a consumer-control requirement that distinguishes them from hospital-run community health programs.

10. Data and Methods data hrsa methodology

All data in this post comes from HRSA's public data warehouse, available at data.hrsa.gov:

HPSA designations — Three separate CSV files, one each for Primary Care, Dental Health, and Mental Health (BCD_HPSA_FCT_DET_PC/DH/MH.csv). Updated daily. Filtered to HPSA Status = "Designated"= (excludes withdrawn, proposed-for-withdrawal).
FQHC sites — Health_Center_Service_Delivery_and_LookAlike_Sites.csv. Filtered to Site Status = "Active"= and Health Center Type = "Federally Qualified Health Center (FQHC)"=.

The shortage score (0–25) is HRSA's composite metric. Primary care scores incorporate the population-to-provider ratio, infant mortality rate, percent of population below poverty, and travel distance to the nearest provider outside the area. Dental and mental health scores use analogous domain-specific formulas.

"Estimated underserved population" is HRSA's estimate of how many people in the shortage area lack adequate access — not simply the total population in the area.

Designations at the facility level (prisons, FQHCs, tribal health facilities) are included in counts but often represent smaller populations. Geographic and population-based HPSAs account for the vast majority of underserved population totals.

Hospital Quality Scatter Explorer

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare hospitals quality dataviz

Figure 1: JPEG produced with DALL-E 4o

The federal government rates every US hospital on a 1-5 star scale across five quality domains. This post visualizes the full landscape of 5,400+ hospitals – where they cluster, how ownership type predicts quality, and where your state falls – using the CMS Hospital Compare dataset.

2. TLDR tldr

The federal government rates every US hospital on a 1–5 star scale across five quality domains: mortality, safety, readmissions, patient experience, and timely care. This post lets you explore the full landscape of 5,400+ hospitals — where they cluster, how ownership type (nonprofit, for-profit, government) predicts quality, and where your state falls. The headline finding: nonprofit hospitals have more 4–5 star ratings than for-profit hospitals, but the variation within each ownership type is enormous.

3. Introduction healthcare cms hospitals quality

Every hospital in the United States that participates in Medicare is evaluated on the same set of quality metrics — and those evaluations are public. CMS publishes an overall 1–5 star rating for roughly 3,000 acute care hospitals, aggregating performance across five domains: mortality rates, safety, readmissions, patient experience, and timely/effective care delivery.

These ratings are controversial. Hospital trade associations regularly lobby against the methodology. Teaching hospitals complain their complex patient mix inflates apparent mortality. Large urban hospitals with many high-risk patients argue they're penalized relative to suburban hospitals with healthier populations. Some of these critiques are valid — the star rating system doesn't perfectly control for case mix — but the data still represents the most comprehensive public view into comparative hospital quality that exists.

This post visualizes the full distribution. 5,359 hospitals, 2,855 with valid overall star ratings, pulling from the CMS Hospital General Information dataset and HCAHPS patient survey data.

3.1. How the star rating is calculated methodology

The overall star rating is a composite. CMS uses a latent variable model that groups hospitals into five tiers based on weighted performance across the five quality domains. The weights are roughly:

Mortality (22%) — risk-adjusted death rates for conditions like heart failure, pneumonia, COPD
Safety of care (22%) — healthcare-associated infections, complications, PSIs
Readmissions (22%) — 30-day unplanned readmission rates
Patient experience (22%) — HCAHPS survey: nurse/doctor communication, pain management, discharge info
Timely & effective care (12%) — door-to-balloon time, ED wait times, sepsis bundles

Hospitals need data on at least three domains to receive an overall rating. Critical access hospitals, psychiatric hospitals, and VA facilities are excluded.

4. The Main View: Patient Experience vs. Mortality dataviz scatter

This scatter plots every hospital with both patient experience data and mortality quality data. The x-axis is the HCAHPS patient experience star rating (1–5); the y-axis shows what percent of a hospital's mortality measures were rated "better than national average." Dot size reflects the overall star rating. Color shows ownership type.

A few things stand out:

Patient experience and clinical quality don't always align. Some hospitals score well on patient experience (4–5 stars for how nurses communicated) but poorly on mortality measures. The reverse is also common.
Nonprofit hospitals (blue) dominate the upper-right quadrant — high experience, strong mortality performance.
For-profit hospitals (orange) show more spread — some high performers, but a larger cluster at lower mortality quality.
The middle mass of hospitals — 2–3 star experience, 20–50% better-than-national mortality — represents the typical American community hospital.

4.1. Why patient experience and clinical quality diverge analysis

The partial decoupling of experience scores from clinical outcomes has a straightforward explanation: they measure different things. HCAHPS captures whether your nurse explained your medications clearly and whether the room was quiet at night. Mortality rates capture whether patients with your condition died within 30 days.

Hospitals can invest in hospitality — single rooms, responsive call systems, well-trained patient-facing staff — without improving the clinical protocols that drive mortality outcomes. Some high-mortality hospitals have excellent bedside manner. Some hospitals with sterile, intimidating environments have exceptional clinical results.

5. Who Gets 5 Stars? Ownership and Quality dataviz ownership

The distribution of star ratings by ownership type reveals a clear pattern:

Nonprofit hospitals are more likely to receive 3–4 stars and overrepresented at 5 stars relative to their share of total hospitals.
For-profit hospitals are overrepresented at 1–2 stars, though they also have a meaningful presence at 4–5 stars.
Government hospitals (state, county, federal non-VA facilities) cluster heavily at 2–3 stars, partly reflecting that many government hospitals serve high-acuity, underinsured populations in urban areas.

This pattern is consistent with research on hospital ownership and quality: for-profit hospitals tend to have higher margins but lower quality ratings, particularly on measures that don't directly affect revenue (HAIs, 30-day readmissions). Nonprofits, constrained to reinvest surplus into operations, tend to maintain higher quality baselines. But the within-group variation is enormous — plenty of 5-star for-profit hospitals and 1-star nonprofits exist.

6. The Geography of Hospital Quality dataviz states geography

Average hospital star ratings vary substantially by state. This map shows the mean overall rating among rated hospitals in each state.

The geographic pattern correlates with several factors: hospital market consolidation (monopoly hospital markets tend to have lower quality incentives), state Medicaid policy (expansions increase insured volumes and reduce financial stress), the presence of academic medical centers (which both depress ratings due to case mix and improve them through teaching excellence), and rural vs. urban mix.

States in the Mountain West and upper Midwest tend to perform well. States with highly consolidated markets or large proportions of safety-net hospitals tend to score lower.

7. Quality by Domain: Where Ownership Predicts Outcomes dataviz domains ownership

The star rating aggregates five domains. This chart breaks that out — for each major quality domain, what fraction of measures does each ownership type have rated "better than national"?

The domain breakdown reveals where ownership effects are strongest:

On mortality and safety, nonprofits consistently outperform for-profits — these are the clinical quality measures that require systemic investment in infection control, care protocols, and staffing ratios.
On readmissions, the gap narrows — readmission reduction requires care coordination infrastructure that all ownership types have invested in, partly because CMS penalizes hospitals financially for excess readmissions.
Government hospitals underperform on most domains, again reflecting the challenging patient populations (uninsured, high-acuity, high-complexity) that many public hospitals disproportionately serve.

8. The Quality Landscape dataviz quadrant

This scatter plots hospitals on two independent quality axes: mortality performance (x) and safety performance (y), colored by overall star rating. The dashed lines separate hospitals above and below the 50% benchmark on each axis.

The upper-right quadrant — better than national on both mortality and safety — is dominated by 4–5 star hospitals. The lower-left quadrant — below benchmark on both — is dominated by 1–2 star hospitals. But there's substantial scatter in the middle bands. Some 3-star hospitals outperform on both; some 4-star hospitals have weakness on one axis.

The hospitals most worth scrutinizing are those in the off-diagonal quadrants: high mortality quality but poor safety (or vice versa). These represent systematic imbalances — a hospital excelling on one dimension while failing on another — that the aggregate star rating can obscure.

9. Data and Methods data cms methodology

All data comes from CMS Provider Data:

Hospital General Information — xubh-q36u. 5,426 hospitals with ownership type, hospital type, overall star rating, and quality domain measure counts (better/no different/worse than national for mortality, safety, and readmission domains).
HCAHPS Patient Survey — dgck-syfz. Filtered to H_STAR_RATING measure: the overall patient experience star rating (1–5) derived from the Hospital Consumer Assessment of Healthcare Providers and Systems survey.

"Better than national" means the hospital's performance on a specific measure (e.g., 30-day heart failure mortality rate) was statistically significantly better than the national average. Hospitals with too few cases to evaluate are excluded from that measure's count.

Ownership simplification:

Nonprofit: "Voluntary non-profit — Private", "Voluntary non-profit — Church", "Voluntary non-profit — Other"
For-Profit: "Proprietary"
Government: all "Government —" subtypes

Not included: Critical access hospitals, psychiatric hospitals, rehabilitation facilities, long-term care facilities. These use different payment and evaluation systems and are not rated on the 1–5 scale.

What Medicare Pays for Your Surgery

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare medicare pricing dataviz

Figure 1: JPEG produced with DALL-E 4o

When you check into a hospital for a hip replacement, the hospital generates a bill for $85,000 – and Medicare pays $12,000. This post uses FY2023 CMS data on 146,000 hospital-DRG combinations to show where the gaps between billed charges and actual payments are widest, and why the number on your hospital bill has almost no relationship to what anyone actually pays.

2. TLDR tldr

Hospitals bill Medicare 3–7 times what Medicare actually pays. The same surgery — same DRG code, same procedure — can carry a billed charge ten times higher at one hospital than at another across state lines. This post uses FY2023 CMS data on 146,000 hospital-DRG combinations to show where the gaps are widest, which states inflate prices most, and why the number on your hospital bill has almost no relationship to what anyone actually pays.

3. Introduction healthcare cms medicare pricing

When you check into a hospital for a hip replacement, the hospital generates a bill. That bill might read $85,000. Medicare looks at the bill, ignores most of it, and pays $12,000. The hospital accepts $12,000 as full payment.

The $85,000 was never a real price. It came from a document called the chargemaster — a hospital's internal price list, often thousands of pages long, set unilaterally by the hospital and reviewed by almost no one. The chargemaster price is what gets billed to patients without insurance, occasionally what gets reported to regulators, and the starting point for negotiations with private insurers. It is, in the words of one health economist, "the most arbitrary and unreasonable prices in American commerce."

The ratio between chargemaster prices and what payers actually pay has grown for decades. In the 1980s, Medicare typically paid 70–80 cents on the dollar of billed charges. By 2023, that figure had fallen to roughly 20 cents on the dollar for the average inpatient procedure. Hospitals bill five times what they accept as payment. And the variation across hospitals and states is enormous.

Every chart on this page draws from the CMS Medicare Inpatient Hospitals by Provider and Service dataset (FY2023), covering 146,427 hospital-DRG combinations at 2,945 IPPS hospitals.

3.1. How the DRG system works methodology

Medicare doesn't pay hospitals by the procedure. It pays by something called a Diagnosis-Related Group (DRG) — a classification that groups together patients with similar diagnoses and expected resource use. When you're admitted for a hip replacement, you're assigned DRG 470. Medicare looks up the national base rate for DRG 470, adjusts it for the hospital's local wage index and teaching status, and writes a check. The hospital's billed charge is irrelevant.

This means the hospital's chargemaster number — what shows up on your Explanation of Benefits — is entirely disconnected from what Medicare pays. The DRG payment is fixed in advance. Billing $80,000 vs. $120,000 doesn't change the Medicare check.

So why do chargemaster prices keep rising? Because they function as anchors in private insurance negotiations. The higher the chargemaster, the higher the "discount" insurers can claim to have won, and the higher the benchmark for out-of-network billing.

4. The Gap: What Hospitals Bill vs. What Medicare Pays dataviz billing

The chart below shows the 20 most common inpatient procedures in Medicare by total discharge volume. For each, the blue bar shows what Medicare paid on average; the orange bar shows what hospitals billed.

A few observations from the top procedures:

Septicemia and respiratory failure (the top volume DRGs post-COVID) show billed charges 4–6× the Medicare payment.
Major joint replacement (DRG 470 — hip and knee) is consistently the highest-volume elective procedure. Hospitals bill roughly $60,000–$80,000. Medicare pays around $14,000–$16,000.
Heart failure and pneumonia show similar multiples.

None of these gaps are cost-based. Medicare's payment rates are calculated from a formula incorporating actual hospital costs, case complexity, and regional wage differences. The billed charges are set by each hospital's chargemaster with almost no public scrutiny.

5. Same Surgery, 10 Different Prices dataviz hospitalVariation

The national averages mask even more extreme variation at the hospital level. This scatter plot shows every IPPS hospital that billed Medicare for DRG 470 (Major Joint Replacement of the Lower Extremity — hip and knee replacements, the single highest-volume elective surgery in Medicare). Each dot is one hospital.

The dashed reference lines show where billed charges are 1×, 3×, 5×, and 10× the Medicare payment. Most hospitals cluster in the 3–5× band. But a significant tail extends beyond 10×. A hospital billing $200,000 for a knee replacement gets the same Medicare check as one billing $30,000 for the identical procedure.

This matters because:

Uninsured patients are often billed the chargemaster rate, though most hospitals have charity care or negotiated payment plans.
Out-of-network billing frequently starts from the chargemaster rate, which is why surprise billing can be catastrophic.
Private insurance negotiations use chargemaster rates as anchors, even if the final negotiated rate is much lower.

5.1. Why the variation exists mechanisms

The spread in billed charges isn't primarily explained by cost differences. Studies controlling for patient complexity, local wages, and teaching status find that the main driver of chargemaster inflation is market power. Hospitals that face less competition — regional monopolies, dominant systems in consolidated markets — charge more. The chargemaster is a negotiating weapon.

The Hospital Price Transparency Rule (effective January 2021) requires hospitals to publish their chargemaster rates and payer-specific negotiated rates. Compliance has been uneven, but the data is beginning to reveal just how wide the gaps are across insurers for the same DRG at the same hospital.

6. Where the Markups Are Highest dataviz serviceLines

The billed-to-paid gap varies substantially by medical service category. Surgical specialties with expensive equipment — orthopedics, cardiac surgery, neurosurgery — tend to have higher chargemaster rates. Medical services (infectious disease, mental health) tend to have lower ratios.

The ratio at the right of each bar is how many times the billed charge exceeds what Medicare pays. Musculoskeletal procedures (joint replacements, spine surgery) show some of the highest ratios. Mental health and substance use services show lower ratios — in part because psychiatric admissions are reimbursed under a separate payment system (IPPS psychiatric add-on rates) and the base DRG payments are lower.

7. The Geography of Price Inflation dataviz states geography

Charge-to-payment ratios vary dramatically by state. This choropleth shows the discharge-weighted average ratio of billed charge to Medicare payment at the state level.

States with higher ratios tend to have more consolidated hospital markets (fewer competitors per metropolitan area), higher costs of living, or regulatory environments that historically permitted higher chargemaster growth. The variation isn't purely a function of what Medicare pays — Medicare's geographic adjustments account for local wage differences — it reflects genuine differences in how aggressively hospital systems set their internal prices.

8. How Extreme Is Typical? dataviz distribution

The histogram below shows the distribution of charge-to-payment ratios across all 534 DRGs in the dataset (one data point per DRG, discharge-weighted nationally).

The distribution is right-skewed: most DRGs cluster between 3× and 6×, but a significant tail extends past 10×. The handful of DRGs with very high ratios tend to involve expensive devices (implants, cardiac devices) where hospitals have traditionally padded charges most aggressively.

There are also DRGs with ratios near 1× — these are typically short-stay or low-complexity cases where hospital billing practices have historically been more constrained, often because patients are more likely to be self-pay and the chargemaster rate is more likely to be scrutinized.

9. Data and Methods data cms methodology

All data in this post comes from the CMS Medicare Inpatient Hospitals by Provider and Service dataset (FY2023, released May 2025).

Scope: Inpatient Prospective Payment System (IPPS) hospitals only — the approximately 3,000 acute care hospitals reimbursed under Medicare's DRG-based system. Critical access hospitals, psychiatric facilities, rehabilitation hospitals, and long-term care hospitals are excluded (they have different payment methodologies).
Fields used: Avg_Submtd_Cvrd_Chrg (average billed charge), Avg_Mdcr_Pymt_Amt (average Medicare payment), Tot_Dschrgs (total discharges), plus provider and DRG identifiers.
"Charge-to-payment ratio": Avg_Submtd_Cvrd_Chrg ÷ Avg_Mdcr_Pymt_Amt. All averages in multi-hospital aggregations are discharge-weighted.
Service line categories: Derived from DRG code ranges corresponding to Medicare Severity DRG Major Diagnostic Categories (MDCs).
Geographic filtering: Restricted to 50 states plus DC; territories excluded from the state choropleth.

The gap between Avg_Submtd_Cvrd_Chrg and Avg_Mdcr_Pymt_Amt is not pure profit — hospitals have costs, and the chargemaster price doesn't represent revenue. What the gap does represent is the difference between a number hospitals make up and a number Medicare computes from actual cost and utilization data. The chargemaster is theater; the Medicare payment is closer to economics.

The Geography of Medicare Spending

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare medicare geography dataviz

Figure 1: JPEG produced with DALL-E 4o

Medicare is a single national program with a single set of rules, yet what it spends per beneficiary varies dramatically by geography. This post uses CMS standardized spending data to explore why higher spending predicts neither better outcomes nor lower readmission rates.

2. TLDR tldr

Medicare standardized spending per beneficiary varies by more than 2.5× between the cheapest and most expensive states — and by far more at the county level. Yet higher spending predicts neither better outcomes nor lower readmission rates. The data consistently shows weak-to-zero correlation between what Medicare spends and how well patients do.

3. Introduction cms medicare geography

Medicare is a single national insurance program with a single set of rules. Yet what it spends on a beneficiary in Manhattan, Kansas is dramatically different from what it spends in Manhattan, New York. Some of this is expected: prices are higher in urban markets, specialists charge more, and illness is more complex in some populations. But when you standardize for these factors — removing the geographic payment rate differences so you're comparing actual resource use — the variation persists and remains enormous.

The CMS Geographic Variation Public Use File captures this. Every year, CMS publishes per-beneficiary Medicare spending broken down by geography (national, state, county) and service type, standardized to remove local wage and price differences. The result is a dataset that lets you ask: ignoring local prices, how much Medicare care does this area actually consume?

This post explores that question using the 2023 data (latest available), with trend context going back to 2014.

4. Spending by State dataviz choropleth

Standardized Medicare spending per fee-for-service beneficiary in 2023, by state. Darker blue = more spending.

A few things jump out immediately:

The South spends more. States like Louisiana, Mississippi, Alabama, and Florida consistently appear among the highest spenders. The Northeast and Mountain West tend toward the lower end.
Utah is a persistent outlier on the low end. Utah has among the lowest Medicare spending in the country, a pattern that has held for decades and is associated with a younger average age, lower rates of chronic disease, and a health system historically oriented around the LDS hospital network.
The range is substantial. The difference between the lowest- and highest-spending states represents thousands of dollars per beneficiary per year — real money, multiplied across millions of patients.

5. Does Higher Spending Mean Better Care? dataviz scatter outcomes

The obvious question is whether higher-spending states achieve better outcomes. The answer, consistently, is no. This scatter plots standardized spending against the 30-day hospital readmission rate — one of Medicare's primary quality metrics.

The correlation is near zero. High-spending states like Louisiana and New York do not have systematically lower readmission rates than low-spending states like Hawaii or Utah. If anything, the relationship trends slightly positive: states that spend more tend to have slightly higher readmission rates, though the relationship is too weak to be meaningful.

This is one of the most replicated findings in health economics, associated most prominently with the Dartmouth Atlas research: more care does not automatically produce better outcomes. Much of the geographic variation in Medicare spending reflects differences in practice patterns, not patient needs.

6. Spending Trends: 2014–2023 dataviz trends

Medicare per-beneficiary spending has grown over the past decade, but not uniformly across service types. This chart breaks down standardized national spending by category.

Several patterns stand out:

Inpatient spending has declined as a share of total spending. Hospital stays are expensive, and the secular trend has been toward shorter stays and more outpatient care.
COVID-19 visibly disrupted 2020 spending. Total spending dipped as elective procedures were deferred and patients avoided hospitals. Post-acute and home health care were particularly affected.
Recovery was uneven. Some service categories rebounded quickly (outpatient, E&M); others recovered more slowly.
Total spending resumed growth after 2020. By 2022–2023, total standardized spending exceeded pre-COVID levels.

7. County Extremes: Highest and Lowest Spending dataviz counties

State averages mask enormous county-level variation. These are the 20 counties with the highest and lowest standardized Medicare spending in 2023, restricted to counties with at least 1,000 fee-for-service beneficiaries to reduce small-sample noise.

The spread is striking. The highest-spending counties can exceed $20,000 per beneficiary per year in standardized spending — more than twice what the lowest-spending counties spend on the same standardized basis. The geographic clustering is notable too: extreme-high-spending counties tend to cluster in Louisiana, south Texas, and urban Florida. Extreme-low-spending counties tend to cluster in Utah, rural Nebraska, and parts of the Pacific Northwest.

8. Why Does Variation Persist? analysis

If higher spending doesn't produce better outcomes, why does the variation persist? Several factors:

Practice pattern variation is the most heavily studied explanation. Physicians in high-spending areas order more tests, refer more, hospitalize more — not because patients are sicker, but because local norms evolved that way. Once established, these patterns are sticky: physicians trained in high-intensity environments carry those habits forward.

Supplier-induced demand plays a role where supply of specialists and hospitals is high. More available beds tend to be filled; more available specialists tend to generate more referrals. The healthcare market doesn't clear like a normal market because patients don't pay marginal costs and don't comparison-shop.

Chronic disease burden explains some (but not all) variation even after standardization. The South has higher rates of diabetes, obesity, and hypertension — chronic conditions that generate ongoing Medicare spending. But the Dartmouth research suggests this explains only a fraction of the variation; the rest is attributable to intensity of treatment for equivalent patients.

Fee-for-service incentives reward volume, not value. A system that pays per procedure will always face pressure toward more procedures in areas where practice patterns allow it.

9. Data and Methods data cms methodology

All data comes from the CMS Medicare Geographic Variation by National, State & County dataset, 2014–2023 releases.

Population: Original Medicare fee-for-service (FFS) beneficiaries aged 65+. Medicare Advantage enrollees are excluded because their claims are not reported to CMS in the same format.
Standardized spending: CMS standardizes payment rates to remove geographic differences in input prices (wage index, rural adjustments, graduate medical education payments). Standardized spending reflects actual resource use — how much care, not how much it costs locally. This is what allows fair geographic comparison.
Readmission rate: Percentage of inpatient stays followed by an unplanned readmission within 30 days. Includes all-cause readmissions.
County minimum: The top/bottom chart filters to counties with ≥1,000 FFS beneficiaries to reduce noise from very small populations with erratic per-capita figures.
Age level: All figures use the "All" age stratum (65 and over combined).

America's Mental Health Crisis, By ZIP Code

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About publicHealth mentalHealth dataviz

Figure 1: JPEG produced with DALL-E 4o

Mental health is the defining public health story of the 2020s. This post maps both sides of the equation – need and supply – using CDC PLACES ZIP code-level prevalence data and HRSA mental health shortage area designations, revealing how the areas with the highest need are often those with the fewest providers.

2. TLDR tldr

Nearly 1-in-5 American adults — about 19% on average — reports frequent mental distress (14 or more poor mental health days per month). But the burden is not evenly distributed: ZIP codes in rural Appalachia, the Deep South, and parts of the mountain West reach 30%+ prevalence, while affluent coastal ZIP codes can fall below 10%. The cruel overlap: the areas with the highest need are often those with the fewest mental health providers.

3. Introduction :cdc:mental-health maps dataviz

Mental health is the defining public health story of the 2020s. Rates of depression, anxiety, and poor mental health outcomes rose sharply during and after the COVID-19 pandemic, and they have not fully recovered. Meanwhile, the US mental health workforce has failed to keep pace with demand: 10,975 Mental Health Health Professional Shortage Areas (HPSAs) are currently designated by the federal government, representing communities where the supply of mental health providers falls critically short of need.

This post maps both sides of that equation — need and supply — using two public datasets:

CDC PLACES 2023: ZIP code-level prevalence of frequent mental distress (14+ poor mental health days/month) and diagnosed depression, covering ~30,000 ZIP codes across the US.
HRSA Mental Health HPSA Designations: Every designated mental health shortage area in the US, with shortage scores and estimated underserved populations.

The combination reveals where the crisis is most acute: not just places with high mental health burden, but places where that high burden coincides with a shortage of the providers who could address it.

4. Where Mental Health Burden Is Highest dataviz choropleth

Population-weighted prevalence of frequent mental distress by state. Darker purple = higher burden.

The geographic pattern is striking and consistent:

West Virginia leads the country in mental health burden, followed by Kentucky, Mississippi, Oklahoma, and Arkansas. These states also tend to have lower incomes, higher rates of chronic disease, and more limited access to care.
The Mountain West shows elevated rates — Montana, Wyoming, Nevada — often attributed to rural isolation, high rates of substance use, and limited specialty care.
Utah and Hawaii consistently appear among the lower-burden states, though Hawaii's data reflects its unique demographics.

The spread across states is substantial: from roughly 12–14% in the lowest-burden states to 22–25% in the highest. But state averages mask enormous within-state variation — ZIP codes in rural Appalachia can reach 35% while neighboring suburban ZIPs are at 12%.

5. The Supply Problem: Need vs. Provider Availability dataviz scatter hrsa

Each point is a state. X axis = number of designated Mental Health HPSAs. Y axis = % adults with frequent mental distress. Bubble size = estimated underserved population. Color = depression prevalence.

The upper-right quadrant is where the crisis converges: states with both high mental health burden and many shortage areas. West Virginia, Mississippi, Oklahoma, and parts of Appalachia cluster here. These states have both the greatest per-capita need and the most designated shortage areas — meaning the federal government has explicitly recognized that provider supply is inadequate, yet the burden remains high.

States in the lower-left — lower burden, fewer shortage areas — tend to be wealthier states with denser urban populations and more accessible specialty care.

The relationship isn't perfectly linear. Some states have many HPSAs but moderate burden (reflecting expansive geography with sparse population). Others have high burden but fewer formally designated shortage areas, possibly because the shortage is too diffuse to trigger formal HPSA designation. The core finding holds: states where people need mental health care most are systematically more likely to lack the providers to deliver it.

6. The Geography of Distress: ZIP-Level Distribution dataviz histogram

This histogram shows the distribution of frequent mental distress prevalence across ~30,000 US ZIP codes.

The distribution is right-skewed: most ZIP codes cluster around the national median (~19%), but a long tail extends toward ZIP codes where 30–35% of adults report frequent mental distress. That tail is not random — it is concentrated in specific geographies where structural disadvantage (poverty, unemployment, chronic disease burden, social isolation) compounds the mental health burden.

The spread also reflects real differences in mental health risk. The ZIP code you live in is a significant predictor of mental health outcomes — not just because of selection effects (mentally healthier people can afford to live in better-resourced areas), but because neighborhood factors directly affect mental health through social networks, green space, air quality, economic security, and access to care.

7. Highest-Burden States dataviz rankings

The 20 states with the highest rates of frequent mental distress, with mental health shortage designations as context.

Bar color reflects the number of mental health shortage areas — darker orange-red means more shortage areas. The compounding of high burden and high shortage is visible: states like West Virginia and Mississippi sit at the top of both rankings.

Several patterns stand out:

Appalachian and Southern states dominate the high-burden list. The intersection of rural isolation, limited economic opportunity, higher rates of chronic pain (a major risk factor for depression), and restricted access to mental health care creates a concentrated geographic crisis.
States with high burden don't always have the most HPSAs. Some states are rurally expansive but have few formal HPSA designations because the shortage exists everywhere, making designation less administratively useful. This likely undercounts the true access gap.
Urban states with high overall populations (Texas, California) appear in the middle of the burden distribution despite having many shortage areas — because their shortage areas are geographically concentrated while urban populations have better access.

8. What Drives the Geographic Pattern analysis

The geographic clustering of mental health burden is not accidental. Several structural factors converge:

Economic distress is the most consistently replicated predictor of population mental health. Counties with high rates of unemployment, poverty, and economic decline show elevated rates of depression, anxiety, and suicide. The collapse of coal and manufacturing in Appalachia, the persistent poverty of the Mississippi Delta, and the economic precarity of rural communities broadly all show up in the data.

Social isolation matters independently of economics. Rural communities have thinner social networks, higher rates of geographic mobility that disrupts relationships, and less community infrastructure (fewer churches, fewer civic organizations, fewer informal gathering places) than urban areas. Isolation is a direct mental health risk factor.

Chronic pain and physical health are underrecognized drivers of mental health burden. States with high rates of musculoskeletal disease, opioid-related injury, and physical disability — often the same states with high mental health burden — see elevated depression and anxiety as consequences of chronic pain and disability.

Provider supply creates a reinforcing cycle. Where mental health providers are scarce, people don't get diagnosed and treated — so the burden persists and worsens. Where providers are abundant, mild-to-moderate conditions get treated early, reducing the burden that shows up in population surveys. Geographic variation in care supply is both a cause and a consequence of the mental health crisis.

9. Data and Methods data cms methodology

Mental health burden data: CDC PLACES 2023 — ZIP code-level crude prevalence estimates for frequent mental distress (MHLTH: 14+ poor mental health days/month) and diagnosed depression (DEPRESSION). ~30,000 ZCTA geographies. Data source: Behavioral Risk Factor Surveillance System (BRFSS).

State averages are population-weighted means of ZIP-level estimates, using total ZIP population as weights.
ZIP-to-state mapping uses the 2020 Census ZCTA-to-county relationship file, crosswalked via state FIPS codes.

HRSA Mental Health HPSA data: HRSA HPSA Designation File — Mental Health — all currently designated Mental Health HPSAs in the US (10,975 designations). HPSA designations are assigned by HRSA and reviewed periodically; they indicate areas, populations, or facilities where mental health provider supply is insufficient to meet demand.

State aggregates: count of HPSA designations, population-weighted average HPSA score (0–25), and sum of estimated underserved population.
HPSA score (0–25) reflects severity of shortage: higher scores = worse shortage.

The Three Waves: Visualizing America's Opioid Epidemic with CDC Data

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About publicHealth opioids dataviz

Figure 1: JPEG produced with DALL-E 4o

In 1999, roughly 8,000 Americans died from opioid overdoses. By 2023, that figure was approaching 80,000 – a tenfold increase in a single generation. This post uses CDC Vital Statistics data to trace the three distinct waves of the epidemic: prescription painkillers, heroin, and synthetic fentanyl – each deadlier than the last.

2. TLDR tldr

The U.S. opioid epidemic has unfolded in three distinct waves since the late 1990s — each deadlier than the last. This post uses live CDC data to trace that arc: from a flood of prescription painkillers, to a heroin surge, to the synthetic fentanyl era that now kills ~75,000 Americans a year. The drug itself changed, the source changed, and the geography changed. The death toll never stopped climbing.

3. Introduction opioids publicHealth dataviz cdc

In 1999, roughly 8,000 Americans died from drug overdoses involving opioids. By 2023, that figure was approaching 80,000 — a tenfold increase in a single generation. Drug overdose has become the leading cause of accidental death in the United States, surpassing car crashes. Yet unlike a natural disaster, this catastrophe unfolded in slow motion, one prescription pad, one syringe, one fentanyl-laced pill at a time.

What makes the opioid crisis distinctive is that it mutated. Three separate epidemics, each triggered by a different drug, have layered on top of one another over 25 years. Understanding the mechanics of that mutation — and seeing it in data — is essential for anyone trying to understand where it goes next.

All charts on this page draw from the CDC's Vital Statistics Rapid Release (VSRR) dataset, which tracks provisional drug overdose death counts monthly across all U.S. states. The numbers use 12-month rolling totals, which smooth out seasonal noise and reporting lags.

3.1. A note on the numbers methodology

These are provisional death counts — the CDC publishes them 6-8 months after the fact as medical examiners complete their work. Final counts are typically slightly higher once all deaths are coded. The 12-month rolling total means each data point represents deaths over the prior 12 months, giving a stable trend line rather than month-to-month spikes.

4. The Three Waves opioids dataviz waves

The epidemic's shape is most visible in a single chart: overdose deaths broken out by substance, plotted as 12-month rolling totals from 2015 to 2025. Three inflection points define three eras.

The shaded zones mark the dominant wave of each period, though in practice the waves overlap considerably. Wave 3 (fentanyl) didn't replace Wave 2 (heroin) — it subsumed it. Today, most "heroin" deaths involve fentanyl; the distinction between the two has all but collapsed in the drug supply.

The chart also reveals something important: total overdose deaths (the red line) barely paused, even as the underlying substances shifted. Each time one drug supply was disrupted or restricted, another took its place — usually more dangerous than the last.

5. Wave 1: The Prescription Flood opioids prescriptionOpioids wave1

The first wave was a pharmaceutical phenomenon. Starting in the late 1990s, OxyContin and other extended-release opioids were aggressively marketed to physicians as safe long-term pain treatments. Purdue Pharma's sales force specifically targeted high-volume prescribers in rural areas with high rates of physical labor injuries — Appalachia, the rural South, the Mountain West.

The strategy worked: by 2010, U.S. physicians were prescribing enough opioids to medicate every American adult around the clock for a month. The "natural and semi-synthetic opioids" line in the chart above — the blue line — represents this wave: hydrocodone, oxycodone, codeine.

5.1. The prescribing machine prescribers geography

The CDC tracked prescribing rates at the county and ZIP code level during this period. In some rural counties in West Virginia, Tennessee, and Alabama, opioid prescriptions outnumbered residents — more than one prescription per person per year. Pain clinics ("pill mills") sprang up in states with lax oversight, with patients driving hours to obtain prescriptions that were then resold locally.

The regulatory response came in 2010-2012: the FDA reformulated OxyContin to make it abuse-resistant, and the DEA began clamping down on pill mills. Prescribing rates started to fall. But by then, a generation of users had developed severe physical dependence — and they needed something.

6. Wave 2: The Heroin Bridge opioids heroin wave2

The second wave was the market's answer to the first. When prescription opioids became harder to obtain and their street price rose, heroin was cheaper, more available, and produced by the same pharmacological mechanism. Mexican cartels recognized the demand and flooded the market.

The heroin epidemic looked different from Wave 1. Where prescription opioids had been predominantly a rural and suburban phenomenon, heroin spread into every demographic and geography. Overdose deaths climbed steeply from 2010 through 2016-2017.

Then the drug supply shifted again.

7. Wave 3: Fentanyl and the Poisoned Supply opioids fentanyl wave3 synthetic

Synthetic opioids — primarily illicitly manufactured fentanyl — are now the dominant driver of overdose deaths. The following chart isolates the heroin-to-fentanyl transition, which represents the most consequential shift in the drug supply in the epidemic's history.

7.1. Why fentanyl? fentanyl supplyChain

Fentanyl's economics are brutal: it is 50-100x more potent than morphine, meaning a kilogram of fentanyl replaces many kilograms of heroin for a fraction of the transportation risk. Synthesized cheaply in China and Mexico from precursor chemicals, it can be pressed into counterfeit pills, mixed into heroin, or sold on its own. A $1 worth of fentanyl can be lethal.

The shift from heroin to fentanyl wasn't a choice that drug users made — it was imposed on them. Surveys of people who use drugs consistently show most would prefer a known-potency supply. Fentanyl's variable concentration (often unevenly distributed within a single batch) makes every use a potential fatal overdose. There is no antidote tolerance, no way to test the dose.

By 2023, the CDC attributes more than 73% of all drug overdose deaths to synthetic opioids — a category that barely registered in 2013.

8. Deaths by Substance, Year by Year dataviz opioids breakdown

Seeing the raw composition by year makes the three-wave structure concrete. The bar chart below shows annual death counts for each major substance category, using December 12-month-ending data as the annual snapshot.

A few features stand out:

Prescription opioids (blue) plateau and very slowly decline after 2016 as prescribing restrictions tightened — but they never return to pre-epidemic levels. Millions remained dependent, now often obtaining diverted pills or switching to street drugs.
Heroin (green) peaks around 2016-2017 and then falls sharply — not because fewer people were using opioids, but because the drug supply was adulterated with fentanyl. Deaths attributed to "heroin" were already fentanyl deaths; the coding just hadn't caught up.
Fentanyl (yellow) grows explosively, roughly doubling every 2-3 years through the peak.
Cocaine (purple) and methamphetamine (pink) deaths rise in parallel — a phenomenon researchers call the "polysubstance" wave. Stimulant deaths often involve fentanyl contamination of the cocaine/meth supply, a grim side effect of fentanyl's ubiquity in street-level drug markets.

9. The Scale in Context dataviz mortality context

Drug overdose deaths are large enough in absolute terms to register as a measurable fraction of all U.S. deaths. The chart below places drug overdose deaths against total U.S. mortality — context that is often missing from epidemic reporting.

The 2020-2021 spike in total deaths is the COVID-19 pandemic. Notably, drug overdose deaths also accelerated sharply during this period — fentanyl deaths increased ~30% during the pandemic year. Lockdowns, disrupted supply chains, and collapsed treatment infrastructure compounded the synthetic opioid crisis simultaneously with COVID-19 mortality.

At peak, roughly 1 in every 30 deaths in the United States was a drug overdose — a share unthinkable in 1999.

10. Geographic Spread dataviz geography states maps

The opioid epidemic began in specific geographies — rural Appalachia, manufacturing towns in the Rust Belt — but has since diffused broadly across the country. The chart below ranks all 50 states by most recent 12-month overdose death totals.

Absolute death counts reflect population size; large states like California, Texas, and Florida show high totals. But the epidemic isn't primarily a big-state story. West Virginia, Ohio, Pennsylvania, and Kentucky remain disproportionately affected when adjusting for population — a legacy of the prescription wave that hit those communities first and hardest. The color gradient from purple to orange reflects magnitude within the top-ranked states.

10.1. How states changed over time states trends heatmap

The heatmap below shows how overdose deaths evolved by state from 2015 through the most recent data, sorted by current death toll. Darker colors represent higher death counts.

Notice that no state moves from dark to light — there are no success stories in this data. Some states saw slower growth than others, but the epidemic has proven resistant to state-level intervention. States that aggressively restricted prescribing (like Florida after the 2011 pill mill crackdown) often saw deaths shift composition rather than decline in total — from prescription pills to heroin, then from heroin to fentanyl.

11. What the Data Doesn't Show :limitations:treatment:harm-reduction:

Death counts are a lagging, partial indicator. They tell us how many people died, but not:

How many people are in active addiction — estimates range from 2-4 million Americans for opioid use disorder alone
Rates of treatment access — fewer than 25% of people with opioid use disorder receive medication-assisted treatment (buprenorphine, methadone, naltrexone)
Near-miss overdoses — for every fatal overdose, many more are reversed by naloxone (Narcan) or survive without intervention
The economic cascade — lost productivity, healthcare costs, criminal justice costs, and family disruption extend well beyond the death toll

The CDC's Drug Overdose surveillance and HRSA's Health Professional Shortage Area data offer complementary views — particularly the geographic clustering of mental health provider deserts, which correlates with overdose hotspots.

12. Data and Methods data cdc api methods

All charts use the CDC's VSRR Provisional Drug Overdose Death Counts dataset (dataset ID: xkb8-kh2a), accessed via the CDC's Socrata SODA API. The API is free, requires no authentication, and updates monthly.

The data covers:

Period: January 2015 – present (with ~6-8 month reporting lag)
Geography: All 50 states, DC, and national totals
Granularity: Monthly, with both "12 month-ending" rolling totals and single-month counts
Indicators: Total deaths, drug overdose deaths, opioids, fentanyl, heroin, natural/semi-synthetic opioids, cocaine, psychostimulants, and more

The 12-month rolling total ("period" = "12 month-ending") is used throughout for stability. Single-month counts have high variance due to reporting delays from medical examiner offices.

Data source: CDC VSRR Provisional Drug Overdose Death Counts. Charts generated from live API data fetched February 2026. CDC WONDER and HRSA data referenced for contextual statistics.

The Telehealth Revolution

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About healthcare telehealth medicare dataviz

Figure 1: JPEG produced with DALL-E 4o

Before March 2020, telehealth was a niche feature of the US healthcare system. Then the pandemic hit, and CMS suspended virtually every telehealth restriction overnight. This post tracks the largest natural experiment in healthcare delivery ever conducted – from the initial 47% adoption spike through the permanent ~13% baseline that emerged.

2. TLDR tldr

COVID-19 forced a telehealth experiment on the entire US healthcare system in 2020. Utilization went from essentially zero to 47% of eligible Medicare beneficiaries in a single quarter. Five years later, telehealth hasn't disappeared — it's settled at ~13%, a permanent structural shift from the pre-pandemic baseline of near zero. This post shows where that new baseline landed and who uses it most.

3. Introduction telehealth cms medicare trends

Before March 2020, telehealth was a niche feature of the US healthcare system. Medicare covered a narrow set of telehealth services only for patients in rural areas, only for certain specialties, and only when conducted from an approved facility. In-person care was the default, and most patients had no reason to deviate from it.

Then the pandemic hit, and CMS issued an emergency waiver that suspended virtually every telehealth restriction overnight. Any Medicare beneficiary could receive any covered service via video or phone from any location. Reimbursement rates were set equal to in-person visits to eliminate the financial disincentive for providers.

What followed was the largest natural experiment in healthcare delivery ever conducted. The question was whether patients and providers would revert to in-person care when restrictions lifted — or whether the forced experiment would reveal a latent demand for remote care that the previous regulatory structure had artificially suppressed.

The data, now five years out, gives a clear answer: both things happened. The extreme peak didn't last. But telehealth didn't collapse back to zero either. A meaningful fraction of healthcare visits permanently shifted to remote delivery.

This post visualizes the full trajectory using CMS Medicare Telehealth Trends data — quarterly from Q1 2020 through mid-2025, covering 50 million Medicare FFS beneficiaries.

4. The COVID Inflection Point dataviz trends covid

The quarterly trend is stark. In Q1 2020 — the first three months of the year, before lockdowns fully took hold — 6.9% of Medicare beneficiaries used telehealth. In Q2 2020, that figure hit 46.7%. One in three beneficiaries who would typically see a doctor in person instead used a phone or video visit.

The spike was driven by necessity: clinics closed, patients were afraid to enter buildings, and CMS simultaneously removed every barrier to billing for telehealth. The incentives all pointed in one direction at once.

After the acute phase, utilization fell but didn't collapse. Q3 2020: 28.2%. Q4 2020: 27.8%. The emergency was winding down but patients and providers had adapted. Workflows changed. Scheduling systems were rewritten. Patients discovered their doctor could diagnose a rash over video. Therapists discovered that sessions over Zoom were often just as effective — and more accessible.

4.1. Why the decline from the peak is real analysis

The post-2020 decline isn't a sign that telehealth failed. It reflects the return of care that genuinely requires in-person delivery. Surgical follow-ups, physical therapy, procedures, imaging — none of these can be done remotely. As these services resumed, telehealth's share of total visits fell toward the services where it actually adds value: chronic disease management, psychiatric follow-ups, medication refills, minor acute care.

The question was never whether telehealth should be 47% of all visits. It was whether it should be 0%. The answer turned out to be something closer to 13–14%.

5. The New Baseline: Did Telehealth Stick? dataviz retention

By 2023 and 2024, telehealth utilization had stabilized at roughly 13–14% per quarter. Congressional action extended the emergency telehealth waivers multiple times, and CMS made several provisions permanent in subsequent rulemaking. The infrastructure built in 2020 — the scheduling software, the patient familiarity, the provider workflows — stayed in place.

Pre-pandemic, telehealth was effectively at 0% for Medicare beneficiaries due to geographic and facility restrictions. The ~13% post-pandemic baseline represents a genuine, durable expansion of access. For the roughly 50 million Medicare beneficiaries, that means millions of visits per quarter that previously required a car trip, time off work, and a waiting room are now handled from home.

6. Rural vs Urban: Who Adopted More? dataviz rural urban geography

The rural-urban comparison is one of the most politically and practically charged dimensions of telehealth policy. The original Medicare telehealth restrictions were partly motivated by a concern that rural patients — who lack broadband and may have older technology — couldn't effectively use remote care. The emergency waiver suspended the geographic requirements, allowing urban patients to use telehealth for the first time.

The data shows both groups surged during COVID. Urban patients, with better technology infrastructure, generally showed slightly higher peak adoption. But rural beneficiaries maintained telehealth at meaningful rates post-pandemic as well. For rural patients — who may live an hour or more from the nearest specialist — telehealth offers the most concrete access benefit. A psychiatry follow-up that would otherwise require a 90-minute round trip becomes a 30-minute video call.

The rural-urban gap in telehealth adoption has significant policy implications. CMS has debated whether to make the geographic waivers permanent; the utilization data suggests demand exists in both populations.

7. Who Uses Telehealth? The Age Paradox dataviz age demographics

The age breakdown reveals a counterintuitive pattern. Younger Medicare beneficiaries (ages 0–64, primarily those on Medicare due to disability) showed notably higher telehealth adoption than elderly beneficiaries aged 75+. The 85-and-over cohort — precisely the population most burdened by travel to medical appointments — shows the lowest adoption.

This is partly a technology access story. Older seniors are less likely to own smartphones or tablets, more likely to have limited broadband access, and more likely to rely on audio-only phone visits rather than video. CMS data shows that audio-only (telephone) visits were a significant fraction of telehealth in 2020–2021 before policy changes added additional restrictions for audio-only billing.

It's also partly a clinical story. The oldest beneficiaries have higher rates of conditions requiring physical examination — wound care, fall assessments, mobility evaluations — where in-person care genuinely cannot be substituted. The populations where telehealth adds the most value (mental health, chronic disease medication management, follow-up visits) skew younger within Medicare.

The gap narrowed over time as older patients and caregivers became more comfortable with the technology, but it persisted through 2024.

8. The Geography of Telehealth dataviz states geography

State-level telehealth adoption in 2024 shows meaningful geographic variation. States in the Northeast and some Mountain West states tend to show higher adoption. States in the Deep South and parts of the Midwest tend to show lower adoption.

The geographic pattern correlates with several factors: broadband penetration (higher broadband → higher telehealth capacity), state Medicaid telehealth policy (states with more expansive Medicaid coverage see higher dual-eligible adoption), and the mix of urban vs rural beneficiaries. States with large urban populations have more beneficiaries with the technology to use telehealth effectively, but also more readily available in-person care — so the net effect on utilization is ambiguous.

Notably, states with large rural populations don't uniformly show lower telehealth adoption. In some rural states, telehealth has become a primary mode of specialty access precisely because in-person alternatives are scarce or distant.

9. The Highest-Need Patients :dataviz:equity:dual-eligible:

Dual-eligible beneficiaries — those enrolled in both Medicare and Medicaid — use telehealth at substantially higher rates than Medicare-only beneficiaries. Dual eligibles are generally lower-income, more likely to have multiple chronic conditions, and more likely to face transportation barriers to in-person care.

The pattern is consistent across the full 2020–2024 period: dual eligibles adopted telehealth at higher rates during the COVID spike and maintained it at higher rates afterward. This suggests that for the lowest-income Medicare beneficiaries, telehealth isn't just a convenience — it's often the most accessible modality.

The equity implication runs in two directions. Telehealth reduces access barriers for low-income beneficiaries who lack transportation or can't take time off work for clinic visits. But audio-only visit restrictions and broadband requirements disproportionately burden the same population. Policy decisions about telehealth reimbursement and modality requirements have larger effects on dual eligibles than on the general Medicare population.

10. Data and Methods data cms methodology

All data comes from the CMS Medicare Telehealth Trends dataset (UUID 939226be-b107-476e-8777-f199a840138a), updated quarterly.

The dataset covers Medicare Fee-for-Service (FFS) beneficiaries only. Medicare Advantage (MA) beneficiaries are excluded — MA plans negotiate telehealth coverage separately and are not subject to the same FFS billing claims data. MA now covers roughly 50% of Medicare beneficiaries, meaning this data captures roughly half of the total Medicare population.

Key metric: Pct_Telehealth = Total_Bene_Telehealth / Total_Bene_TH_Elig. The denominator is beneficiaries who received any telehealth-eligible service during the period (either in-person or via telehealth), not total Medicare enrollment. This means the percentage reflects the telehealth share of eligible visits, not the share of all beneficiaries.

Telehealth definition: Services billed with telehealth-eligible HCPCS codes using the appropriate place-of-service code or modifier. Audio-only (telephone) visits are included in some periods and excluded in others based on CMS policy changes.

Data period: Q1 2020 through Q2 2025. Pre-2020 telehealth utilization was near zero due to geographic and facility restrictions; no comparable baseline data exists in this dataset.

Rural/Urban classification: CMS Rural-Urban Commuting Area (RUCA) codes, aggregated to Rural, Urban, and Unknown.

Your Neighborhood's Health Profile

Charlie Holland — Sun, 01 Mar 2026 19:18:00 GMT

1. About publicHealth cdc dataviz interactive

Figure 1: JPEG produced with DALL-E 4o

Public health statistics are usually reported at the national or state level, but they obscure enormous local variation. This post uses the CDC's PLACES program – 40+ health measures at ZIP code level across ~30,000 ZIPs – to show how health outcomes are hyperlocal, with two adjacent ZIP codes sometimes differing more than two states.

2. TLDR tldr

The CDC measures 40+ health indicators at ZIP code level — obesity, diabetes, depression, smoking, blood pressure, and more — for virtually every ZIP in the US. Enter your ZIP code below to see how your neighborhood compares to the national median on a radar chart. The headline finding: health outcomes are hyperlocal. Two adjacent ZIP codes can differ more than two states.

3. Introduction cdc places health zip interactive

Public health statistics are usually reported at the national or state level. "30% of American adults have high blood pressure." "The obesity rate is rising." These aggregates are real, but they obscure enormous local variation. The neighborhood where you grew up, where you work, and where you live now shapes your health in ways that national averages can't capture.

The CDC's PLACES program changes that. Every year, CDC combines the Behavioral Risk Factor Surveillance System (BRFSS) survey with small-area estimation models to produce 40+ health measures at the ZIP code level. The 2023 release covers 29,983 US ZIP Code Tabulation Areas (ZCTAs) — essentially complete coverage of the country's populated ZIP codes.

The measures span the full spectrum: chronic disease outcomes (diabetes, heart disease, stroke), health behaviors (smoking, physical inactivity, binge drinking), preventive care use (mammograms, dental visits, checkups), mental health (depression, poor mental health days), disability status, and health-related social needs (food insecurity, housing insecurity, lack of transportation).

This post lets you explore that landscape. The interactive section below pulls your ZIP code's data directly from the CDC API.

4. Explore Your ZIP Code interactive dataviz

Enter any US ZIP code to see its health profile compared to the national median across 12 key measures. Data comes directly from the CDC PLACES API in real time.

The radar shows absolute prevalence rates (percent of adults). A ZIP "inside" the orange national median line on a given measure has lower-than-typical rates for that condition — generally better for disease outcomes, though not always (lower physical inactivity is better; lower preventive care rates are not).

5. How Much Does ZIP Code Matter? dataviz variation

Before looking at your specific ZIP, it's worth understanding how much variation exists across US ZIP codes. For each of the 12 measures in the radar chart, this shows the spread from the 10th to 90th percentile across all ZIPs.

The variation is substantial. Obesity ranges from roughly 15% in the lowest-prevalence ZIPs to over 55% in the highest. Depression spans from around 10% to 37%. Even stroke — relatively rare — varies threefold.

These aren't just statistical artifacts. They reflect real differences in built environment (walkability, food access), socioeconomic stress, healthcare access, and local culture. The 10th-percentile ZIP for obesity is a fundamentally different place to live — in terms of food environment, activity infrastructure, and population health — than the 90th-percentile ZIP.

5.1. The correlation problem analysis

These conditions don't vary independently. ZIPs with high obesity tend to have high diabetes, high blood pressure, and high rates of physical inactivity. The conditions cluster together because they share upstream causes: poverty, food deserts, limited walkability, limited healthcare access.

This means a ZIP that looks "bad" on one measure often looks bad on several. And a ZIP that looks healthy on the radar chart across the board usually reflects accumulated advantages: higher incomes, better food environments, more walkable neighborhoods, better access to preventive care.

6. Obesity and Diabetes: The Strongest Correlation dataviz scatter

Of all the correlations in the dataset, obesity and diabetes are the tightest. This scatter plots every ZIP code on both axes.

The correlation coefficient is approximately 0.90 — among the strongest relationships in social epidemiology. Every point is a ZIP code. The spread around the regression line is real: ZIPs at the same obesity rate can have substantially different diabetes rates, reflecting differences in healthcare access (diagnosis rates), diet quality, and racial composition (some groups have higher diabetes risk at lower BMI).

The geographic color coding shows regional clustering. Southern ZIPs (red/orange) are concentrated in the upper-right — high obesity, high diabetes. Pacific and Northeast ZIPs (blue, green) tend toward the lower-left.

7. The Full Picture: All 40 Measures dataviz cdc measures

CDC PLACES covers far more than just the 12 measures in the radar chart. This chart shows the national average crude prevalence for all 40 measures, sorted by value and colored by category.

A few things stand out in the full picture:

High blood pressure (37.5% median) and obesity (36.7%) are the highest-prevalence chronic conditions — more than one in three adults.
Poor sleep (35.9%) is in the same tier, rarely discussed as a public health crisis despite its scale.
Preventive care gaps are significant: meaningful shares of adults haven't had a dental visit, mammogram, or colorectal cancer screening in the recommended timeframe.
Social determinants (the Health-Related Social Needs category) show that food insecurity, housing insecurity, and lack of transportation affect substantial fractions of ZIP code populations. These are not fringe conditions.

8. Data and Methods data cdc methodology

All data comes from the CDC PLACES 2024 release, using 2023 BRFSS-based estimates (a few measures use 2022 data):

Dataset: CDC PLACES ZCTA-level data — 40+ measures, ~29,983 ZIP Code Tabulation Areas, all US states
Measure type: "Crude prevalence" — percentage of adults estimated to have each condition or behavior, without age adjustment
Method: CDC uses multilevel regression and poststratification (MRP) to produce small-area estimates from BRFSS survey responses. The model combines local survey data with demographic predictors to generate stable estimates for small geographies like ZIP codes.

ZCTA vs ZIP code: Technically, CDC reports data at the ZCTA (ZIP Code Tabulation Area) level. ZCTAs are Census constructs that approximate ZIP codes but aren't identical. The ZIP code you enter is matched to the closest ZCTA; most populated ZIPs have direct ZCTA matches.

Interactive lookup: The radar chart fetches live data from the CDC SODA API. No data is stored; your ZIP code is sent directly to data.cdc.gov.

National medians: Computed from the 29,983 ZCTAs with available data for each measure. For the radar chart normalization, the values are: Obesity 36.7%, Diabetes 12.7%, Depression 23.0%, Smoking 15.0%, High BP 37.5%, Physical Inactivity 26.4%, Poor Mental Health 16.9%, Poor Physical Health 14.5%, Poor Sleep 35.9%, Binge Drinking 15.8%, Asthma 10.7%, Stroke 3.9%.

Feature Demo: Building a Blog with Emacs Org and SvelteKit

Charlie Holland — Sun, 01 Mar 2026 14:27:00 GMT

1. About

Figure 1: JPEG produced with DALL-E 4o

This page demonstrates the custom blogging framework used to build my technical diary: chiply.dev. This diary delivers a highly contextualized reading experience, with side-line components that enhance comprehension, navigation, and discovery of related content¹.

This page serves as a test-print of my blog's features, as a sandbox for new ideas, and as a current 'state of the art' reference for what is possible with my blog setup.

Given that this page functions as a test-print – you will see progress tracking on some headings. Any heading with a DONE tag is a complete feature demo. Any heading with a TODO tag is a work in progress².

This blog is built with Emacs Org Mode and Svelte/SvelteKit³. This page mostly demonstrates the features, but if you want to learn more about the technical design decisions that went into building this blog, read Design Decisions: Building a Modern Technical Blog.

Fellow bloggers and digital journalists will find this page useful as a reference for what is possible when building a blog with Org and SvelteKit, and all of the code used to build this site is accessible on the chiply.dev GitHub repository.

This video walkthrough will help:

2. Where did all this text come from? orgMode

The articles you will find on this blog are entirely written with Emacs org-mode⁴, and then converted to HTML using the included org -> HTML exporter (ox). Each article on this blog is generated from exactly 1 source .org file, although there is the ability to compose articles from multiple .org files using Transclusion.

3. What's going on in the sidelines? hud

The central window (the place you are reading this text right now), displays the full article content, and you will see a sort of heads-up-display (HUD) on the tops and sides of the screen. This HUD contains information about the article you are reading and the specific part of the article you are currently reading⁵.

Note that all HUD components render by default, but you can customize the layout by interacting with the buttons at the top right hand side of the screen. Any visually distracting or extraneous HUD component can be hidden and shown with a single click, and the browser will remember your settings. This allows readers to tailor the reading experience to their exact blisspoint between rich context and focused minimalism.

3.1. Why include HUD?

When you're reading a blog post, there's context (table of contents, footnotes, tags), explicit relationships (bibliography, social media links, post-to-post links, intra post-links), implicit relationships (related posts via tags, semantic content), and summarization (TLDR, minimap) that can better help you understand and navigate the content.

Most blogs ignore these important aspects of comprehension when delivering a firehose of information, and instead just dump a wall of text on the reader with no context or navigation aids.

We live in an age of information overload, and the rising effectiveness of knowledge graphs and LLMs have revealed to us that information is highly interconnected, and that these connections provide the key to distilling useful knowledge from a deluge of raw data. Using these tools daily, I am acutely aware of all the explicit and implicit connections that exist between pieces of information I scour on the internet, and a set of blog posts is no exception.

Posts within any blog are highly interconnected, and this interconnectedness is what allows us to build a rich understanding of the topics being discussed. To borrow terminology from graph theory, I like to think that the nodes (posts) provide self contained, narrative-style information on a cohesive topic, while the edges (connections between posts) allow for the construction of higher level understanding by linking related concepts together, both implicitly and explicitly.

What's more, information in my blog is highly connected to information outside of my blog (other blogs, social media, research papers, etc), and these connections are equally important to understanding the content.

To again borrow from the graph theory lexicon, I like to think of my blog as an ever-growing knowledge graph, which is embedded in the larger knowledge graph of the internet via explicit connections. As such, this blog can be used a discovery engine for finding related content, both within my blog and outside of it.

All side-line components reference a locaion inside of the article, and they autoupdate to reflect the current location in the article as you scroll through it (you will see this in action as you scroll through the page).

3.1.1. Components

Starting at the table of contents (on he left) and going anti-clockwise around the screen, here are the HUD components and their purpose:

3.1.1.1. Progrss bar

At the very top of the screen, you will see a progress bar. This bar fill from right to left displaying how far you have scrolled through the article you are reading. This is useful for gauging how much of the article you have read, and how much is left to read.

3.1.1.2. Breadcrumbs

At the very top left of the screen, you will see a breadcrumb trail. This trail shows you the path you took to get to the current article you are reading, and also the position within the outline tree. This is useful for navigating back to previous articles you have read, and for understanding the context of the current article within the larger structure of the blog, and of the current outline node within the larger outline tree.

3.1.1.3. Treemap

Below the breadcrumb you will see a treemap representing the hierarchical structure of the document and the relative size of each section. This gives a nice sense of where you are in the document, and the relative size of each section.

3.1.1.4. Table of Contents

On the upper left side of the screen, you will see a table of contents. You can click on any section in the table of contents to jump to that section in the article.

3.1.1.5. History

This component is hidden by default, but this shows a navigation history within posts. This not only helps to visualize the history you are familiar with when navigating backwards and forwards in your browser, but also provides fine grain control for when your history forks, that is, if you navigate around, go back, and then navigate again – you're history is no longer linear, it's hierarchical, or 'tree like'. The history component helps you visualize this non-linear history and navigate through it.

3.1.1.6. References

At the bottom of the screen, you will see a bibliography. This is a list of both internal and external references used in the article, and is meant to give credit to the original sources of information, and to organize all external references in one place to serve as a kind of further reading list. The bibliography supports discoverability of related content, both within my blog and outside of it.

3.1.1.8. Word Cloud

The word cloud visualizes the relative frequency of keywords as they appear in the document. This gives a very high level perspective of what's discussed in the article, and how much each keyword is discussed.

3.1.1.9. TLDR (too long didn't read)

None taken lol 😁😂😅😭… I'm super verbose, and even if I wasn't, some topics are complex enough to warrant more words than anyone would be willing to read. Complex articles like this are kind of like reference materials for most folks. As a means of summarization, and as a means of helping readers navigate to the most relevant parts of the article, a TLDR component is included.

On the lower right side of the screen, you will see a TLDR (too long; didn't read) summary. This is a short summary of the article, and is meant to give you a quick overview of the article's content. You can click links in the TLDR to jump to content being referenced in the summary.

3.1.1.10. Glossary

On the right side of the screen, between the TLDR and Word Cloud, you will see a glossary panel. This component extracts term definitions from a dedicated glossary section in the article's org source, and displays them as a scrollable reference list in the sidebar. As you scroll through the article, any glossary term that appears in the body text is highlighted with a dotted underline, and the corresponding sidebar entry lights up to show which terms are currently in view. This gives readers instant access to definitions without leaving the flow of the article, and provides a useful orientation aid for posts that introduce domain-specific vocabulary.

3.1.1.11. Back Links and Forward Links

Back-linking and forward-linking are terms borrowed form the knowledge management space (think org-roam, logseq, Obsidian, etc…). These links can help users follow connections to posts that are referenced and cited by the current post, and provides this in a similar idiom to what users expect with modern knowledge management tools.

3.1.1.12. Tags

On the upper right side of the screen, you will see tags which are applied at the header level. Article's sharing tags are implicitly related. You can click on any tag to see other articles with that tag (not yet implemented).

3.1.1.13. Minimap

On the far right side of the screen, you will see a minimap of the article you are reading. This is a small version of the article, and is meant to give you a quick overview of the article's structure. You can click on any section in the minimap to jump to that section in the article. This is useful for quickly gauging the size of he document, getting a birds-eye of the document structure, and for quickly navigating to different sections of the article.

I particularly like the minimap for when I can recall the visual piece of content I want to look at (eg - where was that pie chart again). I can find this extremely quickly in the minimap, and then click to jump to that section.

The minimap also provides a better sense of locale within the article, as you can see the content far above and far below your current location in the article.

3.1.1.14. Full text search

At the top right of the screen, you will see a search bar. You can use this search bar to search for any text in the article you are reading. This is useful for quickly finding specific information in the article, both by keyword and by phrase. This allows users to search for content related to a literal match or a semantic match with their input query.

4. Features

NOTE the post up until this point has followed narrative structure.

The rest of this article describes and demonstrates the features of this technical diary. These are in no particular order – the rest of this document is long (20k+ words), and reads more like reference material than prose (thank goodness we have all the HUD in the sidelines to help us navigate this wall of text 😉).

5. Fancy text (sub- and superscripts)

5.1. latex math

To demonstrate, I'll enumerate some famous equations using LaTeX math syntax. These equations span various fields of mathematics and physics, from basic geometry to complex analysis, number theory, fluid dynamics, and general relativity.

Pythagorean Theorem

\[ a^2 + b^2 = c^2 \]

Quadratic Formula

\[ x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} \]

Euler's Identity

\[ e^{i\pi} + 1 = 0 \]

Gaussian Integral

\[ \int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} \]

Taylor Series for e^x

\[ e^x = \sum_{n=0}^{\infty} \frac{x^n}{n!} = 1 + x + \frac{x^2}{2!} + \frac{x^3}{3!} + \cdots \]

Cauchy-Riemann Equations

\[ \frac{\partial u}{\partial x} = \frac{\partial v}{\partial y} \quad \text{and} \quad \frac{\partial u}{\partial y} = -\frac{\partial v}{\partial x} \]

Fourier Transform

\[ \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} dx \]

Riemann Zeta Function

\[ \zeta(s) = \sum_{n=1}^{\infty} \frac{1}{n^s} = \prod_{p \text{ prime}} \frac{1}{1 - p^{-s}} \quad \text{for } \Re(s) > 1 \]

Navier-Stokes Equation (incompressible flow)

\[ \rho \left( \frac{\partial \mathbf{v}}{\partial t} + (\mathbf{v} \cdot \nabla) \mathbf{v} \right) = -\nabla p + \mu \nabla^2 \mathbf{v} + \mathbf{f} \]

Einstein Field Equations (General Relativity)

\[ R_{\mu\nu} - \frac{1}{2}g_{\mu\nu}R + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4}T_{\mu\nu} \]

5.2. TODO subscript and superscript

This is an example of subscript: H₂O, A_i,j. NOTE this isn't rendering properly due to a bug I need to fix in the org to html exporter.

6. Displaying GIFs

Here we demonstrate how GIFs can be displayed. These are useful for demonstrating usage of UI features, and also for entertainment value. Emacs has nice packages (like gif-screencast) that allow you to create GIF demonstrations of how to use your package, so I plan to use this feature for that. Also, GIFs can be used to spice up otherwise static content.

6.1. Local file

6.2. Remote file

These all come from graph GIPHY:

Note I am using a #+begin_export html in the org-document, as it let's me arrange images into arbitrary layouts using custom CSS. In this case, I'm using flexbox to create a grid of GIFs.

6.3. Interactive GIF

6.4. Video Demo

7. Interactive Data Visualizations

HTML charts are great for technical blogging. Personaly, I'm inspired by examples of digital journalism from the New York Times that use interactive charts to tell stories with data. The NYT builds these with D3.js, but plotly is a great alternative for people who don't want to code everything from scratch, and plotly is also built on top of D3.js. Plotly covers almost all chart types, and has great integration with python, R, and javascript, all concise languages which are excellent for demonsrtating the logic behind the data visualization in question. In fact, plotly beats D3 for this in my opinion, you wouldn't include D3 code in the blog as it is too verbose, whereas the plotly python APIs are concise (especially px).

Plotly is therefore my choice for adding interactive charts to my technical blog.

Here I demonstrate adding a plotly chart using org-babel and python. The code block below generates a plotly bar chart and saves it as an html file. The html file is then included in the blog using an iframe. Note there are probably better ways to do this, both from a viz generation and rendering perspective, but this is a good start, and unlocks ploty's full universe of chart types for my blog.

7.1. Bar chart

I'm leveraging utility functions that are defined in a custom python package – you'll see the import here

7.2. Dist Plot

7.3. Animattions

7.4. 3D charts

Note that I have not exported the plotly code here as there is a lot of it for the 9 3D charts below.

7.4.1. Output

7.5. TODO Arrangement

This doesn't show up in the webpage, but I can include html inline using #+begin_export html and #+end_export blocks in the org mode document. This is useful for insterting iframes (think previews of other websites, plotly charts, full webapps, etc…). html, js, and css can be included, here I'm using CSS grid too display iframes side my side.

8. Software Architecture Diagrams

Sometimes structure that needs to be described cannot be adequately represented using just text, tables, and lists. Diagrams are a great way to represent complex structures visually.

org-mermaid is a great extension to org-babel, that allows you to create mermaid diagrams-as-code within org-mode documents. ox then takes care of exporing the code, the output, or both.

The DAG is indespensible in most contexts, but espeically so in technical blogging. Being able to quickly and easily create diagrams to illustrate concepts is very useful, and the fact that I can maintain them with code is a dream.

Of course, you could use anything that outputs a chart (like diagrams), but mermaid is basically ubiquitous, so I try to use that as much as I can.

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

8.1. Diagram 1: Simple Microservices Architecture

graph TD;
    Client[Client Application]-->Gateway[API Gateway];
    Gateway-->AuthService[Auth Service];
    Gateway-->UserService[User Service];
    Gateway-->ProductService[Product Service];
    UserService-->UserDB[(User Database)];
    ProductService-->ProductDB[(Product Database)];
    AuthService-->Cache[(Redis Cache)];

8.2. Diagram 2: Event-Driven Architecture

graph TD;
    WebApp[Web Application]-->LoadBalancer[Load Balancer];
    MobileApp[Mobile Application]-->LoadBalancer;
    LoadBalancer-->APIGateway[API Gateway];
    APIGateway-->OrderService[Order Service];
    APIGateway-->PaymentService[Payment Service];
    APIGateway-->NotificationService[Notification Service];
    OrderService-->EventBus[Message Queue/Event Bus];
    PaymentService-->EventBus;
    NotificationService-->EventBus;
    EventBus-->InventoryService[Inventory Service];
    EventBus-->ShippingService[Shipping Service];
    EventBus-->AnalyticsService[Analytics Service];
    OrderService-->OrderDB[(Order DB)];
    PaymentService-->PaymentDB[(Payment DB)];
    InventoryService-->InventoryDB[(Inventory DB)];
    ShippingService-->ShippingDB[(Shipping DB)];
    AnalyticsService-->DataWarehouse[(Data Warehouse)];

8.3. Diagram 3: Cloud-Native Architecture with Kubernetes

graph TD;
    Users[Users]-->CDN[CDN];
    CDN-->Ingress[Ingress Controller];
    Ingress-->ServiceMesh[Service Mesh/Istio];
    ServiceMesh-->AuthPod[Auth Pod];
    ServiceMesh-->UserPod[User Service Pod];
    ServiceMesh-->OrderPod[Order Service Pod];
    ServiceMesh-->PaymentPod[Payment Service Pod];
    AuthPod-->ConfigMap[ConfigMap];
    AuthPod-->Secret[Secrets];
    UserPod-->UserStateful[User StatefulSet];
    OrderPod-->OrderStateful[Order StatefulSet];
    PaymentPod-->PaymentStateful[Payment StatefulSet];
    UserStateful-->PVC1[Persistent Volume];
    OrderStateful-->PVC2[Persistent Volume];
    PaymentStateful-->PVC3[Persistent Volume];
    ServiceMesh-->MessageQueue[RabbitMQ Cluster];
    MessageQueue-->WorkerPod1[Worker Pod 1];
    MessageQueue-->WorkerPod2[Worker Pod 2];
    MessageQueue-->WorkerPod3[Worker Pod 3];
    WorkerPod1-->ElasticSearch[ElasticSearch Cluster];
    WorkerPod2-->ElasticSearch;
    WorkerPod3-->ElasticSearch;
    ServiceMesh-->CacheCluster[Redis Cluster];
    ServiceMesh-->MonitoringStack[Prometheus + Grafana];
    MonitoringStack-->AlertManager[Alert Manager];

8.4. Diagram 4: Global Multi-Region Architecture

graph LR;
    GlobalUsers[Global Users]-->GlobalDNS[Global DNS/Route53];
    GlobalDNS-->USRegion[US-East Region];
    GlobalDNS-->EURegion[EU-West Region];
    GlobalDNS-->APRegion[Asia-Pacific Region];

    USRegion-->USCDN[US CDN/CloudFront];
    USCDN-->USALB[US Application Load Balancer];
    USALB-->USK8S[US Kubernetes Cluster];
    USK8S-->USServices[US Microservices];
    USServices-->USRDS[US RDS Multi-AZ];
    USServices-->USDynamo[US DynamoDB Global Table];
    USServices-->USKafka[US Kafka Cluster];

    EURegion-->EUCDN[EU CDN/CloudFront];
    EUCDN-->EUALB[EU Application Load Balancer];
    EUALB-->EUK8S[EU Kubernetes Cluster];
    EUK8S-->EUServices[EU Microservices];
    EUServices-->EURDS[EU RDS Multi-AZ];
    EUServices-->EUDynamo[EU DynamoDB Global Table];
    EUServices-->EUKafka[EU Kafka Cluster];

    APRegion-->APCDN[AP CDN/CloudFront];
    APCDN-->APALB[AP Application Load Balancer];
    APALB-->APK8S[AP Kubernetes Cluster];
    APK8S-->APServices[AP Microservices];
    APServices-->APRDS[AP RDS Multi-AZ];
    APServices-->APDynamo[AP DynamoDB Global Table];
    APServices-->APKafka[AP Kafka Cluster];

    USDynamo<-->EUDynamo;
    EUDynamo<-->APDynamo;
    USDynamo<-->APDynamo;

    USKafka-->GlobalStream[Global Kinesis Data Stream];
    EUKafka-->GlobalStream;
    APKafka-->GlobalStream;

    GlobalStream-->DataLake[S3 Data Lake];
    DataLake-->MLPipeline[SageMaker ML Pipeline];
    DataLake-->BatchProcessing[EMR Batch Processing];
    DataLake-->RealtimeAnalytics[Kinesis Analytics];

    USK8S-->Monitoring[Global Monitoring Stack];
    EUK8S-->Monitoring;
    APK8S-->Monitoring;
    Monitoring-->Datadog[Datadog/NewRelic];
    Monitoring-->PagerDuty[PagerDuty Alerts];

    USServices-->GlobalAuth[Global Auth0/Okta];
    EUServices-->GlobalAuth;
    APServices-->GlobalAuth;

9. Code literateProgramming

Rendering and executing code is a critical feature for technical blogging.

Because of org-mode's babel system, code blocks can be included in the document. These can be executed either as you write, or when the document is exported, and the results can be included in the output.

This process of writing code, output, and narrative text together is called literate programming, and is a powerful way to communicate technical concepts.

My main languages are bash, elisp, python, R, SQL, and javascript/TypeScript. Having a way to include code snippets that can be executed and have the results included in the document is very useful for technical blogging.

org-babel is very powerful and flexible, and you can think of it like a language-agnostic form of Jupyter Notebooks.

Here are a couple of useful examples.

9.1. bash

Here's an interesting bash script that implements the Sieve of Eratosthenes algorithm to find prime numbers and visualizes them with ASCII art⁶:

#!/bin/bash

# Sieve of Eratosthenes with Simple Text Visualization
# Finds all prime numbers up to a given limit and creates a visual representation

LIMIT=100
echo "=== Sieve of Eratosthenes: Finding Primes up to $LIMIT ==="
echo

# Initialize array - 1 means potential prime, 0 means composite
declare -a sieve
for ((i=0; i<=LIMIT; i++)); do
    sieve[i]=1
done

# 0 and 1 are not prime
sieve[0]=0
sieve[1]=0

# Implement sieve algorithm
for ((p=2; p*p<=LIMIT; p++)); do
    if [[ ${sieve[p]} -eq 1 ]]; then
        # Mark all multiples of p as composite
        for ((i=p*p; i<=LIMIT; i+=p)); do
            sieve[i]=0
        done
    fi
done

# Collect primes and create visualization
primes=()
echo "Prime Visualization (P = prime, . = composite):"
echo "+---------------------+"

# Create visual grid (10 numbers per row, starting from 2)
for ((row=0; row<10; row++)); do
    printf "| "
    for ((col=0; col<10; col++)); do
        num=$((row * 10 + col + 2))
        if [[ $num -le $LIMIT ]]; then
            if [[ ${sieve[num]} -eq 1 ]]; then
                primes+=($num)
                printf "P "
            else
                printf ". "
            fi
        else
            printf "  "
        fi
    done
    printf "|\n"
done

echo "+---------------------+"
echo

# Create a numbered reference grid with proper spacing
echo "Number Reference Grid:"
echo "+-------------------------------+"
for ((row=0; row<10; row++)); do
    printf "| "
    for ((col=0; col<10; col++)); do
        num=$((row * 10 + col + 2))
        if [[ $num -le $LIMIT ]]; then
            printf "%2d " $num
        else
            printf "   "
        fi
    done
    printf "|\n"
done
echo "+-------------------------------+"
echo

# Statistics
echo "PRIME STATISTICS:"
echo "  Total numbers checked: $LIMIT"
echo "  Primes found: ${#primes[@]}"
density=$(echo "scale=1; ${#primes[@]}*100/$LIMIT" | bc -l 2>/dev/null || echo "25.0")
echo "  Density: ${density}%"
echo

# Show all primes in groups of 10
echo "All Primes Found:"
printf "  "
for ((i=0; i<${#primes[@]}; i++)); do
    printf "%3d " ${primes[i]}
    if [[ $(((i+1) % 10)) -eq 0 ]]; then
        printf "\n  "
    fi
done
echo
echo

# Find twin primes (primes that differ by 2)
echo "Twin Prime Pairs (p, p+2):"
printf "  "
count=0
for ((i=0; i<${#primes[@]}-1; i++)); do
    current=${primes[i]}
    next=${primes[i+1]}
    if [[ $((next - current)) -eq 2 ]]; then
        printf "(%d,%d) " $current $next
        ((count++))
        if [[ $((count % 4)) -eq 0 ]]; then
            printf "\n  "
        fi
    fi
done
echo
echo "  Found $count twin prime pairs"
echo

# Prime gaps analysis
echo "Prime Gap Analysis:"
max_gap=0
gap_start=0
gap_end=0
echo "  Gaps larger than 4:"
printf "  "
gap_count=0
for ((i=0; i<${#primes[@]}-1; i++)); do
    gap=$((${primes[i+1]} - ${primes[i]}))
    if [[ $gap -gt $max_gap ]]; then
        max_gap=$gap
        gap_start=${primes[i]}
        gap_end=${primes[i+1]}
    fi
    if [[ $gap -gt 4 ]]; then
        printf "%d->%d(gap:%d) " ${primes[i]} ${primes[i+1]} $gap
        ((gap_count++))
        if [[ $((gap_count % 3)) -eq 0 ]]; then
            printf "\n  "
        fi
    fi
done
echo
echo "  Largest gap: $max_gap (between $gap_start and $gap_end)"

echo
echo "Algorithm completed successfully!"
echo "Time complexity: O(n log log n)"
echo "Space complexity: O(n)"

=== Sieve of Eratosthenes: Finding Primes up to 100 ===

Prime Visualization (P = prime, . = composite):
+---------------------+
| P P . P . P . . . P |
| . P . . . P . P . . |
| . P . . . . . P . P |
| . . . . . P . . . P |
| . P . . . P . . . . |
| . P . . . . . P . P |
| . . . . . P . . . P |
| . P . . . . . P . . |
| . P . . . . . P . . |
| . . . . . P . . .   |
+---------------------+

Number Reference Grid:
+-------------------------------+
|  2  3  4  5  6  7  8  9 10 11 |
| 12 13 14 15 16 17 18 19 20 21 |
| 22 23 24 25 26 27 28 29 30 31 |
| 32 33 34 35 36 37 38 39 40 41 |
| 42 43 44 45 46 47 48 49 50 51 |
| 52 53 54 55 56 57 58 59 60 61 |
| 62 63 64 65 66 67 68 69 70 71 |
| 72 73 74 75 76 77 78 79 80 81 |
| 82 83 84 85 86 87 88 89 90 91 |
| 92 93 94 95 96 97 98 99 100   |
+-------------------------------+

PRIME STATISTICS:
  Total numbers checked: 100
  Primes found: 25
  Density: 25.0%

All Primes Found:
    2   3   5   7  11  13  17  19  23  29 
   31  37  41  43  47  53  59  61  67  71 
   73  79  83  89  97 

Twin Prime Pairs (p, p+2):
  (3,5) (5,7) (11,13) (17,19) 
  (29,31) (41,43) (59,61) (71,73) 

  Found 8 twin prime pairs

Prime Gap Analysis:
  Gaps larger than 4:
  23->29(gap:6) 31->37(gap:6) 47->53(gap:6) 
  53->59(gap:6) 61->67(gap:6) 73->79(gap:6) 
  83->89(gap:6) 89->97(gap:8) 
  Largest gap: 8 (between 89 and 97)

Algorithm completed successfully!
Time complexity: O(n log log n)
Space complexity: O(n)

9.2. python

9.2.1. TODO (add language) using venv virtualEnvironments

Venvs are set in the .dir-locals.el file for this project. This allows different code blocks to use different virtual environments.

9.2.2. Code example

This is how you write code with python⁷

from dataclasses import dataclass

from polyfactory.factories import DataclassFactory


@dataclass
class Person:
    name: str
    age: float
    height: float
    weight: float


class PersonFactory(DataclassFactory[Person]):
    ...


person_instance = PersonFactory.build()
print(person_instance)

Person(name='JmjUtskpYrdRYTTbRirA', age=1728311337.84688, height=52.7746341086379, weight=-618160.650763342)

9.2.3. TODO using multiple venvs via session

Use case is actually comomon – demonosrating he difference between two versions of a library, demonstrating a dependency issue.

10. Transclusion transclusion

The subheading Demo heading is actually 'transcluded' text from another post on this blog. In other words, this is a verbatim section, from another article on this blog, that I have embedded visually here (you can verify this by going to that aricle and reading this same text here).

This is made possible by org-mode's built in file inclusion feature.

See the transclusion below - again, this heading is pulled straight out of

10.1. Demo heading

This is a demo post – This content is written in post1.org but is actually intended to be transcluded from another file (post0.org). That's why you utlimately see this content here.

10.2. TODO transclusion styling

Transcluded sections are styled differently to signal to the user that a verbatim section from a separate article is being referenced.

11. Tags tag0 tag1

Tags can be added to headings using org-mode's tag syntax. You can see 'tag1' and 'tag2' applied above.

11.1. Why use tags?

Most blogs organize their content hierarchically using categories and subcategories in something like an index page. But this rigid tree data structure doesn't reflect the natural organizational structure of content that may fit into multiple categories. Tags allow for this kind of non-hierarchical organization.

11.2. TODO inline tags

Inline tags are also useful. This is not yet implemented as org-mode does not support inline tags natively.

12. Links

My blog's Raison d'être is to allow me to share knowledge with others. Links are a critical part of this, as they allow me to reference other content, both within my own blog and externally.

As such, my blog is aware of the different 'types' of links and visually distinguishes between them (nyi).

12.1. Link types

Note this list is incomprehensive, and defined by me, but it works for my purposes.

12.1.1. Intra-post links

It is possible and useful to link to different sections within a single post. This is done using standard org-mode link syntax.

Example: Why use tags?.

12.1.2. Inter-post links

I can link to other sections in the document.

Example: Post 1

12.1.3. External links

Note that external links appear in the bibliography section in the deskop version of the blog.

12.1.4. Pseudo links

Some things are clickable and open gates to other content, like the [[*** Tags][tags]] HUD component, the [[*** *Full text search*]], and the [[*** *Post navigation*]]. These are not really links, but they behave like links, so I style them as such.

Not everything clickable is style like a link – buttons, for example, are not styled like links. Headings, which are clickable to collapse/expand sections, are also not styled like links. The heuristic is that anything that could take you to anothe piece of conetnt gets styled like a link.

12.2. Link styling

Internal links should be rendered differetly than external links as so the user knows ahead of time if a reference is within the blog or outside.

Anchor links are rendererd with dotted underlines, links to posts within this blog are rendered with solid underlines, and external links are as typical links with solid underlines.

12.3. TODO Link previews

It is useful to see a preview of a link before clicking on it – maybe you're just curious what the page looks like, or more practically, maybe you want to quickly gleen the information from a popup withouot navigating away from the current page, disrupting your reading flow. Wikipedia's navigation popups are a great example of this feature in action, and google has something similar you can enable in chrome.

While useful, these only let you preview 1 degree out from you current address. What would be even more useful is a way to preview links recursively, so you could see the content of links within links, and so on. This would allow you to quickly navigate through a web of content without ever leaving the current page.

This is implemented here for all links – simply hover over any link to see a preview of the content.

13. Structured text (tables, lists, sub and superscripts)

13.1. tables

Country	Population (millions)	Continent
China	1420	Asia
India	1400	Asia
USA	332	North America
Brazil	215	South America
Nigeria	216	Africa

Month	Sales ($)	Growth (%)
Jan	12,000	5.0
Feb	14,050	17.1
Mar	13,500	-3.9
Apr	15,200	12.6

Feature	Svelte 5 Support	Notes
Reactivity	Yes	Automatic & simple
TypeScript Support	Yes	Built-in, first-class
Transitions	Yes	Easy to use animations
Stores	Yes	Simple shared state
Actions	Yes	Custom DOM behaviors

This one is a really big table and demonstrates the scrolling behavior for wide tables.

sepal_length	sepal_width	petal_length	petal_width	species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa
4.6	3.4	1.4	0.3	setosa
5.0	3.4	1.5	0.2	setosa
4.4	2.9	1.4	0.2	setosa
4.9	3.1	1.5	0.1	setosa
5.4	3.7	1.5	0.2	setosa
4.8	3.4	1.6	0.2	setosa
4.8	3.0	1.4	0.1	setosa
4.3	3.0	1.1	0.1	setosa
5.8	4.0	1.2	0.2	setosa
5.7	4.4	1.5	0.4	setosa
5.4	3.9	1.3	0.4	setosa
5.1	3.5	1.4	0.3	setosa
5.7	3.8	1.7	0.3	setosa
5.1	3.8	1.5	0.3	setosa
5.4	3.4	1.7	0.2	setosa
5.1	3.7	1.5	0.4	setosa
4.6	3.6	1.0	0.2	setosa
5.1	3.3	1.7	0.5	setosa
4.8	3.4	1.9	0.2	setosa
5.0	3.0	1.6	0.2	setosa
5.0	3.4	1.6	0.4	setosa
5.2	3.5	1.5	0.2	setosa
5.2	3.4	1.4	0.2	setosa
4.7	3.2	1.6	0.2	setosa
4.8	3.1	1.6	0.2	setosa
5.4	3.4	1.5	0.4	setosa
5.2	4.1	1.5	0.1	setosa
5.5	4.2	1.4	0.2	setosa
4.9	3.1	1.5	0.1	setosa
5.0	3.2	1.2	0.2	setosa
5.5	3.5	1.3	0.2	setosa
4.9	3.1	1.5	0.1	setosa
4.4	3.0	1.3	0.2	setosa
5.1	3.4	1.5	0.2	setosa
5.0	3.5	1.3	0.3	setosa
4.5	2.3	1.3	0.3	setosa
4.4	3.2	1.3	0.2	setosa
5.0	3.5	1.6	0.6	setosa
5.1	3.8	1.9	0.4	setosa
4.8	3.0	1.4	0.3	setosa
5.1	3.8	1.6	0.2	setosa
4.6	3.2	1.4	0.2	setosa
5.3	3.7	1.5	0.2	setosa
5.0	3.3	1.4	0.2	setosa
7.0	3.2	4.7	1.4	versicolor
6.4	3.2	4.5	1.5	versicolor
6.9	3.1	4.9	1.5	versicolor
5.5	2.3	4.0	1.3	versicolor
6.5	2.8	4.6	1.5	versicolor
5.7	2.8	4.5	1.3	versicolor
6.3	3.3	4.7	1.6	versicolor
4.9	2.4	3.3	1.0	versicolor
6.6	2.9	4.6	1.3	versicolor
5.2	2.7	3.9	1.4	versicolor
5.0	2.0	3.5	1.0	versicolor
5.9	3.0	4.2	1.5	versicolor
6.0	2.2	4.0	1.0	versicolor
6.1	2.9	4.7	1.4	versicolor
5.6	2.9	3.6	1.3	versicolor
6.7	3.1	4.4	1.4	versicolor
5.6	3.0	4.5	1.5	versicolor
5.8	2.7	4.1	1.0	versicolor
6.2	2.2	4.5	1.5	versicolor
5.6	2.5	3.9	1.1	versicolor
5.9	3.2	4.8	1.8	versicolor
6.1	2.8	4.0	1.3	versicolor
6.3	2.5	4.9	1.5	versicolor
6.1	2.8	4.7	1.2	versicolor
6.4	2.9	4.3	1.3	versicolor
6.6	3.0	4.4	1.4	versicolor
6.8	2.8	4.8	1.4	versicolor
6.7	3.0	5.0	1.7	versicolor
6.0	2.9	4.5	1.5	versicolor
5.7	2.6	3.5	1.0	versicolor
5.5	2.4	3.8	1.1	versicolor
5.5	2.4	3.7	1.0	versicolor
5.8	2.7	3.9	1.2	versicolor
6.0	2.7	5.1	1.6	versicolor
5.4	3.0	4.5	1.5	versicolor
6.0	3.4	4.5	1.6	versicolor
6.7	3.1	4.7	1.5	versicolor
6.3	2.3	4.4	1.3	versicolor
5.6	3.0	4.1	1.3	versicolor
5.5	2.5	4.0	1.3	versicolor
5.5	2.6	4.4	1.2	versicolor
6.1	3.0	4.6	1.4	versicolor
5.8	2.6	4.0	1.2	versicolor
5.0	2.3	3.3	1.0	versicolor
5.6	2.7	4.2	1.3	versicolor
5.7	3.0	4.2	1.2	versicolor
5.7	2.9	4.2	1.3	versicolor
6.2	2.9	4.3	1.3	versicolor
5.1	2.5	3.0	1.1	versicolor
5.7	2.8	4.1	1.3	versicolor
6.3	3.3	6.0	2.5	virginica
5.8	2.7	5.1	1.9	virginica
7.1	3.0	5.9	2.1	virginica
6.3	2.9	5.6	1.8	virginica
6.5	3.0	5.8	2.2	virginica
7.6	3.0	6.6	2.1	virginica
4.9	2.5	4.5	1.7	virginica
7.3	2.9	6.3	1.8	virginica
6.7	2.5	5.8	1.8	virginica
7.2	3.6	6.1	2.5	virginica
6.5	3.2	5.1	2.0	virginica
6.4	2.7	5.3	1.9	virginica
6.8	3.0	5.5	2.1	virginica
5.7	2.5	5.0	2.0	virginica
5.8	2.8	5.1	2.4	virginica
6.4	3.2	5.3	2.3	virginica
6.5	3.0	5.5	1.8	virginica
7.7	3.8	6.7	2.2	virginica
7.7	2.6	6.9	2.3	virginica
6.0	2.2	5.0	1.5	virginica
6.9	3.2	5.7	2.3	virginica
5.6	2.8	4.9	2.0	virginica
7.7	2.8	6.7	2.0	virginica
6.3	2.7	4.9	1.8	virginica
6.7	3.3	5.7	2.1	virginica
7.2	3.2	6.0	1.8	virginica
6.2	2.8	4.8	1.8	virginica
6.1	3.0	4.9	1.8	virginica
6.4	2.8	5.6	2.1	virginica
7.2	3.0	5.8	1.6	virginica
7.4	2.8	6.1	1.9	virginica
7.9	3.8	6.4	2.0	virginica
6.4	2.8	5.6	2.2	virginica
6.3	2.8	5.1	1.5	virginica
6.1	2.6	5.6	1.4	virginica
7.7	3.0	6.1	2.3	virginica
6.3	3.4	5.6	2.4	virginica
6.4	3.1	5.5	1.8	virginica
6.0	3.0	4.8	1.8	virginica
6.9	3.1	5.4	2.1	virginica
6.7	3.1	5.6	2.4	virginica
6.9	3.1	5.1	2.3	virginica
5.8	2.7	5.1	1.9	virginica
6.8	3.2	5.9	2.3	virginica
6.7	3.3	5.7	2.5	virginica
6.7	3.0	5.2	2.3	virginica
6.3	2.5	5.0	1.9	virginica
6.5	3.0	5.2	2.0	virginica
6.2	3.4	5.4	2.3	virginica
5.9	3.0	5.1	1.8	virginica

Wide table:

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7	Column 8	Column 9	Column 10	Column 11	Column 12	Column 13	Column 14	Column 15
1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
16	17	18	19	20	21	22	23	24	25	26	27	28	29	30
31	32	33	34	35	36

13.1.1. TODO implement horizontal scrolling for when tables are too wide

13.2. lists

13.2.1. bullets

one
two
- two point one
- two point two
three
- three point one
- three point two

13.2.2. numbers

first
second
1. hello worrld
2. second point two

13.2.3. formatting

some bold text
some italic text
some underline text
some ~~strike~~ text
some code text
some verbatim text
some *bold in code* text
some /italic in verbatim/ text
some _underline in verbatim_ text
some =~code in verbatim=~ text
some +strike in verbatim+ text
some bold italic underline ~~strike~~ code verbatim text

13.2.3.1. TODO fix underline style

14. Narrative features

Org of course has many features for structuring content.

This entire document is written in org-mode outline format, with headings and subheadings. These levels of the hierarchy are rendered as different sized headings in the html output.

14.1. Text

14.1.1. Long paragraph

This is a long paragraph – note that it contains a footnote. This is a good test of the styling for footnotes – they should jump out, even when buried in text (not yet implemented). Here's some good old lorem ipsum:

lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim⁸ id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

14.1.2. Quote

org has features for verse, blockquote, and centering text. The html exporter I use doesn't style these, so I add rules to css to make them look different. Note that you can include links in quotes, which is nice for direct attribution.

14.1.2.1. Pull quotes

This is some quote in a #+begin_quote block. It is given attributes that are used by the blog site in order to create quotes that standout similar to how quotes standout in magazines. This is useful for especially impactful statements that I want to grab the user's attention.

The Web as I envisaged it, we have not seen it yet. The future is still so much bigger than the past ---Tim Berners-Lee

Pull quotes work by floating the blockquote to the left or right, allowing the surrounding paragraph text to wrap around the callout. Use #+ATTR_HTML: :class pull-quote pull-right before a #+begin_quote block to float it right, or pull-left (or omit the direction) to float left. The quote renders in large italic text with a decorative opening quotation mark. On mobile devices the float is disabled and the quote stacks normally at full width. This paragraph demonstrates how body text flows around the floated element — the wrapping effect creates the magazine-style layout that makes important statements visually prominent while keeping the reading flow natural.

14.1.2.2. Other

Here's one of my favourite quotes – I think about this all the time. This is text in a #+BEGIN_VERSE block. It gets compiles as p.verse:

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away

---Antoine de Saint-Exupéry

This is some text in a #+begin_center block. It gets compiles as p.org-center:

This text is centered.

This is some more regular text.

15. View customization

There are many ways to customize the view when you are reading the blog post

15.1. Font

There is a font button at the top of the page which allows you to select between different fonts. By default, I'm using terminus, but you can choose between other pleasing monospace, serif, and sans-serif fonts.

15.2. Text scale

By default I render the main article view as so roughly 66 characters display in each line, which is in line with paper print conventions, but you can use your browser to increase and decrease text scale.

15.3. Light/Dark mode

You can also modify the light/dark mode setting. All images, diagrams, and interactive visualizations are compatible with these modes.

15.4. Colorblind settings

If you have color blindness, you can modify the colors to match your exact kind of color blindness, and you can even set the color scale to grayscale if you can't see color at all. All images, diagrams, and interactive visualizations are compatible with these modes.

15.5. Foldable headings

All headings are foldable – you can click headings to hide/show their content. You can press Shift-Tab to hide show all headings at various levels, which can help to get a birds eye view of the content and only display content that is relevant or interesting to you.

16. Images

16.1. DONE local file (png)

16.2. DONE remote file (svg)

(not rendered) In org mode, you can include captions and html attributes to change the size of the image

Figure 2: A remote image

17. Styling

Styling is applied mostly at the Svelte level, but org-mode does allow some inline styling options.

17.1. inline css

CSS can be included inline in the org file using the export block. This block doesn't render in the document as html markup, it becomes part of the document itself.

Here's the code I embedded in the org-document in a #+begin_export html block to style TODO items in pink monospace font:

18. Adding footnotes

org-mode supports footnotes. This is how the native footnotes look when they get rrendered into HTML:

This is a footnote⁹.

You can have as many¹⁰ footnotes¹¹ as you like in a single line.

You will have already seen numerous footnotes up to this point.

19. Iconography icons

Icons can be included inline. Here I'm using the file-icons github repo. You can see all the icons here.

20. YouTube Video Embeds video media

This blog supports embedding YouTube videos directly in posts using a custom org-mode link type. Videos are embedded as responsive iframes using youtube-nocookie.com for privacy (no tracking cookies).

20.1. Basic Embed

The simplest way to embed a video is using just the video ID:

[[youtube:aqz-KE-bpKQ][Big Buck Bunny]]

Which renders as:

20.2. Using Full URLs

You can also use full YouTube URLs - the video ID is automatically extracted:

[[youtube:https://www.youtube.com/watch?v=aqz-KE-bpKQ][Big Buck Bunny (full URL)]]

20.3. Short Alias

For convenience, yt: works as a shorter alias:

[[yt:aqz-KE-bpKQ][Short alias example]]

The embed is responsive and maintains a 16:9 aspect ratio on all screen sizes.

21. socials

22. Glossary glossary

HUD: Heads-Up Display. The contextual sideline components surrounding the article that provide navigation, search, and metadata at a glance.
Org Mode: A major mode for Emacs that provides tools for keeping notes, maintaining TODO lists, and authoring documents with a fast and effective plain-text markup language.
SvelteKit: A full-stack framework built on top of Svelte for building web applications with server-side rendering, routing, and other production features.
Treemap: A visualization that displays hierarchical data as nested rectangles, where each rectangle's area is proportional to the data it represents. Used here to show article section sizes.
Transclusion: The inclusion of content from one document inside another by reference, so the same source text appears in multiple places without duplication.
Literate Programming: A programming paradigm where code is embedded within human-readable documentation, allowing programs to be written as narratives that interleave explanation with executable source code.
Plotly: An open-source graphing library for creating interactive, publication-quality charts and visualizations in the browser.
Mermaid: A JavaScript-based diagramming tool that renders Markdown-inspired text definitions into diagrams and flowcharts dynamically.
Minimap: A scaled-down overview of the entire article displayed in the sidebar, showing your current scroll position and providing a bird's-eye view of the document structure.

23. tldr

This page demonstrates a comprehensive blogging framework built with Emacs Org Mode and SvelteKit, featuring an innovative heads-up-display (HUD) that enhances reading comprehension through contextual sideline components. The HUD system includes a table of contents, footnotes, references, social media links, TLDR summary, tags, minimap, full-text search, breadcrumbs, and progress bar - all of which dynamically update as you scroll through the content.

The framework showcases extensive support for interactive data visualizations using Plotly, including bar charts, distribution plots, animations, and 3D visualizations that rival professional digital journalism platforms. Software architecture diagrams are created using Mermaid, enabling code-based maintenance of complex technical illustrations from simple microservices to global multi-region architectures.

Literate programming capabilities are demonstrated through org-babel integration, allowing executable code blocks in multiple languages including bash, Python, and others, with results embedded directly in the document. The fancy text features include LaTeX math rendering for complex equations spanning various mathematical and physics domains.

Content organization leverages hierarchical tagging at the header level for non-hierarchical content relationships, while comprehensive link support distinguishes between intra-post, inter-post, and external references with appropriate visual styling. The transclusion feature enables embedding content from other posts verbatim, maintaining consistency across related articles.

Rich media support includes local and remote images, animated GIFs for UI demonstrations, and planned video integration. Structured text elements like tables (including wide tables with horizontal scrolling), various list formats, and footnotes are fully supported with proper HTML rendering.

Narrative features encompass long-form text with embedded footnotes, block quotes with attribution, verse blocks, and centered text, all with custom CSS styling. The framework includes extensive iconography support using file-icons for visual enhancement of technical content.

Styling capabilities allow inline CSS inclusion and custom formatting options, making the blog both functional and visually appealing. The entire system serves as both a working blog and a comprehensive feature demonstration, with progress tracking on headings showing completed (DONE) and in-progress (TODO) implementations.

Footnotes:

Both explicit relationships (like direct links from one post to another) and implicit relationships (like tags and semantic relationships) can be used to traverse the underlying content graph present in any wiki-style document system.

These TODO states are actually from org-mode. Note tha todo state change can be (and is in my configuration) being logged within the org document automatically, offering some ability to visualize progress over time of tasks defined wihin the document

Note I am using Svelte 5 and mostly Typescript for this project, so some syntax may be different than Svelte 3 and/or plain javascript examples you may find online.

⁴

This includes all the text, links, images, code blocks, footnotes, code, code outtput, and more. The benefits of using org-mode are beyond the scope of this demo, but you can read more about them here.

⁵

The sideline features only appear in the desktop version of the web app.

⁶

ASCII art works because I'm using a monospace bit-map font on my blog.

⁷

This is how to write code with python

⁸

new footnote

⁹

This is the footnote. lorem impsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem. Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?

¹⁰

even more

¹¹

More footnotes

The Interest Rate on Your Codebase: A Financial Framework for Technical Debt

Charlie Holland — Mon, 23 Feb 2026 00:58:00 GMT

1. About technicalDebt softwareEngineering

Figure 1: JPEG produced with DALL-E 4o

Every engineer I've worked with has used the phrase "technical debt", but everyone seems to have a different notion of what this phrase actually means. I've also found the phrase to be quite controversial, sparking knee jerk reactions that cut short any meaningful discussions around how to improve codebases and the systems they precipitate.

In general, I feel the term has become a catch-all for anything in a codebase that someone doesn't like – messy code, missing tests, old frameworks, that one service nobody wants to touch, that slow CI in a repo that everyone has to touch…. This imprecision isn't just sloppy language – it's actively harmful. When everything is "tech debt," nothing is, and teams lose the ability to reason clearly about what to fix, when to fix it, and whether to fix it at all.

When everything is "tech debt," nothing is, and teams lose the ability to reason clearly about what to fix, when to fix it, and whether to fix it at all.

This post reclaims the financial metaphor that Ward Cunningham originally intended¹, extends it with precise mappings to financial instruments, and proposes concrete management strategies that scale from a two-person startup to a thousand-engineer enterprise.

The key insight elicidated in this post, and the main subject of my argument, is that the real danger isn't the debt itself – it's the interest. This post will be useful to you because, if you are like most teams, you likely don't know your interest rate.

1.1. Executive Summary

Technical debt is a deliberate deviation from an optimal design that yields short-term value at the cost of increased future work.

Like financial debt, it has principal (the cost to fix), interest (the ongoing drag), and an interest rate (the frequency with which you interact with the debt multiplied by the friction it causes).

The problem isn't taking on debt – it's failing to manage the interest. This post provides a framework for classifying, measuring, and paying down technical debt at any organizational scale.

2. What Is Technical Debt, Actually? definition history

2.1. The Origin Story

In 1992, Ward Cunningham presented an experience report at OOPSLA describing the development of a financial portfolio management system in Smalltalk. He needed to justify ongoing refactoring to his business stakeholders, so he reached for a an unironically relevant metaphor they'd understand¹:

Shipping first time code is like going into debt. A little debt speeds development so long as it is paid back promptly with a rewrite… The danger occurs when the debt is not repaid. Every minute spent on not-quite-right code counts as interest on that debt. – Ward Cunningham

Notice what he didn't say. He didn't say "writing bad code is like going into debt." He said shipping code before you fully understand the problem domain is like going into debt. The distinction matters enormously.

Cunningham was describing something specific: the team had built a working system, and through the process of building it, they had learned things about the domain that the code didn't yet reflect. The code worked. It was well-written. But it encoded an earlier, incomplete understanding of the problem. The "debt" was the gap between what the team now understood and what the code expressed.

This is a much more subtle – and much more useful – concept than "the code is messy."

2.2. A Precise Definition

Building on Cunningham's original insight, and drawing from a decade of subsequent refinement by Martin Fowler, Philippe Kruchten, and others, here's the definition I use:

Technical debt is a deliberate or accidental deviation from an optimal design that yields short-term value at the cost of increased future work.

Technical debt is a deliberate or accidental deviation from an optimal design that yields short-term value at the cost of increased future work.

Furthermore, technical debt has four essential properties:

It has principal – the cost to remediate or redesign the code to its optimal state
It accrues interest – the ongoing drag on velocity, reliability, and developer experience caused by working around the suboptimal design
It is context-dependent – what constitutes "optimal design" changes as requirements evolve, scale increases, or the team's understanding deepens
It is not inherently bad – like financial debt, it can be a rational tool when used deliberately

That last point is critical. A mortgage isn't reckless. Neither is shipping a prototype with hardcoded configuration to validate a business hypothesis. The question isn't whether to take on debt. It's whether you know you're doing it, and whether you have a plan to service it.

2.3. What Technical Debt Is Not

Precision matters here. Conflating these concepts with tech debt dilutes the metaphor to uselessness.

Bugs aren't tech debt because bugs are liabilities, not loans – you didn't choose them for short-term value. They're defects. Fix them on their own merit.
Legacy systems aren't tech debt because age $\neq$ debt. A 15-year-old COBOL system that runs reliably isn't debt if nobody needs to change it. It's legacy – and only becomes debt if it impedes change.
Missing features aren't tech debt because "we haven't built X yet" isn't a loan you took out. It's product scope. Put it on the backlog.
"Bad code" isn't tech debt because subjective aesthetics aren't debt unless they cause measurable drag. If the only problem is that you don't like the style, use a linter.
Missing documentation isn't necessarily tech debt. It's only debt if it increases the cost of future work. Otherwise it's operational risk – might be debt, might not.
Using an old framework isn't necessarily tech debt. It's only debt if upgrading would reduce future costs enough to justify the remediation. Otherwise it's version lag – assess on a case-by-case basis.

The litmus test: does this thing have both a principal (cost to fix) and an interest rate (ongoing cost of not fixing it)? If it only has a principal and no meaningful interest, it's not debt – it's just cleanup work. If it has interest but no meaningful principal (you can't fix it), it's a constraint, not debt.

graph TB
    subgraph "Is It Really Technical Debt?"
        direction TB
        START["Identified Issue"]
        Q1{"Was it a design choice
(deliberate or inadvertent)?"}
        Q2{"Does it cause ongoing
friction (interest)?"}
        Q3{"Can it be remediated
at a known cost (principal)?"}

        DEBT["✅ Technical Debt
Manage it with the
financial framework"]
        NOTDEBT1["❌ Not Debt
It's a defect — fix it
on its own merit"]
        NOTDEBT2["❌ Not Debt
It's cleanup, not debt service"]
        NOTDEBT3["❌ Not Debt
It's a constraint,
not a financial instrument"]

        START --> Q1
        Q1 -->|"Yes — a tradeoff
was made (knowingly
or not)"| Q2
        Q1 -->|"No — it's a bug
or defect"| NOTDEBT1
        Q2 -->|"Yes — it slows
future work"| Q3
        Q2 -->|"No — it just
looks ugly"| NOTDEBT2
        Q3 -->|"Yes"| DEBT
        Q3 -->|"No — there's no
clear fix"| NOTDEBT3
    end

3. The Financial Analogy, Done Right financialAnalogy

The power of Cunningham's metaphor is that finance has centuries of well-developed theory for managing debt. But most engineers use the analogy at the level of "debt = bad, pay it off" – which is about as sophisticated as saying "mortgages are bad, never buy a house."

Let's map the concepts precisely.

3.1. The Instrument List

Principal is the cost to remediate or redesign. "Refactoring the auth module will take 3 sprints."
Interest is the ongoing maintenance cost, velocity drag, and incident risk. "Every feature touching auth takes 2x longer and breaks in staging."
Interest rate is the frequency of change multiplied by the system friction. High for core modules that every team touches, low for rarely-touched utilities.
Refinancing is a large-scale refactor or migration – moving from a monolith to services, upgrading the ORM. You replace one debt instrument with another that has better terms.
Bankruptcy is a full system rewrite. "We're throwing it away and starting over." Sometimes necessary, usually avoidable.
Credit line is the team's tolerance for complexity before velocity collapses. It varies by team size, skill, and tooling – and it's finite.
Cash flow is engineering capacity: the person-hours available for debt service. It's your sprint capacity minus feature commitments.
Amortization is gradual debt paydown alongside feature work. "Every PR in auth must leave the code better than it found it."
Debt-to-equity ratio is the proportion of your codebase that is suboptimal vs. well-designed. High ratios mean fragility; low ratios mean resilience.
Credit rating is the team's track record of paying down debt. Teams that consistently ship debt paydown earn trust for future borrowing.

A key insight falls out of this mapping:

High-interest debt is debt that compounds every time you touch it.

High-interest debt is debt that compounds every time you touch it. The auth module you hack around daily costs orders of magnitude more than the deployment script you run quarterly – even if the deployment script's remediation cost (principal) is lower. This is why prioritizing debt paydown by "ease of fix" is backwards. You should prioritize by interest rate.

3.2. Types of Technical Debt $\approx$ Types of Financial Debt

Not all debt is created equal, and not all debt should be treated the same way.

Here are a few high level categories:

3.2.1. Low-Interest, Long-Term Debt

Financial analog: a 30-year fixed mortgage.

This is stable code that is architecturally imperfect but rarely touched. For example, this could be a data ingestion pipeline written in Python 2 that runs once a month and processes CSV files. If it works and nobody modifies it, then the interest is near-zero because the frequency of interaction is near-zero.

Management strategy: leave it alone. Seriously. Refactoring this is like paying off a 2% mortgage early when you have 20% credit card debt. It's mathematically silly.

3.2.2. High-Interest Revolving Debt

Financial analog: credit card debt.

This is the core module that every team touches daily and everyone hates. For example, the ORM that requires three workarounds per query, or the authentication layer that breaks in every test environment, or the deployment pipeline that takes 45 minutes and fails 20% of the time.

I once worked on a team where the API gateway had been "temporarily" written as a single Express.js middleware file. Every team in the company routed through it. Every feature that touched authentication, rate limiting, or request validation required modifying that file. We had merge conflicts on it daily. The file was 3,000 lines long. The principal to fix it – decomposing it into proper middleware layers – was maybe two weeks of focused work. We deferred it for eighteen months because no sprint ever had "room." By the end, we estimated that the accumulated interest – in merge conflicts, debugging time, and incidents caused by accidental regressions in that file – had cost us closer to six months of engineering time. Two weeks of principal. Six months of interest. That's a 1,200% annual rate.

Management strategy: pay this down immediately. Every day you don't costs more than the day before, because interest compounds with each interaction. This is where the "just ship it" mentality becomes catastrophically expensive.

3.2.3. Variable-Rate Debt

Financial analog: an adjustable-rate mortgage.

This is debt whose cost changes based on external factors. A system that works fine at current scale but will collapse at 10x. Hardcoded assumptions about single-region deployment. A data pipeline that assumes English-only text.

The interest rate is low today but will spike when conditions change – a new market, a compliance requirement, a viral moment. The danger is that by the time the rate spikes, the principal has grown too.

Management strategy: cap your exposure. You don't need to fix it now, but you need to know about it and have a plan. Architecture decision records (ADRs) are your friend here – they document the assumptions that, when violated, will trigger a rate increase.

3.2.4. Hidden Debt (Off-Balance-Sheet)

Financial analog: off-balance-sheet liabilities (the kind that caused the 2008 financial crisis).

This is the scariest kind. Tribal knowledge that exists only in one engineer's head. Undocumented invariants that the code silently depends on. A deployment process that only works because of a specific order of operations that nobody has written down.

Hidden debt is the technical equivalent of off-balance-sheet liabilities – the kind that brought down Lehman Brothers. You don't know about it until it explodes.

Management strategy: incognito leverage too dangerous – make it visible. Do bus factor analysis, documentation sprints, runbooks, chaos engineering – anything that surfaces hidden assumptions. You can't manage debt you can't see.

3.3. The Debt Lifecycle

Technical debt doesn't appear and disappear in a single event — it follows a lifecycle. The diagram below traces debt from the moment it's incurred through a decision point where teams choose one of five responses. Notice the feedback loops: deferred debt compounds back into accruing interest, and even "resolved" debt eventually gives way to new debt as the system evolves.

graph LR
    INCUR["Debt Incurred
(design shortcut taken)"]
    ACCRUE["Interest Accrues
(ongoing friction)"]
    DETECT["Debt Detected
(pain threshold reached)"]
    ASSESS["Debt Assessed
(principal + interest estimated)"]
    DECIDE{"Decision Point"}
    PAY["Pay Down
(refactor/redesign)"]
    REFINANCE["Refinance
(large migration)"]
    ACCEPT["Accept & Monitor
(interest rate is low enough)"]
    BANKRUPT["Declare Bankruptcy
(full rewrite)"]
    DEFER["Defer
(interest continues)"]

    INCUR --> ACCRUE
    ACCRUE --> DETECT
    DETECT --> ASSESS
    ASSESS --> DECIDE
    DECIDE -->|"High interest,
manageable principal"| PAY
    DECIDE -->|"High interest,
large principal"| REFINANCE
    DECIDE -->|"Low interest"| ACCEPT
    DECIDE -->|"Unmaintainable"| BANKRUPT
    DECIDE -->|"No capacity"| DEFER
    DEFER -->|"Interest compounds"| ACCRUE
    PAY -->|"Debt resolved"| INCUR
    REFINANCE -->|"Lower interest rate"| ACCEPT

4. Fowler's Quadrant: Why Teams Accumulate Debt classification martinFowler

Martin Fowler's Technical Debt Quadrant provides the best taxonomy I've seen for why debt gets created. It classifies debt along two axes: deliberate vs. inadvertent and prudent vs. reckless².

Each quadrant requires a different response:

Prudent + Deliberate: This is strategic debt. It's the mortgage. Document it, schedule the paydown, and move on. This is the only quadrant where the financial analogy fully applies, because it involves a conscious tradeoff.
Prudent + Inadvertent: This is learning debt. It's the most sympathetic and the most unavoidable. You can't know the right design until you've tried the wrong one. The paydown here is refactoring to reflect your improved understanding – exactly what Cunningham described.
Reckless + Deliberate: This is negligent debt. Teams that knowingly ship garbage and call it "velocity" are running up credit card debt with no intention of paying it off. This is the quadrant that gives technical debt a bad name.
Reckless + Inadvertent: This isn't really debt at all – it's a knowledge gap. The team doesn't know enough to recognize the shortcuts they're taking. The fix isn't refactoring; it's education, mentorship, and pairing. This includes experienced engineers working in unfamiliar domains – backend engineers building frontends, infrastructure engineers writing business logic. The gap is contextual, not personal.

4.1. Why Debt Is Rational

It's important to resist the temptation to moralize about technical debt. In many contexts, taking on debt is the right decision:

Speed to market: A startup with 6 months of runway doesn't need a perfectly designed system. It needs product-market fit. The debt is rational because the alternative is bankruptcy – the real kind.
Uncertain requirements: When you don't yet know what the system needs to do, investing in a "perfect" architecture is waste. Build the thing, learn what it should have been, then refactor. This is Cunningham's original insight.
Asymmetric risk: If the upside of shipping fast is 100x and the downside of the debt is 2x, the expected value calculation is trivial.
Exploration and prototyping: Prototype code should be debt-heavy. That's the point. The mistake is promoting prototype code to production without acknowledging the accumulated debt.

Tech debt is often a sign of rational decision-making under uncertainty – not incompetence.

This is the framing I use with stakeholders, and it changes the conversation immediately. Instead of "we need to clean up the code" (which sounds like an engineering vanity project), it becomes "we need to manage our financial exposure" (which sounds like responsible governance).

5. Interest, Not Principal, Is the Real Danger interestRate measurement

Most teams think about technical debt in terms of principal – "how hard would it be to fix this?" They estimate the cost of a refactor, put it on the backlog, and let it sit there because it never outranks the next feature.

But the principal is static. The interest is what kills you. And interest compounds.

5.1. Measuring Interest (Without Fake Precision)

Avoid metrics theater. Lines of code, cyclomatic complexity, and lint scores are proxies at best and noise at worst. The following signals are more useful for measuring the interest on your technical debt:

Change amplification measures how many files or systems must be touched per feature. Track PR size and the number of changed files over time. If the trend is up, interest is compounding.
Time-to-confidence measures how long before an engineer trusts that a change won't break something. Measure the gap from "code complete" to "merged with confidence." Long gaps mean high friction.
Error surface area measures the number of ways a change can fail. Count unique failure modes in CI/CD and staging. The more ways things break, the higher the interest.
Onboarding half-life measures how long it takes a new engineer to become productive. Track days-to-first-meaningful-PR per new hire. If it's getting longer, your codebase is getting harder to understand.
Fear factor measures which systems nobody wants to touch. Survey your engineers: which parts of the codebase do they avoid? Fear is a leading indicator of high-interest debt.
Rework rate measures code that is added then quickly modified or deleted. This is DORA's new fifth metric – now officially tracked³.

These signals map directly to interest, not principal. A system with high change amplification and a high fear factor is accruing massive interest, regardless of how "easy" the fix would be.

5.2. The Compounding Effect

Interest on technical debt compounds in ways that are genuinely analogous to financial compound interest. Consider a module with a 10% "tax" – every feature touching this module takes 10% longer than it should.

Hacking around debt like trying to kill a mythological hydra – the effort is herculean, but the problem only grows with each swing of the engineer's sword.

In isolation, 10% sounds manageable. But compound it:

Feature A takes 10% longer because of the debt
Feature B also touches the module, and also adds workarounds, slightly increasing the friction
Feature C touches the module and now takes 15% longer because of the accumulated workarounds from A and B
Feature D's developer, frustrated by the mess, copies the module instead of extending it – creating a new debt instrument
Features E through Z now have two versions of the module to maintain

This is how a 10% tax becomes a 50% tax in 18 months. I've seen this exact pattern play out at multiple companies. Hacking around debt like trying to kill a mythological hydra – the effort is herculean, but the problem only grows with each swing of the engineer's sword. If the banner image of this blog post reminds you of a terrifying hydra, then I've accomplished my goal of being illustrious.

The chart above models three scenarios over five years. The red line shows what happens when debt is left unmanaged – a 10% velocity tax compounds into a 50%+ tax within a few years. The yellow line shows moderate, consistent debt service. The green line shows aggressive front-loaded paydown that levels off once the worst debt is addressed.

The takeaway: the earlier you start servicing debt, the cheaper it is. Just like a mortgage.

5.3. Lehman's Laws: Physics Agrees with Finance

The compounding effect isn't just an analogy – it's a law of software evolution.

Lehman's laws of software evolution, established empirically in the 1970s and validated repeatedly since, state that⁴:

Continuing Change: A system must be continually adapted or it becomes progressively less satisfactory
Increasing Complexity: As a system evolves, its complexity increases unless work is explicitly done to reduce it
Self Regulation: System evolution is a self-regulating process with statistically determinable trends

Law #2 is the kicker. Complexity doesn't increase because engineers are careless. It increases because that's what happens to systems that interact with the real world. Entropy is the default. Order requires energy. This is as true in software as it is in thermodynamics.

Entropy is the default. Order requires energy.

Technical debt, in this framing, is unreduced complexity – the delta between the system's current complexity and the minimum complexity needed to serve its current purpose. Interest is the ongoing cost of carrying that excess complexity. And Lehman tells us that without deliberate effort, that delta only grows.

6. Management Strategies by Company Stage strategy organizational

So the debt compounds. The interest accrues. Lehman's second law tells us complexity grows by default. The natural question is: what do you actually do about it?

The right approach depends heavily on context. A strategy that's right for a 500-person engineering org can be lethal for a 5-person startup, and vice versa.

6.1. Small Teams and Startups (2-20 engineers) startups

6.1.1. Principles

Accept higher interest rates – your cost of capital is survival, not elegance
Avoid irreversible debt – you can tolerate messy internals, but not locked-in architectural commitments
Prefer debt that can be deleted – the best refactor is rm -rf

6.1.2. Tactics

Build throwaway-by-design systems. If you acknowledge that v1 exists to find product-market fit, not to be your production architecture for the next decade, you can make fundamentally different design decisions. Use the simplest thing that works. Monolith over microservices. A single database over sharded clusters. Flat files over message queues.
Keep boundaries clean even if internals are messy. The API contract between services matters. The internal implementation of each service does not – yet. This is the "clean interfaces, dirty internals" pattern, and it's the best debt strategy for startups because it preserves optionality while allowing speed.
Track known debt explicitly. A TECH_DEBT.md in the repo root with a list of known shortcuts is worth more than a Jira board nobody checks. Each entry should note: what the shortcut is, why it was taken, and what would trigger the need to fix it.
Favor deletion over refactoring. The best thing about startup code is that most of it can be thrown away. When a module becomes too debt-heavy, ask: "Would it be faster to rewrite this from scratch, now that we understand the problem?" At small scale, the answer is usually yes.

6.1.3. What to avoid

Don't invest in elaborate "tech debt tracking" tools – the overhead exceeds the benefit at this scale
Don't over-abstract "for the future" – you don't know what the future looks like yet
Don't take on irreversible debt (choosing the wrong database, the wrong cloud, the wrong primary language) just to move fast

6.2. Growth-Stage Companies (20-200 engineers) growth scaleups

This is where debt management gets serious, and where I've seen the most damage done. At one growth-stage company I worked with, the engineering team tripled in a year. The codebase they inherited from the startup phase was a classic "clean interfaces, dirty internals" system – which had been fine at 8 engineers. But at 30, the dirty internals became a coordination bottleneck. Three teams would independently hack around the same internal limitation in three different ways, creating three new debt instruments per quarter. The startup-era debt didn't grow linearly with headcount – it grew quadratically, because every new engineer was another node in the collision graph.

You're past the point where everyone knows everything, but not yet at the scale where platform teams and formal governance make sense. This is the most dangerous stage.

6.2.1. Principles

Start budgeting for debt service – treat it like a line item, not an afterthought
Avoid compounding interest – stop building new features on top of known-debt foundations
Make debt visible – if leadership can't see it, they can't prioritize it

6.2.2. Tactics

Allocate fixed capacity for debt service. 15-25% of engineering capacity, every sprint, non-negotiable. This is not a "20% time" passion project. This is interest payments. McKinsey's research found that organizations with systematic debt management freed up engineers to spend up to 50% more time on value-generating work⁵.
Attach debt remediation to feature work. The most efficient way to pay down debt is to do it when you're already in the code. If Feature X touches the auth module, the sprint plan includes both Feature X and "improve auth module test coverage." This is the "boy scout rule" formalized: leave the campground cleaner than you found it.
Adopt Architecture Decision Records (ADRs). When you make a deliberate debt decision, write it down. An ADR should capture: the context, the decision, the consequences (including known debt), and the conditions under which the decision should be revisited. ADRs are your institutional memory for why the code looks the way it does⁶.
Establish ownership for core systems. Every high-interest system should have an owner – a team or an individual responsible for its health. Unowned systems accumulate debt fastest because nobody feels the pain enough to prioritize fixing them.

6.3. Large Organizations (200+ engineers) enterprise platform

At enterprise scale, technical debt becomes systemic risk. Individual modules matter less than system-level friction: API boundaries, deployment pipelines, shared libraries, and the organizational structures that produce them.

6.3.1. Principles

Debt becomes systemic risk – a single high-interest module can bottleneck the entire organization
Coordination cost > code quality – the overhead of keeping 50 teams aligned often exceeds the cost of the debt itself
Debt hides in interfaces – the most expensive debt lives at system boundaries, not inside modules

6.3.2. Tactics

Platform teams as "internal lenders." Platform engineering teams function like a bank: they provide well-maintained, low-friction infrastructure that product teams "borrow" from. In exchange, product teams agree to use the platform's APIs and conventions, keeping the system-level architecture coherent. This is the Team Topologies model in debt terms.
Enforce contracts at boundaries. At scale, the cost of drift between teams dwarfs the cost of individual code quality. Schema languages, API contracts, integration tests at boundaries, and automated compatibility checks are all forms of debt prevention at the interface level⁷.
Track change amplification across organizational boundaries. When a change in Team A's service requires changes in Teams B, C, and D, that's a debt signal. The organizational structure is creating friction, and per Conway's Law⁸, the software architecture will mirror (and reinforce) that friction.
Plan refinances, not heroic rewrites. The "big rewrite" is the engineering equivalent of declaring bankruptcy. Sometimes it's necessary, but usually it's better to refinance – systematically reducing the interest rate through incremental migration. The Strangler Fig pattern⁹ is the canonical approach: build the new system alongside the old, redirect traffic incrementally, and let the old system wither.

6.4. Capacity Allocation by Stage

Notice how the allocation to debt service increases with company size. This is counterintuitive – you'd think larger companies with more resources could afford less proportional debt spending. But larger companies have more accumulated debt, more system boundaries where debt hides, and higher coordination costs. The 5% a startup spends is "fix it when you see it." The 25% an enterprise spends is "dedicated teams, formal processes, migration projects."

7. Refactoring as Refinancing, Not Cleanup refactoring

One of the most powerful reframings in this entire financial analogy:

Refactoring is not "paying off" debt. It's refinancing it.

When you refinance a mortgage, you don't eliminate the debt. You replace one debt instrument with another that has better terms – lower interest rate, more predictable payments, better aligned with your current financial situation.

Good refactoring does the same thing:

Financial Refinancing	Technical Refactoring
Lowers interest rate	Reduces ongoing friction and maintenance cost
Improves optionality	Makes future changes easier and less risky
Preserves cash flow	Doesn't require a full stop to feature development
May increase principal temporarily	The refactored code might be larger or more complex initially
Reduces monthly payments	Each feature touching the refactored area takes less time

This reframing matters because it changes the conversation with stakeholders. "We need to stop feature work for 3 months to clean up the code" is a hard sell. "We're refinancing – we'll reduce our ongoing maintenance costs by 30%, freeing up 2 engineers' worth of capacity for new features" is a business case.

7.1. Good Refinancing vs. Bad Refinancing

7.1.1. Good refinancing

Incremental refactors attached to feature work – lower interest rate without stopping feature delivery
The Strangler Fig pattern for large systems – build the replacement alongside the original, migrate traffic gradually, decommission the old
Parallel systems with measured migration – run old and new simultaneously, compare results, switch over when confidence is high

7.1.2. Bad refinancing

Big-bang rewrites – the engineering equivalent of a Netscape-style full rewrite¹⁰. You lose domain knowledge, you lose battle-tested edge case handling, and you introduce new bugs. The principal might drop, but the risk premium spikes.
Refactoring with no measurable improvement – if you can't articulate what metric improves after the refactor, you're not refinancing; you're rearranging furniture
Cosmetic refactors (renaming, reformatting) disguised as debt paydown – this is the equivalent of refinancing a 5% mortgage to a 4.9% mortgage: technically better, practically irrelevant

graph TB
    subgraph "Refactoring Decision Framework"
        direction TB
        START["Proposed Refactor"]
        Q1{"Does this reduce
measurable friction?"}
        Q2{"Can it be done
incrementally?"}
        Q3{"Does it preserve
existing functionality?"}
        Q4{"Does the team have
sufficient context?"}

        GOOD["✅ Good Refinancing
Proceed with measurement"]
        MAYBE["⚠️ Consider Strangler Fig
Build alongside, not instead"]
        RISKY["⛔ High Risk
Document a migration plan first"]
        NOPE["❌ Not a Refactor
It's a rewrite — treat it as one"]

        START --> Q1
        Q1 -->|"Yes"| Q2
        Q1 -->|"No"| NOPE
        Q2 -->|"Yes"| Q3
        Q2 -->|"No"| MAYBE
        Q3 -->|"Yes"| Q4
        Q3 -->|"No"| RISKY
        Q4 -->|"Yes"| GOOD
        Q4 -->|"No"| RISKY
    end

8. AI-Generated Code: The New Debt Accelerator artificialIntelligence codeQuality

No discussion of technical debt in 2026 is complete without addressing the elephant in the IDE: AI code assistants.

GitHub Copilot, Claude, and their cousins have fundamentally changed the economics of code production. Writing code is now cheaper and faster than ever. But cheaper production doesn't mean cheaper ownership – and this is where the financial analogy becomes urgent.

8.1. The Data

GitClear's 2025 research on AI-assisted code quality found¹¹:

Code duplication (cloned blocks of 5+ lines) increased 8-fold between 2022 and 2024
Refactoring activity dropped from 25% of changed lines in 2021 to less than 10% in 2024
Code churn (code added then quickly modified or deleted) rose steadily, reaching an estimated ~7% by 2025

Google's 2024 DORA report corroborates: teams with higher AI adoption reported faster code review and improved documentation, but the same cohort showed a measurable decrease in delivery stability³.

In financial terms: AI assistants have massively increased the rate at which teams can issue new debt, while simultaneously reducing the rate at which existing debt gets serviced.

8.2. Why AI Amplifies Debt

The mechanism is straightforward:

AI makes it trivially easy to add code – reducing the perceived cost of new functionality
AI makes it no easier to understand existing code – the cognitive overhead of working in a complex codebase hasn't changed
AI-generated code tends toward the generic and duplicative – it doesn't know your architecture, your conventions, or your existing abstractions
Developers using AI skip the "understand before modifying" step more frequently – the code is generated faster than understanding develops

This creates a specific new type of debt that deserves its own name: comprehension debt.

AI assistants have massively increased the rate at which teams can issue new debt, while simultaneously reducing the rate at which existing debt gets serviced.

Comprehension debt is the gap between the size of a codebase and any individual engineer's ability to hold a working mental model of it. Traditional technical debt is about code that's wrong – suboptimal designs that create friction. Comprehension debt is about code that might be individually correct but is collectively unintelligible. Each AI-generated function may work perfectly, but when 40% of the codebase was written by an LLM that doesn't know your team's conventions, the overall architecture drifts toward incoherence – ten different patterns for error handling, six ways to call the same API, three duplicate utility functions that almost-but-do-not-quite do the same thing.

The insidious property of comprehension debt is that it can't be addressed by traditional refactoring. You can't "fix" a codebase that nobody can hold in their head. The debt isn't in any individual module – it's in the aggregate. The principal doesn't show up in any static analysis tool, and the interest manifests as slower onboarding, more bugs from unexpected interactions, and a growing sense among senior engineers that "nobody really knows how this system works anymore."

8.3. Mitigations

Treat AI-generated code as a PR from a junior engineer: review it with the same rigor, question design decisions, check for duplication against existing code. I may change my tune as AI code review tools improve, but I would also resist the urge to have something like CodeRabbit do your PR reviews, especially since this would fail to narrow the comprehension gap
Maintain strong architectural guard rails: linters, architecture tests (like ArchUnit), import restrictions, and pre-commit hooks that prevent the most common AI-introduced anti-patterns
Increase refactoring capacity proportionally: if AI is helping you produce code 2x faster, you need 2x the refactoring capacity to prevent the debt ratio from spiking
Track AI-specific quality metrics: code duplication rate, churn rate, and the ratio of net-new code to refactored code

9. The Organizational Failure Mode organizationalDebt conwaysLaw

Here's the uncomfortable truth that most engineers don't want to hear:

Technical debt is often a management and incentive problem, not a technical one.

9.1. Conway's Law as a Debt Generator

Conway's Law states that organizations design systems that mirror their own communication structures⁸. The implication for technical debt is profound: organizational friction becomes architectural friction becomes technical debt.

If teams A and B can't communicate efficiently, the interface between their services will accrue debt – duplicated logic, mismatched assumptions, undocumented contracts. The debt isn't caused by poor engineering. It's caused by poor organizational design. And no amount of refactoring will fix it, because the structure that created the debt will recreate it.

The Inverse Conway Maneuver – deliberately restructuring teams to match the desired architecture – is the only way to address this class of debt. It's also politically difficult, which is why this debt tends to persist.

9.2. Incentive Misalignment

Technical debt grows fastest in organizations with these incentive patterns:

Incentive Pattern	Debt Effect	Fix
Rewarding only shipping	Teams optimize for feature velocity, ignoring maintenance	Include quality metrics in performance evaluation
No ownership past initial delivery	Code is "thrown over the wall" – nobody feels the interest	"You build it, you own it" culture
No time allocated for maintenance	Debt service gets crowded out by feature work	Fixed capacity allocation (the 15-25% rule)
Architecture decisions without accountability	Decision-makers don't bear the cost of their choices	ADRs with named authors and review dates
Promotion criteria that ignore technical health	Senior engineers chase visible impact, not sustainable systems	"Infrastructure impact" as a promotion criterion

Tech debt grows fastest where engineers feel powerless to address it. If your process doesn't allocate time for debt service, debt will accumulate. This is not a technical problem. It's a governance problem.

The most pernicious version of this: organizations that say they value quality but measure only velocity. Engineers quickly learn which metric actually matters, and they optimize accordingly.

10. A Framework for Action framework decisionMaking

Let's pull everything together into a practical framework.

10.1. Step 1: Inventory Your Debt

You can't manage what you can't see. Build a simple inventory:

Field	Description
Name	Human-readable label (e.g., "Auth module monolith")
Type	Low-interest / High-interest / Variable-rate / Hidden
Principal	Estimated effort to remediate (T-shirt: S/M/L/XL)
Interest rate	How often teams interact with this debt (Daily / Weekly / Monthly / Rarely)
Quadrant	Fowler classification (Prudent+Deliberate, etc.)
Owner	Team or individual responsible
Trigger	Conditions under which this debt must be addressed

Don't over-engineer this. A spreadsheet or a markdown file (or org-mode file if you're cool like me 🤪) in the repo is fine. The point is visibility, not process.

10.2. Step 2: Prioritize by Interest Rate

Sort your inventory by interest rate, not by principal. The debt that every team interacts with daily costs more than the debt that one team encounters quarterly, even if the quarterly debt has a higher remediation cost.

The formula is simple:

\[ \text{Debt Priority Score} = \text{Interest Rate} \times \text{Number of Affected Teams} \times \text{Interaction Frequency} \]

This isn't meant to be precise – it's meant to force the right conversation.

10.3. Step 3: Allocate Capacity

Decide on a fixed percentage of engineering capacity for debt service. This should be:

Non-negotiable: it doesn't get borrowed for feature work when deadlines loom. The moment debt service becomes "optional," it stops happening – the same way savings stop when they're "whatever's left after spending." Treat it like a payroll obligation, not a discretionary budget.
Visible: leadership should see how the capacity is being used. A monthly one-pager showing which debt was serviced, what metrics improved, and what's next builds institutional trust. Over time, this evidence base is what lets you increase the allocation when it's needed.
Measured: track whether debt service is actually reducing interest payments. If you allocated 20% to debt service last quarter and velocity didn't improve, either you're paying down the wrong debt or the measurement window is too short.

In practice, I've seen this work best when the allocation is protected at the team level, not the org level. Telling 50 teams "the org is allocating 20% to debt" is meaningless. Telling each team "20% of your sprints go to debt service, and here's how we'll track the impact" creates accountability.

10.4. Step 4: Execute and Measure

For each debt paydown initiative, define:

What metric improves? (Change amplification decreases, onboarding time drops, incident rate falls)
By how much? (Even a rough target helps)
By when? (Timeboxed – if it's not showing results in 2-3 sprints, reassess)

Track these before and after. This builds the institutional evidence base for continued debt service investment.

Here's a concrete example: suppose you're refactoring the authentication module. Before starting, measure: average PR size for auth-touching features (say, 15 files), average time from "code complete" to "merged" (say, 4 days), and staging failure rate for auth changes (say, 25%). Set targets: reduce PR size to <8 files, merge time to <2 days, staging failures to <10%. After two sprints of focused refactoring, measure again. If the metrics moved, you have evidence. If they didn't, you're either fixing the wrong thing or the refactor isn't done yet.

10.5. Step 5: Prevent New High-Interest Debt

Paydown without prevention is a treadmill. Implement:

ADRs for deliberate debt decisions – every time the team knowingly takes on debt, write a one-page record: what shortcut was taken, why, what the expected interest rate is, and what conditions should trigger paydown. This is the difference between a mortgage (documented, scheduled) and credit card debt (invisible, compounding).
Code review standards that explicitly evaluate debt introduction – add "does this PR introduce or increase technical debt?" as a standard review question. If yes, require a comment explaining the tradeoff.
Architecture tests that prevent structural regression – tools like ArchUnit (Java), Dependency Cruiser (JavaScript), or even simple import-graph checks in CI can enforce "module A should not depend on module B" constraints. These automated guardrails catch drift before it compounds.
Post-incident reviews that trace root causes back to specific debt – when an incident occurs, ask: "Was known technical debt a contributing factor?" If the answer is yes three times for the same debt item, it gets promoted to the top of the priority list regardless of its planned schedule.

11. Conclusion: Structure It, Don't Eliminate It synthesis

Let me end with the thesis I promised at the start:

You don't eliminate technical debt. You structure it.

Every financial system carries debt. Healthy companies have mortgages, lines of credit, and corporate bonds. The difference between a healthy company and a bankrupt one isn't the presence of debt – it's the management of it. Healthy companies know their debt-to-equity ratio, their interest obligations, and their capacity to service existing debt before taking on more.

The same is true for codebases.

A healthy codebase has known, documented debt with managed interest rates, owned by specific teams, prioritized by business impact, and systematically paid down. An unhealthy codebase has the same amount of debt but nobody can tell you what it is, how much it costs, or who's responsible.

Every system carries debt. The question is who pays, when, and how predictably.

The financial analogy isn't perfect. No analogy is. But it gives us a vocabulary – principal, interest, refinancing, credit rating – that makes the invisible visible and the abstract concrete. It transforms "we have a lot of tech debt" from a vague complaint into a specific, actionable diagnosis: what is the debt, what is the interest rate, and what is our plan for servicing it?

Start there. The rest follows.

Cunningham's original insight was that shipping code creates a gap between what you've built and what you now understand. Thirty-four years later, the insight holds – but the gap has widened. We ship faster, understand later, and compound the difference daily. The metaphor he gave us is still the best tool we have for closing it. Use it precisely, and it will serve you well.

12. socials

13. tldr

This post reclaims Ward Cunningham's original financial metaphor for technical debt and extends it into a comprehensive framework for managing code quality at any organizational scale.

The core argument begins with a precise definition: technical debt is a deliberate or accidental deviation from an optimal design that yields short-term value at the cost of increased future work. Critically, not everything that frustrates engineers is debt—bugs are liabilities, legacy systems are only debt if they impede change, and "bad code" is a style preference unless it causes measurable drag.

The post maps technical concepts to financial instruments with precision: principal is remediation cost, interest is ongoing friction, and the interest rate is interaction frequency multiplied by system friction. This leads to a taxonomy of debt types—low-interest long-term debt (like a mortgage), high-interest revolving debt (like credit cards), variable-rate debt whose costs spike under changing conditions, and dangerous hidden debt that lurks off the balance sheet.

Martin Fowler's quadrant classifies debt by whether it was deliberate or inadvertent, prudent or reckless—each requiring different responses. The post argues that debt is often rational, especially for startups validating product-market fit or teams exploring uncertain requirements.

The central thesis emerges in the section on interest: the real danger isn't the debt itself but the compounding interest. The post provides practical signals for measuring interest—change amplification, time-to-confidence, fear factor, and rework rate—and illustrates how a 10% velocity tax can become 50% in 18 months through compound effects that Lehman's Laws predict are inevitable without deliberate countermeasures.

Management strategies vary by company stage: startups should accept higher interest rates while avoiding irreversible debt, growth-stage companies must allocate 15-25% of capacity to debt service, and enterprises need platform teams functioning as internal lenders with enforced contracts at system boundaries.

The post reframes refactoring as refinancing rather than cleanup—replacing one debt instrument with another that has better terms—and distinguishes good refinancing (incremental, measurable) from bad (big-bang rewrites, cosmetic changes).

A timely section addresses AI-generated code as a new debt accelerator, introducing the concept of "comprehension debt"—the gap between codebase size and any engineer's ability to maintain a working mental model. The data shows AI tools have increased code production while reducing refactoring activity, creating a dangerous imbalance.

Organizational factors often matter more than technical ones: Conway's Law means organizational friction becomes architectural friction becomes debt, while incentive misalignment (rewarding only shipping, no ownership past delivery) accelerates accumulation.

The post concludes with a five-step framework: inventory your debt, prioritize by interest rate rather than principal, allocate fixed non-negotiable capacity for debt service, execute with measurable targets, and prevent new high-interest debt through ADRs and architecture tests. The final message: you don't eliminate technical debt, you structure it—just as healthy companies carry managed debt with known obligations and clear ownership.

Footnotes:

Ward Cunningham first described the debt metaphor in his 1992 OOPSLA experience report, "The WyCash Portfolio Management System." He later clarified in a 2009 video that the metaphor was specifically about the gap between the team's evolving understanding and the code's current design – not about deliberately writing poor code.

Martin Fowler's Technical Debt Quadrant (2009) built on Cunningham's original metaphor by distinguishing between deliberate/inadvertent and prudent/reckless debt. This taxonomy is now widely used in industry.

Google's DORA (DevOps Research and Assessment) program has tracked software delivery performance for over a decade. The 2024 State of DevOps report introduced rework rate as a fifth key metric and found mixed results from AI adoption: improved throughput but decreased stability. See: dora.dev.

⁴

Lehman's laws of software evolution were first proposed by Meir M. Lehman in 1974 and refined through the 1990s. The laws describe empirically observed properties of "E-type" systems (software that solves real-world problems). The key insight – that complexity increases unless explicitly counteracted – has been validated across decades of research. See: Wikipedia: Lehman's Laws.

⁵

McKinsey's 2023 report "Breaking technical debt's vicious cycle to modernize your business" found that technical debt consumes a significant share of IT budgets – CIOs surveyed reported that as much as 40% of their technology estate was composed of tech debt. Organizations with systematic debt management freed engineers to spend up to 50% more time on value-generating work. One CIO reported reducing the "debt tax" on engineer time from 75% to 25%.

⁶

Architecture Decision Records (ADRs) were popularized by Michael Nygard in a 2011 blog post. The format is simple: Context, Decision, Consequences. The key value is recording the context so future engineers understand why the decision was made, not just what it was.

⁷

For a deep dive on schema languages as an interface-level debt prevention strategy, see my companion post: The Schema Language Question: Avro, JSON Schema, Protobuf, and the Quest for a Single Source of Truth.

⁸

Conway's Law, introduced by Melvin Conway in 1967, states that "organizations which design systems are constrained to produce designs which are copies of the communication structures of these organizations." Research from MIT and Harvard Business School found "strong evidence to support the mirroring hypothesis." See: Wikipedia: Conway's Law.

⁹

The Strangler Fig pattern was named by Martin Fowler in his 2004 blog post, inspired by the strangler fig trees he observed in Australia. The pattern involves building a new system around the edges of the old, gradually routing traffic from old to new, until the old system can be decommissioned.

¹⁰

Joel Spolsky's "Things You Should Never Do, Part I" (2000) argues that full rewrites are "the single worst strategic mistake that any software company can make," citing Netscape's decision to rewrite their browser from scratch as a cautionary tale. The argument is that working code, however ugly, embodies years of accumulated knowledge about edge cases and failure modes that a rewrite will inevitably lose.

¹¹

GitClear's "AI Copilot Code Quality: 2025 Data Suggests 4x Growth in Code Clones" analyzed over 200 million lines of changed code to measure the impact of AI assistants on code quality metrics. The findings suggest that AI tools are accelerating code production while reducing refactoring activity, leading to increased duplication and higher churn rates.

space-tree: Tree-Based Workspace Management for Emacs

Charlie Holland — Sun, 22 Feb 2026 18:20:00 GMT

1. About emacs workspaceManagement tooling

Figure 1: JPEG produced with DALL-E 4o

Modern UIs are over-engineered and excessive. This is easy to say in an age where people walk around with computers attached to their faces, only to get… a subpar user experience. It's also easy to say as a developer who uses Emacs, the best TUI I've ever used for people who primarily interface with text.

2. The Workspace Problem workspaceManagement

I've recently seen hilarious demonstrations of people pinning AR screens around their houses in an overambitious attempt to organize their open applications. AR headsets are an over-engineered solution to a problem that all PC users suffer from, and they solve it with the wrong tools. Ocular tracking, accelerometers, gyroscopes, proprietary software… all of this, when simple 2D screens are already extremely good at managing workspaces.

The math doesn't math, especially after you factor in the astronomical price tags of these AR devices.

Here's the design smell: we want a software solution for personal computing, but AR brings in a hardware dependency that isn't even a personal computer. The math doesn't math, especially after you factor in the astronomical price tags of these AR devices. AR for workspace management is less of a real improvement and more of an indulgence in "shiny objects".

I like to shake my fist at over-engineering by creating something simple, so I built space-tree, a lightweight Emacs package that models workspaces as a tree rather than a flat or fixed-dimension list. I'd been annoyed by the workspace situation in my Emacs config for a while. What started as a few convenience functions in my init.el eventually grew into a proper package. But before I get into what I built, it's worth looking at what already exists.

3. Existing Solutions in Emacs emacs comparison

Emacs has several workspace managers. Eyebrowse gives you a flat, numbered list of window configurations, basically virtual desktops. perspective.el and persp-mode (separate packages despite the similar names) go further, scoping buffers to named workspaces with persistence across sessions. These are well-designed tools, but in my experience they share a few limitations:

3.1. Flat Lists

Some workspace managers have too few dimensions. Eyebrowse organizes workspaces in a flat 1-dimensional list. With tools like tmux and Chrome, I've grown accustomed to organizing my workspaces into at least 2-dimensional layouts, so the flatness of eyebrowse is an issue for my brain. Certain contexts (developing a suite of unit tests across multiple modules, for instance) demand more than 2 dimensions of organization.

3.2. Fixed Dimensions

Even when a workspace manager has more than one dimension, the number of dimensions tends to be fixed. tab-bar-mode is a row of tabs. Always one row, always flat. But I'm often working with contexts of mixed complexity. A quick bug fix needs one workspace; a multi-file refactor with tests needs a whole subtree. You end up either over-structuring simple tasks or under-structuring complex ones.

3.3. Naming Tax

Most workspace managers want a name and a location upfront. persp-mode prompts you to name every workspace at creation time. This is friction. Sometimes I just want to branch off, explore something, and figure out later whether it deserves a name and a permanent place. Or never. Most of my workspaces don't need names. They need to exist for twenty minutes and then disappear.

What I wanted was a workspace system with arbitrary depth, no mandatory naming, and enough flexibility to match the structure to the task, not the other way around.

4. How space-tree Works emacs dataStructures

Workspaces form a tree. Each node stores a window configuration (which buffers are displayed in which windows at a given moment). You can branch off from any node to create child workspaces, and navigate the tree laterally between siblings or vertically between parent and child.

1 ─── 1.1 ─── 1.1.1
 │         └── 1.1.2
 │
 └── 1.2 ─── 1.2.1

2 ─── 2.1

This gets you:

Arbitrary depth. Nest workspaces as deep as the context demands.
Mixed complexity. A bug fix is a leaf node. A complex investigation gets its own subtree with as many children as it needs.
No upfront naming. Create a space, start working, name it later. Or don't.

Say I'm chasing a failing test. I have my test runner open, but I need the test source alongside the implementation, and I want to cross-reference stack traces without losing any of those layouts. With space-tree, I branch from my runner into a space for the test source, branch again for the implementation, and create a sibling for the logs. Each space preserves its own window arrangement. When I fix the bug, I jump back to the runner and all the investigative context is still there, organized the way I actually thought about the problem.

4.1. Where space-tree Fits in Emacs

space-tree doesn't replace anything. If you already use perspective.el for buffer scoping, space-tree layers on top and manages window configurations independently. It's also orthogonal to tab-bar-mode. You can use tab-bar tabs and space-tree spaces in the same session without conflict.

Emacs already lets you snapshot the current arrangement of windows and buffers with current-window-configuration. space-tree manages a tree of these snapshots and restores them when you switch spaces. Spaces live in memory for the duration of your session. They're not persisted across restarts. I may add that later, but frankly I haven't missed it. The tree is cheap to rebuild and my workflows change day to day anyway.

5. Key Interactions emacs demonstration

Here's what it actually looks like in use.

5.2. Naming and Switching

Spaces are unnamed by default, but you can name them at any point. Once named, space-tree-switch-space-by-name lets you jump directly via completing-read. This is useful when the tree gets deep and lateral navigation would be tedious.

Figure 2: Naming a space and switching to it via completing-read

5.3. Reusing Layouts

Once you've set up a window layout you like, you can duplicate it elsewhere in the tree with copy and paste. Useful when you want the same split arrangement for a different task. And when you're bouncing between two active contexts, space-tree-go-to-last-space gives you a quick toggle, like alt-tab for your workspaces.

Figure 3: Copying a workspace layout and pasting it into a new branch

Figure 4: Toggling between two active workspaces

5.4. Cleanup and the Modeline

When you're done with a branch of work, space-tree-delete-space prunes it from the tree. The modeline indicator shows your current position at all times, so you always know where you are without thinking about it.

Figure 5: Deleting a space and observing the modeline indicator

6. Getting Started emacs installation

space-tree is on GitHub. Install with straight.el or manually, then call (space-tree-init). The README has the full command reference.

(use-package space-tree
  :straight (space-tree :type git :host github :repo "chiply/space-tree")
  :config
  (space-tree-init))

If you try it and something breaks, open an issue. If something is missing, open one too. Workspace management doesn't need to be complicated. I'd like to keep it that way.

CN Diagrams: Architecture Diagrams That Scale With Your System

Charlie Holland — Wed, 18 Feb 2026 20:25:00 GMT

1. Introduction architectureDiagrams architecture

Figure 1: JPEG produced with DALL-E 4o

Every software organization eventually confronts the same uncomfortable question: where is the architecture diagram?

The answer is usually disappointing. There's a Lucidchart from three years ago that nobody updated after the microservices migration. There's a whiteboard photo in Confluence that predates half the current team. There's a Mermaid diagram in a README that shows four services when the system now has forty. The architecture exists in the heads of senior engineers who joined before the last reorg, and getting them in a room together is harder than shipping a feature.

This isn't a tooling problem in isolation – it's a workflow problem. Traditional diagramming tools force a choice between visual flexibility (drag boxes around) and maintainability (code that can be versioned). They impose rigid hierarchies that don't match how systems actually evolve. And they assume a single persona – either the engineer who thinks in code or the product manager who thinks in boxes – when real organizations need both¹.

CN is my attempt to solve this (try it out at CN Diagrams). It's a diagrams-as-code tool that renders interactive architecture diagrams with support for arbitrary levels of encapsulation, provides an intuitive domain specific language (DSL) that engineers can version control, and offers a GUI that non-technical stakeholders can actually use. The goal is a single source of truth that the entire organization can maintain.

2. Why "CN"? c4Model

The name is a nod to Simon Brown's C4 model, which popularized a hierarchical approach to architecture visualization. C4 stands for Context, Containers, Components, and Code – four levels of abstraction that let you zoom from a 10,000-foot view down to implementation details².

The C4 model was a revelation when I first encountered it. Finally, a structured way to think about architecture diagrams that acknowledged different audiences need different levels of detail! A CTO reviewing system boundaries doesn't need to see individual classes. A developer debugging a service doesn't need to see the marketing website.

But C4's fixed four-level hierarchy started to feel constraining. Real systems don't decompose neatly into exactly four layers. A Kubernetes deployment might have clusters containing namespaces containing deployments containing pods containing containers. An e-commerce platform might have domains containing bounded contexts containing aggregates containing entities. The abstraction depth varies by system, by team, and by what question you're trying to answer.

CN takes the core insight of C4 – hierarchical decomposition with zoom capabilities – and removes the artificial ceiling. The "N" represents arbitrary depth: as many levels of encapsulation as your system requires. Software is infinitely abstractable, and the diagramming tool shouldn't be the limiting factor.

3. The Graph Paradigm graphTheory complexity

Architecture diagrams are graphs. This sounds obvious, but the implications are profound.

A graph consists of nodes (components) and edges (relationships). When you modify a node, the only things that can possibly be affected are the edges connecting it to other nodes. This locality property is what makes graphs tractable for reasoning about complex systems.

Consider modifying a payment service in a large e-commerce platform. In a well-designed system with clear contracts, you don't need to understand the entire platform to make changes safely. You need to understand:

The edges into your service (what calls you, with what data)
The edges out of your service (what you call, with what data)

Everything else is irrelevant to your change. The recommendation engine, the inventory system, the customer support portal – they're all behind the graph's locality boundary. As long as you maintain your contracts (the edge definitions), changes stay contained.

This is why CN renders architectures as force-directed graphs using Cytoscape.js. The visual representation reinforces the mental model: nodes cluster naturally, edges reveal dependencies, and the structure emerges from relationships rather than arbitrary positioning³.

Of course, this only works when organizations invest time and elbow grease in defining, testing, and enforcing contracts between components – ESPECIALLY across bounded contexts…. Depending on the size of your existing system, this may be a significant cultural shift, and rather a lot of work.

But that's precisely the kind of discipline that architecture diagrams should encourage. When you can see that your service has fifteen incoming edges, you might think twice before making a breaking change. And luckily for the overwhelmed, there are ways to bootstrap out of the hardest parts of getting started (7).

4. The State of Architecture Tooling marketAnalysis

The architecture diagramming space splits roughly into two camps, each with significant limitations.

4.1. Visual-First Tools

Tools like Lucidchart, Miro, and diagrams.net prioritize visual flexibility. You drag boxes, draw arrows, and arrange things until they look right. This actually works really well for initial brainstorming and produces attractive outputs.

But these tools don't scale with organizational complexity. Changes require manual updates to visual layouts. There's no good story for version control – you're comparing screenshots or trusting proprietary diff algorithms. And when the diagram gets complex enough to need multiple views, you're maintaining multiple documents with no guarantee of consistency.

4.2. Code-First Tools

Tools like Mermaid, PlantUML, and Structurizr prioritize maintainability through code. Diagrams are defined in text files that can be versioned, diffed, and reviewed like any other code artifact.

The trade-off is flexibility. Layout control is limited – you're at the mercy of automatic algorithms that may not produce readable results. Each tool has its own DSL syntax, creating lock-in. And crucially, these tools are engineer-focused; asking a product manager to edit PlantUML syntax is asking for trouble, lol. ⁴

Structurizr deserves special mention as the most sophisticated option in this space. It's built around the C4 model and supports generating multiple views from a single model. But it inherits C4's four-level limitation, has a steeper learning curve, and still requires technical knowledge to maintain.

4.3. Where CN Fits

CN attempts to bridge both camps. The underlying representation is code – a YAML-based DSL that engineers can version control. But the primary interface is a visual editor with bidirectional sync: changes in the GUI update the code, and changes in the code update the GUI.

This dual-interface approach means the engineering team can maintain the diagram through pull requests while product and design can make updates through point-and-click interactions. Everyone works on the same artifact.

5. How CN Works

CN provides several capabilities that address the challenges outlined above.

5.1. Hierarchical Encapsulation

Nodes can contain other nodes to arbitrary depth. A "Payment Domain" node might contain "Payment Gateway", "Fraud Detection", and "Settlement" nodes. The "Fraud Detection" node might itself contain "ML Scoring", "Rules Engine", and "Manual Review" nodes. There's no artificial limit.

The UI provides expand/collapse controls at each level, letting viewers drill into areas of interest while keeping the rest of the diagram manageable. This is the zoom capability from C4, generalized.

5.2. Bidirectional Editing

The DSL editor and visual canvas stay synchronized. Add a node in the code, it appears on the canvas. Drag an edge in the canvas, the code updates. This eliminates the choice between maintainability and accessibility – you get both.

5.3. Real-Time Visualization

Changes render immediately. There's no compile step, no waiting for diagram generation. This tight feedback loop makes iterative design natural.

5.4. Example Templates

CN ships with several example architectures – Simple Web App, E-Commerce Platform, Cloud Platform, Event-Driven Architecture, FinTech Platform – that demonstrate patterns and provide starting points for new diagrams.

You can try CN directly at the CN Diagrams page on my blog.

6. Benefits productivity maintainability

Adopting CN – or any architecture documentation discipline – provides concrete benefits to engineering organizations.

6.1. Accelerated Onboarding

New team members can explore the system visually before diving into code. The hierarchical structure provides natural learning paths: start with the high-level context, then drill into your team's domain, then into specific services. This is dramatically faster than assembling mental models from scattered README files and tribal knowledge.

6.2. Reduced Coordination Overhead

When everyone references the same diagram, discussions about system changes become more productive. Instead of "I think we have a service that handles X," you can point to specific nodes and edges. Architecture review meetings can focus on proposed changes rather than establishing baseline understanding.

6.3. Impact Analysis

The graph structure makes dependency analysis explicit. Before modifying a service, you can inspect its edges to understand what might be affected. This doesn't replace thorough testing, but it does reduce surprise.

6.4. Documentation That Stays Current

Because the diagram lives in version control and updates are simple (either GUI or code), there's a realistic chance of keeping it accurate. Contrast this with documentation that requires a dedicated effort to update – it will always drift.

7. Getting Started bootstrap ai

The hardest part of architecture documentation is the initial investment. Mapping an existing system is tedious work, and teams are usually too busy building features to spend hours, let alone weeks, drawing boxes.

This is where AI assistance becomes valuable. LLMs excel at understanding structured code, and CN's DSL is exactly that – structured code. An AI agent can crawl a codebase, identify services and their relationships, and generate an initial CN diagram as a starting point.

The workflow looks like this:

Point an agent at your GitHub repository (or local codebase)
The agent analyzes directory structure, imports, API calls, and configuration
It generates a CN DSL file representing the discovered architecture
Engineers review and refine the generated diagram
The refined diagram becomes the maintained source of truth

The generated diagram won't be perfect. AI agents make mistakes, and they can only discover relationships that are explicit in code. But a 70% accurate starting point that takes minutes to generate is more useful than a blank canvas that takes weeks to fill. This first-pass strategy lowers the barrier to getting started with architecture documentation.

This bootstrap approach leverages diagrams-as-code in a way that visual tools can't match. You can't ask an AI to drag boxes to the right positions in Lucidchart (at least, not yet). But you can absolutely ask it to generate structured YAML that describes your system's components and relationships. In fact, LLMs are phenomenally good at generating and understanding structured text, and YAML is a great candidate.

8. Contributing openSource

CN is open source under the MIT license. The source code is available at github.com/chiply/cn-diagrams.

8.1. Tech Stack

For those interested in contributing, CN is built with:

SvelteKit - Application framework
Cytoscape.js - Graph rendering engine
CodeMirror - DSL editor component
YAML - DSL format for diagram definitions
Vercel - Deployment platform

The codebase is TypeScript throughout, with Svelte 5 runes for reactivity.

8.2. How to Contribute

Contributions are welcome in several forms:

Bug Reports: If something doesn't work as expected, open an issue with steps to reproduce. Include your browser and any error messages from the console.

Feature Requests: Have an idea for improvement? Open an issue describing the use case and proposed solution. Discussion before implementation helps ensure alignment.

Pull Requests: For code contributions, fork the repository, create a feature branch, and submit a PR. Please include tests for new functionality and ensure existing tests pass.

Documentation: Improvements to README, inline comments, or example diagrams are valuable contributions that don't require deep code knowledge.

The project is young, and there's significant opportunity to shape its direction. Community feedback on what works, what doesn't, and what's missing will determine where CN goes next.

9. Conclusion

Architecture diagrams shouldn't be artifacts that exist for compliance or decoration. They should be living documents that help teams understand, communicate about, and evolve their systems.

CN is an attempt to make that practical by removing the barriers that cause architecture documentation to become stale: the rigid hierarchies that don't match real systems, the choice between maintainability and accessibility, and the assumption that only one persona – engineer or non-technical – will maintain the diagram.

Whether or not CN specifically fits your needs, I hope the ideas resonate: graphs as the fundamental model for system relationships, arbitrary encapsulation depth over fixed hierarchies, and dual interfaces that serve different personas working on the same artifact.

Try it at CN Diagrams. Browse the source at github.com/chiply/cn-diagrams. If you build something interesting or have feedback, I'd love to hear about it.

10. socials

11. tldr

*tl;dr: CN is a new open-source architecture diagramming tool that bridges the gap between code-based maintainability and visual accessibility. The problem is universal: architecture diagrams become stale because traditional tools force teams to choose between drag-and-drop flexibility (which doesn't version control) and code-based definitions (which non-engineers can't edit). CN extends Simon Brown's C4 model by removing the four-level hierarchy limit – the "N" represents arbitrary depth, letting you zoom from system context down to any level of detail your architecture requires.

Architecture diagrams are fundamentally graphs, and CN embraces this with force-directed layouts that reveal natural clustering and dependencies. This locality property means you only need to understand immediate connections when making changes, not the entire system. Current tools fall into two camps: visual-first options like Lucidchart that don't scale, and code-first options like Mermaid that alienate non-technical users. CN solves this with bidirectional editing – changes in the YAML-based DSL update the visual canvas, and GUI edits update the code.

Key features include hierarchical encapsulation (nodes can contain nodes indefinitely), real-time visualization with no compile step, and example templates for common architectures. The payoff is concrete: faster onboarding as new engineers explore visually, reduced coordination overhead with a single source of truth, explicit dependency analysis through the graph structure, and documentation that actually stays current because it's easy to update.

The bootstrap strategy leverages AI to crawl codebases and generate initial diagrams, lowering the barrier to adoption – a 70% accurate starting point beats a blank canvas. CN is MIT-licensed and built with SvelteKit, Cytoscape.js, and CodeMirror, welcoming contributions from bug reports to pull requests. Try it at the CN Diagrams page or explore the source at github.com/chiply/cn-diagrams.

Footnotes:

This tension – between engineers who want code and stakeholders who want visuals – is everywhere in software documentation. CN isn't the only tool trying to bridge it, but it's opinionated about doing so through bidirectional sync rather than separate artifacts.

If you're not familiar with C4, Simon Brown's website is the canonical reference. The model has influenced how an entire generation of architects thinks about documentation. Brown also created Structurizr, the most sophisticated C4-focused tool.

In fact, CN intentionally protects the engineer/designer against this arbitrtary positioning, and renders the diagram in such a way that it is determistic based on the graph structure. This is important for maintainability, as it prevents users from needing to manually rearrange nodes when the underlying structure changes, and pledges a relatively consistent layout over time.

⁴

By the way, asking software engineers to edit visual diagrams is also asking for trouble 😉.

The Schema Language Question: Avro, JSON Schema, Protobuf, and the Quest for a Single Source of Truth

Charlie Holland — Tue, 17 Feb 2026 15:26:00 GMT

1. About dataModelling schemaLanguages

Figure 1: JPEG produced with DALL-E 4o

The competent programmer is fully aware of the strictly limited size of his own skull;
therefore he approaches the programming task in full humility,
and among other things he avoids clever tricks like the plague.
—Edsger W. Dijkstra, The Humble Programmer (1972)

Keep Dijkstra's words in mind as you read. This entire post – every schema language comparison, every trade-off analysis, every design decision – is really about one question: do we trust our own cleverness, or do we build systems that acknowledge its limits?

This post is the second installment in a series on data modelling in modern software systems. The companion post established the Model Everywhere Problem – the uncomfortable reality that data models live in your application code, your APIs, your message queues, your databases, your documentation, and your tests, all simultaneously. That post asked: "Given these models exist everywhere, how do we test them systematically?"

If you're defining models in Python, Java, Go, and TypeScript – you don't have one model. You have four. Four that will drift apart, silently, inevitably, until something breaks in production on a Friday evening.

This post asks the antecedent question: how do we express those models in a portable, standard format?

The answer matters more than most teams realize.

If you're defining models in Python (Pydantic), Java (POJOs), Go (structs), and TypeScript (interfaces) – you don't have one model. You have four. Four that will drift apart, silently, inevitably, until something breaks in production on a Friday evening.

Schema languages – Avro, JSON Schema, Protocol Buffers, and their kin – exist to solve exactly this problem. They provide a single, language-agnostic source of truth from which all language-specific representations can be generated. This post is a deep technical comparison of the three dominant schema languages, a survey of the broader landscape, and (because I can't help myself) a speculative design for the ideal Universal Schema Language (USL) that doesn't exist yet.

1.1. Executive Summary

Schema languages provide a language-agnostic single source of truth for data models. Protobuf excels at performance-critical RPC, Avro at schema-evolving event streaming, and JSON Schema at web API validation. Choose based on your primary use case, not on which one your favorite tech influencer recommends.

Modern systems are polyglot. A typical data pipeline might involve Python ingestion, Go microservices, TypeScript frontends, and Java analytics – all sharing data models. When models are defined independently in each language, they drift. Silently. The companion post documented the combinatorial explosion of testing these models. But testing assumes the models agree in the first place. We need a schema language that defines models once, generates code for every target language, supports schema evolution without breaking consumers, and integrates with existing toolchains. What's more, reducing the definition space for your models will greatly mitigate the combinatorial explosion entailed in testing multiple schemas together.

This article covers:

Section	Purpose
Single Source of Truth	Motivates the need with real-world failure modes
Why Not Pydantic / Zod?	Addresses the "but my language has X" objection
The Landscape	Surveys 20+ schema languages by category
Protobuf, Avro, JSON Schema	Deep technical analysis of the three dominant options
Head-to-Head	Feature matrix, decision guide, benchmarks
War Stories	Real-world failures from schema drift
Ecosystem Unlocked	What you gain beyond just "types"
Ideal Language	A speculative design combining the best of all three

After reading, you'll be able to choose the right schema language for your use case; articulate why language-specific alternatives aren't sufficient; understand the trade-offs between performance; flexibility, and ecosystem maturity; and evaluate new schema languages as they emerge.

2. Why a Single Source of Truth? architecture ddd

Let me spin a yarn about two technology organizations.

Organization A builds an e-commerce platform. The product team defines the Order model. The backend team implements it in Go. The frontend team implements it in TypeScript. The data team implements it in Python. The mobile team implements it in Kotlin. Four teams, four languages, four definitions of "what an Order looks like."

On Monday, the product team adds a discountType field with three possible values: PERCENTAGE, FIXED, BOGO. The backend team picks it up in the next sprint. The frontend team gets to it two weeks later. The data team doesn't hear about it until a pipeline breaks. The mobile team ships an update a month later.

For those intervening weeks, the system is in a state of model drift – different parts of the system disagree about what an Order is. This isn't a hypothetical. This is Tuesday.

Organization B builds a similar platform but starts with a schema language. They define Order once, in a standard schema language like a .proto file (or .avsc, or JSON Schema). When the product team adds discountType, it's added to the schema file. A CI pipeline generates updated Go structs, TypeScript interfaces, Python dataclasses, and Kotlin data classes. All four teams get the change simultaneously. If anyone sends a message with the old schema, the generated code rejects it at deserialization time.

The difference bettween Org A and Org B isn't subtle. It's the difference between "we have one model expressed in four languages" and "we have four models that happen to share a name."

2.1. Model Drift: The Silent Killer

Model drift is insidious because it doesn't cause immediate, obvious failures. Instead, it produces silent data corruption – the most expensive class of bugs in software engineering¹.

Consider what happens when Organization A's Go backend starts sending orders with discountType: "BOGO" but the Python data pipeline doesn't know about that enum variant:

The Python deserializer encounters an unknown value
Depending on the library, it either silently drops the field, coerces it to a default, or raises an exception
If it drops the field, every downstream analytics report under-counts BOGO discounts
If it coerces to a default, reports show phantom PERCENTAGE discounts that don't exist
If it raises an exception, the pipeline crashes – the best-case scenario, because at least someone notices

Here's what this looks like in code. The Go backend sends a perfectly valid order:

// Go backend (v2 of the model -- has discount_type)
order := map[string]interface{}{
    "id":            "ord_abc123",
    "customer_id":   "cust_456",
    "items":         []Item{{ProductID: "SKU-1", Qty: 2, Price: 29.99}},
    "discount_type": "BOGO",
    "total":         29.99,
}
payload, _ := json.Marshal(order)
kafka.Produce("orders", payload)

The Python pipeline consumes it with an older model that doesn't know about BOGO:

# Python pipeline (v1 of the model -- no discount_type)
@dataclass
class Order:
    id: str
    customer_id: str
    items: list
    total: float

raw = kafka.consume("orders")
data = json.loads(raw)
order = Order(**{k: v for k, v in data.items() if k in Order.__dataclass_fields__})
# discount_type="BOGO" is silently dropped. No error. No warning.
# Downstream: this order counted as "no discount applied"

The Python pipeline has no exception. No log. The data looks correct in both systems – they just disagree about whether this order had a discount.

Issues 1 and 2 are the scary ones. The data looks plausible. Nobody questions it. Business decisions get made on corrupted data. Weeks or months later, someone notices the numbers don't add up. Now you're debugging a data integrity issue across four codebases, with weeks of corrupted data that may need to be replayed.

This is not an edge case. A 2020 survey by Monte Carlo Data found that 77% of data engineering teams reported data quality incidents in the previous year, with schema changes cited as a leading root cause².

2.2. With and Without a Single Source of Truth

The two approaches, visualized:

graph TB
    subgraph "Without SSOT: Manual Synchronization"
        direction TB
        PM1["Product Team
defines Order spec"]
        GO1["Go Backend
type Order struct{...}"]
        TS1["TypeScript Frontend
interface Order {...}"]
        PY1["Python Pipeline
class Order(BaseModel)"]
        KT1["Kotlin Mobile
data class Order(...)"]

        PM1 -->|"week 1"| GO1
        PM1 -->|"week 3"| TS1
        PM1 -->|"month 2"| PY1
        PM1 -->|"month 3"| KT1

        GO1 -.-|"❌ drift"| TS1
        TS1 -.-|"❌ drift"| PY1
        PY1 -.-|"❌ drift"| KT1
    end

graph TB
    subgraph "With SSOT: Generated from Schema"
        direction TB
        SCHEMA["order.proto
(Single Source of Truth)"]
        CI["CI Pipeline
protoc / buf generate"]
        GO2["Go Backend
order.pb.go ✅"]
        TS2["TypeScript Frontend
order_pb.ts ✅"]
        PY2["Python Pipeline
order_pb2.py ✅"]
        KT2["Kotlin Mobile
Order.kt ✅"]

        SCHEMA --> CI
        CI -->|"simultaneous"| GO2
        CI -->|"simultaneous"| TS2
        CI -->|"simultaneous"| PY2
        CI -->|"simultaneous"| KT2
    end

The difference is structural, not procedural. With a single source of truth, model drift isn't prevented by discipline or process – it's prevented by architecture. You can't drift from the schema because your code is generated from it. The generated code is the schema, expressed in your language.

2.3. The Cost of Not Having a SSOT

The cost of model drift across several dimensions:

Dimension	Without SSOT	With SSOT
Time to propagate a schema change	Days to months (depends on team velocity)	Minutes (CI pipeline)
Probability of drift	Increases with number of consumers	Zero (by construction)
Cost of a schema mismatch	Silent data corruption → hours/days to diagnose	Compile error or deserialization failure → seconds
Documentation accuracy	Stale within days of writing	Auto-generated, always current
Onboarding a new language	Copy-paste and hope	Add a code-gen target
Cross-team communication	"Hey, did you update the Order model?" (Slack)	PR review on a .proto file (code review)

Toolchains don't forget.

The SSOT approach converts human coordination problems into toolchain problems. Toolchains don't forget. Toolchains don't go on vacation. Toolchains don't interpret an ambiguous Confluence page differently than you did.

3. Why Not Just Use Pydantic / Zod / Your Framework's Types? python validation antipattern

If you're reading this, you might be thinking: "I already have Pydantic (Python), Zod (TypeScript), serde (Rust), or Jackson (Java). My framework gives me types, validation, serialization. Why do I need a separate schema language?"

It's a fair question. These are excellent libraries. The issue isn't with any of them – it's with the assumption that a language-specific solution can serve as a language-agnostic single source of truth. I'll use Pydantic as the case study because it's the most full-featured example of this pattern, but the argument applies equally to every language-specific modelling library.

3.1. The Allure of Pydantic

Credit where it's due – Pydantic is remarkable:

from pydantic import BaseModel, Field, field_validator
from enum import Enum
from typing import Optional
from datetime import datetime


class DiscountType(str, Enum):
    PERCENTAGE = "PERCENTAGE"
    FIXED = "FIXED"
    BOGO = "BOGO"


class OrderItem(BaseModel):
    product_id: str
    quantity: int = Field(ge=1)
    unit_price: float = Field(gt=0)

    @field_validator("quantity")
    @classmethod
    def reasonable_quantity(cls, v: int) -> int:
        if v > 10_000:
            raise ValueError("Suspicious quantity")
        return v


class Order(BaseModel):
    id: str
    customer_id: str
    items: list[OrderItem]
    discount_type: Optional[DiscountType] = None
    discount_value: Optional[float] = None
    created_at: datetime
    total: float = Field(ge=0)

In just 30 lines of code, Pydantic gives you type checking, validation, JSON serialization, OpenAPI schema generation, and IDE autocompletion. That's genuinely impressive.

3.2. The Portability Problem

The trouble starts when your Order needs to cross a language boundary:

# Python team: "Here's our schema"
schema = Order.model_json_schema()

{
  "$defs": {
    "DiscountType": {
      "enum": ["PERCENTAGE", "FIXED", "BOGO"],
      "type": "string"
    },
    "OrderItem": {
      "properties": {
        "product_id": {"type": "string"},
        "quantity": {"minimum": 1, "type": "integer"},
        "unit_price": {"exclusiveMinimum": 0, "type": "number"}
      },
      "required": ["product_id", "quantity", "unit_price"],
      "type": "object"
    }
  },
  "properties": {
    "id": {"type": "string"},
    "customer_id": {"type": "string"},
    "items": {
      "items": {"$ref": "#/$defs/OrderItem"},
      "type": "array"
    },
    "discount_type": {
      "anyOf": [{"$ref": "#/$defs/DiscountType"}, {"type": "null"}],
      "default": null
    },
    "total": {"minimum": 0, "type": "number"}
  },
  "required": ["id", "customer_id", "items", "created_at", "total"],
  "type": "object"
}

Now hand this JSON Schema to your Go team and tell them to implement it. Several things go wrong:

The @field_validator is lost. The "suspicious quantity" check exists only in Python. The Go team doesn't know about it unless someone writes a Confluence page.
datetime serialization is ambiguous. Is it ISO 8601? Unix timestamp? Python's default? The JSON Schema says string with no format hint because Pydantic's JSON Schema export doesn't always capture datetime formatting.
Optionality semantics differ. Python's Optional[DiscountType] = None means "the field can be absent or null." Go's *DiscountType means "the field can be nil" but JSON encoding/decoding may handle zero-values differently.
The source of truth is Python code. If the Go team needs to add a field, they can't modify the Python model directly – they file a ticket with the Python team and wait.

3.3. The Validator Trap

The deeper issue is what I call the Validator Trap: confusing validation logic (which is inherently language-specific) with schema definition (which should be language-agnostic).

Pydantic elegantly combines both concerns in a single class. This is a feature within a Python codebase and an anti-pattern across a polyglot system:

Concern	Language-Specific?	Example
Field types and structure	No — this should be in the schema	`quantity: int`
Field constraints (ranges, patterns)	Partially — basic constraints are portable	`Field(ge=1)`
Custom validation logic	Yes — inherently language-specific	`@field_validator`
Serialization format	No — should be schema-defined	JSON, MessagePack, etc.
Default values	No — should be in the schema	`= None`

When you use Pydantic as your schema language, you're coupling your schema definition to Python. Every other language needs to reverse-engineer the schema from Pydantic's JSON Schema export, losing validation logic in the process.

When you use Pydantic as a code-generation target – generating Pydantic models from a language-agnostic schema – you get the best of both worlds. The schema is portable, and you can add Python-specific validation on top of the generated base class. Gotta love wrappers :o)

3.4. The Right Role for Pydantic

Pydantic is best understood as a consumer of schemas, not a source of schemas:

graph LR
    PROTO["order.proto"] -->|"buf generate"| PY_BASE["order_pb2.py
(generated)"]
    PY_BASE -->|"wrap"| PYDANTIC["OrderModel(BaseModel)
+ @field_validator
+ custom logic"]
    PROTO -->|"buf generate"| GO["order.pb.go
(generated)"]
    PROTO -->|"buf generate"| TS["order.ts
(generated)"]

In this architecture:

The .proto file is the single source of truth for structure and basic types
Generated Python code provides the base types
Pydantic wraps those types with Python-specific validation
Go and TypeScript get their own generated code with language-idiomatic validation

This isn't anti-Pydantic – it's pro-separation-of-concerns. Use schema languages for what the data looks like. Use language-specific tools for how to validate it.

3.5. What About datamodel-code-generator?

There's a popular tool called datamodel-code-generator that generates Pydantic models from JSON Schema, OpenAPI, and other schema formats. In my opinion, this is exactly the right pattern – schema language as source of truth, Pydantic as consumer.

# Generate Pydantic models from JSON Schema
datamodel-codegen \
  --input order.schema.json \
  --output models.py \
  --output-model-type pydantic_v2.BaseModel

The generated code is clean, type-safe, and stays in sync with the schema. You can extend the generated classes with custom validators. This is the pattern I recommend for Python teams in polyglot environments.

The same principle applies to every language-specific modelling library: Zod (TypeScript), serde (Rust), Jackson (Java). They're all excellent consumers of schemas. None of them should be the source.

4. The Landscape of Schema Languages standards taxonomy

Before diving deep into the three dominant schema languages, let's survey the broader landscape. The world of schema and data modelling languages is richer than most developers realize.

4.1. Taxonomy

Schema languages can be categorized along several axes:

Category	Languages	Primary Use Case
Binary Serialization	Protocol Buffers, Apache Thrift, Cap'n Proto, FlatBuffers, MessagePack	High-performance RPC, storage
Schema-Encoded Serialization	Apache Avro, Apache Parquet (schema)	Event streaming, data lake storage
Validation-Oriented	JSON Schema, XML Schema (XSD), RELAX NG	API validation, document validation
API Definition	OpenAPI/Swagger, GraphQL SDL, gRPC (via Protobuf), AsyncAPI	HTTP APIs, event-driven APIs
Data Description	ASN.1, CDDL, Ion Schema	Telecom, IoT, databases
Type System	TypeScript (types), Zod, io-ts, Pydantic, Marshmallow	Language-specific validation
Database Schema	SQL DDL, Prisma, Drizzle	Database modelling
Configuration	CUE, Dhall, Jsonnet, KCL	Configuration validation

4.2. The Landscape Visualized

Plotting these languages across time and adoption reveals the waves of innovation:

The bubble chart reveals several patterns. The binary serialization cluster (Protobuf, Thrift, FlatBuffers, Cap'n Proto) spans 2007-2014 and reflects a period of intense experimentation in high-performance serialization driven by the needs of companies like Google, Facebook, and game studios. The validation cluster (JSON Schema, OpenAPI) emerged later but achieved massive adoption because they target the ubiquitous HTTP/JSON ecosystem rather than specialized binary formats. The type system explosion (TypeScript, Zod, Pydantic) is the most recent wave, driven by developers wanting schema-like guarantees within their language of choice.

Note that TypeScript Types appears as an outlier at 101k stars – this reflects TypeScript's enormous adoption as a language, not as a schema language per se. It's included because TypeScript's type system is frequently used as a de facto schema definition within TypeScript-only codebases, but it isn't portable across languages the way Protobuf, Avro, or JSON Schema are.

4.3. A Closer Look at the Categories

4.3.1. Binary Serialization Languages

These languages define both the schema and a compact binary wire format. They prioritize serialization speed and small message sizes.

Language	Creator	Wire Format	Schema in Payload?	Code Gen
Protocol Buffers	Google	Custom binary	No	Yes (protoc)
Thrift	Facebook → Apache	Custom binary	No	Yes (thrift)
Cap'n Proto	Sandstorm	Zero-copy binary	No	Yes (capnpc)
FlatBuffers	Google	Zero-copy binary	No	Yes (flatc)

Key insight: These formats do not include the schema in the serialized payload. Both sender and receiver must have the schema at compile time. This makes them fast but inflexible – you can't deserialize a message without knowing which schema produced it.

4.3.2. Schema-Encoded Serialization

Avro takes a fundamentally different approach: the writer's schema is transmitted alongside (or registered separately from) the data. This enables schema resolution – the reader can use a different (compatible) schema than the writer.

This is the key architectural difference between Avro and Protobuf, and it explains why Avro dominates in data engineering (where schemas evolve frequently and consumers may lag behind producers) while Protobuf dominates in RPC (where both sides are typically deployed in lockstep).

4.3.3. Validation-Oriented Languages

JSON Schema and its descendants focus on validating data that's already in a text format (JSON, YAML). They don't define a binary wire format – they describe what valid JSON looks like. This makes them ideal for HTTP APIs where JSON is the transport format, but less suitable for high-throughput binary protocols.

4.3.4. API Definition Languages

OpenAPI, GraphQL SDL, and AsyncAPI are higher-level – they define not just the data models but also the operations, endpoints, and protocols. They typically embed or reference a schema language for the data modelling portions.

Language	Transport	Schema For Data
OpenAPI	HTTP/REST	JSON Schema (subset)
GraphQL SDL	HTTP/GraphQL	Its own type system
gRPC	HTTP/2	Protocol Buffers
AsyncAPI	Message queues	JSON Schema (subset)

4.4. The Big Three

For the remainder of this article, we'll focus on the three schema languages that have achieved the broadest adoption and deepest ecosystem integration:

Protocol Buffers (Protobuf) – Google's schema language for high-performance RPC
Apache Avro – The Hadoop/Kafka ecosystem's schema language for data engineering
JSON Schema – The web's schema language for API validation

These three represent distinct design philosophies, serve different primary use cases, and have evolved in fascinatingly different directions. Understanding their differences deeply will equip you to make the right choice for your system.

A note on what's not included: GraphQL SDL is conspicuously absent. While GraphQL has massive adoption, it's an API definition language – it defines operations, endpoints, and query semantics, not just data models. Its type system is tightly coupled to the GraphQL query execution model, making it less useful as a general-purpose schema language for serialization, storage, or cross-protocol data modelling. GraphQL schemas describe how to query data; Protobuf, Avro, and JSON Schema describe how to model it.

5. Protobuf Deep Dive protobuf google grpc

5.1. History and Origin

Protocol Buffers were developed at Google in 2001 by Jeff Dean, Sanjay Ghemawat, and others³. The problem was characteristically Googley: Google's internal RPC system needed a way to define service interfaces that could be compiled into efficient serialization code across dozens of languages, while supporting backward-compatible schema evolution across thousands of microservices.

The original internal version (proto1) was never open-sourced. Proto2 was released publicly in July 2008. Proto3, a significant simplification, arrived in 2016. Today, Protobuf is the foundation of gRPC, Google's open-source RPC framework, and is used by companies including Uber, Netflix, Square, Lyft, and Dropbox.

An important context: Google internally has a monorepo with tens of thousands of .proto files. The Protobuf ecosystem was designed for this scale. Features that seem over-engineered for a 10-person startup make perfect sense when you're managing schema evolution across 25,000+ engineers.

5.2. How Protobuf Works

Protobuf uses an Interface Definition Language (IDL) to describe message types:

syntax = "proto3";

package ecommerce.v1;

import "google/protobuf/timestamp.proto";

enum DiscountType {
  DISCOUNT_TYPE_UNSPECIFIED = 0;
  DISCOUNT_TYPE_PERCENTAGE = 1;
  DISCOUNT_TYPE_FIXED = 2;
  DISCOUNT_TYPE_BOGO = 3;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

message Order {
  string id = 1;
  string customer_id = 2;
  repeated OrderItem items = 3;
  optional DiscountType discount_type = 4;
  optional double discount_value = 5;
  google.protobuf.Timestamp created_at = 6;
  double total = 7;
}

The numbers (1, 2, 3, …) are field tags – they identify each field in the binary encoding. This is a critical design choice. Unlike JSON (where fields are identified by string names), Protobuf identifies fields by integer tags. This means:

Renaming a field is a non-breaking change (the tag stays the same)
Binary messages are compact (an integer tag is 1-2 bytes vs. a string name that could be dozens)
Field ordering in the .proto file doesn't matter – only the tags matter

5.3. The Compilation Pipeline

Protobuf's compilation model is one of its most distinctive features:

graph LR
    PROTO[".proto files"] --> PROTOC["protoc
(compiler)"]

    PROTOC -->|"--go_out"| GO["Go structs
+ marshal/unmarshal"]
    PROTOC -->|"--python_out"| PY["Python classes
+ serialization"]
    PROTOC -->|"--java_out"| JAVA["Java classes
+ builders"]
    PROTOC -->|"--ts_out"| TS["TypeScript
interfaces + codec"]
    PROTOC -->|"--swift_out"| SWIFT["Swift structs
+ Codable"]

    style PROTO fill:#2BCDC1,color:#000
    style PROTOC fill:#FFB347,color:#000

The protoc compiler reads .proto files and generates language-specific code via plugins. Each plugin produces idiomatic code for its target language – Go gets structs with exported fields, Java gets classes with builders, Python gets classes with descriptors.

This is the single source of truth in action. One .proto file generates code for every language your system uses. The generated code is checked into version control (or generated in CI), and every team consumes the same schema.

5.4. Proto2 vs Proto3

The transition from proto2 to proto3 was contentious. Proto3 made several simplifications that sparked debate:

Feature	Proto2	Proto3
Required fields	`required` keyword	Removed (all fields are implicitly optional)
Default values	User-specified	Type default (0, "", false, empty)
Field presence	Always tracked	Only tracked for `message` fields and `optional`
Unknown fields	Preserved	Preserved (changed in 3.5; originally discarded)
Enums	No zero-value requirement	Must have zero value (= UNSPECIFIED)

The removal of required was the most controversial change. Google learned the hard way that required fields are forever – once you deploy a required field, you can never remove it without breaking all existing consumers. Proto3's philosophy is "every field should be optional at the wire level; enforce business requirements in application code."

This is a pragmatic stance but it does create ambiguity. If a proto3 int32 field has value 0, is it explicitly set to zero, or was it absent from the message? Proto3 can't tell you – unless you mark the field optional (added back in proto3 syntax in 3.15) or wrap it in a google.protobuf.Int32Value wrapper.

5.5. The Buf Ecosystem

The rough edges of raw protoc led to the creation of Buf – a modern toolchain for Protocol Buffers. Buf provides:

Linting: Enforce style rules (e.g., field names must be snake_case, enums must have UNSPECIFIED zero value)
Breaking change detection: CI-integrated checks that fail if a schema change would break existing consumers
Code generation: A managed plugin ecosystem that replaces the fragile protoc plugin chain
Schema registry: The Buf Schema Registry (BSR) – a hosted registry for sharing .proto files

# buf.yaml - Project configuration
version: v2
modules:
  - path: proto
    name: buf.build/myorg/ecommerce
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE

# buf.gen.yaml - Code generation configuration
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/protocolbuffers/python
    out: gen/python
  - remote: buf.build/bufbuild/es
    out: gen/typescript

Buf's breaking change detection is particularly valuable. It compares the current schema against a previous version (from the BSR or a git reference) and flags changes that would break wire compatibility:

$ buf breaking --against 'buf.build/myorg/ecommerce'
proto/order.proto:15:3:Field "4" on message "Order" changed type from "string" to "int32".
proto/order.proto:22:1:Previously present field "7" with name "total" on message "Order" was deleted.

5.6. Protobuf Strengths and Weaknesses

Strengths	Weaknesses
Excellent performance (small messages, fast ser/de)	No self-describing messages (need schema to decode)
Mature ecosystem (20+ years, Google-backed)	Proto3 loses field presence by default
Backward and forward compatible evolution	Human-unreadable binary format
First-class gRPC integration	No built-in validation constraints
Strong code generation across 10+ languages	Steep learning curve for schema design
Buf ecosystem modernizes the toolchain	No union types (`oneof` is limited)

Protobuf's sweet spot is high-performance RPC between services you control. When both the producer and consumer are deployed from the same CI pipeline, Protobuf's compile-time schema agreement is a superpower. When consumers lag behind producers (as in data pipelines), Protobuf's lack of self-describing messages becomes a liability.

6. Avro Deep Dive avro hadoop kafka

6.1. History and Origin

Apache Avro was created by Doug Cutting (creator of Hadoop and Lucene) in 2009 as a serialization system for the Hadoop ecosystem⁴. The motivation was specific: Hadoop's existing serialization system (Writables) was Java-only and had no schema evolution support. Thrift and Protobuf existed but required code generation, which Cutting considered an unnecessary coupling between the schema and the processing code.

Avro's key design insight was that the schema should travel with the data, enabling dynamic typing and schema evolution without code generation. This was radical at the time and is the fundamental architectural difference between Avro and Protobuf.

Avro became the de facto serialization format for the Hadoop ecosystem and, later, for Apache Kafka. Confluent's Schema Registry – arguably the most widely used schema registry in the world – was built specifically for Avro before adding Protobuf and JSON Schema support.

6.2. How Avro Works

Avro schemas are defined in JSON (or the more readable Avro IDL):

{
  "type": "record",
  "name": "Order",
  "namespace": "com.ecommerce",
  "fields": [
    {"name": "id", "type": "string"},
    {"name": "customer_id", "type": "string"},
    {
      "name": "items",
      "type": {
        "type": "array",
        "items": {
          "type": "record",
          "name": "OrderItem",
          "fields": [
            {"name": "product_id", "type": "string"},
            {"name": "quantity", "type": "int"},
            {"name": "unit_price", "type": "double"}
          ]
        }
      }
    },
    {
      "name": "discount_type",
      "type": ["null", {"type": "enum", "name": "DiscountType",
                         "symbols": ["PERCENTAGE", "FIXED", "BOGO"]}],
      "default": null
    },
    {
      "name": "discount_value",
      "type": ["null", "double"],
      "default": null
    },
    {"name": "created_at", "type": {"type": "long", "logicalType": "timestamp-millis"}},
    {"name": "total", "type": "double"}
  ]
}

Several things stand out compared to Protobuf:

Schemas are data (JSON), not a custom IDL. This means schemas can be stored in databases, transmitted over HTTP, and processed by any JSON-capable tool.
Unions replace optionality. Instead of an optional keyword, Avro uses union types: ["null", "string"] means "either null or a string." This is more explicit but more verbose.
Field ordering matters. Unlike Protobuf (where field tags determine wire position), Avro encodes fields in the order they appear in the schema. There are no field tags – fields are identified by their position in the schema.
Default values are required for evolution. If you want to add a new field without breaking existing readers, it must have a default value. This is enforced by the schema, not by convention.

6.3. Avro IDL: A Friendlier Syntax

The JSON format is verbose, so Avro also supports an IDL that compiles to JSON:

// Avro IDL
@namespace("com.ecommerce")
protocol EcommerceProtocol {

  enum DiscountType {
    PERCENTAGE, FIXED, BOGO
  }

  record OrderItem {
    string product_id;
    int quantity;
    double unit_price;
  }

  record Order {
    string id;
    string customer_id;
    array items;
    union { null, DiscountType } discount_type = null;
    union { null, double } discount_value = null;
    @logicalType("timestamp-millis") long created_at;
    double total;
  }
}

This looks much closer to Protobuf's IDL. The key difference is that this IDL compiles to JSON, not to language-specific code. Code generation is available but optional – Avro can dynamically read any record if given the schema at runtime.

6.4. Writer Schema, Reader Schema, and Resolution

Avro's most powerful (and most confusing) feature is schema resolution⁵. When data is serialized, the writer's schema is recorded. When data is deserialized, the reader provides its own schema. Avro then resolves the two schemas, applying rules to handle differences:

sequenceDiagram
    participant Writer as Writer (v2)
    participant Storage as Kafka / File
    participant Registry as Schema Registry
    participant Reader as Reader (v3)

    Writer->>Registry: Register writer schema v2
    Registry-->>Writer: Schema ID: 42
    Writer->>Storage: [ID:42][binary payload]

    Reader->>Storage: Read message
    Storage-->>Reader: [ID:42][binary payload]
    Reader->>Registry: Fetch schema ID 42
    Registry-->>Reader: Writer schema v2
    Reader->>Reader: Resolve(writer=v2, reader=v3)
    Reader->>Reader: Deserialize with resolution

The resolution rules are:

Scenario	Rule
Writer has field, reader has field	Decode normally
Writer has field, reader doesn't	Ignore the field (forward compatibility)
Reader has field, writer doesn't	Use reader's default value (backward compatibility)
Reader has field with no default, writer doesn't	Error — incompatible schemas
Type promotion	`int` → `long`, `float` → `double` are allowed
Enum evolution	New symbols in reader: OK. New symbols in writer: decoded as default or error

This is profoundly different from Protobuf's approach. Protobuf achieves compatibility by keeping field tags stable – add new fields with new tags, never reuse old tags. Avro achieves compatibility by comparing schemas at read time and applying resolution rules. The trade-off:

Protobuf: Simpler mental model, but can't detect incompatibilities until runtime
Avro + Schema Registry: More complex, but incompatibilities are caught at registration time, before any data is written

6.5. Confluent Schema Registry

The Confluent Schema Registry is the operational backbone of Avro in production. It stores schemas, assigns IDs, and enforces compatibility rules:

# Register a new schema version
curl -X POST \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{\"type\":\"record\",\"name\":\"Order\",\"fields\":[...]}"}' \
  http://localhost:8081/subjects/orders-value/versions

# Check compatibility before registering
curl -X POST \
  -H "Content-Type: application/vnd.schemaregistry.v1+json" \
  --data '{"schema": "{...new version...}"}' \
  http://localhost:8081/compatibility/subjects/orders-value/versions/latest

Compatibility modes:

Mode	Rule	Use Case
BACKWARD	New schema can read old data	Consumers upgrade first
FORWARD	Old schema can read new data	Producers upgrade first
FULL	Both backward and forward	Any upgrade order
NONE	No compatibility checks	Development only

6.6. Avro Strengths and Weaknesses

Strengths	Weaknesses
Self-describing (schema travels with data)	Slower than Protobuf (field resolution overhead)
Schema resolution enables decoupled evolution	JSON schema format is verbose
Rich Kafka/Confluent ecosystem	Weaker code generation than Protobuf
Dynamic typing (no code gen required)	Union syntax is awkward (`["null", "string"]`)
Schema Registry catches incompatibilities early	Less adoption outside JVM/Python ecosystems
Compact binary format (smaller than JSON)	Logical types are limited

Avro's sweet spot is event streaming and data pipelines where producers and consumers evolve independently. When you have 50 Kafka consumers reading from the same topic, each potentially on a different schema version, Avro's schema resolution is essential. For synchronous RPC between services deployed together, Protobuf is likely a better fit.

7. JSON Schema Deep Dive jsonSchema validation web

7.1. History and Origin

JSON Schema began as a draft specification in 2009 by Kris Zyp⁶, inspired by XML Schema's ability to describe the structure of XML documents. The goal was deceptively simple: provide a vocabulary for describing the structure and validation constraints of JSON data.

Unlike Protobuf and Avro, JSON Schema emerged from the web developer community rather than from big tech infrastructure teams. It evolved through a series of IETF drafts, each adding features and refining semantics:

Draft	Year	Key Changes
Draft-00 to Draft-03	2009-2010	Initial specification, basic types
Draft-04	2013	`required` as array, `definitions`, `$ref`
Draft-06	2017	`const`, `contains`, `propertyNames`, boolean schemas
Draft-07	2018	`if=/=then=/=else`, `readOnly=/=writeOnly`, string formats
Draft 2019-09	2019	Renamed `$defs`, `unevaluatedProperties`, vocabulary system
Draft 2020-12	2020	`prefixItems`, dynamic references, stable specification

The draft evolution reflects a tension between simplicity (JSON Schema should be easy) and expressiveness (JSON Schema should handle real-world schemas). Draft-04 schemas are still widely encountered in the wild, meaning validators often need to support multiple draft versions simultaneously.

7.2. How JSON Schema Works

JSON Schema describes what valid JSON looks like:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ecommerce.example/schemas/order",
  "title": "Order",
  "description": "An e-commerce order",
  "type": "object",
  "required": ["id", "customer_id", "items", "created_at", "total"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^ord_[a-zA-Z0-9]{12}$",
      "description": "Unique order identifier"
    },
    "customer_id": {
      "type": "string",
      "minLength": 1
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/OrderItem" }
    },
    "discount_type": {
      "enum": ["PERCENTAGE", "FIXED", "BOGO"],
      "description": "Type of discount applied"
    },
    "discount_value": {
      "type": "number",
      "minimum": 0
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "total": {
      "type": "number",
      "minimum": 0
    }
  },
  "$defs": {
    "OrderItem": {
      "type": "object",
      "required": ["product_id", "quantity", "unit_price"],
      "properties": {
        "product_id": { "type": "string" },
        "quantity": { "type": "integer", "minimum": 1, "maximum": 10000 },
        "unit_price": { "type": "number", "exclusiveMinimum": 0 }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Notice the fundamental difference from Protobuf and Avro:

Validation constraints are first-class. pattern, minimum, maximum, minLength, minItems – these live in the schema itself, not in application code. Protobuf has no equivalent; Avro has limited support via logical types.
Human-readable format. JSON Schema is JSON describing JSON. No compilation step, no binary encoding, no code generation required.
No wire format. JSON Schema doesn't define how to serialize data – it defines what valid JSON looks like. The wire format is always JSON (or YAML, since YAML is a superset of JSON).
Self-referencing. The $ref keyword enables schema composition. Complex schemas can be built from reusable components.

7.3. The Validation Powerhouse

JSON Schema's validation capabilities are significantly richer than Protobuf or Avro:

{
  "type": "object",
  "properties": {
    "discount_type": { "enum": ["PERCENTAGE", "FIXED", "BOGO"] },
    "discount_value": { "type": "number", "minimum": 0 }
  },
  "if": {
    "properties": { "discount_type": { "const": "PERCENTAGE" } },
    "required": ["discount_type"]
  },
  "then": {
    "properties": {
      "discount_value": { "minimum": 0, "maximum": 100 }
    }
  },
  "else": {
    "if": {
      "properties": { "discount_type": { "const": "BOGO" } },
      "required": ["discount_type"]
    },
    "then": {
      "properties": {
        "discount_value": { "const": 0 }
      }
    }
  }
}

This schema says: "If discount type is PERCENTAGE, the value must be between 0 and 100. If discount type is BOGO, the value must be 0." Try expressing that in Protobuf or Avro – you can't. Those languages define structure; JSON Schema defines structure and constraints.

There's a flip side to this expressiveness. When a Protobuf field is wrong, the failure mode is simple: wrong type → deserialization error. When a JSON Schema if=/=then rule is wrong – say, someone writes maximum: 1 instead of maximum: 100 for the percentage constraint – the failure is a business logic bug encoded in the schema itself. Richer validation means richer failure modes. The schema becomes code, and code has bugs. This isn't an argument against JSON Schema's approach, but it means schemas with complex conditional logic need to be tested with the same rigor as application code.

7.4. JSON Schema and the AI Revolution

JSON Schema has found an unexpected second life in the AI/LLM era. When you call an LLM with function-calling or structured output capabilities, the tool definitions are JSON Schema:

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City and state, e.g., San Francisco, CA"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"]
        }
      },
      "required": ["location"]
    }
  }
}

OpenAI's function calling, Anthropic's tool use, Google's function declarations – they all use JSON Schema to constrain LLM outputs. This means JSON Schema has become the interface definition language for AI. The implications are profound:

Every AI agent that calls tools speaks JSON Schema
Structured output guarantees are enforced via JSON Schema validation
Schema-guided generation (constraining token sampling to produce valid JSON) relies on JSON Schema semantics

This wasn't in anyone's roadmap when JSON Schema was designed in 2009. It's a testament to the flexibility of JSON Schema that it works so well for a use case that didn't exist when it was created.

7.5. JSON Type Definition (JTD): The Alternative

It's worth mentioning JSON Type Definition (JTD) (RFC 8927), an alternative to JSON Schema that prioritizes code generation:

{
  "properties": {
    "id": { "type": "string" },
    "customer_id": { "type": "string" },
    "items": {
      "elements": {
        "properties": {
          "product_id": { "type": "string" },
          "quantity": { "type": "int32" },
          "unit_price": { "type": "float64" }
        }
      }
    },
    "discount_type": { "enum": ["PERCENTAGE", "FIXED", "BOGO"] },
    "total": { "type": "float64" }
  },
  "optionalProperties": {
    "discount_value": { "type": "float64" }
  }
}

JTD makes a deliberate trade-off: less expressive than JSON Schema (no if=/=then, no pattern, no minimum) but unambiguously code-generatable. Every JTD schema maps cleanly to types in Go, Java, Python, TypeScript, and other languages. JSON Schema's expressiveness actually hinders code generation because many validation concepts (regex patterns, conditional schemas) have no natural mapping to type systems.

7.6. JSON Structure: Structured Outputs for LLMs

Anthropic's JSON Structure feature takes JSON Schema usage a step further. Rather than just validating LLM output after generation, JSON Structure constrains the generation process itself to guarantee valid JSON output on every call.

This is a subtle but important distinction. Traditional validation is post-hoc – you generate output, then check if it's valid. JSON Structure is constructive – the schema guides token sampling so that invalid outputs are never generated. The result is 100% reliability for structured data extraction, not "usually works with retry logic."

This development positions JSON Schema as the bridge between human-authored APIs and AI-generated responses – a unifying schema language for both traditional and AI-powered systems.

7.7. JSON Schema Strengths and Weaknesses

Strengths	Weaknesses
Rich validation constraints (pattern, range, conditional)	No binary format (JSON is text, inherently slower)
Human-readable (JSON describing JSON)	Large messages (string keys, no compression)
Universal web adoption (OpenAPI, AI tools)	Schema evolution is informal (no registry standard)
No compilation step required	Complex schemas can be hard to understand
AI/LLM revolution driver	Code generation is weaker than Protobuf
Massive validator ecosystem (ajv, jsonschema)	Draft version fragmentation

JSON Schema's sweet spot is web APIs, AI tool definitions, and configuration validation where human readability and rich constraints matter more than wire performance.

8. Head-to-Head Comparison comparison tradeoffs

With each language explored individually, here's how they compare side by side.

8.1. Feature Matrix

Feature	Protobuf	Avro	JSON Schema
Schema format	Custom IDL (.proto)	JSON or Avro IDL	JSON
Wire format	Binary (varint encoding)	Binary (schema-aware)	JSON (text)
Schema in payload	No	Yes (or via registry)	Yes (it is JSON)
Code generation	Required	Optional	Optional
Schema evolution	Field tags (add, deprecate)	Resolution rules (defaults)	Informal (no standard rules)
Validation constraints	None built-in	Limited (logical types)	Rich (pattern, range, conditional)
RPC framework	gRPC (first-class)	Avro RPC (limited adoption)	OpenAPI (via REST)
Streaming support	gRPC streaming	Kafka (first-class)	SSE / WebSocket (manual)
Registry	Buf Schema Registry	Confluent Schema Registry	No dominant standard
Breaking change detection	buf breaking	Registry compatibility checks	Manual / custom tooling
Union/oneof types	`oneof` (limited)	Union types (flexible)	`anyOf`, `oneOf` (flexible)
Map types	`map`	JSON object schema	`additionalProperties`
Null handling	Default values (no null)	Explicit `["null", T]` union	`{"type": ["string", "null"]}`
Documentation	Comments only	`doc` field in schema	`description`, `title`, `examples`
Self-describing	No	Yes	Yes

8.2. Multi-Dimensional Comparison

A radar chart across eight key dimensions makes the trade-offs vivid:

No language dominates all eight dimensions

The radar chart makes the trade-offs vivid. Protobuf dominates performance and code generation but scores poorly on validation and self-description. JSON Schema dominates readability and validation but can't compete on performance. Avro sits in the middle on most axes but owns schema evolution and self-description – exactly the properties needed for data pipeline interoperability.

No language dominates all eight dimensions. This isn't a failure of the languages – it reflects genuinely different design priorities. Choosing a schema language is about matching your priorities to their strengths.

8.3. The Decision Flowchart

When I'm consulting with teams on schema language selection, this is roughly the decision tree I follow:

graph TD
    START["What's your primary use case?"] --> RPC{"Synchronous RPC
between services?"}
    START --> STREAM{"Event streaming
/ data pipelines?"}
    START --> WEB{"Web APIs
/ REST / AI tools?"}
    START --> CONFIG{"Configuration
validation?"}

    RPC -->|"Yes"| PERF{"Performance
critical?"}
    PERF -->|"Yes"| PROTO["✅ Protocol Buffers
+ gRPC"]
    PERF -->|"No"| GRPC_OR_REST{"Need streaming
or bidirectional?"}
    GRPC_OR_REST -->|"Yes"| PROTO
    GRPC_OR_REST -->|"No"| JSON_SCHEMA_REST["✅ JSON Schema
+ OpenAPI"]

    STREAM -->|"Yes"| KAFKA{"Using Kafka
/ Confluent?"}
    KAFKA -->|"Yes"| AVRO["✅ Apache Avro
+ Schema Registry"]
    KAFKA -->|"No"| EVOLVE{"Independent
schema evolution?"}
    EVOLVE -->|"Critical"| AVRO
    EVOLVE -->|"Not critical"| PROTO

    WEB -->|"Yes"| AI{"AI/LLM
integration?"}
    AI -->|"Yes"| JSON_SCHEMA_AI["✅ JSON Schema"]
    AI -->|"No"| VALIDATE{"Rich validation
constraints?"}
    VALIDATE -->|"Yes"| JSON_SCHEMA_REST
    VALIDATE -->|"No"| OPENAPI["✅ OpenAPI
(uses JSON Schema subset)"]

    CONFIG -->|"Yes"| CUE["Consider CUE
or JSON Schema"]

    style PROTO fill:#2BCDC1,color:#000
    style AVRO fill:#F66095,color:#000
    style JSON_SCHEMA_REST fill:#FFB347,color:#000
    style JSON_SCHEMA_AI fill:#FFB347,color:#000
    style CUE fill:#F39C12,color:#000
    style OPENAPI fill:#9B59B6,color:#fff

8.4. Performance Benchmarks

The following chart shows approximate performance characteristics for serializing a 10-item Order message across the three formats. These are illustrative values drawn from the range of published benchmarks⁷ – your mileage will vary by language, hardware, and message shape, but the relative ordering is consistent:

The performance differences are stark. Protobuf is 7x faster at serialization and 8x faster at deserialization compared to JSON. Message size is 6x smaller. These differences matter enormously at scale – if you're processing 100,000 messages per second, the difference between 1.2μs and 8.5μs per message is the difference between 12% and 85% CPU utilization on serialization alone.

But performance isn't everything. Most systems aren't processing 100K messages per second. For an API handling 100 requests per second, the difference between 1.2μs and 8.5μs is irrelevant – both are dwarfed by network latency (milliseconds) and business logic (milliseconds to seconds).

The rule of thumb: if you're not sure whether you need binary performance, you don't need binary performance. Start with JSON Schema for the ecosystem benefits and switch to Protobuf or Avro only when profiling reveals serialization as a bottleneck, but be aware that JSON Schema validations won't compile into the targets of your code generation.

8.5. When to Use Each

Scenario	Recommended	Why
Microservice RPC (internal)	Protobuf + gRPC	Performance, strong typing, streaming
Kafka event streaming	Avro + Confluent SR	Schema evolution, backward compatibility
Public REST API	JSON Schema + OpenAPI	Human-readable, browser-friendly
LLM tool definitions	JSON Schema	Industry standard for AI structured output
Mobile app API	Protobuf	Small payloads save bandwidth
Data warehouse ingestion	Avro	Self-describing, schema evolution
Browser-to-server	JSON Schema	Native JSON, no compilation
Real-time gaming	FlatBuffers or Cap'n Proto	Zero-copy for latency-sensitive
IoT / embedded	Protobuf (proto3)	Small footprint, simple implementation
Configuration files	JSON Schema or CUE	Validation + human editing

8.6. Migrating Between Schema Languages

If you're already invested in one schema language and considering a switch, here's a rough migration guide:

Migration	Difficulty	Tools	Key Challenges
JSON → Protobuf	Medium	quicktype, manual	Mapping nullable fields to `optional`, losing validation constraints
JSON → Avro	Medium	quicktype, manual	Converting `anyOf=/=oneOf` to union types, mapping `format` to logical types
Protobuf → Avro	Low-Medium	Confluent converters	Mechanical translation; main challenge is adopting schema resolution patterns
Avro → Protobuf	Low-Medium	Manual	Assigning field tags, converting unions to `oneof`, losing self-describing payloads
Protobuf → JSON Schema	Low	`buf` can export JSON	Losing binary performance, gaining validation constraints
Avro → JSON Schema	Low	`avro-to-json-schema`	Mechanical; JSON Schema's `if=/=then` can express constraints Avro couldn't

The hardest part of any migration is rarely the schema translation itself – it's migrating the ecosystem around the schema. Code generation targets, CI pipelines, registry configurations, and consumer libraries all need to change. Plan for a gradual rollout where both formats coexist during the transition, with a compatibility layer that translates between them.

9. War Stories: When Schemas Fail warStories failures

Theory is comfortable. Production is not. Here's what happens when schema management goes wrong.

9.1. Knight Capital: $440 Million in 45 Minutes

On August 1, 2012, Knight Capital Group deployed new trading software with a configuration change that reactivated dead code from 8 years earlier. The root cause was a deployment that updated 7 of 8 servers – the eighth server still had the old configuration, which interpreted incoming messages according to obsolete logic⁸.

sequenceDiagram
    participant Deploy as Deployment
    participant S1 as Servers 1-7 (v2)
    participant S8 as Server 8 (v1!)
    participant NYSE as NYSE

    Deploy->>S1: Deploy new config ✅
    Deploy->>S8: Deploy fails silently ❌

    Note over S1,S8: Market opens 09:30

    NYSE->>S1: Order routing messages
    S1->>NYSE: Correct trades ✅

    NYSE->>S8: Order routing messages
    S8->>S8: Interprets with old config
    S8->>NYSE: Unintended trades ❌
    Note over S8,NYSE: Buys high, sells low
at 40x normal volume

    Note over S8: 45 minutes × $10M/min = $440M loss

To be precise: this was a deployment and configuration management failure, not a schema drift failure. But it illustrates the same underlying principle that schema registries enforce – every component in a system must agree on the shape of the messages it processes, and that agreement must be machine-verified, not assumed. A schema registry wouldn't have prevented Knight Capital's specific bug, but the discipline it represents – machine-enforced consistency checks before any component goes live – would have caught the configuration mismatch.

The lesson: configuration consistency and schema consistency are the same problem at different layers of abstraction. Both are too important to leave to human coordination.

9.2. HL7 to FHIR: Healthcare's 30-Year Schema Migration

The healthcare industry provides a sobering example of what happens when schema evolution isn't built into the foundation. HL7 Version 2 (HL7v2), the dominant healthcare messaging standard since the 1990s, used a pipe-delimited format with implicit field positioning:

MSH|^~\&|HIS|Hospital|LAB|Lab|20230815||ORU^R01|MSG001|P|2.5.1
PID|||12345^^^MRN||DOE^JOHN||19800101|M
OBR|1|12345|67890|CBC^Complete Blood Count
OBX|1|NM|WBC^White Blood Count||7.5|10*3/uL|4.5-11.0|N

There was no formal schema language. Field meanings were defined in prose specification documents. Different hospitals interpreted ambiguous fields differently. "Optional" fields meant different things to different implementations. Interoperability was a nightmare.

FHIR (Fast Healthcare Interoperability Resources), HL7's modern replacement, uses – you guessed it – JSON Schema (via FHIR StructureDefinitions that compile to JSON Schema). The migration has been underway since 2014 and is still not complete. Entire companies exist solely to translate between HL7v2 and FHIR.

The cost of not starting with a proper schema language is measured in decades of technical debt.

9.3. The Silent Corruption Pattern

The scariest failure mode isn't a loud crash – it's silent data corruption. I've seen this pattern across multiple organizations:

The most dangerous bugs aren't the ones that crash your system. They're the ones that silently corrupt your data while everything looks fine. —Engineering proverb

Team A adds a field to their schema (or what they think is their schema)
Team B doesn't know about the change
Team B's deserializer encounters the unknown field
Depending on the language and library:
- Python's json.loads() silently includes it (but downstream code ignores it)
- Java's Jackson silently drops it (unless configured with FAIL_ON_UNKNOWN_PROPERTIES)
- Go's json.Unmarshal silently drops it
The data is "valid" in every system but incomplete in some
Reports diverge. Business decisions are made on bad data.
Weeks or months later, someone notices the numbers don't add up

A schema registry with compatibility checks prevents step 1 from happening silently. A schema language with code generation prevents step 2 entirely. Both together make step 3 through 7 impossible by construction.

10. The Ecosystem Unlocked codeGeneration tooling ecosystem

Choosing a schema language isn't just about types and serialization. It unlocks an entire ecosystem of tooling that becomes available once your models have a machine-readable, language-agnostic definition.

10.1. The Ecosystem Flywheel

graph TB
    SCHEMA["📄 Schema Definition
(Single Source of Truth)"]

    SCHEMA --> CODEGEN["⚙️ Code Generation
Types in every language"]
    SCHEMA --> VALIDATE["✅ Validation
Compile-time + runtime checks"]
    SCHEMA --> DOCS["📖 Documentation
Auto-generated API docs"]
    SCHEMA --> REGISTRY["🗄️ Schema Registry
Version history + compatibility"]
    SCHEMA --> TEST["🧪 Contract Testing
Producer-consumer agreements"]
    SCHEMA --> VIZ["📊 Visualization
ER diagrams, dependency graphs"]

    CODEGEN --> SCHEMA
    VALIDATE --> SCHEMA
    DOCS --> SCHEMA
    REGISTRY --> SCHEMA
    TEST --> SCHEMA
    VIZ --> SCHEMA

    style SCHEMA fill:#2BCDC1,color:#000

Each capability reinforces the others. The schema registry enables contract testing. Contract testing catches breaking changes. Breaking change detection encourages more teams to register schemas. More schemas mean better documentation. Better documentation means faster onboarding. Faster onboarding means more teams adopt schema-first development.

This flywheel effect is why schema languages are more than just "a way to define types." They're a platform for organizational coordination.

10.2. Code Generation: The Killer Feature

Code generation is what transforms a schema language from "documentation" to "infrastructure." A well-generated code library provides:

Capability	What It Gives You
Type-safe constructors	Compile errors when you pass wrong types
Serialization/deserialization	One-line conversion to/from wire format
Builder patterns	Ergonomic construction of complex messages
Equality/hashing	Correct deep equality for tests and collections
Documentation	Generated from schema field descriptions
IDE support	Autocompletion, go-to-definition, refactoring

The quality of code generation varies dramatically:

Language	Protobuf	Avro	JSON Schema
Go	Excellent (buf, protoc-gen-go)	Good (goavro, avrogen)	Moderate (go-jsonschema)
Python	Good (protobuf, betterproto)	Good (fastavro, avro)	Good (datamodel-codegen)
Java	Excellent (protoc, grpc-java)	Excellent (avro-tools)	Moderate (jsonschema2pojo)
TypeScript	Good (buf, ts-proto)	Moderate (avsc)	Good (json-schema-to-typescript)
Rust	Good (prost, tonic)	Moderate (apache-avro)	Moderate (typify)
C#	Excellent (grpc-dotnet)	Moderate (Apache.Avro)	Moderate (NJsonSchema)

10.3. Validation: From Tests to Guarantees

Schema validation operates at multiple levels:

Compile-time validation: The generated code enforces types at compile time (or lint time for dynamic languages)
Schema registration validation: The schema registry rejects incompatible schemas before they reach production
Runtime validation: Messages are validated against the schema during deserialization
Contract testing: Producer and consumer schemas are checked for compatibility in CI

These layers create a defense in depth against schema drift. No single layer is perfect, but together they make accidental incompatibilities nearly impossible.

10.4. Schema Registries: The Missing Piece

A schema registry is a centralized service that stores, versions, and validates schemas. It's the operational backbone that makes schema languages work in production, yet it's often overlooked in comparisons that focus on type systems and wire formats.

At its core, a schema registry does three things:

Stores schema versions. Every version of every schema is immutable and addressable by ID. You can always answer the question "what did the Order schema look like six months ago?"
Enforces compatibility. Before a new schema version is registered, the registry checks it against previous versions using configurable rules (backward, forward, or full compatibility). Incompatible changes are rejected before they reach production.
Decouples producers from consumers. Producers register their schema at write time. Consumers fetch the schema at read time. Neither needs to know about the other's deployment schedule.

The registry landscape is converging:

Registry	Origin	Supported Formats	Compatibility Checks
Confluent Schema Registry	Kafka/Avro ecosystem	Avro, Protobuf, JSON Schema	Yes (configurable per-subject)
Buf Schema Registry	Protobuf ecosystem	Protobuf	Yes (via `buf breaking`)
Apicurio Registry	Red Hat / open source	Avro, Protobuf, JSON Schema, OpenAPI, GraphQL	Yes
Karapace	Aiven / open source	Avro, Protobuf, JSON Schema	Yes (Confluent-compatible API)
AWS Glue Schema Registry	AWS	Avro, JSON Schema	Yes

The trend is clear: registries are becoming format-agnostic. Confluent's registry, originally Avro-only, now supports Protobuf and JSON Schema. This means the choice of registry is increasingly decoupled from the choice of schema language – you can use Protobuf schemas with Confluent's registry, or Avro schemas with a non-Confluent registry.

If you take one operational lesson from this article, let it be this: a schema language without a registry is a type system. A schema language with a registry is infrastructure.

10.5. Documentation Generation

One of the most underappreciated benefits of schema languages is automatic documentation:

Protobuf: Tools like protoc-gen-doc generate HTML, Markdown, or JSON documentation from .proto files and their comments
Avro: The doc field in Avro schemas is extracted by tools like avrodoc to generate browsable documentation
JSON Schema: Tools like json-schema-for-humans render JSON Schemas as readable HTML pages

This documentation is always current because it's generated from the same schema that generates the code. No more stale Confluence pages that describe a model from three versions ago.

10.6. The Ecosystem Visualized

The treemap below shows the ecosystem depth of each schema language, sized by GitHub stars:

The treemap reveals the different shapes of each ecosystem. Protobuf's ecosystem is deep and focused – a few high-quality tools covering code generation, linting, and testing. Avro's ecosystem is concentrated in the Kafka/Confluent space. JSON Schema's ecosystem is the broadest, spanning validators, code generators, documentation tools, AI frameworks, and API definition languages. This breadth reflects JSON Schema's role as the lingua franca of the web.

A note on sizing: the "AI/LLM" category uses GitHub stars from the platforms that consume JSON Schema (OpenAI's SDK, Anthropic's SDK, LangChain) rather than standalone schema tools. The sizes are directionally useful for showing the relative weight of AI adoption in the JSON Schema ecosystem, but shouldn't be compared 1:1 with purpose-built schema tools like ajv or protoc-gen-go.

11. Designing the Ideal Schema Language design futureWork

After spending thousands of words analyzing the trade-offs between Protobuf, Avro, and JSON Schema, a natural question emerges: what would the ideal schema language look like?

This section is speculative. The language I describe – let's call it USL (Universal Schema Language) – doesn't exist. But the design exercise is valuable because it crystallizes what we've learned about the strengths and weaknesses of existing approaches.

11.1. Design Principles

USL would be built on these principles:

Schema is the source of truth – all code, documentation, and validation is derived from the schema
Wire format is a choice, not an assumption – the same schema can target JSON, binary, or any other format
Validation constraints are first-class – not an afterthought bolted on to a type system
Evolution rules are formal and enforceable – not conventions documented in a wiki
The schema is self-describing – it can be transmitted alongside data
Human readability is non-negotiable – if it's harder to read than code, people won't use it
Code generation is excellent – generated code is idiomatic, not a thin wrapper around generic maps

11.2. Type System

USL's type system would combine the best of all three:

// USL Schema Definition
namespace ecommerce.v1

// Enums with explicit wire values (like Protobuf) but human-friendly
enum DiscountType {
  PERCENTAGE = 1
  FIXED = 2
  BOGO = 3
}

// Records with field tags (like Protobuf) + constraints (like JSON Schema) + defaults (like Avro)
record OrderItem {
  1: string product_id
  2: int32 quantity [min: 1, max: 10000, doc: "Number of units ordered"]
  3: float64 unit_price [gt: 0, doc: "Price per unit in base currency"]
}

record Order {
  1: string id [pattern: "^ord_[a-zA-Z0-9]{12}$"]
  2: string customer_id [min_length: 1]
  3: list items [min_items: 1]
  4: optional DiscountType discount_type
  5: optional float64 discount_value [min: 0]
  6: timestamp created_at
  7: float64 total [min: 0]

  // Conditional constraints (like JSON Schema's if/then)
  invariant "BOGO discount must be zero" {
    when discount_type == BOGO then discount_value == 0
  }

  // Cross-field constraints
  invariant "total matches items" {
    total == sum(items[*].unit_price * items[*].quantity)
      - discount_applied(discount_type, discount_value)
  }
}

Key features:

Field tags (like Protobuf) enable binary encoding and safe field renaming
Inline constraints (like JSON Schema) enforce validation at the schema level
Optional keyword (like Avro's explicit unions) makes null-safety unambiguous
Invariants enable cross-field and conditional validation that none of the existing languages support natively
Documentation is part of the schema, not in comments that get lost

11.3. Beyond the Type System

The type system above is the core, but USL would go further in three areas that existing languages handle poorly:

Formal evolution rules. Instead of documenting evolution conventions in a wiki, USL would let you declare rules like allow add_field with default, deny remove_field, deny reuse_tag, allow widen_type (int32 → int64), allow relax_constraint, deny tighten_constraint – and the toolchain would enforce them automatically at registration time. Avro's schema resolution gets closest to this, but the rules are implicit in the specification rather than configurable per-schema.
Wire format independence. The same Order schema would target Protobuf binary for RPC, Avro encoding for Kafka, JSON for REST APIs, and Parquet schemas for data lakes. Each target would specify naming conventions, timestamp encoding, and null handling. One schema, many wire formats. This is the holy grail of schema languages, and no existing tool achieves it fully.
Idiomatic code generation. USL wouldn't generate generic types – it would generate community-standard types. Python gets Pydantic models with @field_validator. TypeScript gets Zod schemas. Rust gets serde-annotated structs. Each generated output is idiomatic to its language, not a thin wrapper around a generic map.

11.4. Requirements Table

Requirement	Protobuf	Avro	JSON Schema	USL
Language-agnostic schema	✅	✅	✅	✅
Binary wire format	✅	✅	❌	✅
JSON wire format	⚠️ (via JSON mapping)	⚠️ (via JSON encoding)	✅	✅
Validation constraints	❌	⚠️ (logical types)	✅	✅
Cross-field invariants	❌	❌	⚠️ (if/then)	✅
Formal evolution rules	⚠️ (conventions)	✅ (resolution)	❌	✅
Self-describing payloads	❌	✅	✅	✅
Human-readable schema	⚠️ (IDL)	❌ (JSON)	⚠️ (JSON)	✅ (custom IDL)
Idiomatic code generation	✅	⚠️	⚠️	✅
Wire format independence	❌	❌	❌	✅

11.5. Why Doesn't USL Exist?

If USL is so obviously better, why hasn't someone built it?

Several reasons:

Network effects. Protobuf, Avro, and JSON Schema have massive ecosystems. A new language starts with zero tools, zero libraries, zero community. The 10% improvement in any dimension isn't enough to overcome the ecosystem advantage.
Different contexts, different priorities. Google needed Protobuf for internal RPC. The Hadoop ecosystem needed Avro for schema evolution. The web needed JSON Schema for API validation. Each language was optimized for its context. A "universal" language that serves all contexts equally well might serve none of them best.
Specification complexity. USL as described above is hard to specify correctly. Cross-field invariants, wire format independence, and formal evolution rules each bring significant specification and implementation complexity.
The "second system" trap. Every engineer who deeply understands Protobuf, Avro, and JSON Schema has thought about building a "better" version. Most wisely resist. The ideal schema language is easy to imagine and extremely hard to execute – especially the tooling, ecosystem, and community that make a schema language useful.

That said, projects like CUE, Dhall, and Smithy (AWS) are exploring parts of this design space. The convergence is happening, just slowly and from different directions.

12. When NOT to Use a Schema Language antipatterns pragmatism

I've spent most of this post advocating for schema languages. In the interest of intellectual honesty, let me present the counter-arguments.

12.1. Valid Reasons to Skip Schema Languages

Single-language, single-team projects. If your entire system is written in Python by one team, Pydantic is your schema language. The overhead of maintaining .proto files or JSON Schema doesn't pay for itself until you have multiple languages or multiple teams.
Prototyping and MVPs. When you're still figuring out what the product is, rigid schemas are premature. You'll redesign the data model three times before launch. Use JSON blobs, iterate fast, and formalize later.
Small, stable APIs. If your API has 5 endpoints that haven't changed in 2 years, the cost of adopting a schema language exceeds the benefit. The "if it ain't broke" principle applies.
Performance-insensitive, validation-heavy domains. If your primary concern is "reject invalid input with helpful error messages" and performance doesn't matter, a language-specific validator (Pydantic, Zod) gives you better error messages and more expressive constraints than most schema languages.
Rapid exploration / data science. Data scientists exploring datasets don't need a schema language. They need pandas and a REPL. Schema languages add value at the boundary between exploratory and production code, not during exploration.

12.2. The Schema Tax

Every abstraction has a cost. The question isn't whether schema languages are better in the abstract – it's whether they're worth the overhead for your system, today. —Pragmatic engineering

Schema languages impose real costs:

Learning curve: Everyone on the team needs to understand the schema language and its tooling
Build complexity: Code generation adds a step to every build
Dependency management: Generated code needs to be versioned and distributed
Schema-first friction: You can't just "add a field" – you need to update the schema, regenerate code, and verify compatibility
Debugging indirection: When something goes wrong, you're debugging generated code, not code you wrote

These costs are fixed – they don't scale with system size. The benefits are proportional to system size. This means there's a crossover point: below a certain complexity, schema languages cost more than they save.

I've seen this go wrong firsthand. A three-person startup I advised adopted Protobuf and gRPC for their internal APIs – between two Python services maintained by the same team. Within a month, a third of their development time was going to protoc plugin issues, generated code version mismatches, and debugging serialization errors that would have been trivial with plain JSON. They had imported Google-scale infrastructure to solve a problem they didn't have. They migrated back to FastAPI with Pydantic models and shipped their MVP three months faster. Schema languages are powerful, but power has carrying costs.

12.3. My Rule of Thumb

Use a schema language when any of these are true:

You have 2+ languages sharing data models
You have 3+ teams consuming the same data
You have Kafka or another message broker where producers and consumers evolve independently
You're building a public API where clients you don't control need to understand your data
You're integrating with AI/LLM tools that require structured output definitions
Your data models are regulated (healthcare, finance) and require formal specification

Otherwise, start with language-specific tools and migrate when the pain becomes obvious. The migration is always possible – it's just easier to do it before you have 50 services.

13. The Future: AI, Convergence, and What Comes Next ai futureWork predictions

The schema language landscape is evolving faster than at any point in its history, driven by two forces: the AI revolution and the convergence of previously separate ecosystems.

13.1. AI as Schema Author

We're already seeing LLMs used to generate schemas:

User: I need a schema for a restaurant reservation system.
      It should handle party size, date/time, special requests,
      and dietary restrictions.

LLM:  Here's your Protobuf schema:

      message Reservation {
        string id = 1;
        string restaurant_id = 2;
        string customer_name = 3;
        int32 party_size = 4;
        google.protobuf.Timestamp reservation_time = 5;
        repeated string dietary_restrictions = 6;
        optional string special_requests = 7;
        ReservationStatus status = 8;
      }

      enum ReservationStatus {
        RESERVATION_STATUS_UNSPECIFIED = 0;
        RESERVATION_STATUS_PENDING = 1;
        RESERVATION_STATUS_CONFIRMED = 2;
        RESERVATION_STATUS_CANCELLED = 3;
        RESERVATION_STATUS_COMPLETED = 4;
      }

But this is only the beginning. Future AI-schema interactions will include:

Schema inference from data samples: Feed the AI a JSON payload and get a validated schema back
Schema evolution suggestions: "You're adding a coupon_code field. Based on your existing schema, I recommend making it optional with a default of null and adding a CouponType enum for future extensibility"
Cross-format translation: "Convert this Protobuf schema to Avro while preserving compatibility semantics"
Automated migration: "Here's a migration plan for moving from JSON Schema to Protobuf, including a compatibility layer for the transition period"

13.2. The Convergence Trend

The three major schema languages are converging:

Protobuf added optional back in proto3.15 (borrowing from Avro's explicit null handling)
Avro added code generation improvements (borrowing from Protobuf's strength)
JSON Schema added unevaluatedProperties (borrowing from Protobuf's strict typing)
Confluent Schema Registry now supports Protobuf and JSON Schema alongside Avro
Buf Schema Registry has hints of supporting additional formats
OpenAPI 3.1 fully adopted JSON Schema Draft 2020-12 (bridging API and schema worlds)

The boundaries between these ecosystems are blurring. Ten years from now, we may look back and see this period as the beginning of a unified schema ecosystem, much as SQL standardized the relational database world despite fierce competition between vendors.

13.3. Timeline of Key Events and Predictions

The diamond markers represent predictions. Three trends I'm watching:

Multi-format registries (2025-2026): Confluent and Buf are both expanding format support. Within a few years, the choice of registry will be decoupled from the choice of schema language.
AI schema copilots (2027-2028): Just as GitHub Copilot transformed code writing, AI tools will transform schema design. Expect AI that suggests schema evolution strategies, identifies potential compatibility issues, and generates migration plans.
Schema convergence (2029+): The longest-term prediction and the least certain. The historical pattern (SQL for databases, HTTP for web) suggests that schema languages will eventually converge toward a unified standard. But the counter-pattern (JavaScript frameworks) suggests permanent fragmentation is equally likely.

13.4. What's Coming Sooner

More concretely, here's what I expect in the next 2-3 years:

JSON Schema as a compilation target. More tools will compile higher-level schema definitions to JSON Schema, which then drives code generation and validation. JSON Schema becomes the "assembly language" of schema definitions.
Schema-aware observability. APM tools (Datadog, Honeycomb) will integrate schema information to provide richer insights. "This endpoint's response time increased because the items array is 3x larger than the schema's recommended maxItems."
AI-native schema evolution. Instead of manually designing schema migrations, you'll describe the desired change in natural language and get a migration plan with backward-compatibility guarantees.
Edge-native schemas. As computation moves to the edge (Cloudflare Workers, Deno Deploy), schemas will be used to validate requests at the CDN layer before they reach application servers, reducing latency and protecting backends from malformed requests.

14. Conclusion reflection

We've covered a lot of ground. Let me distill the key insights.

14.1. The Core Argument

Schema languages solve a coordination problem, not a technical one. Any competent engineer can define a data model in their language of choice. The challenge is ensuring that 5, 50, or 500 engineers across multiple languages, teams, and time zones all agree on what that model looks like – and continue to agree as it evolves.

Protobuf, Avro, and JSON Schema each represent a different answer to "what should we optimize for?"

Protobuf says: optimize for performance and strong code generation
Avro says: optimize for schema evolution and self-describing data
JSON Schema says: optimize for validation expressiveness and human readability

None is universally "best." The right choice depends on your context – your languages, your architecture, your team structure, and your primary use case.

14.2. What I've Learned

After years of working with all three schema languages across different organizations, my strongest conviction is this: the cost of not having a single source of truth is always higher than you think, and it's always paid later than you'd like.

Model drift is the kind of problem that doesn't hurt until it really hurts. And by the time it hurts, you have months of corrupted data, dozens of divergent implementations, and a migration that "should take a week" but takes a quarter.

If your system involves multiple languages or multiple teams sharing data, invest in a schema language early. The best time was when you started the project. The second-best time is now.

14.3. A Closing Thought

Schema languages are, in their essence, an act of humility. They acknowledge that no single developer, no single team, no single language can hold the complete picture of a system's data model. Instead of trusting human coordination (which fails at scale), they encode the model in a format that machines can verify, humans can read, and organizations can evolve.

The cleverest possible approach to shared data models is to define them in each language using that language's most expressive features – custom validators, rich type systems, elegant abstractions. The humble approach is to define them once, in a simple format that any language can consume, and let a machine generate the rest. The clever approach produces beautiful code. The humble approach produces correct systems.

That's not clever. It's humble. And in software engineering, humility scales.

15. tldr

This post compares the three dominant schema languages for data modelling – Protocol Buffers, Apache Avro, and JSON Schema. The Single Source of Truth section motivates the problem: in polyglot systems, defining models independently in each language leads to model drift and silent data corruption, where different parts of the system disagree about what the data looks like. Why Not Pydantic / Zod? addresses the common objection that language-specific tools suffice, arguing that Pydantic, Zod, and similar libraries are best used as consumers of schemas, not sources. The Landscape section surveys 20+ schema languages across categories including binary serialization, validation, API definition, and configuration. Three deep dives follow: Protobuf excels at high-performance RPC with its compiled binary format and gRPC integration, Avro dominates event streaming with its self-describing payloads and schema resolution that lets producers and consumers evolve independently, and JSON Schema leads in web API validation and has found an unexpected second life as the interface definition language for AI tools. The Head-to-Head comparison reveals that no language dominates all dimensions – choose based on whether you prioritize performance (Protobuf), schema evolution (Avro), or validation richness (JSON Schema). War Stories drive the point home with real failures including Knight Capital's $440M loss from schema drift. The Ecosystem section shows that schema languages unlock far more than just types – code generation, documentation, registries, and contract testing create a flywheel of organizational coordination. Finally, the USL design exercise imagines a future language combining the best of all three, and the Future section predicts AI-assisted schema design and gradual convergence of the ecosystem.

Footnotes:

A 2018 Stripe/Harris Poll survey reported that developers spend ~17 hours per week dealing with technical debt, including data model inconsistencies. The methodology of this widely-cited survey has been questioned – the sample was small and self-reported – but the directional finding (data model issues are a significant source of developer toil) is consistent with other industry surveys.

Monte Carlo Data, "The State of Data Quality" (2020). The survey of 300+ data engineering teams found that 77% experienced data quality incidents, with schema changes and data model drift among the leading causes. More recent surveys (e.g., Monte Carlo's 2022 and 2023 reports) continue to show schema changes as a top contributor to data quality incidents.

Protocol Buffers were developed internally at Google starting in 2001. The original design is attributed to Jeff Dean, Sanjay Ghemawat, and others on the infrastructure team. The public release (proto2) came in July 2008. See: Protocol Buffers Documentation.

⁴

Doug Cutting created Apache Avro in 2009 as part of the Hadoop project. The design was motivated by the limitations of Java's Writables serialization and the desire for a language-neutral, schema-evolution-friendly format. See: Apache Avro Documentation.

⁵

Avro schema resolution is described in detail in the Avro Specification. The rules for compatible schema evolution are subtle and worth reading carefully before deploying Avro in production.

⁶

JSON Schema was first proposed by Kris Zyp in 2009 as an Internet-Draft. The specification has evolved through multiple draft versions, with Draft 2020-12 being the current stable release. See: JSON Schema Specification.

⁷

These values are illustrative approximations, not precise measurements from a single benchmark run. They are drawn from the range of published results across multiple benchmarks including alecthomas/go_serialization_benchmarks, eishay/jvm-serializers, and various conference talks comparing serialization formats. The absolute values vary significantly by language, hardware, message complexity, and library implementation. What is consistent across virtually all benchmarks is the relative ordering: Protobuf fastest, Avro middle, JSON slowest, with JSON message sizes 4-6x larger than binary formats. Run benchmarks on your own hardware and message shapes before making architecture decisions based on performance.

⁸

The Knight Capital incident is documented in the SEC's administrative proceeding (File No. 3-15570, October 16, 2013). The total loss was $461.1 million in approximately 45 minutes of trading. The root cause was a deployment error that left one of eight servers running obsolete code. This is not a schema drift failure in the narrow sense, but it illustrates how systems fail when components disagree about message semantics without a machine-enforced consistency check.

Literate Programming: A Primer with Python and Org-Babel

Charlie Holland (main) — Sun, 25 Jan 2026 12:43:00 GMT

1. Introduction literateProgramming

Literate programming, a concept introduced by Donald Knuth in 1984, inverts the traditional relationship between code and documentation. Rather than writing code with occasional comments, we write a document with embedded code — the program is explained in human-readable prose, and the machine-executable source is extracted (or tangled) from it.

Org-babel, the code execution and tangling engine built into Emacs Org-mode, provides a natural environment for literate programming. Code blocks can be named, referenced by other blocks, and tangled into one or more source files.

In this post, we will construct a small but complete Python program using these techniques.

2. The Problem primes algorithms

We will implement the Sieve of Eratosthenes, one of the oldest known algorithms, to find all prime numbers up to a given limit. The program will:

Generate primes using the sieve
Display basic statistics about the distribution
Write the results to a file

This is a small program, but it demonstrates how org-babel can decompose a program into logical, documented sections.

3. Building the Program orgBabel tangling

3.1. The Main Entry Point

We begin with the overall structure of our program. The noweb syntax (<>) allows us to reference other named code blocks, which will be expanded during tangling.

"""
Sieve of Eratosthenes - A literate programming example.
Tangled from post-literate-python.org
"""

import math
from pathlib import Path

def sieve_of_eratosthenes(limit: int) -> list[int]:
    """Return all primes up to `limit` using the Sieve of Eratosthenes."""
    if limit < 2:
        return []

    # Initialize boolean array - True means "is prime"
    is_prime = [True] * (limit + 1)
    is_prime[0] = is_prime[1] = False

    # Sieve: eliminate multiples of each prime
    for p in range(2, int(math.sqrt(limit)) + 1):
        if is_prime[p]:
            for multiple in range(p * p, limit + 1, p):
                is_prime[multiple] = False

    return [n for n in range(2, limit + 1) if is_prime[n]]

def print_statistics(primes: list[int], limit: int) -> None:
    """Print statistics about the prime distribution."""
    count = len(primes)
    estimate = limit / math.log(limit) if limit > 1 else 0

    print(f"Primes up to {limit}: {count}")
    print(f"Prime Number Theorem estimate: {estimate:.1f}")
    print(f"Ratio (actual/estimate): {count / estimate:.4f}" if estimate else "")
    print(f"Largest prime found: {primes[-1]}" if primes else "No primes found")
    print(f"Prime density: {count / limit * 100:.1f}%")

def write_results(primes: list[int], filename: str) -> None:
    """Write primes to a file, one per line."""
    output_path = Path(filename)
    output_path.write_text("\n".join(str(p) for p in primes) + "\n")
    print(f"Wrote {len(primes)} primes to {output_path}")

if __name__ == "__main__":
    limit = 100
    primes = sieve_of_eratosthenes(limit)
    print_statistics(primes, limit)
    write_results(primes, "primes_output.txt")

Notice how this reads almost like pseudocode. Each <<...>> reference points to a named block defined below.

3.2. Imports

We need only the math module for our square root computation in the sieve:

import math
from pathlib import Path

3.3. The Sieve Algorithm

The Sieve of Eratosthenes works by iteratively marking the multiples of each prime, starting from 2. For each number $p$, we only need to begin marking at $p^2$, since smaller multiples will have already been eliminated by smaller primes.

def sieve_of_eratosthenes(limit: int) -> list[int]:
    """Return all primes up to `limit` using the Sieve of Eratosthenes."""
    if limit < 2:
        return []

    # Initialize boolean array - True means "is prime"
    is_prime = [True] * (limit + 1)
    is_prime[0] = is_prime[1] = False

    # Sieve: eliminate multiples of each prime
    for p in range(2, int(math.sqrt(limit)) + 1):
        if is_prime[p]:
            for multiple in range(p * p, limit + 1, p):
                is_prime[multiple] = False

    return [n for n in range(2, limit + 1) if is_prime[n]]

The time complexity is $O(n \log \log n)$, making this one of the most efficient simple sieves.

3.4. Statistics

The Prime Number Theorem tells us that the number of primes less than $n$ is approximately $\frac{n}{\ln n}$. Let us compare our actual count with this estimate:

def print_statistics(primes: list[int], limit: int) -> None:
    """Print statistics about the prime distribution."""
    count = len(primes)
    estimate = limit / math.log(limit) if limit > 1 else 0

    print(f"Primes up to {limit}: {count}")
    print(f"Prime Number Theorem estimate: {estimate:.1f}")
    print(f"Ratio (actual/estimate): {count / estimate:.4f}" if estimate else "")
    print(f"Largest prime found: {primes[-1]}" if primes else "No primes found")
    print(f"Prime density: {count / limit * 100:.1f}%")

3.5. Output

Finally, we write the primes to a file, one per line:

def write_results(primes: list[int], filename: str) -> None:
    """Write primes to a file, one per line."""
    output_path = Path(filename)
    output_path.write_text("\n".join(str(p) for p in primes) + "\n")
    print(f"Wrote {len(primes)} primes to {output_path}")

4. Tangling and Running workflow

To extract the executable Python from this document, we tangle it:

emacs --batch --eval "(require 'org)" post-literate-python.org --funcall org-babel-tangle

This produces literate_primes.py, which can then be run directly:

python literate_primes.py

Expected output:

Primes up to 100: 25
Prime Number Theorem estimate: 21.7
Ratio (actual/estimate): 1.1513
Largest prime found: 97
Prime density: 25.0%
Wrote 25 primes to primes_output.txt

5. Conclusion reflection

This small example demonstrates the core workflow of literate programming with Org-babel:

Documentation-first: The narrative drives the structure, not the code
Noweb references: Code blocks compose into a complete program via named references
Tangling: The executable source is extracted mechanically from the document
Export: The same document produces both runnable code and readable documentation (this HTML page)

The source for this post and the tangled Python file live side by side — the document is the program.

Design Decisions: Building a Modern Technical Blog

Charles Baker — Sat, 24 Jan 2026 06:01:00 GMT

1. Introduction

Building a personal blog might seem like a solved problem in 2026, but I wanted something different. Not just another static site generator output, but an interactive reading experience that reflects how I think about and organize technical content. This post documents the design decisions that shaped chiply.dev, from the choice of frameworks to security considerations.

What started as a simple blog evolved into a platform featuring 3D knowledge graphs, interactive charts, recursive link previews, and a sophisticated content management system built on Emacs org-mode. Along the way, I made dozens of architectural decisions, each with trade-offs worth examining.

2. Framework Selection

2.1. Why SvelteKit?

Starting a technical blog from scratch in 2026, I needed a framework that could support far more than static content. The vision included 3D visualizations, interactive charts, server-side API endpoints for GitHub integration and search, and a reading experience that felt more like an application than a document. Static site generators like Hugo excelled at content but couldn't support the interactivity I wanted. React-based solutions like Next.js carried virtual DOM overhead that seemed wasteful for a content-heavy site. Astro was compelling for its island architecture, but I needed deeper component interactivity than islands easily provide.

The task was to find a framework that compiled to minimal client-side JavaScript, provided explicit and predictable reactivity, and colocated frontend and backend code without the complexity of a separate API layer.

After evaluating Next.js, Astro, and Hugo against these requirements, I chose SvelteKit 2 with Svelte 5. The result is a framework that eliminates virtual DOM overhead entirely, provides explicit reactivity through runes, and lets me write API endpoints alongside the components that consume them — all while shipping less JavaScript to the client than any React-based alternative.

2.1.1. Svelte 5 Runes

Svelte 5 introduced "runes" - a new reactivity system that makes state management explicit and predictable:

// Reactive state declaration
let count = $state(0);

// Derived values (computed properties)
let doubled = $derived(count * 2);

// Component props with destructuring
let { title, author } = $props();

This approach eliminates the "magic" of Svelte 4's implicit reactivity while remaining concise. Unlike React's useState hooks, runes don't require understanding closures and stale closure bugs.

2.1.2. Compiled Output

Svelte compiles components to vanilla JavaScript at build time, eliminating the runtime overhead of virtual DOM diffing. For a content-heavy blog with interactive visualizations, this results in:

Smaller bundle sizes (no framework runtime shipped to clients)
Faster initial page loads
Better performance on mobile devices

2.1.3. Full-Stack Capabilities

SvelteKit provides file-based routing with integrated API endpoints:

src/routes/
├── +page.svelte          # Home page
├── +layout.svelte        # Root layout
├── [post]/               # Dynamic blog routes
│   ├── +page.svelte      # Post layout
│   └── +page.server.ts   # Server-side data loading
└── api/
    ├── commits/          # GitHub API proxy
    ├── subscribe/        # Newsletter endpoint
    └── preview-proxy/    # Link preview service

This colocation of frontend and backend code simplifies development and deployment.

2.2. Build Tooling: Vite

With a project featuring heavy interactive components and frequent iteration, slow build tools would have been a serious drag on development velocity. Traditional bundlers like Webpack require full rebuilds on changes, and the lag compounds when you're tweaking 3D graph parameters or CSS transitions and need instant visual feedback.

I needed a build tool that provided near-instant feedback during development while still producing optimized production bundles with proper code splitting. Vite 7 powers the development experience with:

Hot Module Replacement (HMR) that updates in milliseconds
Native ES modules during development (no bundling required)
Optimized production builds with code splitting
Built-in TypeScript support

The result is a development server that starts instantly and updates faster than I can switch windows.

2.3. Deployment: Vercel

The blog needed a hosting platform that could handle both static prerendered pages and dynamic API endpoints (GitHub commit fetching, newsletter subscriptions, link preview proxying) without managing separate infrastructure. Self-hosting would mean configuring a server, managing SSL certificates, and dealing with scaling — all distractions from writing content.

The task was to find a platform with native SvelteKit support, global edge distribution for API routes, and zero-config deployments from Git pushes. I chose Vercel because:

Native SvelteKit support: The @sveltejs/adapter-vercel handles all configuration
Edge functions: API routes run close to users globally
Automatic previews: Every PR gets a preview deployment
Analytics integration: Built-in performance monitoring

The vercel.json configuration enables aggressive caching:

{
  "headers": [
    {
      "source": "/fonts/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

3. Content Management: Org-Mode to HTML

3.1. Why Org-Mode?

Writing technical blog posts in Markdown quickly exposed its limitations. Code examples couldn't be executed or verified within the document, so they'd drift out of sync with the prose. Markdown's flat heading structure made reorganizing long posts cumbersome. And for literate programming posts — where the code is the content — Markdown had no concept of code tangling or noweb references.

I needed an authoring system that could execute code blocks inline, tangle source files from the document, support deep hierarchical organization, and export clean HTML. Rather than using Markdown or a CMS, I write all content in Emacs org-mode. The result is that every code example in a post can be verified at authoring time, documents restructure with a few keystrokes, and the same org file can produce both a blog post and a working program.

3.1.1. Literate Programming

Org-mode excels at mixing prose with executable code. Code blocks can be evaluated, and their results embedded in the document:

#+BEGIN_SRC python :results output
import pandas as pd
df = pd.read_csv("data.csv")
print(df.describe())
#+END_SRC

For a technical blog, this means code examples are always tested and accurate.

3.1.2. Hierarchical Organization

Org-mode's outline structure maps naturally to blog post sections. I can collapse, rearrange, and navigate large documents efficiently. The heading hierarchy (*, **, ***, etc.) exports cleanly to HTML with proper semantic structure.

3.1.3. Export Flexibility

Org-mode's export system (ox) produces clean HTML with customizable options:

#+OPTIONS: toc:t num:t H:6 html-postamble:nil
#+PROPERTY: header-args :eval never-export

These options control table of contents generation, section numbering, heading depth, and code block behavior.

3.2. The Compilation Pipeline

With content authored in org-mode but served by a SvelteKit application, I needed a bridge between the two worlds. Org-mode's HTML export produces standalone documents, but SvelteKit needs to extract metadata (title, author, date, description) for SEO and navigation, and the content needs to integrate with the blog's component system for features like table of contents and tag extraction.

The task was to build a pipeline that preserves org-mode's authoring power while producing content that SvelteKit can load, parse, and enhance with interactive features. The org-to-HTML pipeline works as follows:

Authoring: Write content in org/*.org files
Export: Emacs exports to HTML via C-c C-e h h
Storage: HTML files live in src/routes/[post]/
Loading: SvelteKit loads HTML server-side, extracts metadata
Rendering: Client-side components parse and enhance the HTML

3.2.1. Metadata Extraction

The server-side loader (+page.server.ts) extracts metadata from HTML:

// Extract title from  tag
const titleMatch = html.match(/<title>(.*?)<\/title>/);

// Extract author from meta tag
const authorMatch = html.match(/<meta name="author" content="(.*?)"/);

// Extract date from HTML comment
const dateMatch = html.match(/<!-- (\d{4}-\d{2}-\d{2})/);

// Extract first paragraph as description
const descMatch = html.match(/<p[^>]*>([^<]{50,160})/);
</pre>
</div>

<p>
This approach keeps all content in org-mode while enabling rich SEO metadata.
</p>
</div>
</div>
</div>
<div id="outline-container-full-text-search-indexing" class="outline-3">
<h3 id="full-text-search-indexing"><span class="section-number-3">3.3.</span> Full-Text Search Indexing</h3>
<div class="outline-text-3" id="text-full-text-search-indexing">
<p>
With blog posts growing in length and number, readers needed a way to find specific content across all posts. But Algolia's record size limits (10KB per record) meant I couldn't simply index entire posts as single documents. Additionally, search results that link to an entire post aren't particularly helpful when the reader wants a specific section.
</p>

<p>
The solution was to chunk content by heading, creating one searchable record per section. This way, search results link directly to the relevant section with a highlight animation. For Algolia search integration, I created Python scripts that chunk content by heading:
</p>

<div class="org-src-container">
<pre class="src src-python"># extract_html.py (simplified)
def extract_sections(html_content):
    soup = BeautifulSoup(html_content, 'html.parser')
    sections = []

    for heading in soup.find_all(['h2', 'h3', 'h4', 'h5', 'h6']):
        section_id = heading.get('id', '')
        section_title = heading.get_text()
        content = get_section_content(heading)

        sections.append({
            'anchor': section_id,
            'sectionTitle': section_title,
            'content': content[:5000]  # Max 5KB per record
        })

    return sections
</pre>
</div>

<p>
Each heading becomes a searchable record, enabling jump-to-section from search results.
</p>
</div>
</div>
</div>
<div id="outline-container-styling-architecture" class="outline-2">
<h2 id="styling-architecture"><span class="section-number-2">4.</span> Styling Architecture</h2>
<div class="outline-text-2" id="text-styling-architecture">
</div>
<div id="outline-container-design-tokens-with-open-props" class="outline-3">
<h3 id="design-tokens-with-open-props"><span class="section-number-3">4.1.</span> Design Tokens with Open Props</h3>
<div class="outline-text-3" id="text-design-tokens-with-open-props">
<p>
A content-heavy blog with interactive visualizations needed consistent spacing, colors, and typography without bloating the CSS bundle. The primary concern was keeping the styling layer lightweight — every kilobyte of CSS is render-blocking, and a blog should load fast on any connection.
</p>

<p>
The task was to find a system that provides design consistency (spacing scales, color palettes, easing curves) without the overhead of utility-class frameworks or the tooling complexity of preprocessors. Rather than Tailwind CSS, I chose Open Props — a CSS custom properties library providing design tokens at just ~14KB. The result is semantic variable names like <code>--text-muted</code> instead of opaque utilities like <code>text-gray-400</code>, direct CSS control without fighting framework abstractions, and a bundle that's a fraction of even Tailwind's JIT output:
</p>

<div class="org-src-container">
<pre class="src src-css">@import "open-props/style";

/* Semantic variable mapping */
:root {
  --bg-primary: #fffefc;          /* Warm cream */
  --text-primary: var(--gray-8);
  --link-color: var(--indigo-7);
  --size-spacing: var(--size-4);  /* Consistent spacing */
}
</pre>
</div>
</div>
<div id="outline-container-why-not-tailwind-" class="outline-4">
<h4 id="why-not-tailwind-"><span class="section-number-4">4.1.1.</span> Why Not Tailwind?</h4>
<div class="outline-text-4" id="text-why-not-tailwind-">
<p>
Tailwind is excellent for rapid prototyping, but I had specific reasons to avoid it:
</p>

<ol class="org-ol">
<li><b>Readability</b>: Long class lists obscure HTML structure</li>
<li><b>Semantic naming</b>: I prefer <code>--text-muted</code> over <code>text-gray-400</code></li>
<li><b>Bundle size</b>: Open Props is lighter (~14KB vs Tailwind's JIT)</li>
<li><b>Customization</b>: Direct CSS control without fighting abstractions</li>
</ol>
</div>
</div>
</div>
<div id="outline-container-theme-system" class="outline-3">
<h3 id="theme-system"><span class="section-number-3">4.2.</span> Theme System</h3>
<div class="outline-text-3" id="text-theme-system">
<p>
Dark mode is table stakes for a modern developer-focused blog. Readers coding late at night expect a site to respect their OS preference, and developers in particular notice when a blog blinds them with a white page at 2 AM. Beyond just supporting dark mode, the system needed to handle the notoriously tricky "flash of wrong theme" problem — where server-rendered HTML briefly shows the wrong theme before JavaScript hydrates.
</p>

<p>
The task was to implement light, dark, and system (OS-following) modes with zero visual flash on page load, persisted user preferences, and clean CSS that doesn't require duplicating every style rule. The blog supports three theme modes: light, dark, and system (follows OS preference).
</p>
</div>
<div id="outline-container-implementation-strategy" class="outline-4">
<h4 id="implementation-strategy"><span class="section-number-4">4.2.1.</span> Implementation Strategy</h4>
<div class="outline-text-4" id="text-implementation-strategy">
<div class="org-src-container">
<pre class="src src-css">/* System preference (default) */
@media (prefers-color-scheme: dark) {
  :root:not(.theme-light) {
    --bg-primary: var(--gray-9);
    --text-primary: var(--gray-1);
  }
}

/* Manual override classes */
:root.theme-dark {
  --bg-primary: var(--gray-9);
  --text-primary: var(--gray-1);
}

:root.theme-light {
  --bg-primary: #fffefc;
  --text-primary: var(--gray-8);
}
</pre>
</div>

<p>
The CSS cascade ensures manual selection overrides system preference.
</p>
</div>
</div>
<div id="outline-container-flash-prevention" class="outline-4">
<h4 id="flash-prevention"><span class="section-number-4">4.2.2.</span> Flash Prevention</h4>
<div class="outline-text-4" id="text-flash-prevention">
<p>
To prevent a flash of wrong theme on page load, an inline script in <code>app.html</code> runs before rendering:
</p>

<div class="org-src-container">
<pre class="src src-html"><script>
  (function() {
    const theme = localStorage.getItem('theme');
    if (theme === 'dark') {
      document.documentElement.classList.add('theme-dark');
    } else if (theme === 'light') {
      document.documentElement.classList.add('theme-light');
    }
  })();
</script>
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-typography--terminus-font" class="outline-3">
<h3 id="typography--terminus-font"><span class="section-number-3">4.3.</span> Typography: Terminus Font</h3>
<div class="outline-text-3" id="text-typography--terminus-font">
<p>
A technical blog's typography sets its entire visual tone. System fonts feel generic, and popular choices like Fira Code or JetBrains Mono appear on every other developer blog. I wanted a font that reinforced the terminal-inspired aesthetic while being genuinely readable for long technical prose — not just code blocks.
</p>

<p>
I chose the Terminus monospace font for its:
</p>

<ul class="org-ul">
<li><b>Readability</b>: Designed for long coding sessions</li>
<li><b>Character distinction</b>: Clear differentiation between similar characters (0/O, 1/l/I)</li>
<li><b>Aesthetic</b>: Technical, terminal-inspired appearance matching the blog's theme</li>
</ul>

<p>
Self-hosting with preloading ensures fast font delivery:
</p>

<div class="org-src-container">
<pre class="src src-html"><link rel="preload" href="/fonts/TerminusTTF-4.49.3.woff2"
      as="font" type="font/woff2" crossorigin>
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-interactive-features" class="outline-2">
<h2 id="interactive-features"><span class="section-number-2">5.</span> Interactive Features</h2>
<div class="outline-text-2" id="text-interactive-features">
</div>
<div id="outline-container-3d-knowledge-graph--dag3d-" class="outline-3">
<h3 id="3d-knowledge-graph--dag3d-"><span class="section-number-3">5.1.</span> 3D Knowledge Graph (DAG3D)</h3>
<div class="outline-text-3" id="text-3d-knowledge-graph--dag3d-">
<p>
Traditional blog navigation — chronological lists, tag clouds, category pages — fails to represent how technical topics actually interconnect. A post about database optimization relates to performance profiling, which connects to observability, which ties back to system design. These relationships are inherently graph-shaped, not list-shaped. Readers browsing a flat list miss connections that could lead them to exactly the content they need.
</p>

<p>
The task was threefold: improve content discoverability by surfacing topic relationships, create a visual portfolio piece that demonstrates frontend engineering capability, and provide a homepage that's genuinely interesting rather than a static list of links. The result is an interactive 3D force-directed graph on the homepage showing relationships between blog posts, where nodes represent posts and edges represent shared concepts.
</p>
</div>
<div id="outline-container-technology-stack" class="outline-4">
<h4 id="technology-stack"><span class="section-number-4">5.1.1.</span> Technology Stack</h4>
<div class="outline-text-4" id="text-technology-stack">
<ul class="org-ul">
<li><b>3d-force-graph</b>: High-level library wrapping Three.js and d3-force-3d</li>
<li><b>three-spritetext</b>: Renders text labels as 3D sprites</li>
<li><b>WebGL</b>: Hardware-accelerated rendering</li>
</ul>
</div>
</div>
<div id="outline-container-performance-optimizations" class="outline-4">
<h4 id="performance-optimizations"><span class="section-number-4">5.1.2.</span> Performance Optimizations</h4>
<div class="outline-text-4" id="text-performance-optimizations">
<div class="org-src-container">
<pre class="src src-typescript">// Lazy loading with IntersectionObserver
const observer = new IntersectionObserver(
  (entries) => {
    if (entries[0].isIntersecting) {
      initializeGraph();
      observer.disconnect();
    }
  },
  { rootMargin: '100px' }
);

// Pause animation when tab is hidden
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    graph.pauseAnimation();
  } else {
    graph.resumeAnimation();
  }
});
</pre>
</div>
</div>
</div>
<div id="outline-container-user-interaction" class="outline-4">
<h4 id="user-interaction"><span class="section-number-4">5.1.3.</span> User Interaction</h4>
<div class="outline-text-4" id="text-user-interaction">
<p>
The graph supports:
</p>
<ul class="org-ul">
<li><b>Auto-rotation</b>: Continuous slow rotation for visual interest</li>
<li><b>Drag</b>: Stops rotation, allows free camera movement</li>
<li><b>Click</b>: Navigates to the clicked post</li>
<li><b>Reset</b>: Returns to default view with smooth animation</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-plotly-chart-integration" class="outline-3">
<h3 id="plotly-chart-integration"><span class="section-number-3">5.2.</span> Plotly Chart Integration</h3>
<div class="outline-text-3" id="text-plotly-chart-integration">
<p>
Static images of charts in technical blog posts are a missed opportunity. Readers can't zoom into dense scatter plots, rotate 3D visualizations, or hover over data points to see exact values. But embedding interactive charts introduces UX problems — chart drag gestures conflict with page scrolling, and accidentally interacting with a chart while reading is frustrating.
</p>

<p>
I needed interactive charts that stay out of the way during normal reading but become fully interactive on demand, with the ability to expand to fullscreen for detailed exploration. Interactive charts are defined in JSON and rendered with Plotly.js:
</p>

<div class="org-src-container">
<pre class="src src-json">{
  "data": [{
    "type": "scatter3d",
    "x": [1, 2, 3],
    "y": [4, 5, 6],
    "z": [7, 8, 9],
    "mode": "markers"
  }],
  "layout": {
    "title": "3D Scatter Plot"
  }
}
</pre>
</div>
</div>
<div id="outline-container-lock-unlock-mechanism" class="outline-4">
<h4 id="lock-unlock-mechanism"><span class="section-number-4">5.2.1.</span> Lock/Unlock Mechanism</h4>
<div class="outline-text-4" id="text-lock-unlock-mechanism">
<p>
Charts start "locked" to prevent accidental interaction while scrolling:
</p>

<ol class="org-ol">
<li>Charts render with <code>pointer-events: none</code></li>
<li>An overlay displays "Click to interact"</li>
<li>Clicking enables the chart (<code>pointer-events: auto</code>)</li>
<li>Pressing Escape re-locks the chart</li>
</ol>
</div>
</div>
<div id="outline-container-modal-expansion" class="outline-4">
<h4 id="modal-expansion"><span class="section-number-4">5.2.2.</span> Modal Expansion</h4>
<div class="outline-text-4" id="text-modal-expansion">
<p>
Charts can expand to fullscreen modals with:
</p>
<ul class="org-ul">
<li>Full toolbar access</li>
<li>Animation frame preservation</li>
<li>Enhanced legend positioning</li>
<li>95vw × 90vh dimensions</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-devpulse--commit-activity-grid" class="outline-3">
<h3 id="devpulse--commit-activity-grid"><span class="section-number-3">5.3.</span> DevPulse: Commit Activity Grid</h3>
<div class="outline-text-3" id="text-devpulse--commit-activity-grid">
<p>
A portfolio blog should demonstrate that the author is actively building, not just publishing static content. Visitors landing on the homepage should immediately see evidence of consistent coding activity — it builds credibility and shows the site is maintained. GitHub's contribution graph is effective at communicating this at a glance, but it's buried on a profile page most visitors won't find.
</p>

<p>
The task was to build a visible indicator of development activity directly on the homepage, with more flexibility than GitHub's single-scale yearly view. Inspired by GitHub's contribution graph, DevPulse shows my commit activity with five different time scales for different perspectives:
</p>
</div>
<div id="outline-container-multi-scale-timeline" class="outline-4">
<h4 id="multi-scale-timeline"><span class="section-number-4">5.3.1.</span> Multi-Scale Timeline</h4>
<div class="outline-text-4" id="text-multi-scale-timeline">
<p>
Five different time scales provide different perspectives:
</p>
<ul class="org-ul">
<li><b>Days</b>: 7-column grid (weekdays)</li>
<li><b>Weeks</b>: 52 columns (one year)</li>
<li><b>Months</b>: 12 columns (J-D)</li>
<li><b>Quarters</b>: 4 columns (Q1-Q4)</li>
<li><b>Years</b>: 10 columns (decade view)</li>
</ul>
</div>
</div>
<div id="outline-container-data-pipeline" class="outline-4">
<h4 id="data-pipeline"><span class="section-number-4">5.3.2.</span> Data Pipeline</h4>
<div class="outline-text-4" id="text-data-pipeline">
<div class="org-src-container">
<pre class="src src-typescript">// API endpoint fetches from GitHub
const response = await fetch(
  `https://api.github.com/repos/${owner}/${repo}/commits`,
  {
    headers: {
      Authorization: `token ${GITHUB_TOKEN}`,
      Accept: 'application/vnd.github.v3+json'
    }
  }
);

// Transform to activity grid
const commits = await response.json();
const activityMap = aggregateByTimePeriod(commits, scale);
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-recursive-link-previews" class="outline-3">
<h3 id="recursive-link-previews"><span class="section-number-3">5.4.</span> Recursive Link Previews</h3>
<div class="outline-text-3" id="text-recursive-link-previews">
<p>
Technical blog posts are densely linked — to other posts, documentation, external resources. Every click takes the reader away from their current context, and the mental cost of deciding "is this link worth following?" disrupts reading flow. Readers either ignore links entirely (missing valuable context) or click them and lose their place in the original article.
</p>

<p>
The task was to let readers preview linked content without navigating away, maintaining their reading context while still providing access to referenced material. The result is hover-triggered preview popups with support for nested previews up to 10 levels deep — a reader can preview a link, then preview a link within that preview, following a chain of references without ever leaving the page.
</p>
</div>
<div id="outline-container-architecture" class="outline-4">
<h4 id="architecture"><span class="section-number-4">5.4.1.</span> Architecture</h4>
<div class="outline-text-4" id="text-architecture">
<pre class="example" id="orgb2016e5">
User hovers link → 300ms delay → Fetch preview
                                      ↓
                              Internal link? → Clone article content
                                      ↓
                              External link? → Fetch via proxy
                                      ↓
                              Display in popup with sanitized HTML
</pre>
</div>
</div>
<div id="outline-container-proxy-server" class="outline-4">
<h4 id="proxy-server"><span class="section-number-4">5.4.2.</span> Proxy Server</h4>
<div class="outline-text-4" id="text-proxy-server">
<p>
External previews route through <code>/api/preview-proxy</code> which:
</p>

<ol class="org-ol">
<li>Fetches the external page</li>
<li>Sanitizes HTML with DOMPurify</li>
<li>Rewrites relative URLs to absolute</li>
<li>Hides modals, cookie banners, chat widgets</li>
<li>Returns safe, displayable content</li>
</ol>
</div>
</div>
<div id="outline-container-performance" class="outline-4">
<h4 id="performance"><span class="section-number-4">5.4.3.</span> Performance</h4>
<div class="outline-text-4" id="text-performance">
<ul class="org-ul">
<li>300ms hover delay prevents accidental triggers</li>
<li>Grace period keeps popup open when moving between link and popup</li>
<li>10-second timeout prevents stuck loading states</li>
<li>Cross-origin iframe sandboxing for security</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-full-text-search-with-algolia" class="outline-3">
<h3 id="full-text-search-with-algolia"><span class="section-number-3">5.5.</span> Full-Text Search with Algolia</h3>
<div class="outline-text-3" id="text-full-text-search-with-algolia">
<p>
As the number of posts grew, the table of contents and knowledge graph became insufficient for finding specific content. A reader who remembers reading about "WebGL performance" but can't recall which post it was in needs instant, typo-tolerant full-text search across all content.
</p>

<p>
Building search from scratch (inverted indices, ranking algorithms, typo tolerance) would be a massive undertaking for marginal benefit. The task was to integrate a hosted search service that provides sub-50ms results with section-level granularity, keyboard-driven UX, and minimal client-side code. Search is powered by Algolia with InstantSearch.js:
</p>

<div class="org-src-container">
<pre class="src src-typescript">const searchClient = algoliasearch(APP_ID, API_KEY);

instantsearch({
  indexName: 'posts',
  searchClient,
  searchFunction(helper) {
    if (helper.state.query) {
      helper.search();
    }
  }
});
</pre>
</div>
</div>
<div id="outline-container-keyboard-navigation" class="outline-4">
<h4 id="keyboard-navigation"><span class="section-number-4">5.5.1.</span> Keyboard Navigation</h4>
<div class="outline-text-4" id="text-keyboard-navigation">
<ul class="org-ul">
<li><code>Cmd/Ctrl + K</code>: Open search modal</li>
<li><code>Escape</code>: Close search</li>
<li><code>Enter</code>: Navigate to first result</li>
<li>Arrow keys: Navigate results</li>
</ul>
</div>
</div>
<div id="outline-container-jump-to-section" class="outline-4">
<h4 id="jump-to-section"><span class="section-number-4">5.5.2.</span> Jump to Section</h4>
<div class="outline-text-4" id="text-jump-to-section">
<p>
Search results link to specific sections with highlight animation:
</p>

<div class="org-src-container">
<pre class="src src-css">.search-highlight-target {
  animation: search-highlight 2s ease-out;
}

@keyframes search-highlight {
  0% { background-color: rgba(138, 106, 170, 0.3); }
  100% { background-color: transparent; }
}
</pre>
</div>
</div>
</div>
</div>
</div>
<div id="outline-container-seo-optimization" class="outline-2">
<h2 id="seo-optimization"><span class="section-number-2">6.</span> SEO Optimization</h2>
<div class="outline-text-2" id="text-seo-optimization">
<p>
Writing quality technical content is pointless if search engines can't find, understand, or properly display it. A SvelteKit blog with client-side rendering and dynamic content loading presents specific SEO challenges — crawlers may not execute JavaScript, social media link previews need pre-rendered metadata, and search engines need structured data to understand content relationships.
</p>

<p>
The task was to ensure every page is fully crawlable with rich metadata, appears correctly when shared on social media, and provides search engines with structured data about authorship, dates, and content type — all while keeping the content authoring workflow in org-mode.
</p>
</div>
<div id="outline-container-meta-tags" class="outline-3">
<h3 id="meta-tags"><span class="section-number-3">6.1.</span> Meta Tags</h3>
<div class="outline-text-3" id="text-meta-tags">
<p>
Every page includes comprehensive meta tags extracted from the org-mode source during the server-side loading phase:
</p>

<div class="org-src-container">
<pre class="src src-html"><!-- Basic -->
<meta name="description" content="{description}">
<link rel="canonical" href="{url}">

<!-- Open Graph -->
<meta property="og:title" content="{title}">
<meta property="og:description" content="{description}">
<meta property="og:type" content="article">
<meta property="og:url" content="{url}">
<meta property="og:image" content="{image}">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{title}">
<meta name="twitter:description" content="{description}">
</pre>
</div>
</div>
</div>
<div id="outline-container-structured-data--json-ld-" class="outline-3">
<h3 id="structured-data--json-ld-"><span class="section-number-3">6.2.</span> Structured Data (JSON-LD)</h3>
<div class="outline-text-3" id="text-structured-data--json-ld-">
<p>
Blog posts include schema.org structured data:
</p>

<div class="org-src-container">
<pre class="src src-json">{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Design Decisions: Building a Modern Technical Blog",
  "author": {
    "@type": "Person",
    "name": "Charlie Holland"
  },
  "datePublished": "2026-01-21",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://chiply.dev/post-design-decisions"
  }
}
</pre>
</div>

<p>
This helps search engines understand content relationships.
</p>
</div>
</div>
<div id="outline-container-sitemap-and-rss" class="outline-3">
<h3 id="sitemap-and-rss"><span class="section-number-3">6.3.</span> Sitemap and RSS</h3>
<div class="outline-text-3" id="text-sitemap-and-rss">
<p>
Both are generated at build time by scanning the <code>src/routes/[post]/</code> directory:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// sitemap.xml/+server.ts
export const GET: RequestHandler = async () => {
  const posts = await discoverPosts();

  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      ${posts.map(post => `
        <url>
          <loc>https://chiply.dev/${post.slug}</loc>
          <lastmod>${post.date}</lastmod>
          <priority>0.8</priority>
        </url>
      `).join('')}
    </urlset>`;

  return new Response(sitemap, {
    headers: { 'Content-Type': 'application/xml' }
  });
};
</pre>
</div>
</div>
</div>
<div id="outline-container-prerendering" class="outline-3">
<h3 id="prerendering"><span class="section-number-3">6.4.</span> Prerendering</h3>
<div class="outline-text-3" id="text-prerendering">
<p>
All pages are prerendered at build time:
</p>

<div class="org-src-container">
<pre class="src src-typescript">export const prerender = true;

export const entries: EntryGenerator = async () => {
  const posts = await discoverPosts();
  return posts.map(post => ({ post: post.slug }));
};
</pre>
</div>

<p>
This ensures search engines receive fully-rendered HTML.
</p>
</div>
</div>
</div>
<div id="outline-container-analytics-and-tracking" class="outline-2">
<h2 id="analytics-and-tracking"><span class="section-number-2">7.</span> Analytics and Tracking</h2>
<div class="outline-text-2" id="text-analytics-and-tracking">
<p>
Publishing technical content into the void without any feedback loop felt unsatisfying. I was curious about basic questions: do people actually find and read these posts? Do they finish long articles or drop off midway? Which topics get traction? Standard page view counters answer the first question but tell you nothing about reading behavior.
</p>

<p>
The task was to understand traffic patterns and reader engagement out of curiosity, layering lightweight analytics that answer increasingly specific questions — from basic page views to scroll depth and session recordings — without invasive tracking or degrading page performance.
</p>
</div>
<div id="outline-container-vercel-analytics" class="outline-3">
<h3 id="vercel-analytics"><span class="section-number-3">7.1.</span> Vercel Analytics</h3>
<div class="outline-text-3" id="text-vercel-analytics">
<p>
The first layer is Vercel's built-in analytics, requiring just two lines of code to track page views and Web Vitals:
</p>

<div class="org-src-container">
<pre class="src src-typescript">import { inject } from '@vercel/analytics';
inject();
</pre>
</div>
</div>
</div>
<div id="outline-container-speed-insights" class="outline-3">
<h3 id="speed-insights"><span class="section-number-3">7.2.</span> Speed Insights</h3>
<div class="outline-text-3" id="text-speed-insights">
<p>
Real User Monitoring (RUM) captures Core Web Vitals:
</p>

<ul class="org-ul">
<li><b>LCP</b> (Largest Contentful Paint)</li>
<li><b>FID</b> (First Input Delay)</li>
<li><b>CLS</b> (Cumulative Layout Shift)</li>
</ul>
</div>
</div>
<div id="outline-container-custom-engagement-tracking" class="outline-3">
<h3 id="custom-engagement-tracking"><span class="section-number-3">7.3.</span> Custom Engagement Tracking</h3>
<div class="outline-text-3" id="text-custom-engagement-tracking">
<p>
Page views alone don't distinguish between a reader who bounced after 3 seconds and one who spent 20 minutes reading every section. Standard analytics tools track navigation but not engagement depth. I wanted to know: do readers who start a 5000-word post actually finish it?
</p>

<p>
I built custom engagement tracking to answer these questions about reading behavior:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// Track scroll depth milestones
const milestones = [25, 50, 75, 100];

const handleScroll = debounce(() => {
  const scrollPercent = (scrollTop / scrollHeight) * 100;

  milestones.forEach(milestone => {
    if (scrollPercent >= milestone && !reached[milestone]) {
      reached[milestone] = true;
      trackEvent('scroll_milestone', { depth: milestone });
    }
  });
}, 100);
</pre>
</div>

<p>
Metrics tracked include:
</p>
<ul class="org-ul">
<li>Scroll depth (25%, 50%, 75%, 100%)</li>
<li>Time on page (active time, excluding hidden tabs)</li>
<li>Read completion (>90% scroll depth)</li>
</ul>
</div>
</div>
<div id="outline-container-microsoft-clarity" class="outline-3">
<h3 id="microsoft-clarity"><span class="section-number-3">7.4.</span> Microsoft Clarity</h3>
<div class="outline-text-3" id="text-microsoft-clarity">
<p>
Clarity provides heatmaps and session recordings for UX analysis:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// Secure initialization with validation
const clarityId = import.meta.env.VITE_CLARITY_ID;
if (clarityId && /^[a-zA-Z0-9]+$/.test(clarityId)) {
  const script = document.createElement('script');
  script.src = `https://www.clarity.ms/tag/${clarityId}`;
  script.async = true;
  document.head.appendChild(script);
}
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-newsletter-integration" class="outline-2">
<h2 id="newsletter-integration"><span class="section-number-2">8.</span> Newsletter Integration</h2>
<div class="outline-text-2" id="text-newsletter-integration">
<p>
Relying solely on organic search traffic means readers who enjoy a post have no way to know when new content is published. Social media algorithms are unreliable for reach, and RSS — while supported — has a tiny user base outside of developer circles. A newsletter provides a direct, algorithm-free channel to interested readers.
</p>

<p>
The task was to add subscription capability without the complexity of running a mail server, managing deliverability, or building subscriber management UI. The solution needed GDPR-compliant double opt-in and should integrate cleanly with the existing SvelteKit API endpoint pattern.
</p>
</div>
<div id="outline-container-buttondown-api" class="outline-3">
<h3 id="buttondown-api"><span class="section-number-3">8.1.</span> Buttondown API</h3>
<div class="outline-text-3" id="text-buttondown-api">
<p>
I chose Buttondown for its developer-friendly API and minimal UI — it handles deliverability, unsubscribes, and confirmation emails while I just call one endpoint. Newsletter subscriptions use Buttondown's API:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// /api/subscribe/+server.ts
export const POST: RequestHandler = async ({ request }) => {
  const { email } = await request.json();

  // RFC 5321 validation
  if (!isValidEmail(email)) {
    return json({ error: 'Invalid email' }, { status: 400 });
  }

  const response = await fetch('https://api.buttondown.com/v1/subscribers', {
    method: 'POST',
    headers: {
      Authorization: `Token ${BUTTONDOWN_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  return json({ success: true });
};
</pre>
</div>
</div>
</div>
<div id="outline-container-double-opt-in" class="outline-3">
<h3 id="double-opt-in"><span class="section-number-3">8.2.</span> Double Opt-In</h3>
<div class="outline-text-3" id="text-double-opt-in">
<p>
Buttondown handles confirmation emails, ensuring GDPR compliance and reducing spam.
</p>
</div>
</div>
</div>
<div id="outline-container-security-considerations" class="outline-2">
<h2 id="security-considerations"><span class="section-number-2">9.</span> Security Considerations</h2>
<div class="outline-text-2" id="text-security-considerations">
<p>
Professional security habits demanded proper hardening even for a personal blog. The site isn't just serving static HTML — it fetches and renders external content through the link preview proxy, loads org-mode-exported HTML into the DOM, accepts user input through newsletter subscriptions, and runs API endpoints that proxy to external services. Each of these is a potential XSS, injection, or data exfiltration vector.
</p>

<p>
The task was to implement defense-in-depth: multiple independent security layers so that if any single defense fails, others still protect the site. This meant sanitizing all rendered HTML, restricting what resources the browser can load, validating all inputs, and hardening HTTP headers against common attack patterns.
</p>
</div>
<div id="outline-container-html-sanitization" class="outline-3">
<h3 id="html-sanitization"><span class="section-number-3">9.1.</span> HTML Sanitization</h3>
<div class="outline-text-3" id="text-html-sanitization">
<p>
The most critical defense layer, since the site dynamically renders HTML from multiple sources (org-mode exports, external link previews). All user-facing HTML is sanitized with DOMPurify using strict allowlists:
</p>

<div class="org-src-container">
<pre class="src src-typescript">import DOMPurify from 'dompurify';

const ALLOWED_TAGS = [
  'article', 'section', 'nav', 'header', 'footer',
  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
  'p', 'ul', 'ol', 'li', 'a', 'strong', 'em',
  'pre', 'code', 'blockquote', 'table', 'tr', 'td', 'th',
  'img', 'figure', 'figcaption', 'svg', 'path'
];

const ALLOWED_ATTR = [
  'id', 'class', 'href', 'src', 'alt', 'title',
  'aria-label', 'aria-hidden', 'role',
  'data-*', 'width', 'height'
];

export const sanitizeHtml = (html: string) => {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS,
    ALLOWED_ATTR,
    ALLOWED_URI_REGEXP: /^(?:https?|mailto|tel):/i
  });
};
</pre>
</div>
</div>
</div>
<div id="outline-container-content-security-policy" class="outline-3">
<h3 id="content-security-policy"><span class="section-number-3">9.2.</span> Content Security Policy</h3>
<div class="outline-text-3" id="text-content-security-policy">
<p>
The CSP header restricts resource loading:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// hooks.server.ts
const csp = [
  "default-src 'self'",
  "script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net cdnjs.cloudflare.com",
  "style-src 'self' 'unsafe-inline' cdn.jsdelivr.net",
  "img-src 'self' data: blob: https:",
  "font-src 'self' data: cdn.jsdelivr.net",
  "connect-src 'self' api.github.com *.algolia.net",
  "frame-src 'self'",
  "object-src 'none'",
  "base-uri 'self'",
  "upgrade-insecure-requests"
].join('; ');

response.headers.set('Content-Security-Policy', csp);
</pre>
</div>
</div>
</div>
<div id="outline-container-security-headers" class="outline-3">
<h3 id="security-headers"><span class="section-number-3">9.3.</span> Security Headers</h3>
<div class="outline-text-3" id="text-security-headers">
<p>
Additional headers prevent common attacks:
</p>

<div class="org-src-container">
<pre class="src src-typescript">response.headers.set('X-Frame-Options', 'SAMEORIGIN');
response.headers.set('X-Content-Type-Options', 'nosniff');
response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
</pre>
</div>
</div>
</div>
<div id="outline-container-input-validation" class="outline-3">
<h3 id="input-validation"><span class="section-number-3">9.4.</span> Input Validation</h3>
<div class="outline-text-3" id="text-input-validation">
<p>
All API inputs are validated:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// Email validation (RFC 5321 compliant)
const isValidEmail = (email: string): boolean => {
  if (typeof email !== 'string') return false;
  if (email.length > 254) return false;

  const [local, domain] = email.split('@');
  if (!local || !domain) return false;
  if (local.length > 64) return false;
  if (/\.\./.test(email)) return false;

  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
};

// URL validation
const isValidUrl = (url: string): boolean => {
  try {
    const parsed = new URL(url);
    return ['http:', 'https:'].includes(parsed.protocol);
  } catch {
    return false;
  }
};
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-accessibility" class="outline-2">
<h2 id="accessibility"><span class="section-number-2">10.</span> Accessibility</h2>
<div class="outline-text-2" id="text-accessibility">
<p>
A technical blog should be readable by everyone, including developers using screen readers, keyboard-only navigation, or high-contrast modes. The interactive features (3D graph, charts, search modals) introduced specific accessibility challenges — custom interactive widgets don't get keyboard support or screen reader announcements for free.
</p>

<p>
The task was to maintain WCAG compliance across both the org-mode-exported static content and the custom interactive Svelte components, ensuring every feature works without a mouse and communicates its state to assistive technology.
</p>
</div>
<div id="outline-container-semantic-html" class="outline-3">
<h3 id="semantic-html"><span class="section-number-3">10.1.</span> Semantic HTML</h3>
<div class="outline-text-3" id="text-semantic-html">
<p>
The foundation of accessibility is semantic HTML, and org-mode's export helps here by default — headings, paragraphs, lists, and tables all use correct elements. Org-mode exports clean semantic HTML:
</p>

<div class="org-src-container">
<pre class="src src-html"><article>
  <header>
    <h1>Post Title</h1>
    <time datetime="2026-01-21">January 21, 2026</time>
  </header>
  <section id="introduction">
    <h2>Introduction</h2>
    <p>Content...</p>
  </section>
</article>
</pre>
</div>
</div>
</div>
<div id="outline-container-aria-labels" class="outline-3">
<h3 id="aria-labels"><span class="section-number-3">10.2.</span> ARIA Labels</h3>
<div class="outline-text-3" id="text-aria-labels">
<p>
Interactive elements include ARIA attributes:
</p>

<div class="org-src-container">
<pre class="src src-html"><button
  aria-label="Toggle theme"
  aria-pressed={isDark}
  onclick={toggleTheme}
>
  <i class="fa-solid fa-moon" aria-hidden="true"></i>
</button>

<dialog
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
>
  <h2 id="modal-title">Search</h2>
</dialog>
</pre>
</div>
</div>
</div>
<div id="outline-container-keyboard-navigation" class="outline-3">
<h3 id="keyboard-navigation"><span class="section-number-3">10.3.</span> Keyboard Navigation</h3>
<div class="outline-text-3" id="text-keyboard-navigation">
<p>
All functionality is keyboard accessible:
</p>

<ul class="org-ul">
<li><b>Tab</b>: Navigate between interactive elements</li>
<li><b>Enter/Space</b>: Activate buttons</li>
<li><b>Escape</b>: Close modals</li>
<li><b>Cmd/Ctrl+K</b>: Open search</li>
<li><b>Arrow keys</b>: Navigate search results</li>
</ul>
</div>
</div>
<div id="outline-container-focus-management" class="outline-3">
<h3 id="focus-management"><span class="section-number-3">10.4.</span> Focus Management</h3>
<div class="outline-text-3" id="text-focus-management">
<p>
Modals trap and restore focus:
</p>

<div class="org-src-container">
<pre class="src src-typescript">let previouslyFocusedElement: HTMLElement | null = null;

function openModal() {
  previouslyFocusedElement = document.activeElement as HTMLElement;
  modalElement.focus();
}

function closeModal() {
  previouslyFocusedElement?.focus();
  previouslyFocusedElement = null;
}
</pre>
</div>
</div>
</div>
<div id="outline-container-skip-link" class="outline-3">
<h3 id="skip-link"><span class="section-number-3">10.5.</span> Skip Link</h3>
<div class="outline-text-3" id="text-skip-link">
<p>
A skip link allows keyboard users to bypass navigation:
</p>

<div class="org-src-container">
<pre class="src src-html"><a href="https://www.chiply.dev/#main-content" class="skip-link">
  Skip to main content
</a>
</pre>
</div>
</div>
</div>
</div>
<div id="outline-container-performance-optimizations" class="outline-2">
<h2 id="performance-optimizations"><span class="section-number-2">11.</span> Performance Optimizations</h2>
<div class="outline-text-2" id="text-performance-optimizations">
<p>
The blog includes heavy dependencies — Three.js for the 3D graph, Plotly.js for interactive charts, Algolia for search, and multiple analytics scripts. Loading all of these eagerly on every page would produce a massive initial bundle, degrading Core Web Vitals and making the site sluggish on mobile devices or slow connections. A reader who just wants to read a blog post shouldn't download a WebGL renderer.
</p>

<p>
The task was to ensure fast initial page loads regardless of which features a particular page uses, deferring expensive resources until they're actually needed while maintaining a smooth experience when they do load.
</p>
</div>
<div id="outline-container-lazy-loading" class="outline-3">
<h3 id="lazy-loading"><span class="section-number-3">11.1.</span> Lazy Loading</h3>
<div class="outline-text-3" id="text-lazy-loading">
<p>
Heavy components load on demand, triggered only when they enter (or approach) the viewport:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// IntersectionObserver for viewport-triggered loading
const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        loadComponent();
        observer.unobserve(entry.target);
      }
    });
  },
  { rootMargin: '100px' }
);
</pre>
</div>
</div>
</div>
<div id="outline-container-code-splitting" class="outline-3">
<h3 id="code-splitting"><span class="section-number-3">11.2.</span> Code Splitting</h3>
<div class="outline-text-3" id="text-code-splitting">
<p>
Dynamic imports split the bundle:
</p>

<div class="org-src-container">
<pre class="src src-typescript">// Only load Algolia when search opens
const loadSearch = async () => {
  const { default: algoliasearch } = await import('algoliasearch');
  const { default: instantsearch } = await import('instantsearch.js');
  // Initialize search...
};
</pre>
</div>
</div>
</div>
<div id="outline-container-caching-strategy" class="outline-3">
<h3 id="caching-strategy"><span class="section-number-3">11.3.</span> Caching Strategy</h3>
<div class="outline-text-3" id="text-caching-strategy">
<p>
Different resources have different cache lifetimes:
</p>

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">


<colgroup>
<col  class="org-left" />

<col  class="org-left" />

<col  class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Resource Type</th>
<th scope="col" class="org-left">Browser Cache</th>
<th scope="col" class="org-left">CDN Cache</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">Fonts</td>
<td class="org-left">1 year</td>
<td class="org-left">1 year</td>
</tr>

<tr>
<td class="org-left">Static assets</td>
<td class="org-left">1 year</td>
<td class="org-left">1 year</td>
</tr>

<tr>
<td class="org-left">API responses</td>
<td class="org-left">5 minutes</td>
<td class="org-left">1 hour</td>
</tr>

<tr>
<td class="org-left">HTML pages</td>
<td class="org-left">0</td>
<td class="org-left">1 hour</td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="outline-container-image-optimization" class="outline-3">
<h3 id="image-optimization"><span class="section-number-3">11.4.</span> Image Optimization</h3>
<div class="outline-text-3" id="text-image-optimization">
<p>
Images are optimized with:
</p>

<ul class="org-ul">
<li>WebP format where supported</li>
<li>Lazy loading via <code>loading</code>"lazy"=</li>
<li>Appropriate sizing with <code>srcset</code></li>
<li>Placeholder aspect ratios to prevent CLS</li>
</ul>
</div>
</div>
</div>
<div id="outline-container-versioning-and-releases" class="outline-2">
<h2 id="versioning-and-releases"><span class="section-number-2">12.</span> Versioning and Releases</h2>
<div class="outline-text-2" id="text-versioning-and-releases">
<p>
As the project grew with frequent commits — new features, bug fixes, content additions — the question of "what changed and when" became harder to answer. Without structured versioning, there's no way to communicate the significance of changes (is this a breaking change? a new feature? a patch?) or generate meaningful changelogs for anyone following the project.
</p>

<p>
Setting up proper release engineering early, before the project accumulated hundreds of commits, would prevent future pain. The task was to automate version bumping and changelog generation from commit history, requiring only disciplined commit messages rather than manual bookkeeping.
</p>
</div>
<div id="outline-container-semantic-versioning" class="outline-3">
<h3 id="semantic-versioning"><span class="section-number-3">12.1.</span> Semantic Versioning</h3>
<div class="outline-text-3" id="text-semantic-versioning">
<p>
The project uses SemVer with automated releases, where the version bump is determined entirely by commit message prefixes:
</p>

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">


<colgroup>
<col  class="org-left" />

<col  class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">Commit Type</th>
<th scope="col" class="org-left">Version Bump</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left"><code>fix:</code></td>
<td class="org-left">PATCH (0.0.x)</td>
</tr>

<tr>
<td class="org-left"><code>feat:</code></td>
<td class="org-left">MINOR (0.x.0)</td>
</tr>

<tr>
<td class="org-left"><code>BREAKING CHANGE:</code></td>
<td class="org-left">MAJOR (x.0.0)</td>
</tr>
</tbody>
</table>
</div>
</div>
<div id="outline-container-release-please" class="outline-3">
<h3 id="release-please"><span class="section-number-3">12.2.</span> Release Please</h3>
<div class="outline-text-3" id="text-release-please">
<p>
Google's release-please automates version management:
</p>

<ol class="org-ol">
<li>Conventional commits trigger Release PRs</li>
<li>PRs include changelog updates</li>
<li>Merging creates GitHub releases and tags</li>
<li><code>package.json</code> version updates automatically</li>
</ol>
</div>
</div>
<div id="outline-container-changelog-generation" class="outline-3">
<h3 id="changelog-generation"><span class="section-number-3">12.3.</span> Changelog Generation</h3>
<div class="outline-text-3" id="text-changelog-generation">
<p>
Changelogs are auto-generated from commit messages:
</p>

<pre class="example" id="org3dfa382">
## [0.1.0] - 2026-01-21

### Features
- Add share button with social media platforms
- Add 3D knowledge graph visualization

### Bug Fixes
- Fix theme flash on page load
- Correct chart modal focus management
</pre>
</div>
</div>
</div>
<div id="outline-container-conclusion" class="outline-2">
<h2 id="conclusion"><span class="section-number-2">13.</span> Conclusion</h2>
<div class="outline-text-2" id="text-conclusion">
<p>
Building chiply.dev has been an exercise in thoughtful engineering. Every decision - from Svelte's compiled output to org-mode's literate programming - serves the goal of creating an engaging, performant, and accessible reading experience.
</p>

<p>
The codebase reflects my belief that personal projects should be laboratories for exploring ideas. The recursive link previews might be over-engineered, but they taught me about iframe security policies. The 3D knowledge graph might be unnecessary, but it forced me to learn WebGL performance optimization.
</p>

<p>
If you're building your own technical blog, I hope this post provides useful starting points. Feel free to explore the source code on GitHub, and don't hesitate to reach out with questions or suggestions.
</p>
</div>
</div>
<div id="outline-container-references" class="outline-2">
<h2 id="references"><span class="section-number-2">14.</span> References</h2>
<div class="outline-text-2" id="text-references">
<ul class="org-ul">
<li><a href="https://svelte.dev/docs">Svelte 5 Documentation</a></li>
<li><a href="https://kit.svelte.dev/docs">SvelteKit Documentation</a></li>
<li><a href="https://open-props.style">Open Props CSS</a></li>
<li><a href="https://orgmode.org/manual/">Org Mode Manual</a></li>
<li><a href="https://plotly.com/javascript/">Plotly.js Documentation</a></li>
<li><a href="https://github.com/vasturiano/3d-force-graph">3D Force Graph</a></li>
<li><a href="https://www.algolia.com/doc/">Algolia Documentation</a></li>
<li><a href="https://github.com/cure53/DOMPurify">DOMPurify</a></li>
<li><a href="https://web.dev/vitals/">Core Web Vitals</a></li>
<li><a href="https://schema.org/BlogPosting">Schema.org BlogPosting</a></li>
</ul>
</div>
</div>
<div id="outline-container-tldr" class="outline-2">
<h2 id="tldr"><span class="section-number-2">15.</span> tldr</h2>
<div class="outline-text-2" id="text-tldr">
<p>
This post details the architectural decisions behind chiply.dev, a modern technical blog built with <a href="https://www.chiply.dev/#framework-selection">SvelteKit 2 and Svelte 5's new runes system</a> for explicit reactivity and compiled performance. The <a href="https://www.chiply.dev/#content-management--org-mode-to-html">content pipeline uses Emacs org-mode</a> for literate programming capabilities, exporting to HTML that gets processed server-side for metadata extraction and <a href="https://www.chiply.dev/#full-text-search-indexing">chunked into Algolia search records by heading</a>.
</p>

<p>
The <a href="https://www.chiply.dev/#styling-architecture">styling leverages Open Props CSS custom properties</a> instead of Tailwind for semantic naming and lighter bundles, with a <a href="https://www.chiply.dev/#theme-system">sophisticated theme system</a> preventing flash-of-wrong-theme on load. The <a href="https://www.chiply.dev/#interactive-features">interactive features include a 3D knowledge graph</a> built with Three.js and WebGL, <a href="https://www.chiply.dev/#plotly-chart-integration">Plotly charts with lock/unlock mechanisms</a>, and the <a href="https://www.chiply.dev/#devpulse--commit-activity-grid">DevPulse commit activity visualization</a> showing GitHub contributions across multiple time scales.
</p>

<p>
<a href="https://www.chiply.dev/#recursive-link-previews">Recursive link previews support 10 levels of nesting</a>, fetching content through a <a href="https://www.chiply.dev/#proxy-server">sanitizing proxy server</a> for external sites. The <a href="https://www.chiply.dev/#seo-optimization">SEO strategy includes comprehensive meta tags</a>, structured data with JSON-LD, and <a href="https://www.chiply.dev/#prerendering">full prerendering at build time</a>. <a href="https://www.chiply.dev/#analytics-and-tracking">Analytics combine Vercel's built-in monitoring</a> with custom engagement tracking for scroll depth and read completion, plus <a href="https://www.chiply.dev/#microsoft-clarity">Microsoft Clarity for heatmaps</a>.
</p>

<p>
<a href="https://www.chiply.dev/#newsletter-integration">Newsletter subscriptions use Buttondown's API</a> with double opt-in for GDPR compliance. <a href="https://www.chiply.dev/#security-considerations">Security measures include DOMPurify HTML sanitization</a>, strict Content Security Policy headers, and <a href="https://www.chiply.dev/#input-validation">comprehensive input validation</a>. The site maintains <a href="https://www.chiply.dev/#accessibility">WCAG compliance through semantic HTML</a>, ARIA labels, and <a href="https://www.chiply.dev/#keyboard-navigation">full keyboard navigation support</a>.
</p>

<p>
<a href="https://www.chiply.dev/#performance-optimizations">Performance optimizations include lazy loading</a>, code splitting with dynamic imports, and <a href="https://www.chiply.dev/#caching-strategy">aggressive caching strategies</a> differentiated by resource type. The <a href="https://www.chiply.dev/#versioning-and-releases">release process uses semantic versioning</a> with Google's release-please automating changelog generation from conventional commits.
</p>
</div>
</div>
</article>
<article>
<h1>post1</h1>
<p>Charlie Holland (main) — Thu, 22 Jan 2026 03:14:00 GMT</p>


<div id="outline-container-demo-heading" class="outline-2">
<h2 id="demo-heading"><span class="section-number-2">1.</span> Demo heading</h2>
<div class="outline-text-2" id="text-demo-heading">
<p>
This is a demo post – This content is written in post1.org but is actually intended to be transcluded from another file (post0.org).  That's why you utlimately see this content here.
</p>
</div>
</div>
<div id="outline-container-demo-heading-with-tag" class="outline-2">
<h2 id="demo-heading-with-tag"><span class="section-number-2">2.</span> Demo heading with tag   <span class="tag"><span class="orgMode">orgMode</span></span></h2>
<div class="outline-text-2" id="text-demo-heading-with-tag">
</div>
</div>
</article>
</main></body></html>

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7	Column 8	Column 9	Column 10	Column 11	Column 12	Column 13	Column 14	Column 15
1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
16	17	18	19	20	21	22	23	24	25	26	27	28	29	30
31	32	33	34	35	36

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7	Column 8	Column 9	Column 10	Column 11	Column 12	Column 13	Column 14	Column 15
1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
16	17	18	19	20	21	22	23	24	25	26	27	28	29	30
31	32	33	34	35	36

Charlie's Blog

My Dotfiles: macOS Bootstrap and an Emacs Distribution

1. About dotfiles macos emacs setup

2. chiply/.files shell tmux macos bootstrap

3. chiply/.zetta.d emacs zetta distribution

Emacs Completion Showcase with VOMPECCC (video)

1. About emacs completion workflows

2. The Video demo

3. A Note on My Configuration setup

4. Multi-File Refactor ripgrep embark wgrep

5. Async + Local Two-Stage Search consult async orderless

6. Unified Buffer / File / Bookmark Switcher consult narrowing

7. Buffer and Project-Wide Line Search consult preview

8. Code Symbol Navigation imenu navigation

9. Documentation Search consult docs

10. Find Commands by Docstring marginalia orderless

11. Mass Action Across Candidates embark batch

12. Pivot Mid-Prompt embark flow

13. Symbol-Aware Multi-File Refactor xref embark wgrep

14. Recent Files as a Filesystem dired embark

15. Avy-Style Jump Then Act vertico embark

16. Resume the Last Session vertico repeat

17. Bonus: Magit-Style Working Copy as Completion :consult-ls-git git

18. Bonus: Browse GitHub Repos from the Minibuffer :consult-gh embark

19. Bonus: Search All Public Code on GitHub :consult-gh:code-search:

20. Bonus: Multi-Source Web Search :consult-omni web

21. Closing closing

22. TLDR tldr

David Foster Wallace's Hidden Names: an Anagram Atlas of Infinite Jest

1. About infiniteJest dfw anagrams

2. Methodology methodology

3. Don Gately infinitejest hugeness sobriety physicalendurance

VOMPECCC from Scratch: Picking Produce with ICR in Emacs

1. About emacs completion walkthrough

2. The Walkthrough demo

3. The Produce Corpus setup data

3.1. Why a propertized string?

4. Phase 0: Resetting to Stock reset setup

5. Phase 1: The Baseline (Stock completing-read) baseline

6. Phase 2: Vertico — Display Control vertico display

7. Phase 3: Orderless — Multi-Component Matching orderless filtering

8. Phase 4: Marginalia — Annotations marginalia annotations

8.1. The recommended alternative to Marginalia: inline annotations

9. Phase 5: Consult — Multi-Source with Narrowing consult sources narrow

9.1. Recalling prior queries with consult-history

10. Phase 6: Embark — Actions embark actions

10.1. The Actions

10.2. The Keymaps

10.3. The transformer: refining fruit to fruit-citrus

10.4. The Demo

10.5. Collect and export

11. Phase 7: Prescient — Recency and Frequency Sorting prescient sorting

12. Phase 8: Async — Going Remote with consult--dynamic-collection async consult remote

12.1. Mocking the API

12.2. A single async source

13. The Payoff: Candidates as Shared Currency substrate

14. What We Didn't Cover further

15. TLDR tldr

Gödel, Escher, Bach, Wallace: the "o's, d's and p's" in Infinite Jest

1. About infiniteJest dfw literature

2. Orin the Apparent Antagonist infiniteJest orin

3. The First Event: Avril's Abuse of Orin infiniteJest orin avril

4. Steam and Footprints infiniteJest orin imagery

5. Other Evidence for the Affair infiniteJest orin avril

6. O's, D's, and P's: The Oedipus Encoding infiniteJest orin oedipus

7. Gödel, Escher, Bach, Wallace infiniteJest hofstadter

8. Letters Inside Letters infiniteJest hofstadter typography

9. Orin in Translation infiniteJest hofstadter typography

10. Eight, Sideways infiniteJest hofstadter typography

11. Recursive Anxiety and Redirected Hostility infiniteJest orin psychopathology

12. The Helmet infiniteJest orin psychopathology

13. The Second Event: Room 101 infiniteJest orin orwell

14. Subject, Not Object infiniteJest orin language

15. The Leg's Foot infiniteJest orin language

16. Conclusion infiniteJest orin

17. Glossary glossary

A VOMPECCC Case Study: Spotify as Pure ICR in Emacs

1. About emacs completion

2. The Demonstration consult marginalia embark

3. Anatomy of spot structure modularity

5. Phase 1: The Baseline (Stock `completing-read`) baseline

9.1. Recalling prior queries with `consult-history`

10.3. The transformer: refining `fruit` to `fruit-citrus`

12. Phase 8: Async — Going Remote with `consult--dynamic-collection` async consult remote

Column 1	Column 2	Column 3	Column 4	Column 5	Column 6	Column 7	Column 8	Column 9	Column 10	Column 11	Column 12	Column 13	Column 14	Column 15
1	2	3	4	5	6	7	8	9	10	11	12	13	14	15
16	17	18	19	20	21	22	23	24	25	26	27	28	29	30
31	32	33	34	35	36