Merge pull request #140 from wormeyman/cliffs-crater-add-only

docs(cliffs): the CRATER PLACER is ADD-ONLY - the last untouched idea (#84)

Author: wormeyman

docs/noise/cliffs-NOTES.md

@@ -1051,6 +1051,41 @@ That is a real border-only channel, because the largest cliff half-extent is
 reaching for it: an absent chunk makes the game KEEP a cliff, so its signature
 is a false rejection, not a missed destruction.
 
+### `CliffCraterPlacer::tryToPlaceCliffAsCrater` is ADD-ONLY - closed 2026-08-04 (#84)
+
+The third and last of the untouched ideas in `vulcanus-cliffs-NOTES.md`, listed
+there as "ruled out for the residual by position but never ruled out as a
+mechanism". It is the one thing in the entity stage that touches cliffs at all,
+so it deserved a direct read rather than another position argument.
+
+**It only ever adds.** Both overloads reach the same two calls and nothing else:
+
+| | |
+| --- | --- |
+| `tryToPlaceCliffAsCrater(Surface&, MapPosition const&, CliffPrototype const&, unsigned int)` | `0x10160bc34` - a thin wrapper, single `bl` to the overload below |
+| `tryToPlaceCliffAsCrater(..., CraterPlacementDefinition const&, RandomGenerator&)` | `0x10160bcac` - calls `calculateCliffSegments`, then `Surface::addEntity` (`0x1001b3f8c`) per accepted segment |
+| `CliffCraterPlacer::calculateCliffSegments` | `0x10160be6c` - calls `Surface::wouldCollide` (`0x10160c088`) and emplaces the segments that pass into a `SmallVector<Pair<MapPosition, CliffOrientation>, 16>` |
+
+Across the whole `0x10160bc34..0x10160c088` range there is **no `destroy`,
+`remove` or `erase` path of any kind** - the only other `bl`s are three
+`dyld_stub_binder` PLT entries (`operator delete` / `memmove` shape) and the
+stack-check epilogue. Its callers are `EntityMapGenerationTask::applyEntities`
+and `CliffEditor::buildCliffs`.
+
+**Why that closes it, and why the closing argument is DIRECTION rather than
+position.** The ore effect is *fewer* cliffs when ore is present - 885 against
+916 in `[1500,1500]`, so 31 cliffs must be destroyed or prevented. A function
+that can only add, and only where `wouldCollide` reports the space free, cannot
+produce that sign. The crater counts corroborate it instead of merely permitting
+it: **0 craters with resources on, 8 with them off**, so both populations move
+the *same* way under the lever, which is not what displacement looks like.
+
+The position argument (`[0,0]` and `[1500,1500]` have zero crater-cliffs; all 8
+are in `[-1200,800]`, the region with none of the worst crossing error) was
+already on record and had left the candidate alive for weeks, because it only
+says these objects are not the residual - not that this code cannot cause it.
+One call-list read settles what the position never could.
+
 ### `crater-cliff` is not on the cliff lattice - confirmed, not assumed
 
 **FFF #386 explains why it exists and corroborates both readings**

docs/noise/vulcanus-cliffs-NOTES.md

@@ -1,5 +1,36 @@
 # Vulcanus cliffs - port notes
 
+> ## UPDATE 15, 2026-08-04: the CRATER PLACER is ADD-ONLY - the third and last untouched idea is closed
+>
+> `CliffCraterPlacer::tryToPlaceCliffAsCrater` was the last of UPDATE 9's three
+> untouched ideas, carried there as "ruled out for the residual by position but
+> never ruled out as a mechanism". **It is add-only, so it cannot be the
+> mechanism.** Addresses and the full call lists are in `cliffs-NOTES.md`.
+>
+> Both overloads reach exactly `calculateCliffSegments` (which calls
+> `Surface::wouldCollide` and emplaces the segments that pass) and then
+> `Surface::addEntity`. Across the whole `0x10160bc34..0x10160c088` range there
+> is **no destroy, remove or erase path of any kind**.
+>
+> **The argument that settles it is DIRECTION - which is exactly what that
+> bullet's own framing was missing.** The ore effect is *fewer* cliffs when ore
+> is present, 885 against 916, so something has to destroy or prevent 31 of them.
+> A function that can only add, and only where `wouldCollide` reports the space
+> free, cannot produce that sign. The crater counts corroborate rather than
+> merely permit: **0 craters with resources on, 8 with them off**, so both
+> populations move the *same* way under the lever - not what displacement looks
+> like.
+>
+> Position arguments kept this candidate alive for weeks, because they only say
+> these objects are not the residual, never that this code cannot cause it. One
+> call-list read closed it.
+>
+> **All three of UPDATE 9's ideas are now closed** - chunk order (UPDATE 12), the
+> compute -> apply queue (UPDATE 13), and this one - **and the ore effect is
+> untouched by every one of them.** It still reproduces at precision 1.000 with
+> no surviving mechanism. Whatever comes next should not be another candidate off
+> a list that is now empty.
+>
 > ## UPDATE 14, 2026-08-04: the RUNTIME DESTROY PROBE is BUILT, and the port's cascade reproduces the game EXACTLY
 >
 > #127 asked for a runtime probe that destroys a cliff outside map generation,
@@ -97,7 +128,8 @@
 > **One of the three ideas is left:** `CliffCraterPlacer::tryToPlaceCliffAsCrater`
 > as a *mechanism* (ruled out for the residual by position, never as a
 > mechanism). The ore effect is untouched by this and still reproduces at
-> precision 1.000.
+> precision 1.000. (That one was closed the same day too - see UPDATE 15 above,
+> which leaves the list empty.)
 >
 > ## UPDATE 12, 2026-08-04: CHUNK-GENERATION ORDER is closed - both links, and the ore effect survives
 >
@@ -3683,10 +3715,18 @@ Ideas that are still untouched, for whoever picks this up:
   this bullet used to say, kept because it is the reasoning that made the idea
   worth trying: the queue is filled in the compute phase and drained in the
   apply phase, and no measurement covered what happened to it in between.
-- `CliffCraterPlacer::tryToPlaceCliffAsCrater`, which runs at the head of
+- ~~`CliffCraterPlacer::tryToPlaceCliffAsCrater`, which runs at the head of
   `applyEntities` and is the one thing in the entity stage that touches cliffs at
-  all. Ruled out for the residual by position (#84's crater-cliff note) but never
-  ruled out as a mechanism.
+  all.~~ **CLOSED 2026-08-04 - see UPDATE 15 and `cliffs-NOTES.md`.** It is
+  ADD-ONLY: no destroy, remove or erase path exists anywhere in it, so it cannot
+  produce an effect whose direction is FEWER cliffs. The bullet's own framing is
+  why this took so long - it was "ruled out for the residual by position but
+  never ruled out as a mechanism", and position is not the argument that
+  settles it. Direction is.
+
+**All three ideas on this list are now closed, and the ore effect is unchanged.**
+That is the honest state: 885 against 916 at precision 1.000, with no surviving
+mechanism. The next move is not another candidate off a list that is empty.
 
 ## `crater-cliff` moves under the lever too - a SECOND effect, and an RNG lead (2026-08-03, #84)