Skip to content

pagestore: fence POSIX recovery and reclaim orphan layers#233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hurricane1026 merged 4 commits into from
Sep 8, 2026
Merged

pagestore: fence POSIX recovery and reclaim orphan layers #233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98884cf
pagestore: fence POSIX store recovery and reclaim orphan layers
hurricane1026 Sep 8, 2026
55848ba
pagestore: address recovery ownership review and CI findings
hurricane1026 Sep 8, 2026
27fd0f7
pagestore: normalize proven legacy local layer paths
hurricane1026 Sep 8, 2026
cdc23bf
fix(pagestore): guard repeated close and unsafe copy temporaries
hurricane1026 Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions .github/workflows/pagestore-test.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -73,30 +73,39 @@ jobs:
- name: Compile daemon and test harness
working-directory: contrib/pagestore
run: |
cc -O2 -Wall -Wextra -Werror -o pagestore_daemon pagestore_daemon.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_daemon pagestore_daemon.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_inspect pagestore_inspect.c -lrt
cc -O2 -Wall -Wextra -Werror -o pagestore_test pagestore_test.c -lrt
cc -O2 -Wall -Wextra -Werror -o pagestore_layer_test pagestore_layer_test.c pagestore_layer.c pagestore_layer_store.c pagestore_fault.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_layer_store_test pagestore_layer_store_test.c pagestore_layer_store.c pagestore_layer.c pagestore_fault.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_layer_test pagestore_layer_test.c pagestore_layer.c pagestore_layer_store.c pagestore_fault.c pagestore_store_owner.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_layer_store_test pagestore_layer_store_test.c pagestore_layer_store.c pagestore_layer.c pagestore_fault.c pagestore_store_owner.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_layer_crash_client pagestore_layer_crash_client.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_tiering_test pagestore_tiering_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_cutover_test pagestore_forkmeta_cutover_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_crash_matrix_test pagestore_forkmeta_crash_matrix_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_tiering_test pagestore_tiering_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_cutover_test pagestore_forkmeta_cutover_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_crash_matrix_test pagestore_forkmeta_crash_matrix_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_pgcache_test pagestore_pgcache_test.c pagestore_pgcache.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_manifest_test pagestore_manifest_test.c pagestore_manifest.c pagestore_layer.c pagestore_layer_store.c pagestore_fault.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_manifest_test pagestore_manifest_test.c pagestore_manifest.c pagestore_layer.c pagestore_layer_store.c pagestore_fault.c pagestore_store_owner.c -lrt -pthread
cc -O2 -Wall -Wextra -Werror -o pagestore_retention_test pagestore_retention_test.c pagestore_retention.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_gc_test pagestore_gc_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_gc_test pagestore_gc_test.c pagestore_core.c pagestore_fault.c storage_posix.c pagestore_layer.c pagestore_layer_store.c pagestore_manifest.c pagestore_memtable.c pagestore_pgcache.c pagestore_prune.c pagestore_retention.c pagestore_wal_store.c pagestore_wal_segment.c pagestore_walidx_prune.c pagestore_walidx_snapshot.c pagestore_forkmeta_prune.c pagestore_forkmeta_snapshot.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_walidx_prune_test pagestore_walidx_prune_test.c pagestore_walidx_prune.c -lrt
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_prune_test pagestore_forkmeta_prune_test.c pagestore_forkmeta_prune.c -lrt
cc -O2 -Wall -Wextra -Werror -o pagestore_walidx_snapshot_test pagestore_walidx_snapshot_test.c pagestore_walidx_snapshot.c -lrt
cc -O2 -Wall -Wextra -Werror -o pagestore_forkmeta_snapshot_test pagestore_forkmeta_snapshot_test.c pagestore_forkmeta_snapshot.c -lrt
cc -O2 -Wall -Wextra -Werror -o storage_posix_wal_test storage_posix_wal_test.c storage_posix.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o storage_posix_wal_test storage_posix_wal_test.c storage_posix.c pagestore_store_owner.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o storage_posix_fork_owner_test storage_posix_fork_owner_test.c storage_posix.c pagestore_store_owner.c pagestore_manifest.c pagestore_layer.c pagestore_layer_store.c pagestore_fault.c -lrt -lpthread
cc -O2 -Wall -Wextra -Werror -o pagestore_fault_test pagestore_fault_test.c pagestore_fault.c -pthread

