From 9904ae82e715f4be72f364206bed9c06a2e19040 Mon Sep 17 00:00:00 2001 From: InauguralPhysicist Date: Fri, 28 Aug 2026 04:31:40 -0500 Subject: [PATCH] CLAUDE.md: inherited design is a hypothesis, not terrain MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 90%+ of this code was designed by Claude sessions running models many generations old. The project is pre-v1 with no external consumers, so a decision found in the tree carries no authority from seniority — it is an earlier session's hypothesis and is fair game to question. The tell: writing "X must be true because the design does Y". Ask whether Y is a law (semantics, a physical constant, an external contract) or a decision, and price the alternative before designing around it. Bought 2026-08-28 (ouroboros#127 / DMG): a real seam bug was found, fixed and verified, and reported as unlocking the AOT multiplier for DMG. On being challenged, measurement showed DMG is 818 compiled lines against 2,470 interpreted — including the 128-function opcode dispatch — so the fix makes it run and cannot make it faster. A full investigation cycle had treated that design as terrain, and the alternative was already implemented elsewhere in the same tree for another purpose. --- CLAUDE.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 432aa5c..57ba654 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -195,3 +195,30 @@ constrained for JIT to dominate (`feedback_proxy_vs_real_bench`). the inner timer/lcd/apu calls are *the* per-cycle bottleneck. Adding an indirection there is multiplicative — measure before refactoring. + +## This design is pre-v1 and mostly written by older models — question it + +**90% or more of this repo, and of EigenScript and the AOT it runs on, was +designed by Claude sessions running models many generations old.** Newer +models keep arriving that are substantially stronger, the ecosystem is +**pre-v1**, and there are no external consumers to break. A decision you +find in the tree — here or upstream — carries **no authority from +seniority**. + +That applies in both directions, and the second one is the point of a +consumer repo. When you hit a rough edge in the runtime, the standing rule +is already to surface it as an upstream issue rather than work around it +silently. Add to that: ask whether the thing you hit is a **law** of the +language or an **earlier decision**. The tell is writing, or thinking, +*"X must be true because the runtime does Y."* + +Bought 2026-08-28 (ouroboros#127 / DMG). The AOT compiles a program's main +file but emits `load_file` as a runtime call, so loaded modules are +interpreted by the linked VM. A real bug in that seam was found, minimised, +fixed and verified — and reported as "unlocking the AOT multiplier for +DMG". Measured on being challenged: DMG is 3,288 lines, 818 compiled and +2,470 interpreted, including the 128-function opcode dispatch. Every +emulated instruction runs interpreted, so the fix makes it *run* and cannot +make it *faster*. A whole investigation cycle had treated that design as +terrain, and the capability to do it the other way already existed upstream +for another purpose.