reach's domain names should not be a fresh taxonomy. Where the game already
presents something to the player, the CLI takes that name and that shape: what
you browse in-game is what you generate and inspect from the terminal.
That splits domains in two. atlas, ledger and wiki mirror implant apps and
follow their structure. check, validate, godot, visual, jobs and dev mirror
nothing — no app exists for a lint gate, and inventing a player-facing framing
for one would be worse than having none.
The first consequence corrects a contradiction rather than a preference. D-191
already says "Atlas is the star map extended downward, not a separate app —
implant/map at different zoom levels", four rungs from Reach map to regional.
The domain map had atlas, starmap and planet as peers, which would have
presented as three unrelated things what the game presents as one descent.
Generation now nests by rung; authoring and inspection verbs stay flat on
atlas, because they act on the whole thing rather than a rung.
The second is a rename with the same reasoning: db becomes ledger, after the UI
component that will aggregate economics — markets, wealth, transactions, the
economic counterpart to what the Atlas offers for topography. db named a
storage layer nobody looks at.
One caution recorded because the words collide. D-191's MVP criterion 7 says
"Atlas is read-only (no verbs execute from map)". That governs the app. The
atlas tooling writes — it commits proposals, mutates fields, syncs the wiki —
and a later reader must not take the app's constraint as licence to delete the
authoring verbs.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Clarifies the rewrite decision to what it actually meant: rewriting the bash in
Python does not mean reimplementing the operating system. A guarded exec is the
right answer for rustup, curl, unzip, git, godot, blender. What must become
Python is the LOGIC — which version is wanted, whether it is already present,
what the output means, what to do when it fails. The test of a correct port is
not whether it calls anything external, but whether the decisions can be
exercised without performing them.
Delivered ahead of the remaining ports because every one of them needs it.
core/process.run is the single sanctioned exec, and each of its guards exists
because a per-domain subprocess call is precisely where that guard goes
missing:
- An argv list, never a shell string. A string is rejected outright rather than
helpfully split, since the helpful split is the vulnerability.
- shell=False always.
- A non-zero exit becomes a ReachError naming the command, carrying its output,
and preserving its exit code — not a CalledProcessError traceback at someone
who wanted to know the next step.
- A missing binary reports what to install. FileNotFoundError names the path
that was not found, which is the less useful half of the answer.
All four verified against real commands, including a genuine git failure
relaying exit 128.
A conformance invariant keeps the door single: nothing outside core/process.py
may import subprocess or call os.system/popen/exec*. Proven to fail by
importing subprocess into a domain service.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Found on starting the first port: 17 of the 33 tooling executables are bash,
about 900 lines. Both this record and the domain map had assumed a Python tree,
so those are rewrites rather than moves — a materially larger epic than T-1250
was written for.
Decided: rewrite them, do not wrap them. Wrapping would achieve one door while
leaving half the CLI surface outside the contract — no @command, no remedy on
failure, no streaming, no testable service. reach --help would then list verbs
that behave differently from the ones beside them, which is worse than two
doors, because the inconsistency is invisible until something fails.
The cost lands unevenly and the record says where. The grep-pipeline scripts
compute verdicts and gain most from becoming services. The environment scripts
— install-godot, install-rust, worktree-setup — gain least and carry the most
regression risk, because downloading a specific Godot build or driving rustup
is awkward to exercise in a gate. For those, port the decision logic into a
testable service and keep the irreducible external calls behind core/process: a
rewrite that cannot be tested has to be trusted instead, and trusting an
installer is how a working environment becomes an unreproducible one.
The domain map gains the inventory by shape, and a rule that every per-domain
ticket states which of its sources are bash — since that is what turns a port
from mechanical into a rewrite needing its own parity evidence.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Stated plainly because the record was quietly assuming otherwise: Jeroen runs
make and plays the game; the caller typing reach all day is Claude.
It resolves several arguments in the opposite direction from human-CLI
instinct. --help is a discovery mechanism rather than documentation, since it
is how the tool gets relearned from nothing every session — which makes the
domain list and closed-set enumeration load-bearing rather than polish. Output
volume is a context cost, so quiet-by-default is right for a better reason than
not spamming a hook. Latency matters less than legibility: nobody drums their
fingers at 300 ms, but a multi-minute silence is expensive because a wedge is
indistinguishable from work. And errors that name the next command are the
highest-value requirement here, because the reader is usually deciding what to
run next — "no" costs a whole exploratory turn.
One correction follows directly. D-263 had scoped streaming to "callers with no
escape — a human terminal, a Makefile, a git hook", reasoning that Claude
Code's background mode already solved the timeout for agents. That got the
audience backwards. Background mode solves the timeout and nothing else: it
returns when the process exits, so a nine-minute wedge still looks exactly like
nine minutes of work. Streaming is what makes a long run legible while it runs,
and reattach is worth most to the caller whose attention is not continuous.
Both are primary-user features, not fallbacks.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two decisions taken before the 160-file move, because both change what the
move produces.
The Makefile has 84 targets and is today's front door, so "one CLI for all
repo tooling" was not yet true. The split is by what a target DOES: make keeps
genuine build and test orchestration, and targets that are really tooling
wrappers are retired in favour of reach verbs — retired, not wrapped. A
wrapper leaves two ways to invoke every tool, and then reach --help stops
being the answer to "what tooling exists" because the Makefile is still a
competing index. Two doors is the condition this record exists to end, so
keeping both would defeat it while looking like caution.
Streaming becomes a decorator rather than an API commands call. @command
already wraps every invocation, and that is exactly the seam where job
identity, progress correlation and detach belong: the decorator assigns the
job id, tags the events, and forks on --detach. A command must not know that
jobs exist. The alternative — each command opening a job and remembering to
close it — is call-site discipline wearing a different hat, and it fails the
same way the fortieth command into a porting session, with the failure
vanishing from the log and nothing to indicate anything is missing. Logging
and error handling are decorators for this reason; streaming is the third
cross-cutting concern, not a special case.
Consequent resequencing: T-1264 lands before the T-1250 move, so every ported
command arrives already streaming. Old scripts now retire per domain as each
port passes its parity test, rather than in one sweep at the end — a
continuous shrink, instead of months where every tool exists twice and an edit
can land in the dead copy.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every non-zero exit names the command that would fix it, and still exits
non-zero. Both halves matter; the second is the one that gets lost, because a
tool that explains itself beautifully and exits 0 looks MORE correct while
having silently disabled its own gate.
core/errors.py holds ReachError(message, fix=) and @handle_errors.
core/logging.py holds @logged, emitting through console rather than a second
sink — one output path, so there is nothing to drift. core/command.py composes
them, and the order is load-bearing: handle_errors wraps logged, so the logger
sees the original exception. Inverted, every failure would be recorded as
"SystemExit" and the log would say nothing about what went wrong while looking
like it worked.
core/ raises SystemExit, not typer.Exit. A service must be callable from a
test, another service, or a future second front end, and an exception type that
only makes sense inside a CLI leaks the transport into every layer.
The check router is retrofitted off its hand-rolled verdict-and-exit pattern —
exactly the boilerplate this removes — and test_check_parity.py passes
unchanged across the retrofit. That test predates the decorators and pins exit
codes against the old script, so it is independent evidence, not a test tuned
to match new behaviour.
Unknown domains and unknown verbs now enumerate what exists instead of only
saying no. That needed a shared group class, which collided with "no typer
outside main.py and router.py" — resolved by sharpening the invariant rather
than breaking it, since its purpose is that a SERVICE never knows it was called
from a CLI. Transport now lives in main.py, router.py and core/cli.py; never in
service.py, schemas.py or helpers.py. The upside is that cli.domain() carries
the settings that were previously per-router decisions, including the
load-bearing rich_markup_mode=None that one forgetful domain could have undone.
test_conformance.py makes five invariants executable, AST-based rather than
grep. Scoped to the package, not the 123 legacy scripts — and deliberately so:
as T-1250 moves each script into domains/, it lands inside the scope and the
rules start applying automatically, so the test's reach grows with the
migration.
Proven to fail before being trusted: removing @command and removing a fix= each
produced a failure naming the file, the line and the reason.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
schemas.py becomes pydantic, so the reference domain is the normal pattern
rather than an exception carrying a footnote. Frozen: a result is a statement
about what was found, and nothing downstream should edit the finding on its way
to being reported. pydantic stays off the --help path — test_lazy_domains still
passes, which is precisely the assertion that it loads with the domain and not
with the CLI.
The acceptance criterion could not be met as written, and that is the finding
worth keeping. It asked for byte-for-byte parity with the old script; D-263 was
amended after this ticket to give reach a streaming model that puts the verdict
on stderr, while the old script writes its success line to stdout. Measured:
the text is byte-identical in text mode, only the stream differs. Matching both
would mean abandoning streaming or special-casing every ported gate.
So parity is redefined, and it is stronger than bytes where it counts: exit
codes match exactly, no fact the old message carried is lost, and failures name
a remedy as a structured field. That governs every port in T-1251, not just
this one, so it is in D-263 rather than only here.
test_check_parity.py runs three paths — ok, drift, missing file — through both
implementations and compares. It builds a throwaway fixture repo and copies the
OLD script into it, because that script resolves its root from __file__ and has
no override; the new command just takes SR_REPO_ROOT. That asymmetry is part of
why the port earns its keep. It also asserts the failing paths actually exit
non-zero, without which "the exit codes matched" would be vacuous for two
checks that both silently pass.
Proven to fail twice before being trusted. Once by accident: the first version
asserted the yaml version appears on every failing path, which the old script
does not report when the client file is missing — the test was wrong, not the
code, and it now derives expected facts from what the old output actually
contains. Once on purpose: mutating the router to drop a version made it fail
and name the missing fact.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`reach --help` runs from the console entrypoint in 80 ms. typer 0.27.1 and
pydantic 2.13.4 join the dependencies, both CVE-checked against NVD, OSV and
the GitHub Advisory Database.
The design in the ticket did not survive contact. It specified a click.Group
root, on the reasoning that it would keep typer off the --help path — but
typer vendors Click as of 0.26.0, so there is no top-level click package to
import and no supported way to extract typer's internal one. A click.Group
root hosting Typer sub-apps would put two Click implementations in one
process. The root is therefore a typer.Typer, and lazy registration will go
through the supported typer.Typer(cls=...) surface with a TyperGroup
subclass. T-1260 is corrected to match.
The callback is not decoration: a Typer root with no commands AND no callback
raises at build time, and lazy registration means no command is ever eager.
The ticket claimed a zero-command root always raises — half right, and the
half that matters is that a callback makes it legal.
rich_markup_mode=None is load-bearing rather than cosmetic. It takes an empty
--help from 168 ms to 74 ms, and keeps rich and pygments off the import path
entirely rather than merely skipping the render. It also stops typer drawing
box-art help, which it does even when stdout is a pipe — that would have put
box-drawing characters into every hook log and agent capture. typer-slim was
considered and rejected: deprecated since 0.22.0, now a shallow wrapper that
installs all of typer.
D-263 amended: the feels-instant ceiling goes from 250 ms to 500 ms. A ceiling
is not a typical and most invocations sit far below it; the tighter number was
buying discipline that the import-graph assertion enforces better. Stay smart
about what loads, stop worrying about tightness.
Security, checked 2026-08-23. typer has no advisories on record. pydantic
2.13.4 clears PYSEC-2026-1812 (email-regex ReDoS, fixed in 2.4.0) — and the
2026 SSRF advisories CVE-2026-25580 and CVE-2026-54249 are against
pydantic-ai, a different package that is not a dependency here, recorded in
pyproject so the next sweep does not re-panic. Transitively, pygments 2.21.0
clears CVE-2026-4539.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three amendments, all from pressure-testing the record against how the CLI
will actually be used.
The ~104 ms push-gate ceiling is withdrawn. It was the summed cost of three
single-sample timings, imported as a requirement without asking who pays —
and who pays is the pre-push hook, which already runs cargo test or the
gdUnit4 suite on any code push. A few hundred milliseconds is invisible
there, and on a governance-only push the whole hook is about a second. The
criterion is OUTPUT parity: a ported check must produce the same output and
the same exit code as the script it replaces, and is not required to be as
fast. What replaces the ratchet is a ceiling with headroom — under ~250 ms to
feel instant. Lazy registration stays mandatory, justified by the real
threat rather than by parity: scipy.ndimage alone is 275 ms, and an eager
entrypoint would pay ~460 ms before executing a line of its own.
That budget change removed the only argument for keeping pydantic out of the
gate domain, so the carve-out goes with it. One fewer exception, and the
reference implementation is now the normal pattern rather than a footnote.
Commands also stream. The gates are milliseconds but the generators are
minutes, and an agent Bash call gives up at two and sends nothing. Detaching
alone would fix the timeout and keep the silence; streaming fixes the part
that costs real time — you learn a generator is wedged at minute one instead
of minute nine. JSONL events on stderr, stdout reserved for actual output,
rendering at the sink so a job log and a live terminal are one artefact in
two presentations. Reattach is a byte offset into an append-only file, which
is why there is deliberately no daemon.
The trap, recorded because it would quietly undo the thing this record cares
most about: streaming is ADDITIVE to the failure contract. A remedy emitted
at line 400 of 900 is printed and invisible, so the verdict still prints
once, last.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Q-124 asked whether the 123-file Python tooling should be retooled into a
Rust CLI. The answer is no, and it is a costing rather than a preference.
All three frictions it names — per-script permission prompts, the venv/PATH
split between interactive and non-interactive shells, and interpreter
startup paid four times per push — are packaging problems, and one bare
command on PATH with lazy subcommand loading fixes all three. Rust would
additionally owe a numerical-equivalence proof on the planet-gen path,
whose heightmaps are committed build artefacts with goldens standing on
them: a large one-time cost to avoid a small recurring one, paid in the
currency the project can least afford to spend.
D-263 fixes the shape. tooling/ becomes an installable package behind the
`reach` command: a routing-only main.py, every domain under domains/<name>/
split router/service/schemas/helpers, a core/ bounded on day one to what
has no domain, logging and error handling attached as decorators rather
than call-site discipline, and pydantic confined to domain schemas —
measured at 87 ms against a whole gate check of 20-46 ms, which is why it
must never reach the push path. Failures carry the command that fixes them
and keep their exit code; a tool that explains itself and exits 0 silently
disables its own gate.
R-014 records the Rust option as costed down, not argued down, with the
condition under which it is worth reopening. T-1247 files the work as
eight dependency-ordered epics; only the skeleton is unblocked.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Jeroen's shape for the tooling CLI: move the Python into a package with a
proper domain split, one door that answers everything with help, and errors
that hand back instructions rather than a status.
The domain split turns out to be discoverable rather than invented. tooling/ is
85 top-level entries — 37 loose .py, ~36 extensionless executables, 11 dirs of
which only 6 hold anything — across four coexisting naming conventions. But the
domains are already encoded as filename prefixes: blender x14, atlas x8,
generate x7, check x7, then visual/validate/test x3 and
godot/garment/pql/install x2. Those prefixes are the subcommand groups, which
is what makes the consolidation mechanical enough to be safe.
Two constraints recorded against "a new prompt not an error code", because
taken literally each would break something:
- Exit codes stay. Four of these run in the pre-push hook, which fails a push
ONLY by non-zero exit; a tool that explains itself and exits 0 silently
disables its own gate. That exact failure was observed in clide today, where
unsupported-format, no-such-file and unknown-subsystem all returned 0.
So: code AND message, never either/or.
- It must not become literally interactive. Agents and git hooks have no TTY,
and the tea scar is already written down — its prompts "crash in Claude Code
(no TTY)", which is why every tea call passes all flags explicitly. Any
prompt must be TTY-gated and suppressible.
pql was cited as the precedent and measured rather than assumed. The principle
holds there for unknown subcommands (full usage dump) and not for invalid
values: `ticket status <id> nonsense` says invalid without naming the six legal
values it knows, `ticket new` says "accepts 2 arg(s)" without naming which two.
The gap is the closed sets, and it is the more common failure. Logged upstream
as pql T-112 rather than worked around here — the bar for our CLI is the
stronger one: whenever the accepted set is known, print it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Jeroen raised Typer as the Python-CLI option. Costing it changed what the
question is actually about.
The repo is already most of the way there: pyproject.toml exists, `make
setup-venv` already does `pip install -e ".[dev]"`, and 22 tooling files
already use argparse. What is missing is a single line — there is no
[project.scripts] entry at all, so no console entrypoint exists. This is
consolidation, not authorship, and it resolves the largest friction (per-script
permission prompts) for one allowlist entry.
But the framework is the second decision, not the first. A [project.scripts]
entrypoint lands in .venv/bin/, which is on PATH only when the venv is
activated — and agents and git hooks never activate it. That is the same split
VENV_PY already papers over in the Makefile, and precisely the failure recorded
for tea: an absolute path breaks the Bash(tea *) rule and prompts every time,
fixed only by a bare name on PATH. So the deliverable is "one bare command
reliably on PATH" (uv tool / pipx into ~/.local/bin, or a symlink), and a Typer
app behind an absolute venv path would solve nothing.
Two honest costs recorded against it: Typer and Click are further venv
dependencies, so it does not help the venv friction at all; and a single
entrypoint importing every subcommand eagerly would pay all 123 modules'
import cost on every invocation, four times per push. Lazy subcommand
registration is therefore mandatory rather than an optimisation, and must be
measured before and after.
Net: this looks like the answer for the check/gate family and the day-to-day
scripts, and it leaves the numpy/scipy/PIL planet-gen path alone — the part a
Rust port would have had to prove numerical equivalence for. T-1246 updated to
start here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The relationship between wiki/, the generators, systems.db and the runtime is
a directed graph with two edges running opposite to the obvious direction and
one running backwards into its own producer. Prose renders that badly: every
document that has described it states a single ownership direction and is
therefore wrong about part of the tree. D-262 makes the diagram the source of
truth and points CLAUDE.md, Skill(wiki), project-structure.md and
wiki/GOVERNANCE.md at it.
The correction that matters most: body pages were described everywhere as
machine-owned and reverted on sync. They are not. scaffold_bodies.py writes
one once and never overwrites it, and import_economics then reads that
frontmatter directly as input — so a hand-edit is not reverted, it is obeyed,
and silently changes world generation. Worse than being overwritten, and the
actual reason GOVERNANCE.md forbids the edit.
New: tooling/check-dataflow-graph.py, wired into the Makefile and the pre-push
hook. It asserts every repo path named in a hand-authored diagram still
resolves — and its docstring states plainly what it cannot do: verify that an
edge still MEANS what it says. If wiki_sync.py stopped writing body pages
tomorrow, every path would still exist and the check would still pass. Edge
semantics stay a human check against the tool's source, so nobody reads a green
gate as a verified map.
Verified by breaking it: pointing one label at a moved path fails with exit 1
naming that path; restoring it passes. Building the checker also caught two
real vaguenesses in the diagram — "GJ-*/index.md" and "bodies/{id}/index.md"
were written without their wiki/star-systems/ prefix, which is precisely the
ambiguity this map exists to remove. Generated star-map .d2 files are excluded
by name; their correctness belongs to their generator under D-223.
Also files Q-124 + T-1246 (tooling): whether the 123 Python files under
tooling/ should become one Rust CLI of pql's calibre. The friction is real and
mostly not about the language — the permission gate prefix-matches whole
command strings and a blanket Bash(python3 *) grant is forbidden, so each tool
prompts near-individually, while a single binary is one allowlist entry. The
record requires pricing the cheap alternative (a Python dispatcher entrypoint)
before recommending Rust, and flags the hard constraint: import_economics is
stamped by source SHA, so any port must keep that contract intact through the
transition rather than disabled during it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three findings, all doc-accuracy, and all the same root cause: folding the
spacing predicate into the ring walk changed what three comments describe, and
two of those comments were written by this same PR one round earlier.
TYRE 1 — road_graph.rs's T-1206 gap-closure comment cited `nearest_land_cell`,
which round 2 made `#[cfg(test)]`. A reader chasing that name lands on a
test-only function and reasonably wonders whether they are looking at dead
code. Repointed to `nearest_cell_matching`, and the paragraph's closing claim
that "T-1206 guarantees the placement pixel is land" is corrected: it has been
land-AND-spacing-or-skip since round 2.
TYRE 2 — `max_land_search_ring`'s doc named the same test-only wrapper as the
thing that walks the bound. It now names the production consumer and both
callers.
TYRE 3 — the D-211 amendment was written in round 1, before round 2 existed,
and still described a land-only correction. It now carries a dated refinement
recording what the code actually does: the walk satisfies BOTH of step 4's
promises in one search, and SKIP therefore also fires where land exists but
none of it clears spacing within the bound. The no-re-decision conclusion is
unaffected — position remains a deterministic, non-fabricated function of seed
and terrain — and the refinement notes the spacing promise is step 4's alone,
since Tier A/B/C placements sit on their matched attractor and were never
subject to it.
HOSHE's three findings were the same three hunks, observed uncommitted while
the review ran: accurate content, but not in the branch tip, so the PR would
have merged a governance record that misdescribes its own commit. That is this
commit.
Both reviewers independently confirmed what the round-2 fix claims. Tyre traced
the ring geometry and tie-break order by hand against the spacing predicate;
Hoshe re-ran the full 267-body corpus scan live (850s) and reproduced the
figures exactly — 267 bodies, 267 reaching Layer 3, 344 placements, 109
synthetic, 0 in water, 0 spacing violations.
The shared-ring-search-helper retraction is confirmed and settled, with NEW
grounds rather than a restatement: round 2 strengthened the case for keeping
them separate, since this walk is now parameterized by an arbitrary predicate
over native u16 terrain coordinates while road_graph's is a RouteGrid method
over downsampled routing cells with a fixed cost test and an unrelated bound.
22 module tests green; clippy and fmt clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Measured during T-1213, through the production canvas builder on Ferrath: at
Quarter and below, morphology collapses to ONE zone and vegetation to ONE
class. The uniform frames in the 2026-08-06 descent ladder were those rungs
drawing exactly what they contain.
The cause is arithmetic, not a missing feature. At the uniform 2x2 px display
ratio a 3440x1440 window gives 540 gridunits on the short axis, so:
Quarter 512 m -> 0.948 m/gridunit -> 0.474 m/px ~1 subtile per pixel
Block 128 m -> 0.237 m/gridunit 4 gridunits per voxel
Chunk 64 m -> 0.119 m/gridunit 8 gridunits per voxel
Block and Chunk magnify beneath the finest datum that can exist, so they can
only ever draw one voxel larger. Quarter lands within 5% of one subtile per
pixel and becomes the floor.
Stated as a rule so it survives the constants moving: the deepest Atlas rung
is the one at which a screen pixel shows one subtile. It is derived from the
data model rather than chosen, and it moves automatically if the subtile does.
WHAT THIS IS NOT. Chunk remains the 64 m stream/derive unit of D-243 and stays
vital — it is what Phase 5 derives first-person walkable content on, and
D-012's load-around-the-player is expressed in chunks. Block remains the 128 m
generator planning unit. Only Atlas VIEWABILITY is retired; the containment
ladder is untouched. This record governs what the map draws, not what the
generator builds.
The justification is the Atlas's purpose (Jeroen): it exists to give the player
information, and a rung earns its place by answering a question the rung above
cannot. Once a pixel is a subtile there is no finer datum to answer with.
The resulting Global -> Region -> District -> Quarter steps at ~93x -> 100x ->
4x. That unevenness is NOT from this change — the rungs removed were 4x and 2x
steps carrying no information — it is D-243's one non-power-of-2 rung, and
T-1218 already exists to re-balance it. A compensating rung above Region was
considered and declined here; it belongs with that ticket.
CLAUDE.md's cascade line updated in the same commit.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The 2026-07-27 amendment closed by naming the live question: does biome
un-summarisation need a stored layer, or does it ride the existing
sample-fresh-at-every-rung mechanism. A descent ladder answers a prior one:
it is not happening in any form, stored or derived.
One body, one land-anchored point, one capture per rung, no overlays, at the
panel's native 3440x1440. Ferrath's heightmap is 1024x512 over a 38,089 km
circumference -- 37.2 km per source pixel. Global draws at 35.267 km/gridunit,
about 1:1 with the source, and reads as a world. Region draws at 0.379 --
98x finer than anything stored -- and is a uniform colour field with dither.
District, at 0.0038, is ~9,800x finer and identical in character. The Atlas is
legible exactly where it samples the heightmap and flat everywhere it invents.
So the D-227 carve-out cannot be argued yet on any basis, disproven or
measured, because there is no artefact to store. Ruling: build the expansion
as a pure function first, following the mechanism that already exists
(D-255(f) mechanism B), measure that, and reopen storage only if the numbers
force it. T-1211 re-scoped, T-1212 retired as a gate with its measurement
moved downstream, T-1213 unblocked as the epic's first child.
Recorded with the same process note the previous amendment earned: this was
found by capturing the ladder and looking at it, after the goldens had been
failing for 15 commits with two of them passing against blank screens.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Three findings from Hoshe (QA) and Tyre (architecture), plus a bug the first
of them uncovered.
HOSHE — the headline evidence lived only in a deleted scratch scan. All nine
tests used synthetic fixtures, so nothing committed held the "46 of 109
synthetic placements in water" claim on real data. Two tests now do. The
T-1206 verification scan itself is committed as an #[ignore]d full-corpus
test (267 bodies, run with --ignored), which also makes the recalibration
instruction on the search bound executable rather than aspirational; a fast
test pins the bodies it identifies.
That scan promptly caught a bug in its own first draft, and it is the reason
this commit is worth reading. `CascadeSnapshot::terrain_analysis` is
transient — the cascade nulls it the moment DistrictProfile and RoadGraph are
done (D-203/T-1048, ~2 MB a body) — so it is ALWAYS None on a returned
snapshot, whatever cascade_snapshot_for_body's doc-comment implies. Reading
the ocean mask off the snapshot and skipping when absent therefore skipped
every body while reporting success: 267 bodies "scanned", 0 findings, a green
assert over an empty set, in 697 seconds. Terrain is now re-derived through
the same run_layer1_with_moisture call the cascade used, reproducing the grid
the placements were computed against.
Two habits caught it, both prompted by Hoshe's finding: a vacuity guard that
refuses to pass when no synthetic placement was seen, and counters that stop
"none found" and "never got that far" from looking identical. Corrected
figures at seed 42: 267 bodies, all reaching Layer 3, 344 placements, 109
synthetic, 0 in water — the synthetic count matching the original scan, so
the claim is reproducible now rather than anecdotal.
TYRE 1 — MAX_LAND_SEARCH_RING was justified as grid_h/2 but written as a
literal 128, leaving the 512x256 coupling implicit. It is now derived from
the grid in scope, so the value cannot drift from its own rationale. On the
current working grid it evaluates to exactly 128: no behaviour change, and
the byte-identical-placement guarantee is untouched. Recalibration owner
recorded.
That derivation does change one test. nearest_land_cell_clamps_rows_no_wrap
uses a 16x16 fixture, so its bound drops 128 -> 8, which now sits BETWEEN the
clamped distance to the far pole (15) and the wrapped one (1). The assertion
moves from position to absence and gets sharper for it: previously both
implementations returned Some((15,0)) and only the position could be pinned;
now any Some at all proves rows wrapped.
TYRE 2 — D-211 carried no note though its behaviour changed. Dated amendment
added: step 4's outcome set is no longer total (synthetic overflow may now
resolve to a defined SKIP), and step 5's warning fires for a new legitimate
reason. No re-decision needed — position remains a pure function of seed and
terrain — and the dead-end cross-reference to D-210's closure is now a live
anchor.
Full cargo test green (30 binaries).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A river is sub-pixel at almost every Atlas scale (a 100 m channel against
Global's ~17.6 km per screen pixel), so drawing it to scale draws nothing.
The line becomes a symbol whose job is legibility: a fixed 5 px screen-space
stroke, contiguous through the river's own cell centres, never drawn over
water, and culled when too small to read.
The cull threshold derives from the stroke rather than being stipulated. A
mark reads as a line at roughly 3x its own width, so the minimum is 15 px of
on-screen length — and the kilometre thresholds then fall out of each rung's
scale: 264 km at Global, 2.8 km at Region, 28 m at District. A level-of-detail
ladder with no hand-tuned constants, which self-corrects if the width changes.
Measured on the visible extent, not total river length: a course crossing the
window always spans it and passes, so only a course wholly inside the view and
small is culled. Correct at both ends of the ladder, and no new wire field.
Records a tension that had to be resolved rather than split. Jeroen proposed a
flat 100 km cutoff, then noted that 5x5 px still reads as a dot and asked for
15-20. Those are incompatible: the km threshold depends only on the pixel
length, so 100 km implies ~6 px, which is dot-shaped at a 5 px stroke.
Admitting 100 km rivers AND keeping them line-shaped needs a ~2 px stroke.
Thick lines mean fewer rivers; thin lines mean more. Ruled for the bold stroke.
Client-side, and provably so: the cull is measured in screen pixels, and the
display ratio is a client-side viewport-dependent parameter that never reaches
a wire request or cache key, so the server cannot know how many pixels a
course occupies. Water-clipping needs nothing new either — the per-cell
classification is already in the adopted canvas.
Built on the 2026-07-27 measurement in D-258's amendment: 375 courses present,
458 of 518,400 pixels different. The rivers were not failing to render, they
were correctly beneath notice; the defect was drawing specks instead of
drawing properly or not at all.
T-1237 implements. T-1238 restores size-varying width as polish, deliberately
deferred — noting width and cull are coupled, since a thinner stroke lowers
its own visibility threshold.
Co-Authored-By: Claude <noreply@anthropic.com>
Written one day after the record, on evidence, and it narrows D-258's scope.
The Rationale claimed hydrology 'was not derivable at all under the old
model'. Not true, and not true when written: layer1.rs already solves drainage
AND settled-equilibrium hydrology once per body, folds the filled surface into
TerrainAnalysis, and every rung bilinearly samples it. The code's own comment
names it — 'a coarse continuous primitive computed once, sampled fresh at
every rung, never re-solved', mechanism B, D-255(f). The pattern rung 0.5 was
invented to provide already existed. I inferred the claim from Region having
no rivers without reading the layer-1 pipeline.
What actually made Global flat was a stale sentinel zeroing its extent, giving
a 2x1 canvas. Once sized correctly Global reads as a world with no hydrology
work at all. Rivers there measured negligible: 375 courses present, 458 of
518,400 pixels changed versus courses-off, because at ~39.7 km/gridunit most
courses are shorter than one gridunit.
Survives: reliefmap-as-plurality, composition-on-descent, the conservation
invariant, and the lake-shore amendment — none depend on hydrology moving.
Weakened: the stored expanded layer and its D-227 carve-out, since the
compute-once-sample-everywhere mechanism it argued for is already shipped.
T-1211 and T-1212 flagged needs-refinement with the reasoning attached; the
measurement as scoped would have priced work that is not required.
The amendment also records why this survived review: the sizing fix's tests
called resolve_canvas_extent directly rather than the serve path, and the
capture goldens could not have caught it either since they never supplied a
body radius. Two verification layers, both green, neither looking at the thing.
Co-Authored-By: Claude <noreply@anthropic.com>
Everything else from the pair session was either shipped or ticketed with its
rationale in git. These two were design decisions Jeroen made, living only in
a scratchpad under /tmp, one cleanup away from gone.
D-259 — ENCLOSED SETTLEMENTS. Open-air requires atmosphere == standard;
everything else is enclosed, as point locations on the Atlas with interiors
deferred to a separate generator and handled like embedded stations. Branch on
an explicit `enclosed` property rather than the atmosphere string, so enclosed
settlements on breathable worlds (hostile-biome posts, undersea, arcologies)
need no second code path. NULL defaults to enclosed, which fails safe.
The load-bearing claim is that D-220's density model is PHYSICALLY
INAPPLICABLE to a pressure vessel, not mistuned: it measures people per km2 of
footprint driven by utility cost per metre of street, so run airless it yields
1,500 ppl/km2 of open-air streets in vacuum. The handoff mechanism was already
planned — D-166's door boundary contract, where a dome's airlock IS that door.
Atmosphere keeps its full range for the surface-expedition layer; the binary
collapse applies to settlement layout only, and the record says so to stop the
collapse being read as atmosphere not mattering.
D-260 — GENERATOR SCOPE. Sol is encoded as Authored { deepest_rung: Global }
rather than excluded by convention. The DLC gate is a DEPTH, not a boolean, so
a Sol expansion changes one value instead of unpicking an exclusion. No new
wire status: "viewable at Global, no deeper" IS the existing rung-liveness
path. Sol art is an authored data canvas, not a finished image, so it rides
the existing wire and is drawn by the same map-art function as all 269
procedural bodies.
The hazard that made encoding necessary is recorded: systems.db still carries
terrain_reference rows for Sol bodies pointing at heightmaps deliberately never
baked, so a real Earth DEM dropped at that exact path would silently start
generating a procedural homeworld. The importer comment said Sol was excluded;
nothing enforced it.
Also files the last three parked items, which were likewise /tmp-only:
T-1233 tiled/interlaced map loading (workshop-sized D-255 revision, blocked in
spirit on the rung-0.5 cost numbers), T-1234 enumerate the flow tweaks the
fetch panel exposed but which were never written down, T-1235 zoom
discoverability — the person who specified wheel-only zoom could not find it.
T-1231 closed.
Co-Authored-By: Claude <noreply@anthropic.com>
D-255 described a system that stopped existing this morning. It said a rung
fixes gridunit SPACING and that spacing is "never viewport-derived"; both are
now exactly backwards. Anything reading it — a refinement agent, a reviewer,
a future session — would have built against a fiction with no way to tell.
Records the inversion (a rung fixes EXTENT, the shorter viewport axis spans
one cell of that level, spacing falls out), Global moving from the body's
region grid to a viewport-sized 2:1 canvas, Region leaving the orbital derive
set, and the display-ratio band collapsing to a uniform 2x2.
Two corrections matter beyond bookkeeping.
D-255 justified Global's D-226(d) legality by it being COARSER than the region
grid. It is now finer — 40.8 km against 204.8 km. The conclusion survives,
since D-226(d) prohibits tile-level maps and caps at settlement/quarter
granularity and 40.8 km is twenty times coarser than a district, but the
premise is dead and nothing downstream should lean on it.
And the always-keep cache figure is invalidated. The "~8.85 MB across 267
bodies, trivially process-resident" number assumed ~18,073 cells per body; a
viewport-sized Global is 460,800 on a 1080p display, which is 25x — about
226 MB, and roughly 900 MB on a 4K display, with per-body derive going from
~16-21 ms to about half a second. An always-keep tier whose size scales with
the user's monitor is the wrong shape, which is an independent argument for
D-258: rung 0.5 is fixed-resolution and baked, and Global becomes a view of
it rather than a canvas retained in its own right.
Also records the two retired mechanisms (the S2 station-spacing floor,
cap_extent_to_body superseded by rung liveness) and states plainly that
Global is still broken — correctly sized now, but with no hydrology until
rung 0.5 lands. Region is eyeball-confirmed working.
Pair session with Jeroen, 2026-07-26.
Co-Authored-By: Claude <noreply@anthropic.com>
Eyeballed on Lendel: the Atlas opened on a Global map that was literally two
cells — one green, one blue — stretched across the window, reporting
19,598.512 km/gridunit, which is exactly half the body's circumference.
Two bugs, both of which the D-255 extent inversion turned from harmless into
fatal.
enter() fires its first request BEFORE this Control is laid out, and a
not-yet-laid-out size is not always exactly Vector2.ZERO — a few stray pixels
sailed past the `== Vector2.ZERO` guard, so the viewer asked for a 2x2
gridunit canvas and the server's 2:1 fit floored it to 2x1. That never
mattered while Global discarded the requested extent and took its cell counts
from the body's region grid; the moment the request became the canvas size, a
transient layout artefact became the map. Any viewport below a plausible
panel size is now treated as not-laid-out.
And Global was excluded from the refetch settle entirely, so a canvas born at
the wrong size could never heal however the window was resized. That
exclusion was correct when no viewport could change Global's extent. Global
now takes the SIZE refit like every other rung, but still never the pan
re-float — its canvas is whole-body and origin-anchored, and the server
ignores `center` for it.
Both have regression tests. The second asserts on _world_center rather than
_view_offset, because _recompute_canvas_transform() legitimately re-centres
the offset on any canvas adoption and would have made the test pass for the
wrong reason.
Worth noting for the class: no test written today could have caught this.
Every one supplies an explicit viewport. The bug lived entirely in the gap
between "scene loads" and "layout completes" — a seam a live launch
exercises and a unit test does not.
Also stages governance/README.md's pql-maintained record index (D-258).
Pair session with Jeroen, 2026-07-26.
Co-Authored-By: Claude <noreply@anthropic.com>
Jeroen, eyeballing the lakes: "they did not seem to run the same coastline
code as ocean does". Correct, in two separate ways.
The coastline warp was ocean-only. invent_primitives displaces the sample
through coast_warp_px before reading the ocean mask, but the lake test read
the UNWARPED position, so ocean coasts got invented bays and capes while lake
shores traced the bare elevation contour. It cannot be fixed by warping the
lake sample alone: a lake is where a filled surface sits above terrain, two
reads that must agree, so moving one and not the other puts water on
hillsides or holes inside lakes. Both surfaces move together in the rung-0.5
pass, or neither does.
And shore morphology was structurally unreachable at a lake edge. Every gate
keyed on ocean_fraction_q, which is always 0 in a lake basin because lakes sit
above sea level. Ruled: lakes get full shore morphology — cliffs, beaches,
deltas. Gates key on proximity to water, not to ocean. No new vocabulary
needed; MorphologyZone already carries Fjord, Delta, Wetland, CliffCoast and
DuneStrand.
The interesting part is what separates the sea-flavoured types, because it
isn't salinity. A delta builds land outward where the river deposits faster
than the water removes; an estuary is the inverse, a drowned valley widening
seaward. The discriminator is tidal energy: the microtidal Mediterranean is
ringed with deltas (Nile, Rhone, Po) despite being salt, while the macrotidal
Atlantic gives estuaries (Thames, Severn, Gironde). So lakes always resolve to
Delta — and so does a tideless sea, which an ocean-vs-lake switch would have
got wrong. Tidal energy governs TidalFlat too, so one derived quantity
replaces two stipulations and no "is it the ocean" branch survives.
Salinity is a property of water, not a landform, and is excluded from
morphology entirely. Derive it from below-sea-level connectivity if gameplay
ever needs it. Parked.
Pair session with Jeroen, 2026-07-26.
Co-Authored-By: Claude <noreply@anthropic.com>
Every Atlas rung currently re-derives from the heightmap independently. D-258
inserts one deterministic whole-body layer between the baked inputs and the
ladder, and points every deeper rung at it instead of at the source files.
Two failures forced it. The Global rung was deriving a five-class hue map
while a per-body artefact labelled "clean color hypsometric render (display /
Atlas)" sat unused beside it. And hydrology was not derivable at all: flow is
a global solve, so no per-window derivation could produce a coherent water
system — Region carried no courses and lakes could not fill.
The record also fixes what the reliefmap IS. It is a plurality, not a
classification: each cell names the biome dominating ~38 km, a vote already
counted and discarded. So rung 0.5 un-summarises it rather than upscaling it,
which binds three consequences — biome edges are gradients never lines
(D-243's climate rule extended to biome), descending reveals composition
rather than sharpness, and invented detail must downsample back to the
summary it came from. That last one is the acceptance gate for any sub-biome
algorithm.
Rung 0.5 is a stored derived artefact and therefore a named carve-out from
D-227's derive-don't-store. The boundary is principled: D-227 governs what is
LOCALLY computable, where storage is pure cost. A whole-body flow solve is not
locally computable by construction — that is why it must exist — so storage
here buys correctness, not convenience. Everything below rung 0.5 stays
derive-don't-store.
Record precedes implementation; no code changes here. Complements the same
session's D-255 extent inversion, which governs how a canvas is sized rather
than what it is made of.
Pair session with Jeroen, 2026-07-26.
Co-Authored-By: Claude <noreply@anthropic.com>
synthetic_attractor now takes the terrain analysis and land-corrects
its pure-arithmetic position via a bounded nearest-land ring walk
(T-1116's pattern: row-major tie-break, column wrap, row clamp,
MAX_LAND_SEARCH_RING=128 sized empirically — real polar ocean bands
push nearest land up to 125 cells). Land positions pass through
UNTOUCHED — verified by direct before/after scan of all 267 real
bodies: 63 land-arithmetic placements byte-identical, and every
golden/determinism harness passes unchanged. The gap was real and
widespread: 46 of 109 synthetic-overflow placements sat in open water
at seed 42 (e.g. GJ903c at a genuine polar ocean cell); post-fix zero,
with all 109 preserved (confirmed at a second seed). Degradation is
defined and pinned: no land within the bound -> the synthetic
attractor is skipped and Phase 5's existing not-placed warning
reports it — never a panic, never a fabricated water position (the
bound never triggers on any scanned real body). 9 new unit tests;
road_graph's anchor comment and the D-210 amendment record the gap
CLOSED (validated).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The surcharge is now COASTAL_ACCESS_SURCHARGE_HOPS_PER_RING=1 added
directly to length_cells (a pure hop count) — the old cost-unit
constant div_ceil'd through MIN_CELL_COST silently produced 4 hops per
ring, worst-case +24 (double the waypoint threshold) for physically
short edges; worst case is now 6. A formula-pinning test asserts both
the arithmetic and the constant. GJ251c's repro tightened to the
documented 2 edges. The always-land citation now points at the real
guarantee (features.rs::extract_attractors, D-209) — and checking the
D-211 Phase-4 synthetic-overflow path exposed a real gap: it has no
ocean-mask guard at all (T-1206 filed); documented, not papered over.
D-210 gains a dated amendment recording the surrogate-anchor-at-cost
carve-out and the relaxation-over-nudge adjudication. The bare 100
dependency dissolved with the unit fix. Edge counts on both repro
bodies verified unchanged (reachability was never affected).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tyre's PR #209 finding: every prior D-226 re-scope carries a dated
amendment in the record, and this vocabulary change existed only in
code comments and ticket appends. Records the drops (select_city,
open_regional — no settlement hit-test affordance post-D-255; one
screen Region..Chunk), the additions (open_atlas, jump_to_center via
the constrained jump_to seam), the summary-field reconciliation, and
the in-process-only transport narrowing.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Records the T-1192 presentation ruling: the Global opener's display
ratio is viewport-fitted per body to the largest integer px/gridunit
that fits the legend-reserved viewport (floored at 1x1, letterbox
centred), texel-exact by construction; fixed rungs keep their tuned
constants. Explicitly notes that non-integer resting-state scaling
remains unsanctioned and that a PR #205 review finding removed a
fractional-fit branch which had cited this record for an exception it
does not contain — the mis-citation episode is part of the record so it
cannot recur silently.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Records the T-1174 ruling: derive(seed, absolute world metres) via the
derive_at_metres family is the only derive core; the batch 64x32
pseudo-grid is re-scoped as a survey raster with a real SurveyCellPos
newtype (role name, not a D-243 rung); derive_district_profile becomes
a thin wrapper at survey-cell-centre positions with binding basin and
riparian preservation; point-feature terrain judgments move to exact
world positions; D-255 step canvases are fenced to the window family.
LayerRegionOutput rebuild deferred to T-1181 (tripwire verified: sole
reader is the region_grid overlay); voxel carrier deferred to Phase 5.
Consults: Tyre APPROVE-WITH-CHANGES, Dudley FEASIBLE-WITH-CHANGES —
both incorporated. Discharges the T-1174 blocker on D-255's T-1181
step-canvas envelope.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Jeroen's gap catch: T-750 never stated that the seed-to-tile cascade is
also what determines the world where the player walks. Now connected in
one statement across three homes: D-012 amendment (the founding 'chunks
load/unload around the player' driver now concretely = the D-227/D-239
cascade; 3x3 chunk neighborhood minimum, coarser context self-provided by
D-255(f) function composition, Atlas interaction never a precondition,
byte-identical either way), the matching T-750 deliverable note (in
changelog), and a one-truth consumer note on Q-093 for the Phase-5 insert
minimap (design deferred, no independent map pipeline expected).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tyre's two governance sentences on the D-226 course note: (a) the
Godot rasterizer floor makes per-class course WIDTH differentiation
inert at every shipping fit zoom — classes distinguish by opacity
alone until T-1175's per-vertex tapering; the 'trunk widest' promise
is design intent, not current pixels. (b) The pole-row edge-drain
branch is structurally unreachable; the real mechanism is interior
k<0 (revert-verification discovery). Plus the dangling cargo-fmt
reflow in the course-cost bench from the gate-bounce round.
Tickets: T-1170
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tyre's binding ruling from the three-audit design pass (full text:
docs/architecture/river-courses-t1170.md). Keystone: the wave-1
carrier rule refines three-way — rung-independent discrete features
ride whole-body; continuous fields ride windowed per-cell arrays;
RUNG-INDEXED INVENTED DETAIL rides the windowed payload regardless of
geometric kind (courses = the coast crinkle's vector sibling; no
ceiling impact — content of the one windowed payload, not a second
query). Courses invented server-side per window on the T-1137 queue,
terminated against the window's own rung-consistent water verdict
(the two-waterline terminus fork dissolves); Region's skeleton chords
ARE the rung-truncated course. river_downstream sentinels reserve
TERMINAL for future endorheic basins. D-226 + D-227 captures added.
Tickets: T-1170, T-1168
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The drawn coastline is a family of curves indexed by rung (warp cutoff
admits more octaves at finer rungs), so no single authoritative server-
side waterline exists — reconciliation is a presentation-frame
operation at the draw site; the skeleton stays rung-independent. Clip
retires into T-1170's coast-terminating courses.
Tickets: T-1172
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
I1: _draw_attractor_shape's three stroke-width args (Confluence arc,
Coastal/NaturalHarbor arc, Oasis spokes) were raw screen-space literals
— Godot multiplies stroke widths by canvas scale exactly like radii, so
at the Region orbital fit zoom the outlines rasterized at ~0.01px, the
identical sub-pixel class the dot/ring compensation fixed, missed on
glyph internals (and attractors are Region-only — precisely where it
bites). Widths now arrive pre-compensated via a px_w param, keeping the
primitive pure. Regression pin: a source-scan test asserting no
draw_arc/draw_line in the function carries a bare numeric width (the
draw-smoke suite documents its own vacuous-pass mode, so source-scan is
the environment-independent gate); revert-verified by name. I2: D-226
visibility-direction sentence — Araminta's fade-down inversion recorded
as pre-T-1170 with its single revisit point named. I3: class-header
call-site claim corrected (enter() funnels through _enter_at_rung).
Tickets: T-1156
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Rivers/basins/attractors ride the existing whole-body layer1 field —
neither AtlasLayerResponse ceiling touched, no tagged-envelope
migration. Per-rung refinement is client-side class filtering on the
additive river_class (distinct from T-1162's server-side Nyquist
cutoff: a fixed finite graph has nothing to truncate). General rule:
discrete map features ride the whole-body overlay family filtered
client-side; continuous per-metre fields ride the windowed per-cell
arrays — wave 2's roads/settlements inherit this unchanged. Riparian
vegetation response is the named T-1168 forward contract, deferred.
Tickets: T-1156
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tyre's exact capture: the design pass's 'retire COMPOSITE_SMOOTH /
crisp draw_rect as the only path' is superseded — the const survives
as the compile-time pipeline axis, the crisp path stays as debug/
compare, and crispness-at-sparse-rungs is delivered by the per-rung
sampling-filter policy instead. T-1155's retirement framing is
cancelled (ticket closes on merge). Also records the R2 softening:
the T-1162 relief band adds sub-district elevation variance at
Quarter cutoff, so temperature no longer steps strictly at the
district there — intended, noted so nobody is surprised later.
Tickets: T-1161, T-1162
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Tyre's APPROVE items (T-1163): record the two-legal-wire-shapes-for-one-
logical-state protocol invariant (whole-response Pending AND Ready+null
district_window both mean 're-poll'; only NotFound/Error are terminal) as
a D-226 note under the T-1124 §4 amendment area, so a future server
refactor of the asymmetry must migrate every consumer in the same change.
Drop the duplicated 5-line stagger comment in atlas_window_tile_set.gd.
Follow-up tickets filed on main: T-1164 (tiled terminal-recovery),
T-1165 (queue_redraw edge root-cause), T-1166 (cold-launch test tier).
Tickets: T-1163
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
All Hoshe/Araminta findings addressed (Tyre approved outright), none
retracted — plus a Dudley stop-and-flag discovery that improved on the
asked-for fix:
- Legend 100x lie (Araminta, blocking): subtitle computed via
spacing_for_rung() and refreshed at all three _held_granularity_v2
write sites. Region test asserts 204.800 km/cell; the District
direction needed a stale-header-aware helper — a District-only test
spuriously passes against the old literal by coincidence.
- Region coalescing coverage (Hoshe 1): both directions tested
(Region-vs-District separate slots; Region-vs-Region coalesces).
- Clamp boundary tests + dangling citations (Hoshe 2): writing the
requested halving-loop-fires test surfaced that the loop is PROVABLY
UNREACHABLE at current constants (per-axis clamp forecloses it —
brute-forced independently on both server and client sides). Ruling:
the loop stays as defensive code; the test became a property sweep
pinning both the wire-cap invariant and the loop's no-op status (a
future constant change breaks it loudly); doc comments on both sides
drop the load-bearing framing and state the truth; the old client
mirror test that claimed the loop fires (passing on the per-axis
clamp alone) is replaced the same way. Client citations now name the
real server tests verbatim.
- Governance (Tyre): D-226 amendment note — progressive cross-rung
refinement EXTENDS T-1124 §4 (not supersedes); legacy u32 field
scheduled for retirement (T-1159).
Server: 1818 lib tests green, clippy/fmt clean. Client: zoom_ladder
48/48, window_request 26/26, viewer 74/74; gdlint clean. Every fix
revert-verified.
All seven Hoshe/Tyre findings addressed, none retracted:
- n-clamp/echo/staleness triangle (Tyre C1): client _clamp_window_n_mirror
(bit-for-bit twin of the server clamp, canonicalize_district_center
precedent) applied before _n is stored/sent; server test pins the
quarter n=32 -> echo 16 contract.
- min_wl band quantization (Hoshe 1/Tyre C3): quantize_min_wl_m snaps to
MIN_WL_BANDS_M {0, 32768, 16384, 8192, 4096} before cache key and echo
(design doc §5's unbounded-key fix), reusing the one true
OCTAVE_WAVELENGTHS_M array; docstrings now state the server-quantizes/
client-sends-raw split; same-band cache-sharing test.
- coalescing granularity axis (Hoshe 2): two tests pin different-
granularity requests as separate in-flight slots and same-granularity
coalescing unchanged.
- orphaned fixture (Hoshe 3): test_protocol.gd consumer decodes
atlas_response_ready_with_window.msgpack through the real IPC path and
asserts the new fields.
- atlas_window_request coverage (Hoshe 4): new test file — stale-drop on
granularity mismatch, old-server-shape defaults accepted, clamp mirror
formula + wiring. First draft's quarter-via-request_now test would have
passed for the wrong reason (request_now resets granularity by design
until T-1153) — split into formula pin + reachable-path wiring proof.
- granularity type seam (Tyre C2): field + resolver docstrings state
finer-only integer multiples with resolve_window_granularity as the
single widening point; matching contract note added to the D-226
T-1143-rulings amendment.
cargo --lib 1807/1807; goldens bit-identical; gdlint clean.
Jeroen's three rulings on the zoom-ladder design pass, recorded as a
D-226 amendment: (1) 'we set a new BHAG so old restrictions are up for
debate' — the item-(d) ceiling opens for the Atlas windowed viewport
(below-quarter rungs gated on the T-1154 measurement pass; chunk/tile
still never a whole-body planetary layer); (2) planetary rung ships as
progressive capped-density tiling on the generalized district_window
carrier; (3) planetary->regional entry becomes continuous cursor-anchored
zoom with full-zoom-out resetting to the canonical orbital frame (D-013
zoom-owns-descent restored; click-through cut superseded).
Design doc stamped with the resolved rulings. T-1143 closed. Implementation
chain: T-1149 (derive_at_metres + octave cutoff) -> T-1150 (granularity
carrier + aliasing test) / T-1151 (window par_iter) -> T-1152 (derived
planetary rung) / T-1153 (client continuous ladder) -> T-1155 (smoothing
retirement); T-1154 below-quarter measurement gate.
Jeroen's same-day corollary to the zoom-ladder condition: no zoom level
displays the authored heightmaps directly — even the orbital/planetary map
is derived output, sampled at canvas resolution (continuous field, not
fixed rasters). Kills zoom over/undersampling by construction and makes
the map viewport-adaptive. import_heightmaps survives as input storage
only; AtlasViewer's texture display path retires when the derived
planetary rung lands. T-1143 design pass extended with items (e)-(g).
Jeroen's ruling from the Groombridge/Lendel zoom-ladder captures: the BHAG
stays 'a Reach a character can travel through'; the Phase 4 exit bar now
additionally requires a continuous Atlas zoom ladder (planetary map -> tile
scale, each level deterministically derived at native granularity, never
magnified interpolation). Evidence in the record: the 16-district window is
sub-pixel vs its heightmap source at Lendel scale, so everything below fit
zoom is D-227 invented detail that must be derived, not smoothed.
CLAUDE.md Phase-4 row carries the condition; T-1143 (the ladder design
pass) appended + raised to high — it and the D-226(d) floor question are
now phase-gating.
Cover-fit: fit_window_view zooms from the viewport's LARGER dimension,
no margin factor (any factor under 1.0 leaves a long-axis gap — checked
numerically) — the composite fills edge to edge, overhanging the short
axis into pan-space; the refloat center-equality early-return already
prevents refetch churn at rest (proved, not just tested).
Input model (Jeroen: drag breaks click semantics with map objects):
LMB-drag pan REMOVED from the regional window; clicks are
object-reserved. Pan = held WASD/arrows polled in _process (delta- and
zoom-scaled, camera-pans-toward-key convention verified numerically)
plus edge-scroll within 24px of the viewport border; both suppressed
over UI and on OS focus loss; both set _user_adjusted; wheel zoom and
Esc unchanged. Reads RAW physical keycodes deliberately — independent
of the shared D-054 move_* InputMap actions bound to the same keys
(whose occlusion-leak is pre-existing and now ticketed as T-1146).
Pole wall + east-west wrap unchanged, re-driven through the new
inputs; drag tests replaced, not kept.
Smoothed composite (interim pending T-1143): per-cell colors bake into
an n x n Image/ImageTexture (exact existing colorizer incl. overlay +
ice tint) drawn once with LINEAR filtering — GPU bilinear reads as
terrain, the planetary heightmap's own treatment. Crisp per-cell path
preserved behind COMPOSITE_SMOOTH for T-1143 A/B. Rebuild only on
reference-identity change of window/toggle (is_same — verified true
reference equality; value-equal distinct dicts DO rebuild).
Governance: T-1145 amendment paragraph on D-226 T-1124 SS5 (all three
supersessions); pql decisions validate ok.
Suites: window_viewer 74/74, window_geometry 32/32, window_overlay
(new) 16/16; gdlint clean on all six files.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
SS4: the 7/29ms per-window figures now state their warm-analysis
assumption — the first window on a body additionally pays one ~45ms
run_layer1 into the lazy per-body LRU on the GenerationQueue
(capacity 8, browsed-bodies-only, recency eviction, eviction re-pays);
subsequent windows any (center, n) hit the LRU. SS5: the glaciation
tint gate corrected from >= Light to >= Moderate, matching
apply_ice_tint's reference gate (Light is erosion signatures, not
visible ice) — code stood, prose was wrong.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The regional-map entry changes from zoom-threshold LOD swap to
explicit click-through: the planetary heightmap view becomes FIXED
(pan/zoom removed together with its replacement in T-1138, never
before); hovering shows a rectangle cursor representing the
regional-mode bounds; click descends centered on the click point's
derived DistrictPos. DISTRICT_WINDOW_MIN_ZOOM retired before ever
being built; D-013's zoom-owns-descent superseded for this seam only
(click owns descent). In-mode behavior unchanged (pan-only refetch,
debounce, cache, border-fade). Morph transition explicitly deferred.
Open at T-1138: the rectangle is an affordance, not to scale — n=64
is ~131 km = a few px on a planetary canvas; resolve the honest
representation in the screen design. T-1138 description updated;
T-1140 filed for the two companion UI defects fixed alongside.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
All five findings applied, none touching the option-(c) carrier choice:
(1) SS2 gains a binding windowed-family ceiling — exactly ONE
windowed-query field; a second windowed query is a dedicated response
message by rule (two concurrent windowed payloads would need the
per-field request-correlation that IS the tagged framing — that is the
trigger to build it); symmetric with the request side's five-hard cap.
(2) SS1 gains a binding serving model — window derives ride the same
Rayon queue + Pending pattern as whole-body cache misses, never inline
in the PreInput drain (which the codebase deliberately keeps expensive
work off); per-connection coalescing recommended; SS4's 7/29ms figures
reframed as worker latency, not tick-thread cost. (3) The
layer_proxy.rs growth-ceiling comment (comment-only diff) now records
the T-1124 ruling as RESOLVED — scoped to the dense whole-body family,
district_window outside it, second windowed field = dedicated-message
migration — instead of deferring to an open design question. (4) SS2
documents that body scoping rides the enclosing AtlasLayerResponse
envelope (cache key body_id+center+n; echo disambiguates within-body).
(5) SS5 entry clarified: zoom threshold alone triggers the swap
(works over open ocean), first window centers on the pan-center's
derived DistrictPos; downstream settlement-anchoring phrasing
reconciled.
pql decisions validate clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
