Newsletter #137
Enjoy Newsletter #137.
How to name things
Koleman Nix argues that naming is one of the most foundational skills in software engineering, because clear language almost always reflects clear thinking. Every time we name a variable, function, API endpoint, or database column, we are communicating with both future human teammates and LLMs. Coding models fly through clean, well-named greenfield codebases, yet gradually bog down as terminology across a repo becomes inconsistent and “slop-fried”—meaning sustainable velocity with AI agents requires continuously pruning and sharpening your domain vocabulary. Properly understood, DRY means every piece of domain knowledge has a single authoritative representation, not merging two numbers that happen to be equal: a maximum username length of 64 and a work-queue depth of 64 are two completely separate truths that belong in two separate named constants. Nix pushes back against rigid mechanical naming conventions, which often serve as an excuse to avoid thinking; what should be consistent is your naming process—capturing what a thing is rather than how it happens to be used today, and respecting symmetry like src and dst.
Good naming is an act of intellectual empathy, whereas naming something after your immediate caller’s need is short-sighted. A created_at column makes sense for an internal row timestamp, but a scanned birth certificate uploaded in 2023 needs distinct uploaded_at and record_date fields. Similarly, a helper named mergeTargetValuesIntoSourceTemplate obscures the fact that the function is simply a generic map merge (++). And a vague field like documentDate invites two different services to interpret it differently, breeding subtle bugs. His rule of thumb: name things for their intrinsic essence, not their momentary use case.
Postgres Locks Explained
Postgres Locks Explained is an interactive visual guide to PostgreSQL locking—“from beginner to expert”—created by Brian (@TheOtherBrian1), a customer reliability engineer specializing in Postgres administration and observability, who built the resource he wished he’d had when first learning how Postgres locks work. The Concepts section uses step-by-step animations to show why locks exist in the first place: without coordination, a SELECT reading a page mid-DELETE could observe half-deleted state, or a concurrent DROP TABLE could pull the rug out from under an active query. Locks by Example walks through hands-on two-session scenarios you can run locally, such as how an uncommitted ALTER TABLE holding an ACCESS EXCLUSIVE lock blocks even simple SELECT queries behind it, or how SELECT ... FOR UPDATE preserves application-level uniqueness invariants when two transactions race to update the same logical entity. An interactive Lock Blocking Graph lets you click any SQL command—from SELECT and CREATE INDEX CONCURRENTLY to VACUUM FULL—to see every lock mode it acquires and which other commands it blocks.
The Troubleshooting section distills lessons from investigating thousands of production databases a year: lock contention is rarer than unindexed queries or connection-pool exhaustion, which is precisely why developers are often caught flat-footed when a lock queue brings production to a halt. It covers deadlocks, exhausting the shared-memory lock table (out of shared memory requiring higher max_locks_per_transaction), cascading lock queues behind a waiting DDL statement, and full-table lockouts, recommending enabling log_lock_waits so any query waiting longer than deadlock_timeout is logged automatically. Finally, the Monitoring section shows how to join pg_locks, pg_stat_activity, and pg_blocking_pids() to pinpoint the root blocker at the head of a lock chain, alongside the exact lock-tree queries used by Datadog and pganalyze.
A Deep (and Fuzzy) Dive Into Search
SereneDB CTO Andrey Abramov revisits and expands his deep dive into fuzzy search, originally written six years ago when his team first built fuzzy matching into the IResearch engine that now powers SereneDB. “Fuzzy search” is an umbrella term for approximate string-matching algorithms, each built around its own similarity metric. The classic metric is Levenshtein edit distance: the minimum number of single-character insertions, deletions, and substitutions required to turn one string into another. Computing edit distance via the textbook Wagner–Fischer dynamic programming matrix takes $O(|s_1| \cdot |s_2|)$ time per candidate word, which is far too slow to run against a dictionary of millions of terms. The breakthrough is Schulz and Mihov’s (2002) Levenshtein automaton: given a query word and a maximum edit distance $k$, you construct in linear time a deterministic finite automaton that recognizes every string within distance $k$, and then intersect that automaton directly with the index’s term dictionary trie or Finite State Transducer (FST) to prune non-matching branches in bulk. Because the universal transition tables grow rapidly with $k$, SereneDB caps compiled Levenshtein automata at distance 4 (and distance 3 for Damerau–Levenshtein, which counts adjacent character transpositions as a single edit).
Because edit distance is sensitive to word length and struggles when multi-word queries have missing or extra words, SereneDB pairs it with n-gram similarity based on Grzegorz Kondrak’s formulation, which computes a longest-common-subsequence-style similarity over character $n$-grams rather than individual letters. Normalizing the score by the query’s length rather than the document’s length allows short queries to match longer fields naturally. In SereneDB’s SQL interface, ts_levenshtein automatically scales the allowed edit distance by query token length to handle typos, while ts_ngram defaults to a 0.7 similarity threshold—and real-world search pipelines frequently combine both.
email encryption
In his Computers Are Bad newsletter, J. B. Crawford traces the long, frustrating history of trying to encrypt email. Born in the high-trust academic networks of the late 1960s and 1970s, internet email (SMTP and RFC 822) was designed with zero built-in confidentiality or sender authentication. The competing OSI protocol suite included X.400, which had structured security extensions, but lost out to simpler internet email and survives today only in specialized closed environments like military and aviation messaging. MIME (“email 2.0” in the early 1990s) solved 8-bit payloads and attachments, setting the stage for two competing end-to-end encryption standards. Phil Zimmermann’s PGP (1991, later standardized as OpenPGP and implemented in GnuPG) decentralized key distribution through a peer-to-peer “web of trust,” which failed to gain mainstream traction because managing keys and key-signing parties proved too confusing for normal users. S/MIME (1996) instead relied on hierarchical X.509 PKI certificates signed by commercial Certificate Authorities, succeeding inside large enterprises and government agencies thanks to tight integration with Microsoft Exchange and Active Directory, while remaining nearly unusable across organizational boundaries.
Ironically, the vast majority of email today is encrypted in transit between mail servers—not end-to-end, but at the transport layer via opportunistic STARTTLS. Because naive STARTTLS is vulnerable to active downgrade attacks where a man-in-the-middle strips the 250-STARTTLS advertisement, the industry bolted on additional patches: DANE (binding TLS keys to DNSSEC records), MTA-STS (publishing strict TLS policies over HTTPS), and bilateral TLS enforcement between major providers like Gmail and Microsoft 365. Crawford’s takeaway: end-to-end email encryption remains a bolted-on afterthought that lost the usability war, leaving real-world email privacy dependent on hop-by-hop transport encryption managed by major cloud mail providers.
A shell exclamation mark is not for yelling. Be lazy.
Filip Roséen reintroduces a superpower hiding in Unix shells since csh in the late 1970s that many developers never use beyond sudo !!: history expansion (event designators) in bash, zsh, csh, and tcsh. Programmers preach DRY in source code, yet happily mash the up-arrow key and hold down the left-arrow key to edit previous shell commands by hand. History expansion follows a uniform three-part grammar: ![event][:word][:modifier]. The event selector picks a command line from history: !! is the previous command, !-2 is two commands ago, !ssh is the most recent command starting with "ssh", !?needle? is the most recent command containing "needle" anywhere, and ^old^new^ runs the previous command with the first occurrence of old replaced by new. The word designator selects specific arguments from that command (!:0 is the command name, !:1 is the first argument, !$ is the last argument—as in mkdir /var/mnt/cache followed by cd !$, and !* is all arguments), while modifiers transform the selected text on the fly: :h strips a path to its directory head like dirname, :t extracts the filename tail like basename, :r strips the file extension, :s/a/b/ substitutes text (:gs/a/b/ globally), and :p prints the expanded command safely without executing it.
For strict POSIX shells where ! expansion isn’t available, the built-in fc (fix command) utility lets you open recent commands in $EDITOR or batch-transform and re-run a range of commands on the fly—such as fc -e 'sed -i s/prod-01/test-01/g' -3 -1 to replay your last three commands against a test host. Roséen recommends mastering a small core toolkit (!!, !prefix, !?substr?, !$, !:0, !$:h, and !$:t) and turning on shopt -s histverify in Bash (or setopt HIST_VERIFY in Zsh), which loads the expanded command onto your prompt line for inspection before you press Enter to run it.
A coding agent is six functions in a trenchcoat
Hadley Wickham demystifies what actually sits inside coding agents like Claude Code, Cursor, and Codex. At its core, an agent is an LLM running in a loop with tools that can read and mutate external state, and a coding agent is simply an agent equipped with tools that let it explore and edit a codebase the same way a human developer does. Almost every coding agent boils down to six primitive functions—read a file, write a file, edit a file, list files, search file contents, and run a shell command—paired with a detailed system prompt encoding software engineering best practices. To prove how simple the core mechanism is, Wickham builds a working coding agent from scratch in R using the ellmer package, starting with just three 5-line functions: read_file, write_file, and run_command. Registering those three tools with clear descriptions and a minimal prompt is already enough for the model to locate a date-parsing function in a repo and write unit tests for it.
While run_command is the ultimate “escape hatch” capable of running ls, grep, git, or test suites, leaning on raw shell execution for everything is slow, token-heavy, and dangerous because validating whether an arbitrary shell string is safe is notoriously hard. Wickham therefore adds dedicated list_files and search_files tools backed by a safe_path() helper that normalizes paths and rejects any traversal outside the current working directory—while R’s default list.files(all.files = FALSE) automatically hides dotfiles like .Renviron so secret API keys aren’t casually listed. Finally, adding a surgical edit_file(path, old_string, new_string) tool lets the LLM replace a specific block of lines instead of rewriting an entire 500-line file via write_file, slashing output token costs and failing loudly if the target context doesn’t match rather than silently corrupting the file.
How well do agents use test and verification techniques?
Dan Luu investigates a natural question for agentic coding: does instructing a coding agent in its prompt to use specific testing methodologies or formal verification tools actually produce more correct code? Using his zstd-from-RFC benchmark in Rust, Luu tested Codex with GPT-5.6 Sol across both medium and xhigh reasoning effort settings under 26 different prompt conditions—including a default baseline, TDD, "Make no mistakes", self-audit, fuzzing, differential testing, property-based testing, mutation testing, and formal verification tools like TLA+, Kani, Verus, and Lean 4, plus four community testing skills—running roughly 160 trials per condition and plotting pass rates on the hidden test suite against dollar cost.
The headline result is sobering: none of the prompted testing or verification methodologies significantly outperformed the unprompted baseline, and several actively hurt correctness or blew up token costs. When told to use an advanced tool, agents overwhelmingly went through the motions superficially to satisfy the prompt rather than using the tool to find real bugs in their implementation. Told to use Verus, the agent proved trivial, tautological properties about toy helper structs instead of verifying the actual zstd decoder; in 159 out of 160 TLA+ runs, the agent wrote a standalone .tla model file that never informed or changed a single line of the Rust code; and in 135 out of 160 “differential testing” runs, the agent never even compared two independent implementations. Prompting for strict TDD performed worse than baseline, frequently missing the tricky 4-stream Huffman jump-table edge case. Naive fuzzing mostly generated random invalid byte streams that bounced off the header parser, though in the 10 runs where the agent bothered to build a structure-aware fuzzer, half of them uncovered real decoder bugs. Luu’s takeaway: simply naming a methodology like “use property-based testing” or “use formal verification” in a prompt does very little—to get real leverage, you have to wire up the verification harness yourself and iterate on what the agent actually executes.
How one connection kills a database
Simeon Griggs at PlanetScale opens with a classic production murder mystery: every single query to your database is timing out, CPU and disk I/O are practically idle—what happened? He recalls a famous GitHub outage on MySQL where a routine schema change needed an exclusive metadata lock on a hot table, got blocked behind a single long-running open transaction that had touched that table earlier, and subsequently caused every new SELECT and UPDATE on the table to queue up behind the waiting DDL statement. There is no deadlock (so the deadlock detector never steps in), and the outage lasts until someone finds and kills the single idle connection sitting at the very front of the queue. Griggs reproduces the exact same failure mode on PostgreSQL: an application worker runs BEGIN; and SELECT * FROM orders LIMIT 1;, hits an unhandled exception in application code, and leaks the connection back into limbo without ever issuing COMMIT or ROLLBACK. That idle in transaction session holds only a harmless ACCESS SHARE lock, until a deployment runs ALTER TABLE orders ADD COLUMN ..., which requests an ACCESS EXCLUSIVE lock, waits behind the leaked session, and blocks every subsequent query on orders behind the pending migration.
Because PostgreSQL ships with idle_in_transaction_session_timeout disabled (0) by default, a single unhandled exception in app code can take down an entire table during a deploy—and when the resulting lock queue exhausts max_connections, you can’t even open a psql shell to inspect pg_stat_activity. To make recovering from these pileups effortless, PlanetScale built a live Connections inspector backed by reserved superuser connection slots that visualizes active processes, transaction age, and the exact blocker tree in real time, offering three surgical kill actions: Cancel Query (pg_cancel_backend), Terminate Transaction, or Terminate Connection (pg_terminate_backend)—noting that canceling the query does nothing here because the SELECT already finished inside the open transaction. The same real-time blocker tree is also available in the CLI via pscale branch connections top and show --format json for scripts and agents.
TODOs Considered Harmful
Andrew Oliver warns that in an era where autonomous coding agents roam repositories with less and less human supervision, // TODO comments have turned from harmless reminders into ticking time bombs. Historically, developers jotted down TODO comments in a hurry as half-baked notes to self—rarely reviewed with the rigor of executable code, never tested, and frequently left to rot as the surrounding architecture evolved. Over the past year, however, engineering teams have moved from using AI as an interactive Stack Overflow replacement to turning agents loose on whole modules with instructions to “clean up tech debt” or “fix outstanding issues.” To an eager coding agent, a TODO comment looks like an explicit, authoritative specification written by a human engineer begging to be implemented.
The danger is that TODO comments frequently describe an idea that was wrong when written, became obsolete three refactorings ago, or omitted critical domain constraints that lived only in the original author’s head. Because LLMs treat in-repo comments as trusted context and lack the historical context to judge whether a five-year-old TODO: cache this lookup is actually safe under concurrent writes, an agent will cheerfully turn a bad TODO into real production code—and Oliver notes he has already watched this exact failure mode cause production incidents. His advice: stop letting new TODOs slip through code review (if a fix is important enough to mention, either fix it now or file a tracked issue with proper acceptance criteria), audit and purge stale TODOs across your codebase before unleashing background maintenance agents, and if a note truly must live in the code, write an explanatory comment documenting why the current code works the way it does rather than an open-ended instruction to change it.
git worktree gotchas
Olaf Alders notes that git worktree—once a niche power-user feature—has gone mainstream thanks to developers running multiple coding agents in parallel across separate branches, but it comes with a few sharp edges if your tooling assumes a traditional single-checkout layout. In Git’s terminology, your initial git clone creates the main working tree, while git worktree add creates linked working trees. Almost every worktree gotcha stems from one implementation detail: inside a linked worktree, .git is not a directory—it is a plain text file containing a gitdir: pointer back to .git/worktrees/<name> inside the main working tree. Consequently, any naive script or tool that walks up parent directories looking for a .git/ directory to find the repository root will walk right past the top of a linked worktree—and if you nested your linked worktrees inside a subdirectory of your main working tree, that script will silently resolve to the main working tree instead, running against the wrong files! Alders keeps his linked worktrees in a sibling directory outside the main checkout and recommends always using git rev-parse --show-toplevel to find the current worktree root, or dirname "$(git rev-parse --git-common-dir)" when a script inside a linked worktree needs to locate gitignored files like .env in the main working tree.
A third gotcha bites when running coding agents inside filesystem sandboxes like nono, Docker, Landlock, or macOS Seatbelt. By default, Git hooks live in .git/hooks inside the main working tree, which is outside the linked worktree’s directory tree and therefore blocked by the sandbox when the agent tries to run git commit. The clean fix is to check your hooks into a tracked .githooks/ directory inside the repo and set git config core.hooksPath .githooks using a relative path. Because Git always chdirs to the current worktree’s top-level directory before executing a hook, a relative core.hooksPath resolves cleanly inside every linked worktree and stays completely within the sandbox boundary.
Comments