From fe53bc36a69c0df80bd566e736e32da09a6b6c5b Mon Sep 17 00:00:00 2001
From: TheMeinerLP <github@themeinerlp.dev>
Date: Sat, 10 Oct 2026 20:27:39 +0200
Subject: [PATCH 1/2] docs: correct versions, counts and catalogue entries that
 had drifted from the code

Corrections, each checked against the tree at this commit:

- Current version 2.1.0 -> 3.0.0 on modules-and-coordinates and in the
  how-to and tutorial snippets (build.gradle.kts:7, .release-please-manifest.json).
- BOM covers falco-anvil, falco-light, falco-instance only; falco-migration
  is published but not in the BOM (falco-bom/build.gradle.kts).
- Minestom is compileOnly in anvil, light and instance; migration and bom
  declare none (*/build.gradle.kts). fastutil/flare are compileOnly in instance only.
- Renovate rule in renovate.json matches README.md only; the docs say so.
- ChunkDataException.Reason has seven constants; the five missing ones are
  added to the reason table (ChunkDataException.java:37-75).
- Logging table: INFO for the pre-migration backup copy (FalcoAnvilLoader.java:2203).
- SECTIONS_KEY is private; the link is replaced by plain text
  (FalcoAnvilLoader.java:94).
- Minestom resolved version 2026.06.20-26.1.2 -> 2026.09.12-26.2 via
  mycelium-bom 1.8.7 (settings.gradle.kts, dependencyInsight offline).
  Historical measurement and source-citation statements are untouched.
- Dependency pins in contributing docs and benchmark catalogue follow
  settings.gradle.kts: mycelium-bom 1.8.7, adventure 5.2.0, slf4j 2.0.20,
  fastutil 8.5.19, cyano 0.7.6, junit 6.1.3, archunit 1.5.1.
- Gradle wrapper 9.6.1 -> 9.8.1 (gradle-wrapper.properties).
- Module count seven -> eight (settings.gradle.kts); falco-migration listed
  as published (build.gradle.kts publishedModules).
- Workflow pins @v2.4.0 replaced by a link to the pinned file in
  .github/workflows (currently v2.9.0).
- Benchmark catalogue: nine classes that had no entry added (AreaPassStage,
  ChunkComparison, ChunkLookup, ChunkResendCost, GeneratorCommit, LazySection,
  PaletteIndirectGet, SectionAllocation, SetBlockContention) from their
  @Param and @Benchmark declarations.
- Heap statement: three classes set no heap flags, not two
  (AreaVsPerChunk, IncrementalVsFull, ChunkLookup which has no @Fork).

Claude-Session: https://claude.ai/code/session_01Q6AxU7jRLmNPHdwg2GpasT
---
 docs/contributing/README.md                   | 29 ++++++++++---------
 docs/contributing/build-setup.md              |  6 ++--
 docs/contributing/dependency-management.md    | 19 ++++++------
 .../contributing/documentation-conventions.md |  6 ++--
 docs/contributing/publishing.md               |  2 +-
 docs/contributing/testing-and-javadoc.md      |  2 +-
 docs/contributing/versioning-and-releases.md  |  2 +-
 docs/how-to/add-falco-to-your-build.md        | 17 ++++++-----
 docs/reference/benchmark-catalogue.md         | 22 +++++++++++---
 docs/reference/exceptions-and-faults.md       | 13 ++++++---
 docs/reference/logging.md                     |  2 +-
 docs/reference/measured-results.md            |  6 ++--
 docs/reference/modules-and-coordinates.md     | 28 +++++++++++-------
 docs/reference/supported-versions.md          |  4 +--
 .../load-your-first-world-with-falco.md       |  4 +--
 15 files changed, 96 insertions(+), 66 deletions(-)

diff --git a/docs/contributing/README.md b/docs/contributing/README.md
index 3542485..475c4cc 100644
--- a/docs/contributing/README.md
+++ b/docs/contributing/README.md
@@ -36,23 +36,25 @@ a republication of the BOM without a single commit in this repository.
 | | | Pinned here |
 | --- | --- | --- |
 | Java | 25 (toolchain and `release`), no `--enable-preview` anywhere | yes, in the root `build.gradle.kts` |
-| Minestom | `2026.06.20-26.1.2`, `compileOnly` | **no** — `library("minestom", …).withoutVersion()`, resolved through `net.onelitefeather:mycelium-bom` `1.7.2` |
-| Adventure | `5.1.1`, `adventure-nbt` used directly — Minestom speaks `CompoundBinaryTag` natively, so there is no conversion layer | yes, `adventure-bom` `5.1.1` |
+| Minestom | `2026.09.12-26.2`, `compileOnly` | **no** — `library("minestom", …).withoutVersion()`, resolved through `net.onelitefeather:mycelium-bom` `1.8.7` |
+| Adventure | `5.2.0`, `adventure-nbt` used directly — Minestom speaks `CompoundBinaryTag` natively, so there is no conversion layer | yes, `adventure-bom` `5.2.0` |
 | Annotations | `org.jetbrains:annotations:26.1.0` | yes |
-| Tests | JUnit 6.1.0, Cyano `0.6.2` (`MicrotusExtension`) for anything needing a server | **no** — both `withoutVersion()`, resolved through `mycelium-bom` `1.7.2` |
+| Tests | JUnit 6.1.3, Cyano `0.7.6` (`MicrotusExtension`) for anything needing a server | **no** — both `withoutVersion()`, resolved through `mycelium-bom` `1.8.7` |
 | Benchmarks | JMH 1.37 via `me.champeau.jmh` 0.7.3, in the separate `falco-benchmarks` module | yes, both |
-| `fastutil` | `8.5.18` | yes |
-| Architecture | ArchUnit 1.4.2, in the separate `falco-archunit` module | yes |
-| Build | Gradle 9.6.1, seven modules on one shared version | yes |
+| `fastutil` | `8.5.19` | yes |
+| Architecture | ArchUnit 1.5.1, in the separate `falco-archunit` module | yes |
+| Build | Gradle 9.8.1, eight modules on one shared version | yes |
 
