Cod3xDocs
guide

Paid For With Blood

Production bugs, failed optimizations, bad assumptions, and the rules they purchased.

These are not hypothetical best practices.

A Paid For With Blood entry requires an actual wound: production bug, regression, crash, stale-state failure, performance cliff, misleading type assumption, reverted optimization, or architecture that became expensive enough to replace.

The useful structure is always the same:

  1. What looked reasonable?
  2. What actually happened?
  3. Why?
  4. What changed?
  5. What rule survived?

The goal is not to make old code look stupid. Most dangerous mistakes are dangerous precisely because they looked reasonable when written.

Keep the scar. Skip the injury.

Receipt convention

Important entries should make the trail easy to follow:

  • Experiment — the change that tested a hypothesis;
  • Revert — the failure or regression that rejected it;
  • Finding — the evidence that identified the actual cause;
  • Current pattern — the implementation or rule that survived.

When possible, link each commit, link the file at the relevant revision, and link the current implementation. A commit tells you what changed; a commit-pinned source link tells you what the code looked like when it changed.

Paid For With Blood — Invalidate the Resolver Too Clearing source data did not make S3maphore's derived playlist state dirty. Paid For With Blood — Generations for Deferred Work CellPresence work was valid when sent and stale when it returned. Paid For With Blood — Quitting Is Not Returning Requesting OpenMW shutdown does not terminate the current Lua control flow immediately. Paid For With Blood — Context Availability Is a Contract An API that exists elsewhere in OpenMW does not exist in every sandbox. Paid For With Blood — A Shadow Cache Needs the Same Invalidation as Its Source Overriding a subscription handler accidentally bypassed the cache invalidation that made the proxy truthful. Paid For With Blood — The Content Does Not Owe You a Happy Path Cells do not necessarily have pathgrids, and annotations must describe real data. Paid For With Blood — Userdata Is Not a Table Engine wrappers can look collection-like while obeying different Lua semantics. Paid For With Blood — The Number Was Userdata DreamScripts tried to remove a conversion based on semantic type; runtime representation disagreed. Paid For With Blood — If You Catch It, Keep the Traceback Protected execution that destroys the diagnostic turns one bug into two. Paid For With Blood — The FFI String Was Not the Bug Revert the experiment, isolate the failure, then reapply only what the evidence supports. Paid For With Blood — Cache the Result, Not the Machinery DreamScripts cached compiled chunks where callers expected loaded module values. Paid For With Blood — The Raycast Was the Optimization Target Targeting code evolved from fixing accidental UI churn to restructuring the expensive engine work itself. Physics and Rendering Raycasts Answer Different Questions Starwind cursor selection produced false positives because a physics query was being used for a visual-selection problem. Paid For With Blood — The Userdata Cache Was Not Free Rubic0n added allocator/finalizer userdata caches, then removed the experiment wholesale. A Faster Finalizer Still Has to Fit the GC Budget Rubic0n batched finalizers needed explicit accounting and pacing after the fast path changed how much work one GC step performed. Paid For With Blood — “Nothing Changed” Still Had Work to Do S3maphore skipped dependent silence state when ordinary playback kept the same playlist.