docs: restructure the wiki along Diátaxis
Seven pages carried all four modes at once. Anvil-Chunk-Loader opened with
status, ran through usage, architecture, a comparison, measured tables and
error handling in one file; Light-Engine, Benchmarking, Installation,
Instances-And-Chunks and World-Migration had the same shape. Every paragraph
was correct and no reader was ever in all four states at once.
The four quadrants are now separate pages, encoded in the title because that
is the only structure a wiki preserves: 1 tutorial, 10 how-tos, 9 reference
pages, 15 explanation pages. Project-Status and the Research pages stay
outside the four on purpose — they are the operational record, not
documentation of the software — and so does the build documentation.
Three things the split fixed rather than moved:
- There was no tutorial anywhere. Tutorial-Load-your-first-world-with-Falco
is the one guided path: empty Gradle project to a served world with light,
one path, no alternatives.
- Reference existed only as prose embedded in explanation. The nine pages now
carry generator banners naming the source in the code repository, so the
next step is a generator and a CI drift gate rather than proofreading.
Reference-Exceptions-and-faults says outright that it is incomplete: the
two Reason enums declare eleven constants and the wiki ever recorded two.
- The measured tables were published twice. The four charts lived only in
Benchmarking, their tables only in Measured-Results, and _Footer.md carried
a rule about which source wins — the symptom, not the cure. The charts now
sit with their tables on Reference-Measured-results and the duplicate block
is gone; every figure in it was verified present first. Same for the
reproduction command lines, which stood in two pages.
Prose was moved, not rewritten. What is not carried over is the intros and
tables of contents of the dissolved pages, and the duplicated headline
block. All 195 cross-page links, their anchors and their link texts were
rewritten to the new titles; nothing dangles.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
docs: the migration module, and the counts that had drifted
falco-migration arrived with #48 and #50 and had no page at all — it did not
appear anywhere in this wiki. World Migration is that page: the three modes,
the backup that cannot be switched off, why migration runs before the version
guard, and where the rules' version numbers come from.
Project Status: item 1 of Open resolved by #49, items 2 and 3 renumbered. The
entry is kept in full down to "What was built", the way the #34 entry is,
because its reproduction is what made the defect actionable — and because the
first attempt at fixing it answered too broadly and broke two tests that
assert versionPolicy(null) means the check does not run. That is recorded
rather than tidied away.
The counts in that page had drifted further than the migration module alone.
"What is in the branch" said 14 types for falco-anvil where the tree has 26,
3 for falco-instance where it has 16, and carried no row for falco-migration
or falco-archunit; "Where things live" listed types that predate several
merged pull requests. Every column is now re-derived at cbd74ccb from one
tree and one test run, which the previous table could not claim: its
executed-test counts came from a build whose commit was not recorded, and its
falco-demo cell carried no number because nothing reproduced it.
Architecture Rules said 39 rules in five classes; there are 48 in seven.
ForeignWritePathTest and MigrationBoundaryTest were missing entirely.
Both pages now state the same thing plainly: falco-migration sits outside
ModuleBoundaryTest's PUBLISHED set because it legitimately depends on
falco-anvil, and the other rules of that class therefore do not reach it. A
gap, not a decision.
Installation and Publishing carried three modules at 1.0.0; there are four at
2.1.0, and five artefacts with the BOM.
Anvil Chunk Loader: ChunkMigrator as the third service of that shape, the
truncated-chunk refusal from #49 under the version floor, and one sentence
that #50 made false — "nothing is converted or migrated" — corrected rather
than left standing.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016jtJ4GUtmyCSHkiGY1CvgR
docs: add the architecture rules page and count seven modules
falco-archunit landed in the repository and the wiki still described six
modules, with two build tables that did not know the seventh. The stale
counts are corrected in Build Setup, Project Status, Publishing, Dependency
Management and Benchmarks and Demo, and the two tables in Testing and
Javadoc now say what check and javadoc do for a module whose only source
set is test.
The new page covers what the 39 rules enforce, why the module sees only
main sources — which is what lets it catch a public method carrying a
package-private type, a mistake no test inside the modules can see — and
which invariants it deliberately cannot check: synchronized blocks, the
ordering of the seqlock protocol, and the claim that no CPU-bound work
happens while a lock is held.