- name: Run standalone test suite
working-directory: contrib/pagestore
run: ./pagestore_test ./pagestore_daemon ./pagestore_inspect

- name: Run store ownership and orphan recovery tests
working-directory: contrib/pagestore
run: |
./storage_posix_fork_owner_test
python3 harness/tests/test_store_owner_recovery.py \
--daemon-binary ./pagestore_daemon \
--inspect-binary ./pagestore_inspect

- name: Run named fault registry unit test
working-directory: contrib/pagestore
run: ./pagestore_fault_test
Expand Down
19 changes: 19 additions & 0 deletions contrib/pagestore/MVP_COMPLETION_PLAN.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -809,6 +809,25 @@ Acceptance:

Expected scope: one or two PRs.

### Local POSIX store ownership and orphan-layer recovery

Store recovery and local provider mutations share an exclusive advisory store
lease. Startup may remove canonical, unreferenced local layer files only after
validating the manifest and the complete candidate namespace. Manifest-owned
IDs, including deleting and remote-only records, remain protected. Unknown
non-layer files and object-tier artifacts are not part of this sweep.

Ambiguous manifest-tail repair must durably inhibit orphan sweeping before
truncating the manifest, and the inhibition persists across restart. Missing
manifest metadata does not authorize deletion. Recovery retries must preserve
referenced data after partial unlink or directory-sync failures.

Acceptance includes competing owners with distinct SHM names, release after
process death, failed-open cleanup, canonical orphan reclamation, namespace
validation before deletion, and continued H1 sentinel recovery. This closes
local orphan cleanup only; the other H1 crash families and R6 space acceptance
remain separate gates.

### H1. Compose process-level crash scenarios

Status: **materializer replay/restartpoint, branch prepared-receipt/service-
Expand Down
28 changes: 25 additions & 3 deletions contrib/pagestore/MVP_STATUS.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -86,9 +86,31 @@ harness keeps the pre-recovery physical snapshot, then checks a sentinel
page/LSN, the expected manifest state, and one additional restart for
idempotence. A crash after ADD but before its flush watermark conservatively
retains the durable layer and republishes segment-backed coverage once; the
intervening clean shutdown compacts that conservative duplicate, and the second
restart proves convergence to one layer. The slice does not delete crash
orphans; cross-process ownership is required before adding that policy.
second restart waits for background maintenance to compact that conservative
duplicate to one layer. Clean shutdown alone does not guarantee compaction.

POSIX store opens now hold an exclusive advisory ownership lease across recovery
and provider teardown. Cooperating storage and local-layer
provider users share the same ownership mechanism. After successful manifest
replay, startup reconciles canonical local layer files against manifest-owned
IDs, preserving referenced layers and removing validated unreferenced files.
Legacy relative, symlinked-directory, and dot-dot local URI spellings are
normalized in the replayed map when their parent resolves to the owned store
and their filename matches the layer ID. Unresolvable or foreign-store paths
still fail closed; this is not an arbitrary store-relocation mechanism.
An invalid layer namespace or unsafe file type fails closed before deletion;
unrelated files and object-tier contents are outside this reconciliation.
Missing manifests do not authorize a sweep. Before accepting an ambiguous
manifest-tail repair, recovery durably records an orphan-sweep inhibition
marker; automatic cleanup remains disabled across subsequent restarts because
the repaired manifest cannot prove that omitted files were never referenced.
The persistent lock file must not be removed while a store is in use. Older
binaries and external tools that do not acquire the lock must remain stopped
during recovery; the lock is advisory, not a fence against arbitrary filesystem
writes. This is local POSIX recovery, not SPDK or power-loss certification.
Child processes cannot mutate through inherited provider handles; a child that
inherits an open core must exec a fresh process before using the core. SPDK
storage retains its original caller-owned teardown contract.

## MVP gates

Expand Down
Loading
Loading