feat(instance): a chunk that owns its storage, and an instance split along what it does - #39

Merged

TheMeinerLP merged 90 commits into

mainfrom

feat/block-storage

Aug 3, 2026

Commits on Aug 1, 2026

feat(bom): add falco-bom, a platform pinning the published modules

TheMeinerLP
and
claude
committed
8355d4f
docs: move the build script rationale to the wiki

TheMeinerLP
and
claude
committed
ca79507
docs(readme): tie every figure to its conditions and restructure the page

TheMeinerLP
and
claude
committed
0297d3c
docs(spec): design a chunk, an instance and a shared instance of Falco's own

TheMeinerLP
and
claude
committed
627e766
docs(plan): plan stage 1, the seam the later stages need

TheMeinerLP
and
claude
committed
3634a6c
test(benchmarks): measure the chunk, the palette and the instance against Minestom

TheMeinerLP
and
claude
committed
6ec6973
feat(instance): introduce BlockStorage, the implementation side of the chunk

TheMeinerLP
and
claude
committed
63d2960
feat(instance): store blocks in sections behind BlockStorage

TheMeinerLP
and
claude
committed
7c3d575
refactor(instance): hold block storage instead of inheriting it

TheMeinerLP
and
claude
committed
dc97ad2
test(instance): prove the bridge chunk agrees with DynamicChunk everywhere

TheMeinerLP
and
claude
committed
6c5a971
test(instance): run the bridge chunk inside a plain InstanceContainer

TheMeinerLP
and
claude
committed
56f180a
test(benchmarks): assert what the seam costs instead of assuming it is free

TheMeinerLP
and
claude
committed
125c870
fix(instance): restore the guards and the contract the storage seam dropped

TheMeinerLP
and
claude
committed
78b6a89
docs(benchmarks): correct what the control benchmark claims about the chunk

TheMeinerLP
and
claude
committed
cc02fef
docs(plan): name the run that carries US-1.03

TheMeinerLP
and
claude
committed
099a44d
docs(plan): plan stage 2, where the memory actually goes down

TheMeinerLP
and
claude
committed
d7f17b8
feat(instance): give the storage a read-only way to look at a section

TheMeinerLP
and
claude
committed
486a33c
docs(instance): raise the test class version the last change forgot

TheMeinerLP
and
claude
committed
30b0fa9
feat(instance): share one empty section instead of allocating twenty-four

TheMeinerLP
and
claude
committed
9b5a020
test(instance): make the shared-read case fail when the US-2.07 shortcut is gone

TheMeinerLP
and
claude
committed
dde0369
refactor(instance): read the chunk's own sections without creating them

TheMeinerLP
and
claude
committed
5b52fca
fix(benchmarks): say which storage the chunk comparison runs on, and test the scan it copies

TheMeinerLP
and
claude
committed
19c222a

Commits on Aug 2, 2026

fix(benchmarks): stop the equivalence check from materialising what it measures

TheMeinerLP
and
claude
committed
b60cf9d
test(instance): state what every boundary caller makes a lazy chunk allocate

TheMeinerLP
and
claude
committed
34eb462
test(benchmarks): price the palette optimisation against the commit it follows

TheMeinerLP
and
claude
committed
f790f0d
test(benchmarks): stage the commit fixture the way a generator leaves it

TheMeinerLP
and
claude
committed
88e71b3
test(benchmarks): make the fixture guard check the thing that can actually break

TheMeinerLP
and
claude
committed
ae73096
test(benchmarks): stage the commit fixture through setAll instead of re-enacting it

TheMeinerLP
and
claude
committed
de4d90e
feat(instance): commit only the sections a generator filled, and pack their palettes

TheMeinerLP
and
claude
committed
44e5b25
perf(instance): ask whether a palette can still be narrowed before narrowing it

TheMeinerLP
and
claude
committed
828c35c
test(instance): cover the two skip clauses no case reached, and name the condition on the four

TheMeinerLP
and
claude
committed
40da0e3
perf(instance): build a heightmap when something asks for one

TheMeinerLP
and
claude
committed
53a1550
docs(instance): say which chunk the heightmap share is a share of

TheMeinerLP
and
claude
committed
dc40710
test(instance): pin what ticking a chunk does before the second map goes

TheMeinerLP
and
claude
committed
556ac40
perf(instance): keep one block map and a counter instead of two maps

TheMeinerLP
and
claude
committed
bbcf44f
test(instance): make the tickable counter's arithmetic observable

TheMeinerLP
and
claude
committed
c82d4be
docs(benchmarks): correct the three places that still describe a second block map

TheMeinerLP
and
claude
committed
d56c3d0
test(benchmarks): declare what the lazy chunk no longer holds, class by class

TheMeinerLP
and
claude
committed
3c9b114
docs: hand the instance and chunk work over to a session that was not here

TheMeinerLP
and
claude
committed
083a5f8
docs(benchmarks): name the one defect the footprint comparison cannot see

TheMeinerLP
and
claude
committed
b1da4b4
docs(benchmarks): say which rows of the fresh table the plan got wrong

TheMeinerLP
and
claude
committed
7424422
test(benchmarks): compare the two chunks class by class instead of by one number

TheMeinerLP
and
claude
committed
c8b916f
docs(plan): record what stage 2 bought and what it did not

TheMeinerLP
and
claude
committed
9475066
docs: mark stage 2 done in the handoff

