Bring the instance and chunk pages level with what shipped on 2026-08-03
falco-instance gained its own chunk storage, a facade split, a shared instance
and a lighting chunk that finally sits on the same class as the rest. The wiki
described the state before all four, and in three places it now said the
opposite of the code.
Corrected, each read against the source first:
- Project Status listed "FalcoInstance and FalcoLightingChunk are mutually
exclusive" under things that cannot be used together. That was the limitation
the whole rewrite existed to remove; FalcoLightingChunk extends FalcoChunk now
and the two run together. The section says what it was, what closed it, and
what it cost -- the class is final, which is a deliberate break of binary
compatibility recorded in gradle/api-breaks.properties.
- Rationale: Instances and Chunks explained "why the superclass is DynamicChunk"
and stated that FalcoChunk adds no storage because Minestom's was never the
part that needed replacing. Both were true of the first version. The section
now says what changed the answer, which was a measurement rather than an
opinion.
- Research: Shared Instances asserted FalcoChunk extends DynamicChunk in the
present tense and named two ways out of the batch light gap. It closed by
neither of them, and the paragraph says so.
- Four places across three pages said there is no instance benchmark in the
repository at all, one of them quoting the build file as proof. The build file
declares jmhImplementation(project(":falco-instance")) since 2026-08-03 and
four JMH classes exist. None has been run as a baseline, so the conclusion
those passages drew is unchanged and each now says which half is missing: the
instrument is there, the run is not.
New: a "Counted" section on Measured Results, kept apart from the timings
deliberately. Object counts have no spread and are unaffected by what else the
machine was doing, so they are the only figures on that page that survive being
taken on a busy machine -- 25 objects and 840 bytes against 192 and 6 848, the
62.24 % empty-section census, the materialisation counts per operation, and the
palette break-even. No timing figure was added anywhere, because the instance
suite has still never run.
Two open items added to Project Status: the unlocked tick map, which is
inherited from DynamicChunk rather than introduced, and the macOS hang that
leaves the counted figures proven on two platforms out of three.
Both page headers that claimed their page carries no measurement were corrected
too -- adding a number and leaving that sentence standing is how a page starts
lying about itself.
docs: split the working record into status, measurements and contributing
Project Status had grown to 1 783 lines and eighteen sections, from Environment
and Conventions through Measured to Defects and Open. A table of contents above
a page that holds three unrelated things does not make it one thing.
Measured Results now holds every measured table and all eleven provenance
lines. Contributing holds Environment, Working on this, Conventions and
Releasing and snapshots, and is what the repository's new CONTRIBUTING.md
points at. Project Status keeps what its name says: facts, decisions, what is
in the branch, defects, what is open.
The text moved word for word. Heading levels are unchanged, so every
subsection anchor still resolves — only the page in front of it differs. The
old file was checked paragraph by paragraph against the three new ones: 257 of
274 identical, the other 17 differing only in a redirected link or a rewrapped
line. ± appears 94 times before and 94 in the moved text, × 106 times in both.
No figure changed.
The split also broke eighteen sentences that no link checker can catch. They
carry no anchor — "the full tables are in Project Status", "the working
record: benchmark results with their conditions" — so they resolve perfectly
and say something that stopped being true. The worst of them was in
_Footer.md, which renders under all thirty pages. Every one of the twenty-eight
references to Project Status has since been read in context and either
redirected or confirmed.
The Gradle group folds to Build Setup, which already listed all six pages
behind it. Five more long pages gained a table of contents. Home no longer
opens with a greeting.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QzEdy5fN5JKGxJo8gwtNeu
docs: state every measured claim with its conditions and its limits
Reworks all 21 wiki pages so that no performance claim can be read as
saying more than the measurement supports.
The measurement model is now stated once and authoritatively: JMH's
score error is the half-width of a 99.9 % confidence interval over the
measurement iterations of a single fork, which bounds dispersion within
one JVM and says nothing about run-to-run variance. Every published
comparison was re-graded against a mechanical significance rule and is
labelled supported, indicative-only, or not usable. Ratios whose
intervals overlap no longer carry a factor.
The 8.00x loader figure is withdrawn. The two-thread 1.9x now carries
the independent repeat that did not reproduce it next to the number
rather than two pages away. What those repeats do establish - Falco's
read time repeats at every thread count and Minestom's does not repeat
above one - is stated as the asymmetry it is, not as a factor.
Each page separates what was measured from what is reasoned from the
code and what is judgement, cites the type or method behind every
structural claim, and carries threats-to-validity and reproduction
sections precise enough for a third party to attempt replication.
Environment facts that were never recorded are marked as gaps rather
than filled in.
No measured number was changed.
Add the instance performance research findings