A decode guide for the informal idioms and metaphors that recur in these docs (and in the working chat around them). Nothing here is being replaced — the phrasing is deliberate and, in a few cases, deliberately colorful. This page just says, in plain English, what each term means, so a reader who trips on one has somewhere to look.
This is NOT the domain glossary. Technical terms that carry precise meaning — RAG, RLS,
embedding, HNSW, OCC, DENORM, MoA / MoE, keyset pagination, blinding,
nudge, Matryoshka / MRL, prompt cascade, JWT, CDC, temperature — are not
idioms. They are defined inline on first use in the documents themselves. Collecting those into a
separate domain glossary is a possible follow-on; this page is only the figures of speech.
The Where column tags where a term actually shows up: docs = a published/reader-facing document
(schema ERDs, scenarios, datasheets, architecture doc); notes = working design
notes and brainstorms; chat = my conversational shorthand, which shows up in messages more than in
the written docs.
| Term | Plain-English meaning | Where |
|---|---|---|
| at scale | once data volumes grow large enough to matter | notes |
| bake in / baked-in | build a value or rule into the structure permanently so it cannot drift later (e.g. an author's email baked into created_by_email) |
docs |
| blast radius | how much would be affected if this changed or broke ("the blast radius is contained") | notes |
| carve out / carve-out | a deliberate exception to an otherwise-general rule (e.g. a privacy carve-out for profile.notes) |
docs |
| chatty | producing a high volume of items — an enrollee who sends many rounds, or an API that makes many calls | docs |
| come-and-go | a leave-and-return usage pattern (an enrollee who disconnects and reconnects, continuing the same session) | docs |
| contaminate / non-contaminating | let something unrelated leak into a measurement and spoil it (routing overhead must not contaminate the generation cost it is read against) | docs |
| dangling (reference) | a foreign key pointing at a row that no longer exists ("so it never dangles") | docs |
| degenerate (to) | collapse into a simpler case when a general mechanism is handed trivial input (with one generator, the peer-broadcast loop degenerates to plain refinement) | docs |
| drift | slowly diverge from what it should match, with no single moment where it broke (documentation drifting from the schema; a rewrite drifting from the request) | docs |
| dud | a consistently poor performer — a model that keeps scoring low; "the dud signal" is the indicator that flags it | docs |
| escape hatch | an intentional way around a constraint, for edge cases | notes |
| fan-out / fan out | one source producing many downstream rows or calls (one message_recipient row per reader is a fan-out) |
docs |
| fast path / slow path | the cheap common route through a decision, versus the expensive route taken only when the cheap one cannot settle it | docs |
| first-class | treated as a full, native concept in the model, not bolted on as an afterthought | notes |
| for free / near-free / near-zero | at no cost, or negligible cost ("near-zero cost for a local model") | docs |
| good-enough (bar) | a threshold that, once met, means "stop trying to improve" (this is what score_target is) |
docs |
| Goodhart's law | once a measure becomes a target it stops being a good measure, because effort goes to the metric rather than to the thing the metric stood for | docs |
| gotcha | a non-obvious catch that can bite you; a caveat | docs |
| guardrail | a constraint that prevents a whole class of mistakes before they happen | notes |
| hang(s) off | is attached to, and depends on, a parent — a child row keyed to (and deleted with) its parent ("run_result hangs off experiment_run") |
docs |
| hangs together | how the pieces fit and work as a coherent whole ("how it all hangs together") | docs |
| knob(s) | an adjustable setting or configuration control | docs |
| lean toward | incline toward as a preference — a recommendation, not a firm decision | notes |
| load-bearing | carries real weight in the design; remove it and something breaks. A load-bearing column or rule is essential, not decorative | docs |
| orphan / orphaned | a row whose owner or parent was deleted, leaving it unowned (an orphaned row becomes admin-managed) | docs |
| plumbing | the internal machinery that makes something work but is not the feature itself ("the sidecar's own plumbing") | docs |
| quietly / silently | happening with no signal or record; undetected ("silently overwrite," "quietly re-score") | docs |
| round-trip | one full request-and-response cycle to the database or network ("cut round-trips") | docs |
| short-circuit | skip the rest of a process once an early condition already settles the outcome (combine_method = single short-circuits the ensemble) |
docs |
| sidecar | a companion subsystem that runs alongside the main app and adds a capability — here, the embedding/search subsystem; from the cloud "sidecar pattern" | docs |
| source of truth | the one authoritative record that everything else derives from (schema.dbml is the source of truth) |
docs |
| swamp (verb) | overwhelm by sheer volume so the real signal is lost ("would swamp the index") | docs |
| sycophantic (tone) | flattering, deferential phrasing in a prompt — one end of the tone axis in the objective-benchmark study, opposite "threatening". Distinct from the model behavior of the same name, where a model agrees with whatever it is shown instead of judging it | notes |
| tear down / teardown | shut down and remove — an instance, or an entire schema (DROP SCHEMA … CASCADE) |
docs |
| two-hop (join) | a query that has to pass through an intermediate table to connect two others ("the two-hop join through run_enrollment") |
docs |
| under the hood | internally; the implementation beneath the surface | docs |
| wire up / wiring | connect components so they work together ("wire the trigger into the pipeline") | notes |
| worker / faceless worker | an enrollee in a run, seen as an anonymous unit of participation (kept faceless for blinding). Distinct from the background "reconciler worker," which is a real process | docs |
You will see these in my messages more than in the written docs. Listed because you asked what they
mean — including the two that started this: footgun and boil the ocean.
| Term | Plain-English meaning |
|---|---|
| ablation | removing one component to measure how much it was actually contributing |
| back-of-the-envelope / napkin math | a rough calculation meant to show whether an idea is worth pursuing at all, not to be accurate |
| back-pressure | slowing a producer down when the consumer cannot keep up |
| belt and suspenders | redundant safeguards — two independent mechanisms for one guarantee |
| bikeshedding | over-focusing on a trivial detail while the important decision goes unexamined |
| boil the ocean | attempt something impossibly broad all at once, instead of scoping it down to something doable |
| bus factor | how many people would have to leave before a project stalls — a bus factor of one is a risk, not a compliment |
| cargo cult | copying the visible form of a practice without the reason behind it. The ancestor of wing-flapping error below, which names the same failure with a different image |
| clobber | overwrite existing data and thereby lose it |
| cold start | having no history to go on yet — a new model, a new topic, a first run — which is usually when you most want the estimate you cannot make |
| counterfactual | what would have happened under the choice you did not make; normally unobservable unless you deliberately pay to find out |
| defense in depth | layered safeguards, so a single failure is not catastrophic (a security idea) |
| dogfooding | using your own product to find its rough spots |
| earn its keep / earn its place | justify its existence against what it costs to have around |
| exhaust | useful data produced as a byproduct of doing something else, at no extra cost |
| fall off a cliff | degrade sharply past some point instead of gracefully |
| footgun | a feature or API that is easy to use in a way that hurts you — a gun pointed at your own foot; an easy-to-misuse sharp edge. (Example from this project: string.Template turning $$ into $ and corrupting the triggers.) |
| greenfield / brownfield | building new from scratch / building constrained by what already exists |
| happy path / sad path | the normal, everything-works case / the error or edge case |
| headroom | how much improvement is still available before hitting the ceiling |
| heisenbug | a bug that disappears when you try to observe it, usually because observing it changed the timing |
| idempotent | safe to run more than once with the same net effect |
| in the weeds | deep in low-level detail |
| kick the can (down the road) | defer a problem rather than solve it now |
| LGTM | "looks good to me" — a review approval, sometimes carrying the wry sense that the reviewer did not look very hard |
| long tail | the many rare cases that each look negligible and together dominate |
| low-hanging fruit | the easy, high-value wins to take first |
| magic number | an unexplained literal sitting in code with nothing to say where it came from |
| nit | a trivial review comment, offered without insisting on it ("nit: ...") |
| noisy neighbor | one process or tenant degrading others by hogging shared resources |
| north star | the guiding goal that decisions align to |
| nuke / blow away | delete wholesale |
| oracle | the best answer that was achievable, known only because you paid to compute every option — the yardstick a cheaper method gets scored against |
| path-dependent | the outcome depends on the order of what came before, not only on the current inputs, so the same input can give different results |
| punt | defer a decision or task to later |
| race / race condition | two operations interleaving so the result depends on timing, usually wrongly |
| regret | how much worse your choice was than the best one available; the standard way to score a decision rule, from the bandit literature |
| rubber ducking | explaining a problem out loud — to a colleague or to an inanimate duck — and solving it in the telling |
| shadow mode | running a system alongside the real one and recording what it would have done, without letting it act on anything |
| sharp edge(s) | an error-prone part of a tool that is easy to cut yourself on |
| smell test / code smell | a quick intuition that something is off; a surface sign of a deeper problem |
| spaghetti code | code whose control flow is tangled enough that following one path means following all of them |
| spin up | start something — a server, an instance, a process |
| table stakes | the minimum baseline needed just to be in the running |
| tech debt | a shortcut taken now that costs more to live with later |
| thundering herd / cache stampede | many clients hitting the same resource at the same instant |
| WET | "write everything twice" — the deliberate opposite of DRY, tolerating duplication when the two copies are likely to diverge anyway |
| wing-flapping error | copying a mechanism when you only needed the principle behind it — aircraft fly without flapping. Coined in this project; not an established term |
| YAGNI / DRY / KISS | "you aren't gonna need it" / "don't repeat yourself" / "keep it simple" |
| yak-shaving | a chain of prerequisite side-tasks you have to finish before you can even start the real task |
Maintenance: this is a hand-kept reference, not generated. When a new idiom creeps into the docs, add a row rather than assuming the reader shares the vocabulary. Keep both tables in case-insensitive alphabetical order, sorting a slash entry under its first alternative.