retoorandClaude Sonnet 5
0b3b207bc0
bench/bench.c (`make bench`) measures create/read/stat/readdir/unlink/
mkdir on mem, dir, and raw fs; large sequential I/O; random-access pack
reads via mmap vs raw fs; compaction throughput; and 8-thread
concurrent mixed workloads. Results from one full run, with honest
analysis (what each "raw fs" vs "raw+fsync" vs "dir" label actually
measures, so they aren't misread as interchangeable), are in BENCH.md.
The benchmark surfaced a real, quantitatively-confirmed finding, not
just favorable numbers: bulk sequential create/unlink on mem/dir is
O(n^2) in file count (~9-22x slower than raw fs at N=20,000), because
every structural write copies the entire snapshot entry array before
publishing it (Section 5.3). concept.md itself names the exact trigger
condition for reconsidering this ("a persistent structurally-shared
tree structure is not required until this assumption is empirically
violated") — this benchmark is that violation, measured rather than
hypothesized: mkdir at N=4,000 vs create at N=20,000 (same mechanism,
5x the N) shows a 28.4x slowdown, matching the O(n^2) prediction (25x)
far better than O(n) (5x).
Also found: dir-backend stat() costs ~2x raw stat() (open+fstat vs one
syscall, the direct cost of openat2 containment on the metadata path);
mem-backed large writes lose to raw fs above ~16MB (Section 5.7's
buffer-growth discipline re-copies prior writes on every capacity
doubling, the price of never exposing a reader to a freed buffer).
Recorded the O(n^2) finding in CLAUDE.md's new "Known performance
characteristics" section, per the same pattern used for the
reclaim_gate use-after-free discovery, since it's exactly the kind of
fact that would otherwise have to be rediscovered by benchmarking
again from scratch. Linked from README and CONTRIBUTING.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqJpkdJ6Njnt1pw3CbghzB
3.3 KiB
Contributing to PackFS
Before changing anything
Read concept.md in full. It is the project's specification,
not background reading — every backend, lock, and on-disk field in src/
exists because a section of concept.md requires it, and most functions'
comments cite the section they implement rather than re-explaining it.
concept.md is frozen (see CLAUDE.md): if you believe the
design itself needs to change, that belongs in a new document that amends
or supersedes it, not in an edit to concept.md.
Then read CLAUDE.md, which states the load-bearing constraints
a change must respect (static linking, the write model, the concurrency
model, path containment, pack integrity) and the documentation register this
project is written in.
Workflow
make test # must pass before any PR
cc ... -fsanitize=address,undefined # ASan/UBSan: see .github/workflows/ci.yml for exact flags
cc ... -fsanitize=thread # TSan, for anything touching src/upper.c, src/overlay.c, or src/vfs.c
Any change to the concurrency-sensitive files (upper.c, overlay.c,
vfs.c) must be run under ThreadSanitizer, not just the plain test suite —
a data race there is exactly the class of bug Section 5 of concept.md
exists to prevent, and the plain build will not surface it.
A change to the index structure in upper.c (snapshot_upsert,
snapshot_remove, or the UpperSnapshot/UpperEntry representation)
should be run through make bench before and after, not just make test:
BENCH.md records a real, measured O(n²) cost in bulk sequential
create/unlink that any such change is liable to affect, for better or
worse, in ways the correctness-only test suite cannot detect.
Scope
Changes that add functionality concept.md Section 10 lists as explicitly
out of scope for v0 (full POSIX semantics, enforced permissions/symlinks/hard
links, cross-process concurrency, content-defined chunking/delta
compression) should discuss the tradeoff with a maintainer first — those
exclusions were deliberate design decisions, not gaps waiting to be filled.
zip and tar import/export backends will not be accepted, full stop —
not discussed, not behind a flag. concept.md Section 11 recommends them,
but that recommendation is permanently superseded; see CLAUDE.md, "Project
decisions that supersede concept.md." This is a harder line than the v0
exclusions above, which are open to future discussion — this one is not.
Static-linking constraint
concept.md Section 11.1 is a hard constraint: the core must build with
zero required third-party libraries and zero dynamic loading. In practice
this project has no optional-dependency boundary at all: concept.md
described one at the zip/tar backend for miniz/libarchive, but per
the decision above, that backend will never exist, so there is no path by
which a third-party dependency enters this codebase — a change proposing
one, for any backend, will not be accepted.
Style
Match the register already in the file you're editing — precise,
constraint-labeled comments citing the concept.md section they implement,
no filler. See the "Documentation standard" section of CLAUDE.md for the
full rule; it applies to code comments and commit messages, not only to
.md files.