TheMeinerLP
and
claude
committed
de6e140
fix(instance): publish a materialised section with a compare and exchange

TheMeinerLP
and
claude
committed
a5ad29f
fix(instance): commit every palette before the first special block is written

TheMeinerLP
and
claude
committed
9b138e6
docs(instance): retire the footprint figures that tasks 7 and 8 superseded

TheMeinerLP
and
claude
committed
f9c1c8b
docs(plan): plan stage 3, the instance split and the listeners it enables

TheMeinerLP
and
claude
committed
79a8269
Merge branch 'main' into feat/block-storage

TheMeinerLP
and
claude
committed
ea77687
docs: record the tick race the merge surfaced and did not fix

TheMeinerLP
and
claude
committed
e25802f
test(instance): pin the block write paths before they move

TheMeinerLP
and
claude
committed
83276e5
test(instance): pin the save paths before they move

TheMeinerLP
and
claude
committed
b88db64
test(instance): name the break case after what it actually asserts

TheMeinerLP
and
claude
committed
758af91
test(instance): pin the placement rule branch of a block write

TheMeinerLP
and
claude
committed
07aa7f2
refactor(instance): give the chunk positions a registry of their own

TheMeinerLP
and
claude
committed
e561b83
refactor(instance): point FalcoInstance at the chunk registry

TheMeinerLP
and
claude
committed
74d585e
docs(instance): write down what a step inside the position lock may do

TheMeinerLP
and
claude
committed
93546e6
refactor(instance): give the chunk loader a part of its own

TheMeinerLP
and
claude
committed
874f2fd
refactor(instance): point FalcoInstance at the chunk persistence

TheMeinerLP
and
claude
committed
f352feb
refactor(instance): move the generator and its forks into ChunkGeneration

TheMeinerLP
and
claude
committed
200ec54
docs(instance): raise the version of the three classes whose references moved

TheMeinerLP
and
claude
committed
f91000f
refactor(instance): make publish and load completion reachable one at a time

TheMeinerLP
and
claude
committed
d67b8b2
docs(instance): name the class that actually hands in the two steps

TheMeinerLP
and
claude
committed
781e178
fix(instance): let the loader read an instance whose lifecycle already stands

TheMeinerLP
and
claude
committed
b7d4425
refactor(instance): give the block write path a class of its own

TheMeinerLP
and
claude
committed
7b03928
docs(instance): say how far the chunk write lock actually reaches

TheMeinerLP
and
claude
committed
d9cf73e
refactor(instance): make the instance a facade and assert that it stays one

TheMeinerLP
and
claude
committed
4476022
docs(instance): say what the facade actually promises, not what it nearly does

TheMeinerLP
and
claude
committed
f2f5906
feat(instance): let a chunk carry more than one lifecycle extension

TheMeinerLP
and
claude
committed
83825cc
docs(instance): name the two things a listener can be surprised by

TheMeinerLP
and
claude
committed
571d08c
fix(instance): give a loaded chunk the listener too, not only a generated one

TheMeinerLP
and
claude
committed
fa71013
fix(instance): give the viewer cache entry back when a chunk unloads

TheMeinerLP
and
claude
committed
0f0f48a
test(instance): tell a targeted release apart from a wipe

TheMeinerLP
and
claude
committed
4401cf2
feat(light): put the lifecycle and the light on one chunk instance

TheMeinerLP
and
claude
committed
8cbf4d2
docs(instance): stop pointing the lifecycle pair at the chunk that outgrew it

TheMeinerLP
and
claude
committed
5a0584e
docs: say what the second arm of the lifecycle costs a listener

TheMeinerLP
and
claude
committed
c288f84

Commits on Aug 3, 2026

perf(instance): look a chunk up without boxing its index

TheMeinerLP
and
claude
committed
66f4210
test(archunit): let the published modules see flare, and say why

TheMeinerLP
and
claude
committed
bf4b4e2
docs(plan): record what stage 3 measured

TheMeinerLP
and
claude
committed
dd4d0f7
docs(benchmarks): stop the lookup benchmark asserting a cost it then measured away

TheMeinerLP
and
claude
committed
6a37f9c
docs(instance): stop claiming a lookup takes no lock, and pin what it does

TheMeinerLP
and
claude
committed
721a18c
fix(instance): complete the load future when a lifecycle listener throws

TheMeinerLP
and
claude
committed
9ec302a
docs(instance): name the fourth piece of foreign code under the chunk write lock

TheMeinerLP
and
claude
committed
770301c
docs(plan): pull the stage 3 acceptance level with the closing review

TheMeinerLP
and
claude
committed
87ffd65
docs(plan): take the stage 3 gate at the commit the stage ends at

TheMeinerLP
and
claude
committed
50330be
docs(plan): say what the two broken runs actually showed, not more

TheMeinerLP
and
claude
committed
bfd9cc4
build(api)!: declare FalcoLightingChunk's break instead of hiding it

TheMeinerLP
and
claude
committed
96d2c6c
Merge remote-tracking branch 'origin/main' into feat/block-storage
TheMeinerLP
committed
54f373f
ci: skip the footprint tests on macOS, where they hang before the first test

TheMeinerLP
and
claude
committed
0710238
docs(handoff): bring the handoff level with four finished stages

TheMeinerLP
and
claude
committed
dbb213d