-The seven modules are `falco-anvil`, `falco-light`, `falco-instance`, `falco-benchmarks`,
-`falco-demo`, `falco-archunit` and `falco-bom`; the first three are published, `falco-bom` publishes
-only their constraints, and the other three are not published at all.
+The eight modules are `falco-anvil`, `falco-light`, `falco-instance`, `falco-migration`,
+`falco-bom`, `falco-benchmarks`, `falco-demo` and `falco-archunit`; `falco-anvil`, `falco-light`,
+`falco-instance` and `falco-migration` are published, `falco-bom` publishes only version constraints
+for `falco-anvil`, `falco-light` and `falco-instance`, and `falco-benchmarks`, `falco-demo` and
+`falco-archunit` are not published at all.
 
 **The Minestom version is the one that would invalidate a comparison silently.** Every head-to-head
 table under [Measured](../reference/measured-results.md#measured) measures the Minestom of the day the run happened,
-and that version is decided by `mycelium-bom` `1.7.2`, not by anything in this repository.
-`2026.06.20-26.1.2` is what it resolved to; a third party reproducing a number has to check that
+and that version is decided by `mycelium-bom` `1.8.7`, not by anything in this repository.
+`2026.09.12-26.2` is what it resolves to today; a third party reproducing a number has to check that
 theirs resolves to the same thing before comparing.
 
 `adventure-nbt`, `jetbrains-annotations` and `fastutil` are declared explicitly rather than taken
@@ -169,7 +171,8 @@ Four of its checks decide most of the outcome.
 
 [`.github/workflows/build-pr.yml`](https://github.com/OneLiteFeatherNET/Falco/blob/main/.github/workflows/build-pr.yml)
 is what then runs on the branch. It is a thin caller of the shared
-`OneLiteFeatherNET/workflows/.github/workflows/gradle-build-pr.yml` job at `v2.4.0`, pinned to
+`OneLiteFeatherNET/workflows/.github/workflows/gradle-build-pr.yml` job at the version pinned in
+[`.github/workflows/build-pr.yml`](https://github.com/OneLiteFeatherNET/Falco/blob/main/.github/workflows/build-pr.yml), pinned to
 Java 25 on Temurin with `run-tests: true`, so a pull request is checked by the same build the first
 command under [Working on this](#working-on-this) runs locally. A second workflow,
 `close_invalid_prs.yml`, calls the organisation's `close-invalid-prs` job when a pull request is
@@ -184,7 +187,7 @@ default owner later cannot silently widen who approves a release.
 
 - The versions in [Environment](#environment) are declared in
   [`settings.gradle.kts`](https://github.com/OneLiteFeatherNET/Falco/blob/main/settings.gradle.kts)
-  for the version catalogue and the seven modules, in
+  for the version catalogue and the eight modules, in
   [`build.gradle.kts`](https://github.com/OneLiteFeatherNET/Falco/blob/main/build.gradle.kts) for the
   toolchain, the release target and the single `version = …` line, and in
   [`gradle/wrapper/gradle-wrapper.properties`](https://github.com/OneLiteFeatherNET/Falco/blob/main/gradle/wrapper/gradle-wrapper.properties)
diff --git a/docs/contributing/build-setup.md b/docs/contributing/build-setup.md
index fe29dc7..9b9ccee 100644
--- a/docs/contributing/build-setup.md
+++ b/docs/contributing/build-setup.md
@@ -11,7 +11,7 @@ Everything below is checkable in four files:
 [`build.gradle.kts`](https://github.com/OneLiteFeatherNET/Falco/blob/main/build.gradle.kts),
 [`settings.gradle.kts`](https://github.com/OneLiteFeatherNET/Falco/blob/main/settings.gradle.kts),
 [`gradle.properties`](https://github.com/OneLiteFeatherNET/Falco/blob/main/gradle.properties) and
-the seven module scripts. Gradle itself is pinned by the wrapper at `9.6.1`, in
+the eight module scripts. Gradle itself is pinned by the wrapper at `9.8.1`, in
 [`gradle/wrapper/gradle-wrapper.properties`](https://github.com/OneLiteFeatherNET/Falco/blob/main/gradle/wrapper/gradle-wrapper.properties),
 so `./gradlew` is the only supported way to run any of it.
 
@@ -43,7 +43,7 @@ the architecture rules over the other modules — see [Architecture Rules](archi
 
 `falco-benchmarks/build.gradle.kts` holds the only `plugins { }` block in the repository, a single
 `alias(libs.plugins.jmh)`. Every other plugin in the table is applied imperatively from the root, so
-the seven module scripts contain dependencies, a `description`, and — in `falco-benchmarks` and
+the eight module scripts contain dependencies, a `description`, and — in `falco-benchmarks` and
 `falco-demo` — task wiring, and nothing else.
 
 `falco-archunit` gets `java-library` and `jacoco` from the root like every non-BOM module, and both
@@ -128,7 +128,7 @@ This assignment sits outside the `java-library` configuration block precisely so
 
 ## No repositories are declared per-project
 
-None of the seven module build files declares a `repositories { }` block. Repositories come
+None of the eight module build files declares a `repositories { }` block. Repositories come
 exclusively from `dependencyResolutionManagement` in `settings.gradle.kts`, and that file does not
 set `repositoriesMode`, so Gradle's default `RepositoriesMode.PREFER_PROJECT` applies: the moment a
 module declared its own block, that block would win and the settings-level declaration would be
diff --git a/docs/contributing/dependency-management.md b/docs/contributing/dependency-management.md
index 4742c02..470d5b5 100644
--- a/docs/contributing/dependency-management.md
+++ b/docs/contributing/dependency-management.md
@@ -62,30 +62,31 @@ itself. Where a version is stated below it is the one the catalog declares today
   `net.kyori:adventure-text-minimessage`, `net.onelitefeather:cyano`, Mockito and the JUnit BOM, and
   nothing else — checkable in the published `mycelium-bom` POM. JMH is not among them, so both the
   benchmark harness and the Gradle JMH plugin need an explicit version here.
-- **`slf4j` (`2.0.18`) and `annotations` (`26.1.0`).** Not managed by the mycelium BOM either, for
+- **`slf4j` (`2.0.20`) and `annotations` (`26.1.0`).** Not managed by the mycelium BOM either, for
   the same reason and with the same consequence.
-- **`adventureBom` (`5.1.1`).** The library modules receive Adventure transitively through Minestom,
+- **`adventureBom` (`5.2.0`).** The library modules receive Adventure transitively through Minestom,
   which is `compileOnly` and therefore never reaches a runtime classpath (see below). The benchmarks
   module runs its code for real and needs Adventure at runtime, so it imports the Adventure platform
-  directly. The value matches what Minestom pulls in — `net.minestom:minestom:2026.06.20-26.1.2`
-  declares `net.kyori:adventure-nbt` at version `5.1.1` — but nothing in the build asserts that the
-  two agree, so a Minestom upgrade that moves Adventure has to be followed here by hand.
+  directly. The value is meant to match what Minestom pulls in. It matched `net.minestom:minestom:2026.06.20-26.1.2`,
+  which declares `net.kyori:adventure-nbt` at `5.1.1`; whether `2026.09.12-26.2` declares the same
+  version was not re-checked for this page. Nothing in the build asserts that the two agree, so a
+  Minestom upgrade that moves Adventure has to be followed here by hand.
 - **`slf4j.simple`.** Only `falco-demo` needs an SLF4J binding, and it takes it as `runtimeOnly`. The
   library modules depend on `slf4j-api` alone and leave the choice of binding to the consumer; a demo
   that actually runs would otherwise greet the user with "No SLF4J providers were found" before
   printing anything of its own.
-- **`fastutil` (`8.5.18`, explicit version).** Minestom declares `it.unimi.dsi:fastutil` at
+- **`fastutil` (`8.5.19`, explicit version).** Minestom declares `it.unimi.dsi:fastutil` at
   **runtime** scope, so it never reaches a *compile* classpath through Minestom. `falco-instance`
   compiles against fastutil types, and `falco-light`'s equivalence test and the comparison benchmarks
   call Minestom methods that take a fastutil collection, so the dependency has to be named
-  explicitly — and naming it means pinning it. `8.5.18` is the same version Minestom
-  `2026.06.20-26.1.2` declares.
+  explicitly — and naming it means pinning it. The value is meant to match the version Minestom
+  declares: `8.5.18` was the match for `2026.06.20-26.1.2`, and `2026.09.12-26.2` was not re-checked.
 
 Six entries are declared with `withoutVersion()` — `minestom`, `adventure.nbt`, `cyano` and the
 three JUnit coordinates. Their versions come from a platform at use site: the mycelium BOM for
 Minestom, Cyano and JUnit, and Minestom's own dependency graph for `adventure-nbt`. The consequence
 worth knowing is that **no Minestom version string appears anywhere in this repository**: it is
-whatever `net.onelitefeather:mycelium-bom:1.7.2` manages, which today is `2026.06.20-26.1.2`. What
+whatever `net.onelitefeather:mycelium-bom:1.8.7` manages, which today is `2026.09.12-26.2`. What
 that costs is traceability — an upgrade to the mycelium BOM moves Minestom, and therefore moves the
 Minestom side of every comparison this project publishes, through a diff that mentions only a BOM
 version. Anyone reproducing a measured result therefore needs the Minestom version stated alongside
diff --git a/docs/contributing/documentation-conventions.md b/docs/contributing/documentation-conventions.md
index 5f829a2..f840ffa 100644
--- a/docs/contributing/documentation-conventions.md
+++ b/docs/contributing/documentation-conventions.md
@@ -50,10 +50,10 @@ limit in its own provenance line rather than in a page footer, because a disclai
 something only where the number is.
 
 **Claims about somebody else's code carry a revision.** Minestom is read from the sources jar of
-`net.minestom:minestom:2026.06.20-26.1.2`, which is the version this repository compiles against —
+`net.minestom:minestom:2026.09.12-26.2`, which is the version this repository compiles against —
 `settings.gradle.kts` declares `minestom` `withoutVersion()` and takes the version from
-`net.onelitefeather:mycelium-bom:1.7.2`, whose `dependencyManagement` pins exactly
-`2026.06.20-26.1.2`. That is a resolved version and not a pinned one: republishing the BOM changes
+`net.onelitefeather:mycelium-bom:1.8.7`, whose `dependencyManagement` pins exactly
+`2026.09.12-26.2`. That is a resolved version and not a pinned one: republishing the BOM changes
 the Minestom side of every comparison without any commit here. Each such claim names the file, the
 line and the member, so it can be checked in a minute and so it reads as analysis of a specific
 revision rather than as a verdict on another project. The same rule governs Starlight and Phosphor
diff --git a/docs/contributing/publishing.md b/docs/contributing/publishing.md
index dc0e0a3..d0171f9 100644
--- a/docs/contributing/publishing.md
+++ b/docs/contributing/publishing.md
@@ -143,7 +143,7 @@ runs that workflow, and exactly one of its two publish jobs fires:
 | `publish` | `release_created == 'true'` | `publish` |
 | `publish-snapshot` | `release_created != 'true'` | `-Psnapshot build`, then `-Psnapshot publish` |
 
-Both jobs call `OneLiteFeatherNET/workflows/.github/workflows/gradle-publish.yml@v2.4.0` with
+Both jobs call `OneLiteFeatherNET/workflows/.github/workflows/gradle-publish.yml` at the version pinned in [`.github/workflows/release-please.yml`](https://github.com/OneLiteFeatherNET/Falco/blob/main/.github/workflows/release-please.yml), with
 `java-version: "25"` and `secrets: inherit`, which is where the two `ONELITEFEATHER_MAVEN_*` values
 the block above reads come from. The conditions are exact opposites of the same output, so a push
 publishes either a release or a snapshot and never both. [Versioning and
diff --git a/docs/contributing/testing-and-javadoc.md b/docs/contributing/testing-and-javadoc.md
index fbcef45..c255fd9 100644
--- a/docs/contributing/testing-and-javadoc.md
+++ b/docs/contributing/testing-and-javadoc.md
@@ -34,7 +34,7 @@ in the same package.
 The run is reproducible in the sense that matters for a build: the JDK is not whichever one launched
 Gradle. The root build pins a Java 25 toolchain and `options.release = 25` (see [Build
 Setup](build-setup.md)), and `.github/workflows/build-pr.yml` requests Temurin 25 from the shared
-`gradle-build-pr.yml@v2.4.0` workflow with `run-tests: true`, so a pull request runs the same
+`gradle-build-pr.yml` workflow, at the version pinned in [`.github/workflows/build-pr.yml`](https://github.com/OneLiteFeatherNET/Falco/blob/main/.github/workflows/build-pr.yml), with `run-tests: true`, so a pull request runs the same
 compiler and the same test JVM version a local `./gradlew check` does.
 
 Every test JVM is started with one system property:
diff --git a/docs/contributing/versioning-and-releases.md b/docs/contributing/versioning-and-releases.md
index 1fdd208..3fd647e 100644
--- a/docs/contributing/versioning-and-releases.md
+++ b/docs/contributing/versioning-and-releases.md
@@ -104,7 +104,7 @@ publish-snapshot:
 ```
 
 `-Psnapshot` reaches Gradle inside the task strings because the shared
-`OneLiteFeatherNET/workflows/.github/workflows/gradle-publish.yml@v2.4.0` workflow passes them to
+`OneLiteFeatherNET/workflows/.github/workflows/gradle-publish.yml` workflow, at the version pinned in [`.github/workflows/release-please.yml`](https://github.com/OneLiteFeatherNET/Falco/blob/main/.github/workflows/release-please.yml), passes them to
 `./gradlew` verbatim and offers no separate input for properties or environment variables.
 
 Everything that is not a release therefore ships a snapshot: a merged feature, a documentation fix,
diff --git a/docs/how-to/add-falco-to-your-build.md b/docs/how-to/add-falco-to-your-build.md
index b2e55ae..8a351d9 100644
--- a/docs/how-to/add-falco-to-your-build.md
+++ b/docs/how-to/add-falco-to-your-build.md
@@ -21,17 +21,18 @@ snapshot endpoints are both public.
 
    ```kotlin
    dependencies {
-       implementation(platform("net.onelitefeather:falco-bom:2.1.0"))
+       implementation(platform("net.onelitefeather:falco-bom:3.0.0"))
 
        implementation("net.onelitefeather:falco-anvil")
        implementation("net.onelitefeather:falco-light")
        implementation("net.onelitefeather:falco-instance")
-       implementation("net.onelitefeather:falco-migration")
+       implementation("net.onelitefeather:falco-migration:3.0.0") // not in the BOM, so it takes its version here
    }
    ```
 
-   Take only the modules you need. The platform constrains a version for each; it does not pull in
-   one you did not declare.
+   Take only the modules you need. The platform constrains a version for `falco-anvil`, `falco-light`
+   and `falco-instance`; it does not pull in one you did not declare, and it does not cover
+   `falco-migration`.
 
 3. Declare Minestom yourself. Falco does not bring it:
 
@@ -47,10 +48,10 @@ Version each module individually instead of step 2:
 
 ```kotlin
 dependencies {
-    implementation("net.onelitefeather:falco-anvil:2.1.0")
-    implementation("net.onelitefeather:falco-light:2.1.0")
-    implementation("net.onelitefeather:falco-instance:2.1.0")
-    implementation("net.onelitefeather:falco-migration:2.1.0")
+    implementation("net.onelitefeather:falco-anvil:3.0.0")
+    implementation("net.onelitefeather:falco-light:3.0.0")
+    implementation("net.onelitefeather:falco-instance:3.0.0")
+    implementation("net.onelitefeather:falco-migration:3.0.0")
 }
 ```
 
diff --git a/docs/reference/benchmark-catalogue.md b/docs/reference/benchmark-catalogue.md
index 1fdd4a1..2b73a01 100644
--- a/docs/reference/benchmark-catalogue.md
+++ b/docs/reference/benchmark-catalogue.md
@@ -47,6 +47,7 @@ would land inside the `codec` stage and hide the very thing the benchmark isolat
 | [`ChunkLightPropagatorBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/light/ChunkLightPropagatorBenchmark.java) `.propagate` `.propagateSky` | library | `sectionCount` 4, 16, 24 × `lightSourcesPerSection` 1, 8 | The same search across section borders, over a flat map (4), a shallow world (16) and a full-height overworld (24). Both searches are measured because the engine runs both per chunk and they behave very differently: block light is bounded by the amount of emitting blocks, sky light seeds nearly every block of an open column. |
 | [`AreaVsPerChunkBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/light/AreaVsPerChunkBenchmark.java) `.area` `.perChunk` | decision | `chunkCount` 1, 4, 9, 16 | Whether area forming earns its complexity: an area of *n* chunks against *n* separate `calculateWithNeighbours` calls. Written as a decision rather than a report — had it not held, the simpler per-chunk design was the better one and area forming was to be dropped rather than tuned. The `chunkCount = 1` row is the control: a lone chunk has no loaded neighbours, so neither side has a ring to read and the two must come out level. |
 | [`IncrementalVsFullBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/light/IncrementalVsFullBenchmark.java) `.incremental` `.full` | decision | `sky` false, true | Whether replaying a changed position earns the memory the kept light costs. Both sides toggle the same block, compute the same nine chunks plus the same ring and write into the same sections; only the origin of a chunk's light differs. The block is *toggled* rather than placed, so both directions of an incremental update are measured — adding brightness and taking it back — and the world alternates between two states instead of drifting. `sky` is a parameter because a tick pays for both kinds and they gain very differently. |
+| [`AreaPassStageBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/light/AreaPassStageBenchmark.java) `.wholePass` `.opacityTablesOnly` | decision | `chunkCount` 1, 4, 16 | How much of an area pass is spent building opacity tables rather than propagating light. The ratio of the two methods is the share a perfectly effective table cache could remove, an upper bound. It loads and fills the ring around the area, which `AreaVsPerChunkBenchmark` leaves out, because the ring is read once per pass and is the part a table cache would pay for. |
 
 Both propagators keep their working buffers between runs, so the benchmarks reuse one instance for
 the whole trial and warm the buffers in `@Setup`. A fresh instance per invocation would measure two
@@ -54,11 +55,24 @@ array allocations instead of the search. The residual cost is that the measured
 growing a buffer, which is realistic for a running server and not for the first chunk after startup.
 
 The last two start a server, unlike everything else in this table, because an area and a scheduler
-pass are defined over real chunks of a real instance. They are also the only two classes in the
-harness that set no heap flags, so their numbers rest on a default, unrecorded heap configuration.
+pass are defined over real chunks of a real instance. They are two of the three classes in the
+harness that set no heap flags; the third, `ChunkLookupBenchmark`, has no `@Fork` annotation at all
+([Instance](#instance)). Their numbers rest on a default, unrecorded heap configuration.
 `ChunkLightService` has no benchmark of its own; what it costs is covered by those two and by the
 comparison benchmarks below.
 
+### Instance
+
+| Benchmark | Kind | Parameters | What it answers |
+| --- | --- | --- | --- |
+| [`ChunkComparisonBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkComparisonBenchmark.java) `.minestomSetBlock` `.falcoSetBlock` `.minestomGetBlock` `.falcoGetBlock` `.minestomCopy` `.falcoCopy` `.minestomCopyIsolated` `.falcoCopyIsolated` `.minestomHeightmapRefresh` `.falcoHeightmapRefresh` | control | `distinctStates` 1, 2, 16, 64, 256, 1024 × `fillShape` UNIFORM, LAYERED, RANDOM_RUNS | Falco's chunk against Minestom's chunk on `setBlock`, `getBlock`, `copy` and the full heightmap refresh. The expected answer is that the two are indistinguishable, which makes it the control that shows whether the harness is biased before any other chunk number is read. Starts a server. |
+| [`ChunkLookupBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java) `.boxedLookup` `.primitiveLookup` `.boxedLoadAndUnload` `.primitiveLoadAndUnload` | library | `positions` 289, 1089, 4096 | The boxed chunk index (`Map<Long, Object>`) against the primitive `Long2ObjectSyncMap`, on lookup and on load and unload. Both directions are measured on purpose: the lookup is what the change is for, and the write is where the primitive map is expected to cost more. The boxed arm's allocation includes `HashMap` treeification, not only the box. |
+| [`ChunkResendCostBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkResendCostBenchmark.java) `.buildOneChunkPacket` `.serializeOneChunkPacket` `.buildAndSerializeOneChunkPacket` `.resendViewDistance10` | decision | `content` EMPTY, UNIFORM, TERRAIN, DENSE | What a full chunk resend at view distance 10 costs in time, bytes on the wire and allocated heap. It is the number behind the `SharedInstance` question: whether a player changing instance has to resend chunks that are already on the client. |
+| [`GeneratorCommitBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java) `.commitPlain` `.commitOptimized` `.commitGuarded` `.packAlreadyPacked` `.optimizeAlreadyPacked` | library | `distinctStates` 1, 64, 1024 | What `Palette#optimize(Optimization.SIZE)` costs on the palettes of a chunk a generator has just filled, measured next to the copy it follows rather than on its own. The byte side is stated in the class javadoc from an earlier measurement and is not measured again here. |
+| [`LazySectionBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/LazySectionBenchmark.java) `.readEmptyEager` `.readEmptyLazy` `.readFullEager` `.readFullLazy` `.steadyWriteEager` `.steadyWriteLazy` `.firstWriteLazy` `.buildSectionsMinestom` `.buildSectionsEager` `.buildSectionsLazy` | decision | `emptyPercent` 0, 62, 90 | What a chunk pays for twenty-four eagerly allocated sections against one shared empty section that is materialised only when something is written into it. Reads, steady writes, the first write and building are measured separately, because the lazy layout is only worth it where the saving outweighs the first-write cost. |
+| [`PaletteIndirectGetBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/PaletteIndirectGetBenchmark.java) `.minestomGet` `.arrayGet` `.minestomReverseLookup` `.arrayReverseLookup` `.fastutilIndexGrowth` `.arrayIndexGrowth` | library | `paletteSize` 16, 32, 64, 128, 192, 256 | The indirect read path of Minestom's block palette at the widths between 5 and 8 bits, its reverse lookup and the growth of the palette, each against a plain array structure. Minestom's own palette benchmarks do not cover these three. |
+| [`SectionAllocationBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SectionAllocationBenchmark.java) `.minestomDynamicChunk` `.eagerReplicaLight` `.packedFlagLight` `.sharedUnlitLight` `.sharedAirSection` | library | – | What constructing one chunk costs, split into its sections, the palettes inside them and the light carriers hanging off them, before a single block is written. A fresh Minestom overworld chunk allocates 24 sections, 48 palettes, 48 light carriers and 48 `AtomicBoolean`s. |
+| [`SetBlockContentionBenchmark`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SetBlockContentionBenchmark.java) `.minestom` `.falco` | library | `scenario` DISJOINT_CHUNKS, SAME_CHUNK, DISJOINT_CHUNKS_WITH_HANDLER | Block writes per second that `InstanceContainer` and `FalcoInstance` accept while several threads write at once. The one difference this module can defend with a number is Minestom's instance-wide monitor in `UNSAFE_setBlock`, which the scenarios expose by separating writes to disjoint chunks from writes to one chunk. Starts a server. |
 ### Against the implementations Minestom ships with
 
 These are the ones that answer "is this actually better", and they are the reason the
@@ -128,8 +142,8 @@ code change to recover.
 | --- | --- | --- |
 | [`me.champeau.jmh`](https://github.com/melix/jmh-gradle-plugin) | `0.7.3` | Latest release. Gives the benchmarks their own source set so JMH never lands on the main or test classpath of a published library. |
 | `org.openjdk.jmh:jmh-core` | `1.37` | Latest release. **Not managed by `mycelium-bom`** — the BOM covers adventure, minestom, cyano, junit and mockito only — so both versions are pinned explicitly in `settings.gradle.kts`. |
-| `net.kyori:adventure-bom` | `5.1.1` | The main source set gets adventure through `compileOnly(minestom)`, which never reaches a runtime classpath. The benchmarks run their code for real and need adventure at runtime, so they import the platform directly. **Keep this in sync with the version Minestom resolves to** — check with `./gradlew dependencyInsight --configuration compileClasspath --dependency adventure-nbt`. |
-| `net.minestom:minestom` | not pinned here | Declared `withoutVersion()` and resolved through `mycelium-bom` `1.7.2`. The published comparisons were measured against `2026.06.20-26.1.2`; a republication of the BOM moves the Minestom side without any commit in this repository. |
+| `net.kyori:adventure-bom` | `5.2.0` | The main source set gets adventure through `compileOnly(minestom)`, which never reaches a runtime classpath. The benchmarks run their code for real and need adventure at runtime, so they import the platform directly. **Keep this in sync with the version Minestom resolves to** — check with `./gradlew dependencyInsight --configuration compileClasspath --dependency adventure-nbt`. |
+| `net.minestom:minestom` | not pinned here | Declared `withoutVersion()` and resolved through `mycelium-bom` `1.8.7`, which resolves `2026.09.12-26.2`. The published comparisons were measured against `2026.06.20-26.1.2`, not against that version; a republication of the BOM moves the Minestom side without any commit in this repository. |
 
 The plugin generates the harness classes with its bytecode generator. No `jmhAnnotationProcessor` is
 declared on purpose: with both present, the two generators emit the same classes and the jar ends up
diff --git a/docs/reference/exceptions-and-faults.md b/docs/reference/exceptions-and-faults.md
index b078905..0187ca5 100644
--- a/docs/reference/exceptions-and-faults.md
+++ b/docs/reference/exceptions-and-faults.md
@@ -6,9 +6,9 @@ caller can catch.
 > **This page is a generation target, currently written by hand, and it is incomplete.**
 > Source of truth: the exception types in
 > [`net.onelitefeather.falco.anvil`](https://github.com/OneLiteFeatherNET/Falco/tree/main/falco-anvil/src/main/java/net/onelitefeather/falco/anvil).
-> `RegionFormatException.Reason` declares five constants and `ChunkDataException.Reason` six; only
-> the two named below are recorded in this documentation. Read the enums for the full set until the generator
-> lands.
+> `RegionFormatException.Reason` declares five constants and `ChunkDataException.Reason` seven. The
+> seven `ChunkDataException.Reason` constants are recorded below; the five `RegionFormatException.Reason`
+> constants are not. Read the enums for the full set until the generator lands.
 
 ## Types
 
@@ -51,7 +51,7 @@ sectors, unsupported compression scheme.
 | --- | --- |
 | Kind | checked, final |
 | Extends | `AnvilFormatException` |
-| Reasons | six constants on `ChunkDataException.Reason` |
+| Reasons | seven constants on `ChunkDataException.Reason` |
 | Source | [`ChunkDataException`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-anvil/src/main/java/net/onelitefeather/falco/anvil/ChunkDataException.java) |
 
 Broken chunk NBT: missing key, wrong type, empty palette, palette index out of range.
@@ -84,6 +84,11 @@ format is defined.
 | --- | --- | --- |
 | `UNSUPPORTED_CHUNK_VERSION` | `ChunkDataException.Reason` | The chunk is below the version floor, or carries the pre-`21w43a` `Level` layout. |
 | `MISSING_OR_MISTYPED_KEY` | `ChunkDataException.Reason` | A key the caller requires is absent or holds the wrong tag type — including a chunk claiming `Status: minecraft:full` while carrying neither `sections` nor `Level`. |
+| `EMPTY_PALETTE` | `ChunkDataException.Reason` | A palette container holds no entry, so no block state can be resolved from it. |
+| `PALETTE_DATA_NOT_LONG_ARRAY` | `ChunkDataException.Reason` | The packed data of a palette container is not the long array the format requires. |
+| `PACKED_LENGTH_MISMATCH` | `ChunkDataException.Reason` | The packed data holds a number of longs that fits no bit count for the entry count. |
+| `PALETTE_INDEX_OUT_OF_RANGE` | `ChunkDataException.Reason` | A packed index addresses an entry the palette does not hold. |
+| `UNEXPECTED_LIST_ELEMENT_TYPE` | `ChunkDataException.Reason` | A list holds elements of a type other than the one the key requires. |
 
 ## What each entry point does on failure
 
diff --git a/docs/reference/logging.md b/docs/reference/logging.md
index 5f70612..afd7e89 100644
--- a/docs/reference/logging.md
+++ b/docs/reference/logging.md
@@ -32,7 +32,7 @@ Example: `Failed to load the chunk chunk=[{},{}] region={} dim={}`.
 
 | Level | Emitted for |
 | --- | --- |
-| `INFO` | Loader opening; a close with no errors. |
+| `INFO` | Loader opening; a close with no errors; a region file copied to the migration backup directory before its chunks are migrated (`Copied {} to {} before migrating its chunks on disk`, [`FalcoAnvilLoader.java:2203`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-anvil/src/main/java/net/onelitefeather/falco/anvil/FalcoAnvilLoader.java)). |
 | `WARN` | A throttled data problem; a close with errors; the skip breakdown. |
 | `ERROR` | A failed chunk load; a failed chunk save; a failed group in `saveChunks`; a region file that could not be closed. |
 | `DEBUG` | A region file opened or closed; the first chunk found with no region file or no entry in one. |
diff --git a/docs/reference/measured-results.md b/docs/reference/measured-results.md
index 2787fd5..e4f5dcb 100644
--- a/docs/reference/measured-results.md
+++ b/docs/reference/measured-results.md
@@ -95,9 +95,9 @@ load on a machine that was not idle is also a live candidate explanation for the
 here, which are all in
 [the loader contention table](#the-region-file-against-the-one-minestom-ships-with).
 
-**One heap gap worth naming.** Every benchmark class pins `-Xms` equal to `-Xmx` in `jvmArgsAppend`
-except `AreaVsPerChunkBenchmark` and `IncrementalVsFullBenchmark`, which set no heap flags at all.
-Those two are also the two that build a world of real Minestom chunks, so they have the largest live
+**One heap gap worth naming.** Every benchmark class with a `@Fork` annotation pins `-Xms` equal to `-Xmx` in `jvmArgsAppend`
+except `AreaVsPerChunkBenchmark` and `IncrementalVsFullBenchmark`, which set no heap flags at all, and
+`ChunkLookupBenchmark`, which has no `@Fork` annotation. The first two are also the ones that build a world of real Minestom chunks, so they have the largest live
 set and the most garbage-collector sensitivity in the suite. Their numbers rest on a default,
 unrecorded heap configuration.
 
diff --git a/docs/reference/modules-and-coordinates.md b/docs/reference/modules-and-coordinates.md
index c73e23d..dbfcb98 100644
--- a/docs/reference/modules-and-coordinates.md
+++ b/docs/reference/modules-and-coordinates.md
@@ -6,8 +6,9 @@ Every published artefact, its coordinate, the repository that serves it and its
 > Source of truth: the `maven-publish` configuration and the version catalog in the
 > [Falco repository](https://github.com/OneLiteFeatherNET/Falco). Until the generator lands, the
 > version numbers below can go stale — Renovate keeps the snippets in the
-> [repository README](https://github.com/OneLiteFeatherNET/Falco#readme) current and cannot reach these
-> docs, so **where this page and the README disagree, the README is right**. The authoritative list
+> [repository README](https://github.com/OneLiteFeatherNET/Falco#readme) current (its custom manager in
+> [`renovate.json`](https://github.com/OneLiteFeatherNET/Falco/blob/main/renovate.json) matches only `README.md`)
+> and does not update these pages, so **where this page and the README disagree, the README is right**. The authoritative list
 > of published versions is [Releases](https://github.com/OneLiteFeatherNET/Falco/releases).
 
 ## Repositories
@@ -27,7 +28,7 @@ Consuming Falco needs no credentials. Only building Falco itself does — see
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `2.1.0` |
+| Current version | `3.0.0` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-anvil/latest) |
 
@@ -38,7 +39,7 @@ An Anvil region-file chunk loader for Minestom.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `2.1.0` |
+| Current version | `3.0.0` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-light/latest) |
 
@@ -49,7 +50,7 @@ A block- and sky-light engine for Minestom.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `2.1.0` |
+| Current version | `3.0.0` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-instance/latest) |
 
@@ -61,7 +62,7 @@ sections on demand.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `2.1.0` |
+| Current version | `3.0.0` |
 | Since | `2.0.0` |
 | Javadoc | not yet rendered at a stable address |
 
@@ -73,12 +74,15 @@ Lifts a world older than the running server to it. Needed only when loading such
 | | |
 | --- | --- |
 | Kind | `java-platform` |
-| Current version | `2.1.0` |
+| Current version | `3.0.0` |
 | Since | `1.0.0` |
 | Javadoc | none — the artefact carries no classes |
 
-Carries one version constraint for each of the four modules above, so a build states the version
-once. A platform constrains versions; it does not pull in a module that was not declared.
+Carries one version constraint for each of the three modules `falco-anvil`, `falco-light` and
+`falco-instance` ([`falco-bom/build.gradle.kts`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-bom/build.gradle.kts)),
+so a build states the version once for those. `falco-migration` is published but is not in the BOM,
+so its version is stated on its own dependency line. A platform constrains versions; it does not pull
+in a module that was not declared.
 
 `falco-bom` was added after `0.3.0` was cut, so releases before `1.0.0` do not serve it.
 
@@ -102,7 +106,9 @@ snapshot endpoint serves `1.0.1-SNAPSHOT`. That version keeps moving as commits
 
 ## Dependencies Falco does not bring
 
-Minestom, fastutil and adventure-nbt are `compileOnly` in every module and do not arrive with these
-artefacts. A consumer declares its own Minestom version; Falco declares none.
+Minestom is `compileOnly` in `falco-anvil`, `falco-light` and `falco-instance`; `falco-migration` and
+`falco-bom` declare no Minestom dependency at all. fastutil and flare-fastutil are `compileOnly` in
+`falco-instance` only. None of these arrive with the artefacts. A consumer declares its own Minestom
+version; Falco declares none.
 
 Related: [How-to Add Falco to your build](../how-to/add-falco-to-your-build.md) · [Explanation Why a second Anvil loader](../explanation/why-a-second-anvil-loader.md)
diff --git a/docs/reference/supported-versions.md b/docs/reference/supported-versions.md
index 9aa6265..770bb59 100644
--- a/docs/reference/supported-versions.md
+++ b/docs/reference/supported-versions.md
@@ -12,7 +12,7 @@ The versions Falco is built against, the versions it accepts, and the floors it
 | | Value | Note |
 | --- | --- | --- |
 | Java | 25 | required to build Falco and to run it |
-| Minestom | `2026.06.20-26.1.2` | the version every claim in this documentation was checked against; `compileOnly`, so a consumer picks its own |
+| Minestom | `2026.09.12-26.2` | resolved through `net.onelitefeather:mycelium-bom` `1.8.7` (`settings.gradle.kts`, `mycelium-bom` `version("bom", "1.8.7")`); `compileOnly`, so a consumer picks its own |
 
 ## Chunk data version floor
 
@@ -26,7 +26,7 @@ The versions Falco is built against, the versions it accepts, and the floors it
 | Enforced by | `ChunkVersionPolicy`, by default `DefaultChunkVersionPolicy` |
 
 `21w43a` is where a chunk's data moved out of the `Level` compound onto the root compound, under the
-key `sections` ([`FalcoAnvilLoader.SECTIONS_KEY`](https://github.com/OneLiteFeatherNET/Falco/blob/main/falco-anvil/src/main/java/net/onelitefeather/falco/anvil/FalcoAnvilLoader.java)).
+key `sections` (`FalcoAnvilLoader.SECTIONS_KEY`, a `private` constant, so it is not linkable).
 
 ### What the guard does with each case
 
diff --git a/docs/tutorials/load-your-first-world-with-falco.md b/docs/tutorials/load-your-first-world-with-falco.md
index cc2e3f0..1f04eea 100644
--- a/docs/tutorials/load-your-first-world-with-falco.md
+++ b/docs/tutorials/load-your-first-world-with-falco.md
@@ -17,11 +17,11 @@ This takes about fifteen minutes.
    }
 
    dependencies {
-       implementation(platform("net.onelitefeather:falco-bom:2.1.0"))
+       implementation(platform("net.onelitefeather:falco-bom:3.0.0"))
        implementation("net.onelitefeather:falco-anvil")
        implementation("net.onelitefeather:falco-light")
 
-       implementation("net.minestom:minestom:2026.06.20-26.1.2")
+       implementation("net.minestom:minestom:2026.09.12-26.2")
    }
    ```
 

From 92ca65890b4d841a462c5d724591e466cc6f961b Mon Sep 17 00:00:00 2001
From: TheMeinerLP <github@themeinerlp.dev>
Date: Sat, 10 Oct 2026 20:44:25 +0200
Subject: [PATCH 2/2] docs: bring versions in line with the 3.0.1 release

Falco 3.0.1 (build.gradle.kts, .release-please-manifest.json), mycelium-bom
1.8.9 (settings.gradle.kts) and the Minestom it resolves to, 2026.10.07-26.2
(dependencyInsight on falco-anvil compileClasspath). Historical measurement
statements keep their versions.

Claude-Session: https://claude.ai/code/session_01Q6AxU7jRLmNPHdwg2GpasT
---
 docs/contributing/README.md                        |  8 ++++----
 docs/contributing/dependency-management.md         |  6 +++---
 docs/contributing/documentation-conventions.md     |  6 +++---
 docs/how-to/add-falco-to-your-build.md             | 12 ++++++------
 docs/reference/benchmark-catalogue.md              |  2 +-
 docs/reference/modules-and-coordinates.md          | 10 +++++-----
 docs/reference/supported-versions.md               |  2 +-
 docs/tutorials/load-your-first-world-with-falco.md |  4 ++--
 8 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/docs/contributing/README.md b/docs/contributing/README.md
index 475c4cc..961cd10 100644
--- a/docs/contributing/README.md
+++ b/docs/contributing/README.md
@@ -36,10 +36,10 @@ a republication of the BOM without a single commit in this repository.
 | | | Pinned here |
 | --- | --- | --- |
 | Java | 25 (toolchain and `release`), no `--enable-preview` anywhere | yes, in the root `build.gradle.kts` |
-| Minestom | `2026.09.12-26.2`, `compileOnly` | **no** — `library("minestom", …).withoutVersion()`, resolved through `net.onelitefeather:mycelium-bom` `1.8.7` |
+| Minestom | `2026.10.07-26.2`, `compileOnly` | **no** — `library("minestom", …).withoutVersion()`, resolved through `net.onelitefeather:mycelium-bom` `1.8.9` |
 | Adventure | `5.2.0`, `adventure-nbt` used directly — Minestom speaks `CompoundBinaryTag` natively, so there is no conversion layer | yes, `adventure-bom` `5.2.0` |
 | Annotations | `org.jetbrains:annotations:26.1.0` | yes |
-| Tests | JUnit 6.1.3, Cyano `0.7.6` (`MicrotusExtension`) for anything needing a server | **no** — both `withoutVersion()`, resolved through `mycelium-bom` `1.8.7` |
+| Tests | JUnit 6.1.3, Cyano `0.7.6` (`MicrotusExtension`) for anything needing a server | **no** — both `withoutVersion()`, resolved through `mycelium-bom` `1.8.9` |
 | Benchmarks | JMH 1.37 via `me.champeau.jmh` 0.7.3, in the separate `falco-benchmarks` module | yes, both |
 | `fastutil` | `8.5.19` | yes |
 | Architecture | ArchUnit 1.5.1, in the separate `falco-archunit` module | yes |
@@ -53,8 +53,8 @@ for `falco-anvil`, `falco-light` and `falco-instance`, and `falco-benchmarks`, `
 
 **The Minestom version is the one that would invalidate a comparison silently.** Every head-to-head
 table under [Measured](../reference/measured-results.md#measured) measures the Minestom of the day the run happened,
-and that version is decided by `mycelium-bom` `1.8.7`, not by anything in this repository.
-`2026.09.12-26.2` is what it resolves to today; a third party reproducing a number has to check that
+and that version is decided by `mycelium-bom` `1.8.9`, not by anything in this repository.
+`2026.10.07-26.2` is what it resolves to today; a third party reproducing a number has to check that
 theirs resolves to the same thing before comparing.
 
 `adventure-nbt`, `jetbrains-annotations` and `fastutil` are declared explicitly rather than taken
diff --git a/docs/contributing/dependency-management.md b/docs/contributing/dependency-management.md
index 470d5b5..d271dbf 100644
--- a/docs/contributing/dependency-management.md
+++ b/docs/contributing/dependency-management.md
@@ -68,7 +68,7 @@ itself. Where a version is stated below it is the one the catalog declares today
   which is `compileOnly` and therefore never reaches a runtime classpath (see below). The benchmarks
   module runs its code for real and needs Adventure at runtime, so it imports the Adventure platform
   directly. The value is meant to match what Minestom pulls in. It matched `net.minestom:minestom:2026.06.20-26.1.2`,
-  which declares `net.kyori:adventure-nbt` at `5.1.1`; whether `2026.09.12-26.2` declares the same
+  which declares `net.kyori:adventure-nbt` at `5.1.1`; whether the version resolved today declares the same
   version was not re-checked for this page. Nothing in the build asserts that the two agree, so a
   Minestom upgrade that moves Adventure has to be followed here by hand.
 - **`slf4j.simple`.** Only `falco-demo` needs an SLF4J binding, and it takes it as `runtimeOnly`. The
@@ -80,13 +80,13 @@ itself. Where a version is stated below it is the one the catalog declares today
   compiles against fastutil types, and `falco-light`'s equivalence test and the comparison benchmarks
   call Minestom methods that take a fastutil collection, so the dependency has to be named
   explicitly — and naming it means pinning it. The value is meant to match the version Minestom
-  declares: `8.5.18` was the match for `2026.06.20-26.1.2`, and `2026.09.12-26.2` was not re-checked.
+  declares: `8.5.18` was the match for `2026.06.20-26.1.2`, and the version resolved today was not re-checked.
 
 Six entries are declared with `withoutVersion()` — `minestom`, `adventure.nbt`, `cyano` and the
 three JUnit coordinates. Their versions come from a platform at use site: the mycelium BOM for
 Minestom, Cyano and JUnit, and Minestom's own dependency graph for `adventure-nbt`. The consequence
 worth knowing is that **no Minestom version string appears anywhere in this repository**: it is
-whatever `net.onelitefeather:mycelium-bom:1.8.7` manages, which today is `2026.09.12-26.2`. What
+whatever `net.onelitefeather:mycelium-bom:1.8.9` manages, which today is `2026.10.07-26.2`. What
 that costs is traceability — an upgrade to the mycelium BOM moves Minestom, and therefore moves the
 Minestom side of every comparison this project publishes, through a diff that mentions only a BOM
 version. Anyone reproducing a measured result therefore needs the Minestom version stated alongside
diff --git a/docs/contributing/documentation-conventions.md b/docs/contributing/documentation-conventions.md
index f840ffa..4b9a02a 100644
--- a/docs/contributing/documentation-conventions.md
+++ b/docs/contributing/documentation-conventions.md
@@ -50,10 +50,10 @@ limit in its own provenance line rather than in a page footer, because a disclai
 something only where the number is.
 
 **Claims about somebody else's code carry a revision.** Minestom is read from the sources jar of
-`net.minestom:minestom:2026.09.12-26.2`, which is the version this repository compiles against —
+`net.minestom:minestom:2026.10.07-26.2`, which is the version this repository compiles against —
 `settings.gradle.kts` declares `minestom` `withoutVersion()` and takes the version from
-`net.onelitefeather:mycelium-bom:1.8.7`, whose `dependencyManagement` pins exactly
-`2026.09.12-26.2`. That is a resolved version and not a pinned one: republishing the BOM changes
+`net.onelitefeather:mycelium-bom:1.8.9`, whose `dependencyManagement` pins exactly
+`2026.10.07-26.2`. That is a resolved version and not a pinned one: republishing the BOM changes
 the Minestom side of every comparison without any commit here. Each such claim names the file, the
 line and the member, so it can be checked in a minute and so it reads as analysis of a specific
 revision rather than as a verdict on another project. The same rule governs Starlight and Phosphor
diff --git a/docs/how-to/add-falco-to-your-build.md b/docs/how-to/add-falco-to-your-build.md
index 8a351d9..94d237a 100644
--- a/docs/how-to/add-falco-to-your-build.md
+++ b/docs/how-to/add-falco-to-your-build.md
@@ -21,12 +21,12 @@ snapshot endpoints are both public.
 
    ```kotlin
    dependencies {
-       implementation(platform("net.onelitefeather:falco-bom:3.0.0"))
+       implementation(platform("net.onelitefeather:falco-bom:3.0.1"))
 
        implementation("net.onelitefeather:falco-anvil")
        implementation("net.onelitefeather:falco-light")
        implementation("net.onelitefeather:falco-instance")
-       implementation("net.onelitefeather:falco-migration:3.0.0") // not in the BOM, so it takes its version here
+       implementation("net.onelitefeather:falco-migration:3.0.1") // not in the BOM, so it takes its version here
    }
    ```
 
@@ -48,10 +48,10 @@ Version each module individually instead of step 2:
 
 ```kotlin
 dependencies {
-    implementation("net.onelitefeather:falco-anvil:3.0.0")
-    implementation("net.onelitefeather:falco-light:3.0.0")
-    implementation("net.onelitefeather:falco-instance:3.0.0")
-    implementation("net.onelitefeather:falco-migration:3.0.0")
+    implementation("net.onelitefeather:falco-anvil:3.0.1")
+    implementation("net.onelitefeather:falco-light:3.0.1")
+    implementation("net.onelitefeather:falco-instance:3.0.1")
+    implementation("net.onelitefeather:falco-migration:3.0.1")
 }
 ```
 
diff --git a/docs/reference/benchmark-catalogue.md b/docs/reference/benchmark-catalogue.md
index 2b73a01..cb2f000 100644
--- a/docs/reference/benchmark-catalogue.md
+++ b/docs/reference/benchmark-catalogue.md
@@ -143,7 +143,7 @@ code change to recover.
 | [`me.champeau.jmh`](https://github.com/melix/jmh-gradle-plugin) | `0.7.3` | Latest release. Gives the benchmarks their own source set so JMH never lands on the main or test classpath of a published library. |
 | `org.openjdk.jmh:jmh-core` | `1.37` | Latest release. **Not managed by `mycelium-bom`** — the BOM covers adventure, minestom, cyano, junit and mockito only — so both versions are pinned explicitly in `settings.gradle.kts`. |
 | `net.kyori:adventure-bom` | `5.2.0` | The main source set gets adventure through `compileOnly(minestom)`, which never reaches a runtime classpath. The benchmarks run their code for real and need adventure at runtime, so they import the platform directly. **Keep this in sync with the version Minestom resolves to** — check with `./gradlew dependencyInsight --configuration compileClasspath --dependency adventure-nbt`. |
-| `net.minestom:minestom` | not pinned here | Declared `withoutVersion()` and resolved through `mycelium-bom` `1.8.7`, which resolves `2026.09.12-26.2`. The published comparisons were measured against `2026.06.20-26.1.2`, not against that version; a republication of the BOM moves the Minestom side without any commit in this repository. |
+| `net.minestom:minestom` | not pinned here | Declared `withoutVersion()` and resolved through `mycelium-bom` `1.8.9`, which resolves `2026.10.07-26.2`. The published comparisons were measured against `2026.06.20-26.1.2`, not against that version; a republication of the BOM moves the Minestom side without any commit in this repository. |
 
 The plugin generates the harness classes with its bytecode generator. No `jmhAnnotationProcessor` is
 declared on purpose: with both present, the two generators emit the same classes and the jar ends up
diff --git a/docs/reference/modules-and-coordinates.md b/docs/reference/modules-and-coordinates.md
index dbfcb98..c219d06 100644
--- a/docs/reference/modules-and-coordinates.md
+++ b/docs/reference/modules-and-coordinates.md
@@ -28,7 +28,7 @@ Consuming Falco needs no credentials. Only building Falco itself does — see
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `3.0.0` |
+| Current version | `3.0.1` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-anvil/latest) |
 
@@ -39,7 +39,7 @@ An Anvil region-file chunk loader for Minestom.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `3.0.0` |
+| Current version | `3.0.1` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-light/latest) |
 
@@ -50,7 +50,7 @@ A block- and sky-light engine for Minestom.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `3.0.0` |
+| Current version | `3.0.1` |
 | Since | `0.1.0` |
 | Javadoc | [latest release](https://repo.onelitefeather.dev/javadoc/releases/net/onelitefeather/falco-instance/latest) |
 
@@ -62,7 +62,7 @@ sections on demand.
 | | |
 | --- | --- |
 | Kind | `java-library` |
-| Current version | `3.0.0` |
+| Current version | `3.0.1` |
 | Since | `2.0.0` |
 | Javadoc | not yet rendered at a stable address |
 
@@ -74,7 +74,7 @@ Lifts a world older than the running server to it. Needed only when loading such
 | | |
 | --- | --- |
 | Kind | `java-platform` |
-| Current version | `3.0.0` |
+| Current version | `3.0.1` |
 | Since | `1.0.0` |
 | Javadoc | none — the artefact carries no classes |
 
diff --git a/docs/reference/supported-versions.md b/docs/reference/supported-versions.md
index 770bb59..4211a08 100644
--- a/docs/reference/supported-versions.md
+++ b/docs/reference/supported-versions.md
@@ -12,7 +12,7 @@ The versions Falco is built against, the versions it accepts, and the floors it
 | | Value | Note |
 | --- | --- | --- |
 | Java | 25 | required to build Falco and to run it |
-| Minestom | `2026.09.12-26.2` | resolved through `net.onelitefeather:mycelium-bom` `1.8.7` (`settings.gradle.kts`, `mycelium-bom` `version("bom", "1.8.7")`); `compileOnly`, so a consumer picks its own |
+| Minestom | `2026.10.07-26.2` | resolved through `net.onelitefeather:mycelium-bom` `1.8.9` (`settings.gradle.kts`, `mycelium-bom` `version("bom", "1.8.9")`); `compileOnly`, so a consumer picks its own |
 
 ## Chunk data version floor
 
diff --git a/docs/tutorials/load-your-first-world-with-falco.md b/docs/tutorials/load-your-first-world-with-falco.md
index 1f04eea..5fa616d 100644
--- a/docs/tutorials/load-your-first-world-with-falco.md
+++ b/docs/tutorials/load-your-first-world-with-falco.md
@@ -17,11 +17,11 @@ This takes about fifteen minutes.
    }
 
    dependencies {
-       implementation(platform("net.onelitefeather:falco-bom:3.0.0"))
+       implementation(platform("net.onelitefeather:falco-bom:3.0.1"))
        implementation("net.onelitefeather:falco-anvil")
        implementation("net.onelitefeather:falco-light")
 
-       implementation("net.minestom:minestom:2026.09.12-26.2")
+       implementation("net.minestom:minestom:2026.10.07-26.2")
    }
    ```