Add version API, pkg-config, SPDX headers, SECURITY.md, CHANGELOG.md

Project-hygiene pass toward being a properly citable, embeddable,
professionally-packaged C library rather than just working code:

- PACKFS_VERSION_MAJOR/MINOR/PATCH/STRING in include/packfs.h, the single
  source of truth for the project's version, plus a runtime pfs_version()
  (src/vfs.c, next to vfs_new/vfs_free) so a dynamically-linked consumer
  can check ABI/API compatibility without recompiling. Covered by a new
  assertion in tests/test_mem.c that the macro and the runtime function
  never disagree.
- packfs.pc.in + a `make install` rule that generates packfs.pc with its
  Version: field derived from PACKFS_VERSION_STRING via a Makefile-level
  grep/sed, never hand-maintained separately -- verified end-to-end with a
  scratch `make install PREFIX=...` + `pkg-config --cflags --libs packfs`
  + `make uninstall`, not just by reading the rule.
- SPDX-License-Identifier: MIT added to every src/*.c and src/internal.h
  (include/packfs.h already had one); the whole distributed source tree
  now carries consistent machine-readable license metadata.
- SECURITY.md, stating precisely what this project's containment and pack-
  integrity code actually claims as a security boundary (concept.md
  Section 6/7) versus what it explicitly does not (unenforced `mode`, no
  cross-process concurrency) -- not generic boilerplate -- with a real
  reporting contact rather than a placeholder.
- CHANGELOG.md (Keep a Changelog format), summarizing the real history in
  git log to date; explicitly notes no version is tagged yet.

Verified: clean `make all` + `make test` (all 6 binaries, including the
new version-check assertion), and a full ASan/UBSan sweep of all 6
binaries with zero real findings (one run hit the already-documented
DEADLYSIGNAL sandbox flake on test_pack_write_perf across all 3 retries;
re-verified directly afterward with 5/5 additional clean passes and timing
well under any plausible timeout, confirming it was the flake, not a
regression, before treating this as done).

Deliberately not done here, by the user's explicit choice: no
CODE_OF_CONDUCT.md, and no git remote/publishing -- this repository still
has neither, and both are decisions left to the maintainer.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqJpkdJ6Njnt1pw3CbghzB
This commit is contained in:
2026-09-14 10:58:35 +00:00
co-authored by Claude Sonnet 5
parent 529935deb4
commit 419182bb05
17 changed files with 317 additions and 6 deletions
+71
View File
@@ -0,0 +1,71 @@
# Changelog
All notable changes to this project are documented in this file, in the
style of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This
project follows [Semantic Versioning](https://semver.org/); see
`PACKFS_VERSION_STRING` in `include/packfs.h` for the authoritative current
version (`packfs.pc`, generated by `make install`, is derived from it, not
maintained separately).
No version has been tagged yet — this project is pre-release (`0.x`, an
initial, partial implementation of `concept.md`, not a completed one; see
`README.md`'s "Status"). Entries below are grouped as they will read once
`0.1.0` is tagged.
## [Unreleased]
### Added
- Initial implementation of `concept.md`: `vfs_*` core, `mem`/`dir`/`pack`
backends, the copy-on-write overlay (copy-up, whiteouts, compaction, an
append journal), path containment (`openat2`/Landlock on Linux 5.6+/5.13+,
a documented weaker fallback elsewhere), and pack integrity validation.
- `tests/test_*.c` covering each backend, concurrency, and randomized
structural-index stress testing against an independent reference model.
- `bench/bench.c` (`make bench`) and `BENCH.md`, comparing PackFS against
the host filesystem across metadata operations, large sequential I/O,
random-access pack reads, mount-table scaling, and concurrent workloads.
- `PACKFS_VERSION_MAJOR`/`MINOR`/`PATCH`/`STRING` and `pfs_version()` for
compile-time and runtime version/ABI checks.
- `packfs.pc` (pkg-config), generated by `make install` from
`packfs.pc.in`, version always derived from `include/packfs.h`.
- `SPDX-License-Identifier: MIT` on every file under `src/` and
`include/`.
### Fixed
- **Bulk sequential `create`/`unlink`/`mkdir` on `mem`/`dir` was O(n²) in
file count.** The index (`UpperSnapshot`) was a flat sorted array copied
in full on every structural write; rewritten as a persistent treap
(`src/upper.c`), reducing a structural write to the O(log n) nodes on
the path to the change. See `BENCH.md`'s "Resolution" for the full
before/after measurement and complexity-class confirmation.
- **`pack_write`'s compaction-time exact-duplicate elimination (Section
9.2) was O(n²) in entry count, and trusted a hash match without
comparing actual bytes** (a latent correctness bug: FNV-1a64 is
explicitly not collision-resistant). Rewritten as an open-addressing
hash table with a `memcmp` verification before ever reusing a
`data_off`, fixing both at once. See `BENCH.md`'s "Resolution #2".
- **`backend_pack_new` was declared in `include/packfs.h` but never
implemented** — any program calling it failed at link time. Implemented
as a standalone, read-only `pack` `Backend`.
- `.github/workflows/ci.yml`'s sanitizer-build steps never passed
`-D_GNU_SOURCE` when compiling test files (only the library object
files got it), which was harmless until a test included `internal.h`
(needed for `pthread_rwlock_t`) and became a link failure.
### Documented
- **`vfs.c`'s mount table (`MountSnapshot`) is O(n²) in mount count, the
same pattern the file index used to have — confirmed, and deliberately
left unfixed.** Mount counts are bounded by a program's own source code,
not workload-driven, so they do not reach the scale that made the file
index's O(n²) a real problem. See `BENCH.md`'s "Finding: mount table
scaling" for the numbers and reasoning.
- A ThreadSanitizer environment limitation (some sandboxes block the
`personality(ADDR_NO_RANDOMIZE)` syscall TSan needs) and a related
ASan/UBSan sandbox startup flake (`AddressSanitizer:DEADLYSIGNAL`),
both in `CONTRIBUTING.md` and `CLAUDE.md`, with the confirming tests and
the required mitigation (`timeout`-wrapped sanitizer runs).
<!-- This repository has no remote configured yet (see `git remote -v`),
so there is no comparison-link URL to cite here truthfully; add
"[Unreleased]: <repo-url>/compare/v0.1.0...HEAD" once one exists and
v0.1.0 is tagged, per Keep a Changelog's own convention. -->