diff --git a/docs/PARAMETER-REGISTRY.md b/docs/PARAMETER-REGISTRY.md index 257487aba4..5b5321e96f 100644 --- a/docs/PARAMETER-REGISTRY.md +++ b/docs/PARAMETER-REGISTRY.md @@ -11,30 +11,44 @@ Rules: - **Full name** — the complete sentence describing exactly what it is. 2. All three resolve to the same registry row; changing the value changes it everywhere at once. 3. No bare values anywhere in code — a number never appears without its technical name. -4. Values live as registry rows (data), revisable, history logged per change. -5. Every row carries its own **why** — the reason it was set where it's set. +## The only real constants -## Finding new ones — no orphans allowed +**0, 1, −1, +∞, −∞. That's the whole list.** -The failure mode: you're coding, you reach for a number, you type it -bare, and six months later nobody knows what it serves. So: +These five need no registry, no definition, no history — they are +structure itself: nothing, unity, negation, and the two endless ends. +They may appear bare anywhere. -1. **The linter is the shepherd.** No bare numeric literals in kernel - code (0, 1, and array indices excepted). Any magic number fails the - build with one message: *"register it or name it."* -2. **Registry-first workflow.** Need a new knob? Add the row first — - three names, full sentence, why — then use it. Thirty seconds now, - saves the archaeology later. -3. **Tuning proposes, registry disposes.** When behavior feels wrong - and the fix is "adjust something," that instinct is the discovery - event: propose a row for the thing you want to adjust. If two - different tweaks keep wanting the same knob, that's one parameter - trying to be born. -4. **Periodic sweep.** Grep for repeated suspicious literals; anything - appearing twice outside tests gets named. +Everything else is **not a constant and must never be invented as one.** +Inventing numbers is how systems rot: someone types `0.73`, someone +else copies it, soon it's load-bearing folklore nobody can explain. -New parameters are discovered by friction. The registry makes sure -friction turns into knowledge instead of folklore. +Every other quantity is a **named relationship** — a registry row +carrying what it connects, which direction it pushes, and why its +current setting is what it is. Relationships get tuned; constants +don't exist to tune. + +## Finding new ones — no orphans, no inventions + +The failure mode isn't just forgetting what a number does. It's +*inventing* numbers like they're free. So: + +1. **The linter is the shepherd.** In kernel code, the only legal bare + literals are `0`, `1`, `-1`, `Infinity`, `-Infinity` (and array + indices). Anything else fails the build: *"express it as a + relationship."* +2. **Relationships, not inventions.** Need a quantity? Don't mint a + constant — name a RELATIONSHIP between existing registered + readings ("how fast truth cools when unasserted"), give it three + names and a why, and set its current value as data. +3. **Tuning proposes, registry disposes.** When behavior feels wrong, + that instinct reveals a missing relationship — propose the row. +4. **Periodic sweep.** Repeated suspicious literals get converted into + relationships or deleted. + +The registry doesn't collect constants. It catalogs how this system's +quantities relate — because π was never a number either; it's a +relationship we got lucky enough to shorten. ## Registered parameters