From b4d446f46762bb98201ab4f3aec512135478a2c2 Mon Sep 17 00:00:00 2001 From: rain Date: Sun, 15 Nov 2026 23:33:18 +0000 Subject: [PATCH] feat(gc): implement 2.0 logical removal and store compaction (#41) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements the frozen 2.0 GC spec (#41/#42-#52): marker-based branch/project/path removal, admission (gc_intent), mark/closure (kept_node, object closure, keptWaste, live-heads digest), SQLite and PostgreSQL compaction (Phase M/A/B/C, install fence, crash/kill recovery), §11 report + store.status, metrics, API/MCP/CLI/SDK (76 calls), SQLite/PG tests, ext4 CI harness, capacity model (50GB measured), runbook/rollout docs. --- .../references/methods/branch.md | 30 +- .../references/methods/project.md | 47 +- .../layerfs-sdk-observe/references/tracing.md | 10 +- .github/workflows/store-ext4.yml | 203 ++ AGENTS.md | 862 ++++--- Cargo.lock | 1 + api/AGENTS.md | 17 +- api/README.md | 2 +- api/crates/layerfs-api/src/branch/mod.rs | 4 +- api/crates/layerfs-api/src/branch/publish.rs | 13 +- api/crates/layerfs-api/src/branch/remove.rs | 28 + api/crates/layerfs-api/src/calls/mod.rs | 3 +- api/crates/layerfs-api/src/calls/render.rs | 97 +- api/crates/layerfs-api/src/calls/scope.rs | 5 + api/crates/layerfs-api/src/lib.rs | 2 +- api/crates/layerfs-api/src/project/delete.rs | 24 + api/crates/layerfs-api/src/project/mod.rs | 8 +- .../layerfs-api/src/project/remove_file.rs | 29 + api/crates/layerfs-api/src/store/compact.rs | 24 + api/crates/layerfs-api/src/store/mod.rs | 4 +- api/crates/layerfs-api/tests/calls_scope.rs | 11 +- api/crates/layerfs-api/tests/calls_table.rs | 137 +- api/crates/layerfs-api/tests/gc_calls.rs | 351 +++ api/crates/layerfs-api/tests/gc_trace.rs | 309 +++ api/crates/layerfs-api/tests/home_layout_3.rs | 15 +- api/crates/layerfs-api/tests/logs.rs | 44 +- .../layerfs-api/tests/project_export.rs | 95 +- .../layerfs-api/tests/project_family.rs | 183 +- .../layerfs-api/tests/project_init_worker.rs | 11 +- .../tests/project_list_intersection.rs | 141 + .../layerfs-api/tests/project_list_worker.rs | 296 +++ .../layerfs-api/tests/store_projects.rs | 13 +- api/crates/layerfs-api/tests/store_stats.rs | 60 +- .../layerfs-cli/tests/concurrent_reads.rs | 6 +- api/crates/layerfs-cli/tests/gc.rs | 180 ++ .../tests/sqlite_compact_process_kill.rs | 426 ++++ api/mcp/src/profiles.js | 18 +- api/mcp/src/tools.js | 5 + api/mcp/test/profiles.test.mjs | 14 +- api/mcp/test/workflow.test.mjs | 7 +- api/node/README.md | 2 +- api/node/src/index.d.ts | 20 +- api/node/test/branch-file/inventory.mjs | 4 +- api/node/test/calls.mjs | 4 +- api/node/test/package.mjs | 24 - api/python/src/layerfs/_client.pyi | 16 +- api/python/src/layerfs/aio.pyi | 7 +- api/python/test/test_calls.py | 18 +- api/scripts/gen-coverage.mjs | 5 +- control/AGENTS.md | 25 +- .../crates/layerfs-control/src/inventory.rs | 12 - control/crates/layerfs-control/src/project.rs | 14 +- control/crates/layerfs-control/src/store.rs | 7 +- .../layerfs-control/src/worker_server.rs | 38 +- .../layerfs-control/tests/in_use_detail.rs | 38 +- .../crates/layerfs-control/tests/inventory.rs | 7 - .../tests/project_delete_call.rs | 17 + .../tests/project_delete_worker.rs | 652 +++++ .../tests/store_transfer_recovery.rs | 1 - .../layerfs-sandbox/src/daemon/channel.rs | 13 + .../layerfs-sandbox/src/daemon/internal.rs | 11 +- .../src/daemon/workspace/mount.rs | 14 +- .../src/daemon/workspace/recovery.rs | 27 +- .../crates/layerfs-sandbox/src/registry.rs | 4 +- .../layerfs-sandbox/src/workspace/serve.rs | 13 +- control/crates/layerfs-store/Cargo.toml | 6 + .../crates/layerfs-store/src/calls/branch.rs | 35 +- control/crates/layerfs-store/src/calls/op.rs | 15 +- .../crates/layerfs-store/src/calls/project.rs | 22 + control/crates/layerfs-store/src/compact.rs | 212 ++ control/crates/layerfs-store/src/lib.rs | 2 + .../layerfs-store/src/postgresql/connect.rs | 24 + .../crates/layerfs-store/src/project/add.rs | 28 +- .../layerfs-store/src/project/delete.rs | 940 +++++++ .../layerfs-store/src/project/export/walk.rs | 18 + .../layerfs-store/src/project/family.rs | 182 +- .../crates/layerfs-store/src/project/frame.rs | 344 ++- .../layerfs-store/src/project/listing.rs | 45 + .../crates/layerfs-store/src/project/mod.rs | 3 +- .../layerfs-store/src/project/record.rs | 15 + control/crates/layerfs-store/src/related.rs | 4 +- control/crates/layerfs-store/src/report.rs | 116 + .../layerfs-store/src/sqlite/transfer/step.rs | 7 + .../src/sqlite/transfer/steps.rs | 16 + control/crates/layerfs-store/src/status.rs | 67 +- .../tests/compact_report_status.rs | 238 ++ .../layerfs-store/tests/postgresql_status.rs | 405 +++ .../layerfs-store/tests/project_delete.rs | 561 ++++ .../tests/project_delete_frames.rs | 180 ++ .../tests/project_delete_store.rs | 238 ++ .../layerfs-store/tests/project_frames.rs | 31 +- .../tests/project_list_frames.rs | 122 + .../layerfs-store/tests/restore_install.rs | 1 - .../crates/layerfs-store/tests/store_ops.rs | 36 +- core/AGENTS.md | 18 +- .../layerfs-history/src/contract/catalog.rs | 227 +- .../layerfs-history/src/contract/error.rs | 272 ++ .../layerfs-history/src/contract/mod.rs | 1 + .../layerfs-history/src/contract/path.rs | 154 ++ .../layerfs-history/src/contract/records.rs | 279 +- core/crates/layerfs-history/src/lib.rs | 13 +- .../tests/contract_constructors.rs | 70 + .../src/encoding/delta/select.rs | 179 +- .../crates/layerfs-storage/src/save/pooled.rs | 13 +- .../docs/issues/project-41/LayerFS-GC-spec.md | 1236 +++++++-- .../issues/project-41/gc-acceptance-matrix.md | 187 ++ .../docs/issues/project-41/gc-api-contract.md | 120 + .../issues/project-41/gc-capacity-model.md | 122 + .../project-41/gc-implementation-report.md | 485 ++++ core/docs/issues/project-41/gc-rollout.md | 119 + core/docs/issues/project-41/gc-runbook.md | 181 ++ core/docs/issues/project-41/gc-spec-gaps.md | 96 + .../issues/project-41/gc-t10-report-status.md | 180 ++ .../gc-t12-sqlite-compaction-fixtures.md | 88 + .../gc-t12.3a-sqlite-matrix-report.md | 203 ++ .../gc-t12.3b-postgresql-acceptance.md | 150 ++ .../issues/project-41/gc-t8-sqlite-rebuild.md | 157 ++ .../project-41/gc-t9-postgresql-rebuild.md | 121 + docs/architecture/api/README.md | 4 +- docs/architecture/api/calls/README.md | 14 +- docs/architecture/api/calls/coverage.md | 39 +- docs/architecture/api/front-ends/mcp.md | 17 +- docs/architecture/api/sdk/README.md | 16 +- docs/architecture/api/sdk/branch.md | 63 +- docs/architecture/api/sdk/project.md | 78 +- docs/architecture/api/sdk/store.md | 46 +- docs/architecture/control/home/README.md | 8 +- docs/architecture/core/history/README.md | 4 +- docs/architecture/engine/README.md | 2 +- .../architecture/engine/store-calls/README.md | 2 +- docs/architecture/engine/store/README.md | 8 +- docs/architecture/engine/store/postgresql.md | 7 +- docs/architecture/engine/store/testing.md | 295 +++ docs/architecture/flows/call.md | 2 +- docs/architecture/flows/merge.md | 2 +- docs/architecture/glossary.md | 4 +- docs/general/parallel-worktrees.md | 13 - docs/research/README.md | 1 - docs/versioned/2.0.0/calls.md | 8 +- engine/AGENTS.md | 857 ++++--- engine/crates/layerfs-bridge/src/control.rs | 2 +- .../layerfs-bridge/src/control_request.rs | 67 +- .../layerfs-bridge/src/control_types.rs | 53 + .../layerfs-bridge/tests/control_records.rs | 13 + .../src/application/diagnostics.rs | 2 + .../src/application/retained.rs | 2 + .../layerfs-daemon/src/control/failure.rs | 2 + .../layerfs-daemon/src/control/operations.rs | 38 +- .../layerfs-daemon/src/control/unmount.rs | 1 + .../crates/layerfs-daemon/src/operator/mod.rs | 6 + .../layerfs-daemon/src/operator/workspace.rs | 212 +- .../layerfs-daemon/tests/mount_holders.rs | 127 + engine/crates/layerfs-persistence/Cargo.toml | 2 + .../layerfs-persistence/sql/postgresql/gc.sql | 84 + .../queries/history/branch_snapshot.sql | 2 +- .../queries/history/branch_snapshot_named.sql | 2 +- .../queries/history/gc_epoch_read.sql | 1 + .../queries/history/gc_epoch_share.sql | 1 + .../history/gc_lock_session_exclusive.sql | 1 + .../history/gc_lock_session_shared.sql | 1 + .../history/gc_lock_xact_exclusive.sql | 1 + .../queries/history/gc_lock_xact_shared.sql | 1 + .../history/gc_unlock_session_exclusive.sql | 1 + .../history/gc_unlock_session_shared.sql | 1 + .../history/layerstack_stack_by_name.sql | 2 +- .../sql/postgresql/schema.sql | 6 +- .../layerfs-persistence/sql/sqlite/gc.sql | 96 + .../sql/sqlite/history.sql | 3 + .../sql/sqlite/metadata.sql | 3 +- .../queries/history/branch_branch_by_id.sql | 2 +- .../history/branch_branch_by_id_any.sql | 1 + .../queries/history/branch_branch_by_name.sql | 2 +- .../history/branch_branch_first_page.sql | 2 +- .../history/branch_branch_name_taken.sql | 2 +- .../history/branch_branch_next_page.sql | 2 +- .../queries/history/branch_retire_insert.sql | 1 + .../queries/history/branch_snapshot.sql | 2 +- .../queries/history/branch_snapshot_named.sql | 2 +- .../queries/history/commit_insert_commit.sql | 2 +- .../queries/history/gc_branch_stack_any.sql | 1 + .../sqlite/queries/history/gc_epoch_read.sql | 1 + .../sqlite/queries/history/gc_epoch_share.sql | 1 + .../queries/history/gc_inode_blocks.sql | 1 + .../queries/history/gc_intent_all_branch.sql | 10 + .../queries/history/gc_intent_all_project.sql | 13 + .../queries/history/gc_intent_all_store.sql | 5 + .../sqlite/queries/history/gc_intent_get.sql | 5 + .../queries/history/gc_intent_insert.sql | 8 + .../sqlite/queries/history/gc_intent_list.sql | 6 + .../queries/history/gc_intent_ops_branch.sql | 11 + .../queries/history/gc_intent_ops_project.sql | 14 + .../queries/history/gc_intent_ops_store.sql | 6 + .../queries/history/gc_intent_release.sql | 1 + .../queries/history/gc_intent_uncertain.sql | 1 + .../sqlite/queries/history/gc_kept_roots.sql | 7 + .../queries/history/gc_live_branches.sql | 4 + .../sqlite/queries/history/gc_live_stacks.sql | 3 + .../queries/history/gc_object_locations.sql | 2 + .../sqlite/queries/history/gc_tuple_read.sql | 6 + .../queries/history/kept_node_clear.sql | 1 + .../sqlite/queries/history/kept_node_mark.sql | 81 + .../sqlite/queries/history/kept_node_read.sql | 1 + .../history/layerstack_bump_project_epoch.sql | 1 + .../queries/history/layerstack_deleted_ms.sql | 1 + .../history/layerstack_insert_layer.sql | 2 +- .../layerstack_insert_project_epoch.sql | 1 + .../history/layerstack_insert_retired.sql | 1 + .../history/layerstack_stack_by_id.sql | 2 +- .../history/layerstack_stack_by_name.sql | 2 +- .../history/layerstack_stack_first_page.sql | 2 +- .../history/layerstack_stack_name_taken.sql | 2 +- .../history/layerstack_stack_next_page.sql | 2 +- .../queries/history/paths_advance_epoch.sql | 1 + .../sqlite/queries/history/paths_marker.sql | 1 + .../sqlite/queries/history/paths_markers.sql | 1 + .../sqlite/queries/history/paths_upsert.sql | 1 + .../queries/history/position_high_water.sql | 1 + .../queries/history/position_next_serial.sql | 1 + .../queries/history/position_node_serial.sql | 1 + .../history/position_stack_high_water.sql | 1 + .../src/backend/postgresql/access.rs | 89 +- .../src/backend/postgresql/compact.rs | 1560 ++++++++++++ .../backend/postgresql/history/statements.rs | 24 + .../src/backend/postgresql/mechanics.rs | 3 + .../src/backend/postgresql/mod.rs | 1 + .../src/backend/postgresql/schema.rs | 437 +++- .../backend/postgresql/schema_diagnostic.rs | 59 + .../src/backend/postgresql/status.rs | 184 ++ .../src/backend/records.rs | 4 + .../layerfs-persistence/src/backend/seam.rs | 2 + .../src/backend/sqlite/compact.rs | 2260 +++++++++++++++++ .../src/backend/sqlite/lane/lane.rs | 11 + .../src/backend/sqlite/lifecycle/identity.rs | 51 + .../src/backend/sqlite/lifecycle/mod.rs | 1 + .../src/backend/sqlite/lifecycle/seal.rs | 135 +- .../src/backend/sqlite/mechanics.rs | 3 + .../src/backend/sqlite/mod.rs | 1 + .../src/backend/sqlite/schema.rs | 368 ++- .../src/backend/sqlite/schema_diagnostic.rs | 153 +- .../src/backend/sqlite/session/checkpoint.rs | 34 + .../src/backend/sqlite/session/connection.rs | 22 + .../src/backend/sqlite/session/query.rs | 111 + .../src/backend/sqlite/session/transaction.rs | 3 + .../src/compact_metrics.rs | 581 +++++ .../src/diagnostic/history.rs | 5 +- .../src/history/admission.rs | 746 ++++++ .../layerfs-persistence/src/history/branch.rs | 77 +- .../src/history/catalog.rs | 97 +- .../layerfs-persistence/src/history/commit.rs | 7 + .../layerfs-persistence/src/history/epoch.rs | 69 + .../layerfs-persistence/src/history/kept.rs | 196 ++ .../src/history/layerstack.rs | 95 +- .../layerfs-persistence/src/history/merge.rs | 27 +- .../layerfs-persistence/src/history/mod.rs | 10 + .../src/history/objects.rs | 573 +++++ .../layerfs-persistence/src/history/paths.rs | 112 + .../src/history/position.rs | 49 + .../src/history/removal.rs | 33 +- .../src/history/transaction.rs | 6 +- engine/crates/layerfs-persistence/src/lib.rs | 15 +- .../crates/layerfs-persistence/src/report.rs | 129 + .../layerfs-persistence/src/store/open.rs | 11 + .../src/store/postgresql.rs | 11 +- .../layerfs-persistence/tests/admission.rs | 355 +++ .../tests/branch_removal.rs | 253 ++ .../tests/compact_metrics.rs | 371 +++ .../tests/concurrent_first_installs.rs | 7 + .../tests/diagnostic_history.rs | 26 + .../layerfs-persistence/tests/epoch_fence.rs | 442 ++++ .../sqlite_compact_capacity_measure.json | 89 + .../sqlite_compact_capacity_measure_50gb.json | 74 + .../tests/fixtures/sqlite_compact_golden.json | 407 +++ .../fixtures/sqlite_compact_measure.json | 16 + .../layerfs-persistence/tests/gc_backfill.rs | 492 ++++ .../layerfs-persistence/tests/kept_node.rs | 390 +++ .../layerfs-persistence/tests/kept_objects.rs | 466 ++++ .../tests/lineage_backfill.rs | 76 +- .../tests/old_format_columns.rs | 204 ++ .../tests/old_format_open.rs | 32 +- .../layerfs-persistence/tests/path_removal.rs | 172 ++ .../tests/pg_doctor/conninfo.rs | 242 ++ .../tests/pg_doctor/mod.rs | 15 +- .../tests/postgresql_commit_round_trips.rs | 7 +- .../tests/postgresql_compact.rs | 1668 ++++++++++++ .../tests/postgresql_compact_fixtures.rs | 1790 +++++++++++++ .../tests/postgresql_diagnostic.rs | 45 +- .../tests/postgresql_doctor_access.rs | 9 +- .../tests/postgresql_doctor_physical.rs | 46 +- .../tests/postgresql_gc_fence.rs | 532 ++++ .../tests/postgresql_gc_mark.rs | 387 +++ .../tests/postgresql_narrow_locations.rs | 21 +- .../tests/postgresql_position_columns.rs | 459 ++++ .../tests/postgresql_status.rs | 272 ++ .../tests/project_delete.rs | 211 ++ .../tests/sqlite_compact.rs | 865 +++++++ .../tests/sqlite_compact_capacity.rs | 902 +++++++ .../tests/sqlite_compact_crash.rs | 957 +++++++ .../tests/sqlite_compact_fixtures.rs | 1596 ++++++++++++ .../tests/sqlite_compact_matrix.rs | 1952 ++++++++++++++ .../tests/sqlite_publication.rs | 6 +- .../tests/support/metrics.rs | 91 + .../layerfs-persistence/tests/support/mod.rs | 5 + .../layerfs-persistence/tests/support/pg.rs | 281 ++ .../crates/layerfs-project/src/import/init.rs | 72 + .../crates/layerfs-project/src/store/init.rs | 11 +- .../crates/layerfs-project/src/store/live.rs | 20 +- .../layerfs-project/tests/init_postgresql.rs | 19 +- .../src/history/admission.rs | 144 ++ .../src/history/branch.rs | 240 +- .../src/history/deletion.rs | 77 + .../src/history/lookup.rs | 141 +- .../layerfs-store-service/src/history/mod.rs | 3 + .../src/history/removal.rs | 42 + .../src/history/saved.rs | 4 +- .../crates/layerfs-store-service/src/lib.rs | 1 + .../layerfs-store-service/src/methods/args.rs | 9 +- .../src/methods/branch/mod.rs | 2 + .../src/methods/branch/publish.rs | 37 +- .../src/methods/branch/remove.rs | 10 + .../src/methods/dispatch.rs | 2 + .../src/methods/file/blame.rs | 17 +- .../src/methods/file/glob.rs | 22 +- .../src/methods/file/grep.rs | 15 +- .../src/methods/file/list.rs | 19 +- .../src/methods/file/read.rs | 12 +- .../src/methods/file/revision.rs | 1 + .../src/methods/file/stat.rs | 19 +- .../src/methods/project.rs | 56 +- .../src/operator/files.rs | 2 +- .../src/operator/inspect.rs | 14 +- .../src/read/attribution.rs | 29 +- .../layerfs-store-service/src/read/blame.rs | 44 +- .../src/read/branch_compare.rs | 42 +- .../layerfs-store-service/src/read/compare.rs | 24 +- .../src/read/file_compare.rs | 68 +- .../layerfs-store-service/src/read/mod.rs | 1 + .../src/read/paged_reads.rs | 16 + .../layerfs-store-service/src/read/reads.rs | 22 +- .../src/read/revision.rs | 41 +- .../src/read/snapshot.rs | 7 + .../src/read/visibility.rs | 276 ++ .../layerfs-store-service/src/removal.rs | 365 +++ .../layerfs-store-service/src/store/bind.rs | 106 +- .../layerfs-store-service/src/store/commit.rs | 14 + .../src/store/commit_merge.rs | 25 +- .../src/store/operation.rs | 24 +- .../layerfs-store-service/src/store/types.rs | 2 + .../layerfs-store-service/src/write/files.rs | 56 +- .../layerfs-store-service/tests/admission.rs | 73 + .../tests/branch_remove.rs | 131 + .../tests/epoch_fence.rs | 77 + .../tests/golden/sdk_methods.txt | 16 +- .../tests/history_ancestry_oracle.rs | 7 +- .../tests/project_delete.rs | 81 + .../tests/scale_lineage_cap.rs | 7 +- .../tests/sdk_mount_bind_failure.rs | 95 + .../tests/sdk_path_hidden_semantics.rs | 290 +++ .../tests/sdk_path_merge_removal.rs | 290 +++ .../tests/sdk_path_reads.rs | 620 +++++ .../tests/sdk_path_removal.rs | 135 + .../tests/sdk_path_whiteouts.rs | 346 +++ tools/ci/test_store_ext4.sh | 384 +++ 362 files changed, 42774 insertions(+), 2313 deletions(-) create mode 100644 .github/workflows/store-ext4.yml create mode 100644 api/crates/layerfs-api/src/branch/remove.rs create mode 100644 api/crates/layerfs-api/src/project/delete.rs create mode 100644 api/crates/layerfs-api/src/project/remove_file.rs create mode 100644 api/crates/layerfs-api/src/store/compact.rs create mode 100644 api/crates/layerfs-api/tests/gc_calls.rs create mode 100644 api/crates/layerfs-api/tests/gc_trace.rs create mode 100644 api/crates/layerfs-api/tests/project_list_intersection.rs create mode 100644 api/crates/layerfs-api/tests/project_list_worker.rs create mode 100644 api/crates/layerfs-cli/tests/gc.rs create mode 100644 api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs create mode 100644 control/crates/layerfs-control/tests/project_delete_call.rs create mode 100644 control/crates/layerfs-control/tests/project_delete_worker.rs create mode 100644 control/crates/layerfs-store/src/compact.rs create mode 100644 control/crates/layerfs-store/src/project/delete.rs create mode 100644 control/crates/layerfs-store/src/project/listing.rs create mode 100644 control/crates/layerfs-store/src/report.rs create mode 100644 control/crates/layerfs-store/tests/compact_report_status.rs create mode 100644 control/crates/layerfs-store/tests/postgresql_status.rs create mode 100644 control/crates/layerfs-store/tests/project_delete.rs create mode 100644 control/crates/layerfs-store/tests/project_delete_frames.rs create mode 100644 control/crates/layerfs-store/tests/project_delete_store.rs create mode 100644 control/crates/layerfs-store/tests/project_list_frames.rs create mode 100644 core/crates/layerfs-history/src/contract/path.rs create mode 100644 core/crates/layerfs-history/tests/contract_constructors.rs create mode 100644 core/docs/issues/project-41/gc-acceptance-matrix.md create mode 100644 core/docs/issues/project-41/gc-api-contract.md create mode 100644 core/docs/issues/project-41/gc-capacity-model.md create mode 100644 core/docs/issues/project-41/gc-implementation-report.md create mode 100644 core/docs/issues/project-41/gc-rollout.md create mode 100644 core/docs/issues/project-41/gc-runbook.md create mode 100644 core/docs/issues/project-41/gc-spec-gaps.md create mode 100644 core/docs/issues/project-41/gc-t10-report-status.md create mode 100644 core/docs/issues/project-41/gc-t12-sqlite-compaction-fixtures.md create mode 100644 core/docs/issues/project-41/gc-t12.3a-sqlite-matrix-report.md create mode 100644 core/docs/issues/project-41/gc-t12.3b-postgresql-acceptance.md create mode 100644 core/docs/issues/project-41/gc-t8-sqlite-rebuild.md create mode 100644 core/docs/issues/project-41/gc-t9-postgresql-rebuild.md create mode 100644 docs/architecture/engine/store/testing.md create mode 100644 engine/crates/layerfs-daemon/tests/mount_holders.rs create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/gc.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_read.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_share.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_exclusive.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_shared.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_exclusive.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_shared.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_exclusive.sql create mode 100644 engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_shared.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/gc.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id_any.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_retire_insert.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_branch_stack_any.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_read.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_share.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_inode_blocks.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_store.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_get.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_insert.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_list.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_store.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_release.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_uncertain.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_kept_roots.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_branches.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_stacks.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_object_locations.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_tuple_read.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_clear.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_mark.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_read.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_bump_project_epoch.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_deleted_ms.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_project_epoch.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_retired.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_advance_epoch.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_marker.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_markers.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_upsert.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_high_water.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_next_serial.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_node_serial.sql create mode 100644 engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_stack_high_water.sql create mode 100644 engine/crates/layerfs-persistence/src/backend/postgresql/compact.rs create mode 100644 engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs create mode 100644 engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/identity.rs create mode 100644 engine/crates/layerfs-persistence/src/compact_metrics.rs create mode 100644 engine/crates/layerfs-persistence/src/history/admission.rs create mode 100644 engine/crates/layerfs-persistence/src/history/epoch.rs create mode 100644 engine/crates/layerfs-persistence/src/history/kept.rs create mode 100644 engine/crates/layerfs-persistence/src/history/objects.rs create mode 100644 engine/crates/layerfs-persistence/src/history/paths.rs create mode 100644 engine/crates/layerfs-persistence/src/history/position.rs create mode 100644 engine/crates/layerfs-persistence/src/report.rs create mode 100644 engine/crates/layerfs-persistence/tests/admission.rs create mode 100644 engine/crates/layerfs-persistence/tests/branch_removal.rs create mode 100644 engine/crates/layerfs-persistence/tests/compact_metrics.rs create mode 100644 engine/crates/layerfs-persistence/tests/epoch_fence.rs create mode 100644 engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_capacity_measure.json create mode 100644 engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_capacity_measure_50gb.json create mode 100644 engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_golden.json create mode 100644 engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_measure.json create mode 100644 engine/crates/layerfs-persistence/tests/gc_backfill.rs create mode 100644 engine/crates/layerfs-persistence/tests/kept_node.rs create mode 100644 engine/crates/layerfs-persistence/tests/kept_objects.rs create mode 100644 engine/crates/layerfs-persistence/tests/old_format_columns.rs create mode 100644 engine/crates/layerfs-persistence/tests/path_removal.rs create mode 100644 engine/crates/layerfs-persistence/tests/pg_doctor/conninfo.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_compact.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_compact_fixtures.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_gc_fence.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_gc_mark.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_position_columns.rs create mode 100644 engine/crates/layerfs-persistence/tests/postgresql_status.rs create mode 100644 engine/crates/layerfs-persistence/tests/project_delete.rs create mode 100644 engine/crates/layerfs-persistence/tests/sqlite_compact.rs create mode 100644 engine/crates/layerfs-persistence/tests/sqlite_compact_capacity.rs create mode 100644 engine/crates/layerfs-persistence/tests/sqlite_compact_crash.rs create mode 100644 engine/crates/layerfs-persistence/tests/sqlite_compact_fixtures.rs create mode 100644 engine/crates/layerfs-persistence/tests/sqlite_compact_matrix.rs create mode 100644 engine/crates/layerfs-persistence/tests/support/metrics.rs create mode 100644 engine/crates/layerfs-persistence/tests/support/pg.rs create mode 100644 engine/crates/layerfs-store-service/src/history/admission.rs create mode 100644 engine/crates/layerfs-store-service/src/history/deletion.rs create mode 100644 engine/crates/layerfs-store-service/src/history/removal.rs create mode 100644 engine/crates/layerfs-store-service/src/methods/branch/remove.rs create mode 100644 engine/crates/layerfs-store-service/src/read/visibility.rs create mode 100644 engine/crates/layerfs-store-service/src/removal.rs create mode 100644 engine/crates/layerfs-store-service/tests/admission.rs create mode 100644 engine/crates/layerfs-store-service/tests/branch_remove.rs create mode 100644 engine/crates/layerfs-store-service/tests/epoch_fence.rs create mode 100644 engine/crates/layerfs-store-service/tests/project_delete.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_mount_bind_failure.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_path_hidden_semantics.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_path_merge_removal.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_path_reads.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_path_removal.rs create mode 100644 engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs create mode 100755 tools/ci/test_store_ext4.sh diff --git a/.agents/skills/layerfs-js-sdk/references/methods/branch.md b/.agents/skills/layerfs-js-sdk/references/methods/branch.md index 0cc8d154ea..df913adea1 100644 --- a/.agents/skills/layerfs-js-sdk/references/methods/branch.md +++ b/.agents/skills/layerfs-js-sdk/references/methods/branch.md @@ -125,14 +125,10 @@ reply, never out of the merge. For an incomplete summary, page ## `branch.publish` -`branch.publish(project, branch, commit?, { expected_base, expected_head, force })` +`branch.publish(project, branch, commit?)` Makes `main` show the Branch's head, or the given Commit, by adding a Layer -to `main`. It refuses (`HeadMoved`) when `main` gained a Layer since your -Branch forked, so another agent's work is never dropped by accident. -`expected_base` (a Layer id) and `expected_head` (a Commit id) refuse unless -`main` and your Branch are still where you read them; `force: true` -overwrites `main` on purpose. +to `main`. ```bash layerfs branch publish shop/api work @@ -147,29 +143,29 @@ layerfs branch publish shop/api work | `kind` | Meaning | | --- | --- | -| `Added` | `main` now shows that Commit; `published_layer` is the new Layer; `overwrote` lists `main` Layers that a `force` publish skipped | -| `UpToDate` | That Commit is already published (`{ kind, layer }`), even if `main` moved on since | -| `NoChanges` | `main` already holds that tree (`{ kind, head_layer }`) | +| `Added` | `main` now shows that Commit; `published_layer` is the new Layer; `overwrote` lists `main` Layers that were skipped | +| `UpToDate` | `main` already shows it (`{ kind, layer }`) | +| `NoChanges` | Nothing to publish (1.1.0 shape; not seen in this pass) | | Code | Meaning | Do | | --- | --- | --- | | `NoCommit` | The Branch has no Commit yet | Commit something first | | `NoSuchBranch` | No such Branch | Check the name | -| `HeadMoved` | `main` moved since your Branch forked (or since `expected_base`), or the Branch head is not `expected_head`; `detail` has `expectedBase`/`actualBase` or `expectedHead`/`actualHead` | Merge with `main` into a new Branch (below), then publish that | -| `InvalidInput` | `commit` is not a full Commit id, or an expected id names the wrong kind | Pass a full id | +| `HeadMoved` | `main` moved during the call | Merge `main` in (below), then publish again | +| `InvalidInput` | `commit` is not a full Commit id | Pass a full id | -**Publishing replaces `main`'s view** with your Commit, so it is refused when -`main` has Layers your Commit doesn't contain. Publishing your own Branch -again at milestones is fine. If someone else published since you forked, -merge `main` in (a merge makes a new Branch), check the result, then publish -the merged Branch: +**Publishing replaces `main`'s view** with your Commit. Layers published to +`main` after your Branch's base that your Commit doesn't contain are skipped: +they stay in history and `overwrote` lists them. If someone else may have +published since you forked, merge `main` in first, check the result, then +publish the merged Branch: ```js const P = "shop/api"; const m = await layerfs.branch.merge(P, "work-release", "work", "main", { message: "merge main before publish" }); // mount m.branch in a Sandbox and run the tests here, then: const p = await layerfs.branch.publish(P, m.branch); -// a merge with main publishes as a fast-forward: nothing is skipped +if (p.kind === "Added" && p.overwrote.length) console.log("warning: skipped", p.overwrote); ``` ## `branch.diff` diff --git a/.agents/skills/layerfs-js-sdk/references/methods/project.md b/.agents/skills/layerfs-js-sdk/references/methods/project.md index bbd29a11b0..59e6ea6a6c 100644 --- a/.agents/skills/layerfs-js-sdk/references/methods/project.md +++ b/.agents/skills/layerfs-js-sdk/references/methods/project.md @@ -13,7 +13,8 @@ project.init(project, folder, { timeout, on_progress }) project.list(store?, { page_size, page_pos }) project.get(project) project.export(project, destination, { branch, on_progress }) -project.remove(project) +project.delete(project) +project.remove_file(project, path) ``` ## `project.init` @@ -119,23 +120,41 @@ The project's record: its Store, the Store's kind and machine. {"project":"shop/api","store":"shop","name":"api","kind":"sqlite","machine":"native","created":1793574061265} ``` -## `project.remove` +## `project.delete` -`project.remove(project)` +`project.delete(project)` -Removes one project from its Store. Its Branches, Commits and `main` go with -it; there is no undo. The live result: +Retires one project in its Store and removes its home entry (spec §4). The +project disappears from `project.list` and `project.get`; its Layers, +Branches, Commits and stored content stay until a later `store.compact`, and +the Store stays addressable. The live result: ```json -{"stack":"3104401f11fb…","packs_kept":true,"project":"shop/api"} +{"kind":"Removed","project":"shop/api","deleted_ms":1793574061265,"home_entry_removed":true} ``` -`packs_kept: true`: the project's records are gone, but its stored content -stays in the Store file. Removing a project from a PostgreSQL Store is -`Unsupported` in this build. While a Sandbox of the project is recorded it is -refused `InUse`; `detail.related` lists each as `{ kind: "sandbox", name }` -(close them first). To delete a whole Store with every project in it, use -`store.remove`. +The Store marker is the commit point. If the home entry cannot be removed the +call still succeeds with `home_entry_removed: false` and keeps a durable +intent, so the same call retried from the same home reuses `deleted_ms` and +finishes the entry. A mount of the project is refused `MountsActive`, another +user or operation `Busy`/`Unresolved`. -An agent working on a project never needs `remove`; it is for whoever owns the -home. +## `project.remove_file` + +`project.remove_file(project, path)` + +Hides one absolute project path from every node at or below its marker +frontier (spec §4.3). It writes a marker only; no bytes are freed. The path is +normalized (one leading `/` stripped) and must be a canonical absolute POSIX +path. The live result: + +```json +{"kind":"Removed","project":"shop/api","path":"docs/old.md","frontier_serial":42,"removed_ms":1793574061265} +``` + +`kind` is `UpToDate` when no project node is above this path's marker +frontier. Later reads and stats of the path are refused `Removed`; a Commit +after the frontier that writes the path again is visible. + +An agent working on a project never needs `delete` or `remove_file`; they are +for whoever owns the home. diff --git a/.agents/skills/layerfs-sdk-observe/references/tracing.md b/.agents/skills/layerfs-sdk-observe/references/tracing.md index 316686abfa..5f3534511c 100644 --- a/.agents/skills/layerfs-sdk-observe/references/tracing.md +++ b/.agents/skills/layerfs-sdk-observe/references/tracing.md @@ -19,12 +19,16 @@ Python, direct `layerfs_api::call`) appends one line to and `LAYERFS_TRACE` / `LAYERFS_TRACE_STEP` do not affect it. ```json -{"v":1,"at":1793000004120,"ms":212,"client":"node","argv":["file","write","demo/app","main","/index.ts","<5321 bytes>"],"outcome":"ok","kind":"Committed","commit":"<66 hex>","tag":"dsh:s_4d2a:a91e"} +{"v":1,"at":1793000004120,"ms":212,"client":"node","argv":["file","write","demo/app","main","<8 bytes>","<5321 bytes>"],"outcome":"ok","kind":"Committed","commit":"<66 hex>","tag":"dsh:s_4d2a:a91e"} ``` It keeps 1.1.0's redaction rule (values cut to 200 characters; contents, -JSON, commands, messages, edit strings, passwords and URLs as byte counts) -and drops the daemon telemetry: no `sizes`, `scope` or `daemon`. `argv` is +JSON, commands, messages, edit strings, passwords and URLs as byte counts; +a path argument as the byte count of its normalized form, one leading `/` +stripped, so `/a` and `a` are both `<1 bytes>`; a glob or grep `pattern` by +its own bytes) and drops the daemon telemetry: no `sizes`, `scope` or +`daemon`. A refusal is logged as its code only: its message and `detail` are +never traced, so a `Removed` path stays out of the line. `argv` is the call as CLI words (`argv[0]`/`argv[1]` are the family and call), `outcome` is `"ok"` or the refusal code, `kind` and `commit`/`layer` come from the result, `client` is `cli`/`node`/`python`/`rust`, and `tag` is the diff --git a/.github/workflows/store-ext4.yml b/.github/workflows/store-ext4.yml new file mode 100644 index 0000000000..cffa8038de --- /dev/null +++ b/.github/workflows/store-ext4.yml @@ -0,0 +1,203 @@ +# Store lane: the Store suites, on a filesystem that carries SQLite's locks. +# +# A Store opens only on a directory that is private, owned by the test user and +# on a local filesystem whose locks reach every opener: ext4, xfs or btrfs on +# Linux (engine/crates/layerfs-store-service/src/kernel_guard.rs). The Store +# suites keep their Stores in TMPDIR and in $CARGO_TARGET_DIR/tmp, so both must +# be on such a filesystem, and an overlay checkout or a tmpfs /tmp is refused. +# tools/ci/test_store_ext4.sh refuses any other directory before cargo starts +# and points TMPDIR, CARGO_TARGET_DIR and CARGO_HOME at the one it is given; +# this lane only provides that directory. See +# docs/architecture/engine/store/testing.md. +# +# It adds no test selection of its own: every target it runs is already in the +# push or nightly lane chosen by tools/ci_tests.py. It runs them under the +# environment contract their guard requires. +# +# Reports only, like the other lanes (AGENTS.md §4): never a required check. +# The runner's /mnt is a separate ext4 data disk while /tmp is tmpfs, so the +# prepare step asserts the filesystem: a runner image whose /mnt is not ext4 +# fails there, with its own message, instead of as a guard refusal inside a +# suite. +name: store-ext4 + +on: + push: + branches: [main] + paths: + - "core/**" + - "engine/**" + - "control/**" + - "api/crates/**" + - "!api/crates/layerfs-node/**" + - "Cargo.*" + - ".config/**" + - "tools/ci/**" + - ".cargo/**" + - ".github/workflows/store-ext4.yml" + - "!**/*.md" + pull_request: + # off for pull requests into layerfs_v2_0_0, like the other lanes + branches-ignore: [layerfs_v2_0_0] + paths: + - "core/**" + - "engine/**" + - "control/**" + - "api/crates/**" + - "!api/crates/layerfs-node/**" + - "Cargo.*" + - ".config/**" + - "tools/ci/**" + - ".cargo/**" + - ".github/workflows/store-ext4.yml" + - "!**/*.md" + schedule: + # After nightly.yml's 04:23 UTC run; the two lanes never share runner time. + - cron: "47 4 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: store-ext4-${{ github.ref }} + cancel-in-progress: true + +env: + CARGO_TERM_COLOR: always + CARGO_INCREMENTAL: "0" + # CI needs no debugger: smaller objects, much shorter links. + CARGO_PROFILE_TEST_DEBUG: "0" + # Link the test binaries with mold instead of GNU ld, as ci.yml's test job + # does. Scoped to this target, so the repository's aarch64 rustflags + # (.cargo/config.toml) stay. + CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold" + # The harness requires this and validates it before cargo starts. /mnt is the + # runner's ext4 data disk; never /tmp, which is tmpfs there. + LAYERFS_TEST_TMPDIR: /mnt/layerfs-store-tests + +jobs: + quick: + name: store ext4 (--quick) + # The push lane: one or two targets per suite, across the four suites. + if: github.event_name == 'push' || github.event_name == 'pull_request' + runs-on: ubuntu-24.04 + timeout-minutes: 60 + steps: + - uses: actions/checkout@v7.0.1 + - run: rustup toolchain install 1.85.1 --profile minimal + - name: Install mold + run: | + sudo apt-get update -qq + sudo apt-get install -y -qq --no-install-recommends mold + mold --version + - name: Prepare the ext4 test directory + run: | + # /mnt belongs to root on the runner image and the tests run as the + # runner, so hand the directory over before the harness probes it. + sudo mkdir -p "$LAYERFS_TEST_TMPDIR" + sudo chown "$(id -u):$(id -g)" "$LAYERFS_TEST_TMPDIR" + fs="$(findmnt -n -o FSTYPE --target "$LAYERFS_TEST_TMPDIR")" + echo "LAYERFS_TEST_TMPDIR=$LAYERFS_TEST_TMPDIR ($fs)" + df -h "$LAYERFS_TEST_TMPDIR" + case "$fs" in + ext4|xfs|btrfs) ;; + *) + echo "::error title=unsupported filesystem::$LAYERFS_TEST_TMPDIR is on $fs; the Store guard admits only ext4, xfs or btrfs" + exit 1 + ;; + esac + # No Swatinem/rust-cache here: the harness moves CARGO_HOME and + # CARGO_TARGET_DIR onto LAYERFS_TEST_TMPDIR, so the checkout-scoped cache + # the other lanes restore is never read. The cold build is the price of + # running the suites where their guard admits them. + - name: Run the Store suites (--quick) + run: tools/ci/test_store_ext4.sh --quick + + full-postgresql: + name: store ext4 (--full, PostgreSQL 17) + # The scheduled and manual lane: every Store suite, with the PostgreSQL + # cases on. A manual dispatch runs this job only, which is the full sweep. + if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + runs-on: ubuntu-24.04 + timeout-minutes: 120 + env: + # A libpq connection string, not a URL (testing.md). A service + # container's published port is 127.0.0.1 on the runner. The server is + # scratch -- each PostgreSQL test creates and drops its own schema -- and + # lives only for this job. Setting this adds `--features postgresql` to + # every suite in the harness. + LAYERFS_TEST_POSTGRES_URL: host=127.0.0.1 port=5432 user=postgres dbname=postgres sslmode=disable + # The full-mode doctor calls amcheck's verify_heapam and bt_index_check; + # the step below creates it in this database. The physical doctor's two + # extra servers (an amcheck-free database and a physical standby) are + # not available in this job; see testing.md. Set so the diagnostic test + # asserts relation coverage is Pass instead of only printing it. + LAYERFS_TEST_EXPECT_AMCHECK: "1" + services: + postgres: + # PostgreSQL 17 is the supported version for these cases: the schema + # needs 16 or newer for STORAGE PLAIN, and the suites are qualified on + # 17.x (docs/architecture/engine/store/testing.md). + image: postgres:17 + env: + POSTGRES_USER: postgres + POSTGRES_DB: postgres + # Trust authentication: a throwaway server, reachable from this job's + # steps only, and the tests create and drop their own schemas. + POSTGRES_HOST_AUTH_METHOD: trust + ports: + - 5432:5432 + options: >- + --health-cmd "pg_isready --username=postgres --dbname=postgres" + --health-interval 5s + --health-timeout 5s + --health-retries 20 + steps: + - uses: actions/checkout@v7.0.1 + - run: rustup toolchain install 1.85.1 --profile minimal + - name: Install mold + run: | + sudo apt-get update -qq + sudo apt-get install -y -qq --no-install-recommends mold + mold --version + - name: Prepare the ext4 test directory + run: | + sudo mkdir -p "$LAYERFS_TEST_TMPDIR" + sudo chown "$(id -u):$(id -g)" "$LAYERFS_TEST_TMPDIR" + fs="$(findmnt -n -o FSTYPE --target "$LAYERFS_TEST_TMPDIR")" + echo "LAYERFS_TEST_TMPDIR=$LAYERFS_TEST_TMPDIR ($fs)" + df -h "$LAYERFS_TEST_TMPDIR" + case "$fs" in + ext4|xfs|btrfs) ;; + *) + echo "::error title=unsupported filesystem::$LAYERFS_TEST_TMPDIR is on $fs; the Store guard admits only ext4, xfs or btrfs" + exit 1 + ;; + esac + # The service health check gates this job on the server answering. The + # engine never installs extensions: a full-mode audit calls amcheck's + # verify_heapam and bt_index_check and reports every relation as + # Unknown when the extension is absent, while the compaction suite + # asserts a clean full audit. A fresh cluster therefore needs these + # contrib extensions before any suite connects (T-G14). The server is + # scratch, and this is the one database every suite reaches. + - name: Create the PostgreSQL extensions + run: | + set -euo pipefail + # The runner image does not ship psql; the distro client reaches the + # PostgreSQL 17 service container. + sudo apt-get update -qq + sudo apt-get install -y -qq --no-install-recommends postgresql-client + psql --version + psql "$LAYERFS_TEST_POSTGRES_URL" -X -v ON_ERROR_STOP=1 <<'SQL' + CREATE EXTENSION IF NOT EXISTS amcheck; + CREATE EXTENSION IF NOT EXISTS pgstattuple; + SQL + # Fail here, with a readable list, rather than as five Unknown + # relation checks inside a compaction suite. + psql "$LAYERFS_TEST_POSTGRES_URL" -X -A -t -v ON_ERROR_STOP=1 \ + -c "SELECT extname FROM pg_catalog.pg_extension WHERE extname IN ('amcheck','pgstattuple') ORDER BY extname" + # The suites own their schemas; the harness reports the mode it took. + - name: Run the Store suites (--full) + run: tools/ci/test_store_ext4.sh --full diff --git a/AGENTS.md b/AGENTS.md index b76053d386..fb2f6b79ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,392 +2,450 @@ > **Status:** Current general guide. -Instructions for agents working in LayerFS. Read this file, then the guide of -each layer you change: [core](core/AGENTS.md), [engine](engine/AGENTS.md), -[control](control/AGENTS.md), [API](api/AGENTS.md). A layer guide adds only -what differs in its layer. Current owner instructions and documented -supersessions govern; a closed handoff or historical receipt is not a new -assignment. Earlier wording of these guides is in the -[archived guide history](docs/research/history/agents-guides/README.md). - -## Rules you must not break - -| Rule | Where | -| --- | --- | -| Disposable / WAL / synchronous=OFF is the only SQLite Store profile; Durable execution is `NOT_RUN` | [Persistence profile](#active-persistence-profile--owner-direction-2026-10-07) | -| One attempted operation: no automatic retry, busy handler, refresh or replay | [§4](#4-code-build-and-docs) | -| Build tests with `--no-run` first; every test command stops at 120 s, and reaching it is a hang | [§4](#4-code-build-and-docs) | -| CI reports and never gates; verify your own change and report checks and gaps | [§4](#4-code-build-and-docs) | -| No new dependency an existing crate covers; no third-party patch, fork or vendor except the fuser Git fork | [§4](#4-code-build-and-docs) | -| Refactors delete tests that are tricky to adapt; never weaken a surviving assertion | [§4](#4-code-build-and-docs) | -| Architecture docs change in the same commit as the code | [§4](#4-code-build-and-docs) | -| Every commit records production LOC, split by core, engine, control and api | [Production LOC](#production-loc-comparison-for-every-commit) | -| A warm cache never credits a measured phase; one sample per case | [Measurements](#measurements) | -| Retired stays retired: the v0.1.6 reference, `layerfs-server`, standalone UI pages, removed platforms; fs-bench-pro is frozen | [Retired and frozen](#retired-and-frozen) | - -## Layers - -| Layer | Crates (root manifest) | Guide | +Repository-wide instructions for LayerFS. Also read the applicable [core](core/AGENTS.md), [engine](engine/AGENTS.md), +[control](control/AGENTS.md) and [API](api/AGENTS.md) guides for implementation in those layers. Current owner instructions and documented +supersessions govern; a closed handoff or historical receipt is not a new assignment. + +## Product scope and current workstreams + +**Implement both workstreams through the core, engine and API layers.** The v0.1.6 +reference implementation that lived under root `crates/` was retired on +2026-10-10 (R9c) and is absent at HEAD. It was never a dependency, source +include or fallback for core, and must not return as a second product. Its last +source is at local tag `reference-v0.1.6-final` (`d296981ac`, `crates` tree `498dd1917812`); +see the [R9c record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R9C-COMPLETION-20261010.md). +Historical evidence, receipts and verdicts are retained unchanged in Git +history: `core/docs/` (issue records, numbered papers, receipts) was removed +by #671 and stays readable at commit `af2ad92bce`. Link it there by pinned +URL; do not restore it to the tree. The +retirement is a legacy retirement in the source-size comparison, not a +simplification. + +| Workstream | Current scope | Entry point | | --- | --- | --- | -| core | `layerfs-content`, `layerfs-history`, `layerfs-storage`, `layerfs-telemetry` | [core](core/AGENTS.md) | -| engine | `layerfs-bridge`, `layerfs-daemon`, `layerfs-fuse`, `layerfs-mount-ports`, `layerfs-nfs`, `layerfs-overlay`, `layerfs-persistence`, `layerfs-project`, `layerfs-store-service`, `layerfs-workspace` | [engine](engine/AGENTS.md) | -| control | entities `layerfs-home`, `layerfs-machine`, `layerfs-store`, `layerfs-sandbox` (with its `workspace/` module); drivers `layerfs-platform`, `layerfs-bucket`, `layerfs-sandbox-backend`; and `layerfs-control` | [control](control/AGENTS.md) | -| api | the call surface `layerfs-api`, the `layerfs` command `layerfs-cli`, the Node binding `layerfs-node`, the PyO3 module `layerfs-python`; the JavaScript and Python packages under `api/` | [API](api/AGENTS.md) | - -- **Dependencies point down:** `core < engine < control < api`, including dev - dependencies and test includes; nothing in engine depends on control. The - control layer (`control/crates`, renamed from `connect/` by the owner - 2026-11-06, layerfs-project#101 D-6; #535 D4) holds the management code and - the crates that reach a machine or the network. -- **[Cargo.toml](Cargo.toml) decides membership**; a directory or old test does - not establish a built replacement. -- **Two workstreams, one set of layers.** Cluster one is the core algorithms - (Content, Storage, History, Telemetry) with engine Persistence and Project - Init: start with the [cluster-one handbook](docs/general/cluster_one_handbook.md) - and the [CAS/CDC/delta handbook](docs/general/cas_cdc_deltaencoding_handbook.md). - Cluster two is engine Workspace, FUSE, daemon and Sandbox with API execution - and Commit integration: start with the - [architecture guide](docs/architecture/README.md) and its - [flows](docs/architecture/flows/README.md). C1/C2/C5 in older documents mean - content/storage/history. -- **What establishes what.** Source and public contracts establish implemented - behaviour. Owner requirements and proposals establish target behaviour; - research establishes neither capability nor qualification. Preserve source - pins, limits, failures and open prerequisites. - -## Retired and frozen - -- **The v0.1.6 reference** under root `crates/` was retired on 2026-10-10 (R9c) - and is absent. It was never a dependency, source include or fallback for - core and must not return as a second product; its last source is at local - tag `reference-v0.1.6-final` (`d296981ac`, `crates` tree `498dd1917812`); see - the [R9c record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R9C-COMPLETION-20261010.md). - Its retirement is a legacy retirement in the source-size comparison, not a - simplification. -- **`core/docs/`** (issue records, numbered papers, receipts) was removed by - #671 and stays readable at commit `af2ad92bce`; link it there by pinned URL - and do not restore it. Historical evidence, receipts and verdicts stay - unchanged. -- **`layerfs-server` and the host-mediated SDK runtime** are retired, not - extended; build no host/server adapter in the data path. -- **The LayerFS UI is the dsh LayerFS plugin** (owner, 2026-10-19), the LayerFS - tab in DeepSeek Harness, in its own repository - [dsh-layerfs](https://github.com/Ephemeral-AI-Lab/dsh-layerfs) (moved out on - 2026-10-23, #428), which pins the LayerFS commit it builds on; this - repository holds no dsh code. Build no standalone HTML or TUI pages. The - `dsh-layerfs-demo` bundle is disabled permanently (owner, 2026-10-21): it - loads nothing, is not released and no guide installs it. -- **Firecracker, Microsandbox and SSH machines are removed** (owner, - 2026-11-08); see [Where calls run](#where-calls-run). -- **fs-bench-pro is frozen and left broken** (owner, 2026-10-18). Do not edit, - build, run or repair it, and leave it out of workspace builds and checks. - Its call sites broken by #352 F-020 (`ProjectApi` fork and commits, - `ForkRequest`, a `SandboxCreate` without `connect_host`) stay broken; a - product change never adapts it. Only an explicit owner instruction reopens - it. Benchmarks, harnesses and released data live in - [layerfs-benchmark](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark) - (moved out of `benchmark/` on 2026-10-23; routing is its - [fs-bench-pro/AGENTS.md](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark/blob/main/fs-bench-pro/AGENTS.md)). - Older documents' `benchmark/` paths are that repository's paths without the - prefix; the root harness for the retired reference is at tag - `reference-v0.1.6-final`. -- **Old prompts and research.** Completed Stage 0–6 prompts are historical. - The former #303 contracts and the - [optimization investigation](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/303/fuse-optimization-investigation.md) - are archived research that selects no algorithm, profile or capability. Do - not resume old loops, reopen closed rows or run old campaigns unless the - task selects that work, and do not choose authority by issue number alone. +| Cluster one | Core Content/Storage/History/Telemetry algorithms; Engine Persistence and Project Init | [Cluster-one handbook](docs/general/cluster_one_handbook.md), [CAS/CDC/delta handbook](docs/general/cas_cdc_deltaencoding_handbook.md) | +| Cluster two | Engine Workspace/FUSE/daemon/Sandbox; API execution and Commit/runtime integration | [Architecture guide](docs/architecture/README.md): engine and control topics and the [flows](docs/architecture/flows/README.md) | +| Legacy reference | v0.1.6, retired from `main` by R9c; read at the recovery tag only | [R9c record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R9C-COMPLETION-20261010.md) | + +**The LayerFS UI is the dsh LayerFS plugin** (owner, 2026-10-19): the LayerFS tab in +DeepSeek Harness. It lives in its own repository, +[dsh-layerfs](https://github.com/Ephemeral-AI-Lab/dsh-layerfs) (moved out of `dsh/` +on 2026-10-23, #428), which pins the LayerFS commit it builds on; this repository +holds no dsh code. +Do not build or revive standalone HTML or TUI pages. **The `dsh-layerfs-demo` +bundle (the LayerFS mock model and its demo workspace) is disabled permanently** +(owner, 2026-10-21): it loads nothing, is not released and no guide installs it. + +Cluster names are workstreams. C1/C2/C5 in older component documents mean +content/storage/history. Check [Cargo.toml](Cargo.toml) for active +members: a directory or old test does not establish a built replacement. +Source and public contracts establish implemented behavior. Owner requirements +and proposals establish target behavior; research establishes neither capability +nor qualification. Preserve source pins, limits, failures and open prerequisites. ## Active persistence profile — owner direction 2026-10-07 -- **Disposable / WAL / synchronous=OFF is the only permitted profile for a - SQLite Store.** Durable execution is disabled indefinitely, until the owner - explicitly allows it again; this supersedes earlier instructions to exercise - both profiles or resume Durable. A milestone, old benchmark selection, - default argument or passing build does not reauthorize Durable. -- Select Disposable explicitly for every new Store, application run, test, - diagnostic and measurement; never execute Durable or fall back to it. - Retained Durable code may compile; report its execution as - `NOT_RUN — disabled by owner until explicit reauthorization`. Historical - Durable receipts keep their verdicts. This policy does not claim the Durable - API was removed. -- Disposable's COMMIT does not checkpoint (`wal_autocheckpoint=0`); its writing - session's own thread checkpoints the WAL off the commit path (owner approval, - 2026-11-07; [SQLite checkpoints](docs/architecture/engine/store/sqlite.md#checkpoints)). -- A PostgreSQL Store has no profile; its write setting is `synchronous_commit` - (default `off`), recorded by `store.connect`. -- Each Workspace's daemon overlay is a separate MEMORY/OFF/EXCLUSIVE database - file. +**Disposable / WAL / synchronous=OFF is the only permitted global Store +profile. Durable execution is disabled indefinitely, until the owner explicitly +allows it again.** This supersedes earlier instructions to exercise both profiles +or to resume Durable after Disposable development. A milestone, old benchmark +selection, default argument or passing build does not reauthorize Durable. + +Select Disposable explicitly for every new Store, application run, test, +diagnostic and measurement. Do not execute Durable or fall back to it. Retained +Durable implementation may compile, but report its execution as +`NOT_RUN — disabled by owner until explicit reauthorization`. Preserve historical +Durable receipts and their original verdicts. This execution policy does not +claim that the Durable API has been removed. Each Workspace's daemon overlay +remains a separate MEMORY/OFF/EXCLUSIVE database file. +Disposable's COMMIT does not checkpoint (`wal_autocheckpoint=0`); its writing +session's own thread checkpoints the WAL off the commit path (owner approval, +2026-11-07; [SQLite checkpoints](docs/architecture/engine/store/sqlite.md#checkpoints)). ## LayerFS mental model -- **A Workspace is a complete mutable filesystem view** over an immutable - committed root, including `.git` and its index, ignored files, - dependencies, symlinks, caches and output; Git ignore rules do not filter - LayerFS state. -- **Granularity is free.** Per-tool-call orchestration is the common case and - needs fast bootstrap; per-task works too. A Workspace can serve many - sequential or concurrent calls, last long and Commit incrementally. - Workspace granularity, Exec duration and Commit cadence are independent. - Ordinary Bash has no automatic timeout, command-specific restore/install, - implicit Commit or automatic unmount; only explicit terminal unmount closes - local ownership. -- **Filesystem access needs no Exec.** Any process with mount visibility and - permission, including Bash launched by an external executor, gets the same - Workspace semantics through ordinary filesystem calls. The Sandbox or the - external executor owns command launch, streams, exit status and - cancellation; the filesystem daemon supervises no commands. See - [execution ownership](engine/AGENTS.md#filesystem-access-and-execution-ownership). -- **Mount is cheap.** Initial full-root acquisition is explicit. Mount binds - the complete root with no whole-tree scan, copy, materialization or - dependency restore; the only file it creates is the Workspace's overlay - database, copied from a template built before readiness and deleted at - terminal unmount. Demand-loaded metadata and content still pay real I/O. -- **Workspaces share nothing mutable.** A Workspace's metadata, payload and - operation records live only in its overlay file; its open-file, +- A Workspace is a complete mutable filesystem view over an immutable committed + root. Include `.git` and its index, ignored files, dependencies, symlinks, + caches and output; Git ignore rules do not filter LayerFS state. +- Support both per-tool-call and per-task orchestration. Per-tool-call is the + expected common case and needs fast bootstrap. A Workspace can serve multiple + sequential/concurrent calls, last a long time and Commit incrementally. +- Workspace granularity, Exec duration and Commit cadence are independent. + Commands may be short or long-lived in either mode. Ordinary Bash has no + automatic runtime timeout, command-specific restore/install, implicit Commit + or automatic unmount. Only explicit terminal unmount closes local ownership. +- Filesystem access does not require `workspace_api.exec` or an Exec registration. + Any process with mount visibility and permission, including Bash launched by an + external executor, uses the same Workspace semantics through ordinary filesystem + calls. Sandbox or the external executor owns command launch, streams, exit + status and explicit cancellation. The filesystem daemon supervises no commands; + optional `WorkspaceApi.exec` only delegates ordinary Sandbox execution. + Keep this boundary explicit in implementation + and proofs; see [execution ownership](engine/AGENTS.md#filesystem-access-and-execution-ownership). +- Initial full-root acquisition is explicit. Repeated mount binds the complete + root without a whole-tree scan/copy/materialization or dependency restoration. + The only file it creates is the Workspace's own overlay database, copied from + the template. Demand-loaded metadata/content still pay real I/O. +- Each mounted Workspace has its own local overlay SQLite file, copied at mount + from a template built before readiness and deleted at terminal unmount. Its + metadata, payload and operation records live only in that file; its open-file, directory-position and kernel-reference state lives in daemon memory. Workspaces share no overlay connection, writer, page cache or memory budget; - the daemon shares only committed immutable content and the global Store. - One lock guards a Workspace's connection: hold it for one short atomic job, - never across Store I/O, a whole Exec or a whole Commit. -- **Commit captures the published frontier**, which may hold several calls' - changes however their processes were launched; never filter by Exec - registration or completion. Retain stable input without a bulk overlay copy. - A known install advances the base while preserving later mutations and the - live view. UpToDate need not create a new Commit; invocation auditing is - separate. -- **Outcomes are not inferred.** A lost reply does not remove a published - mutation. Bash exit does not prove that descendants, descriptors, dirty - mappings or requests are finished. -- **FUSE** preserves permissions, stable identity, coherent caches and exact - request/open/lookup ownership; qualify both frequent fresh mounts and - sustained same-mount calls and Commits. Kernel writeback stays off. -- **No artificial caps.** Large files, huge namespaces and mutation bursts use - indexed or backed state, bounded windows, streaming and backpressure; - resident containers and transport frames impose no total file, edit, - Workspace, Commit, flow or time cap. Physical capacity, platform and format - limits and explicit admission remain. The one resident exception is a - Workspace's open state, which grows with open files and the files the - kernel references. -- **Reclamation is automatic and bounded**, after last-owner release, during - activity and idle time; a Commit's own reclamation follows its answer - (owner approval, 2026-11-07). Terminal unmount drains requests, closes the + the daemon shares only committed immutable content and the global Store. One + lock guards a Workspace's connection: hold it for one short atomic job, never + across Store I/O, a whole Exec or a whole Commit. +- Commit captures the shared locally published Workspace frontier, potentially + including several calls' changes regardless of how their processes were + launched. Do not filter captured changes by Exec registration or completion. + Retain stable existing input without a bulk overlay copy. Construct/save/publish + it; known install advances the base while preserving later active mutations and + the effective live view. +- Namespace Init and captured Workspace construction reuse the same Content, + Storage and Persistence libraries. Project adapts native files and metadata; + Workspace adapts the captured immutable base plus Overlay changes. Keep + canonical construction in Content, object encoding/packing in Storage and + database writes in Persistence. Reuse these ports when completing daemon + construction; do not add a second encoder or route it through host Init. See + [shared construction boundaries](engine/AGENTS.md#shared-construction-and-completion-boundaries) + for implemented entrypoints and the remaining S10 namespace integration. +- `Save::finish()` completes saved objects while the Store remains open; + History publication follows. `SqliteHandles::seal()` consumes the sole Store + session for host/offline handoff, checkpoints and closes it. Its macOS unused + extent cleanup belongs to that lifecycle. A live daemon keeps the shared + Store open across Saves and Commits; it does not seal it per file or Commit. +- A lost reply does not remove an already published mutation. Bash exit is not + proof that descendants, descriptors, dirty mappings or requests are finished. + UpToDate need not create a new Commit; invocation auditing is separate. +- FUSE must preserve permissions, stable identity, coherent caches and exact + request/open/lookup ownership. Qualify both frequent fresh mounts and sustained + same-mount calls/Commits. Kernel writeback remains off under the target contract. +- Large files, huge namespaces and mutation bursts require indexed/backed state, + bounded windows, streaming and backpressure. Resident containers/transport + frames must not impose artificial total file/edit/Workspace/Commit/flow/time + caps. Physical capacity, platform/format limits and explicit admission remain. + The one resident exception is a Workspace's open state, which grows with open + files and with the files the kernel currently references. +- Automatic bounded local reclamation follows last-owner release, including + during live activity and idle periods. A Commit's own reclamation (its + captured generation's retired rows) follows its answer (owner approval, + 2026-11-07). Terminal unmount drains requests, closes the Workspace's overlay connection and deletes its file. Neither deletes global history. -- **History is not a checkpoint of everything.** Immutable objects support - reuse and distribution; authority, reference closure, mutable history, - durability and safe GC still need exact contracts. Filesystem history is not - a process, memory, socket or stdout/stderr checkpoint. - -## Where calls run - -Per-call routes are in -[Where each call runs](docs/architecture/control/README.md#where-each-call-runs), -machines in [Platforms](docs/architecture/control/machines/platforms.md) and -workers in [Workers and reach](docs/architecture/control/machines/workers-and-reach.md). - -- **Store calls never run in the daemon.** Every daemon opens the global Store - directly and reads, saves and publishes in-process (owner, 2026-10-07; - revised 2026-10-18). A sqlite Store's calls run on the Store's kernel: in - the caller on a local `native` machine, else in that machine's worker. - PostgreSQL Store calls and bucket (s3) I/O run in the caller's process on - any OS (owner, 2026-11-02, #533 G2). Workspace calls (mount, Exec, Commit, - status, unmount) go to the daemon. Project Init into an existing Store is a - live add (2.0, #533). -- **One kernel, local filesystem.** A sqlite Store's openers share one kernel - and a local ext4, xfs or btrfs (Linux) or apfs or hfs (macOS) filesystem - (`kernel_guard`, #427); another kernel reaches it only through that - machine's worker. Anywhere else sqlite Store calls fail `Unsupported`, with - no fallback. -- **Routes come from the home's records** (machines, owner 2026-11-02, #533 - G2; `native` on macOS, 2026-11-01, #527 D5; `native` on Windows through a - WSL2 worker, 2026-10-22). Both Store kinds work on every machine (owner, - 2026-11-03, #535 D9): a sqlite Store is on exactly one machine, and a - PostgreSQL Store is usable from the machines it is attached to - (`store.attach`, each checked from that machine; supersedes #535 G3) where - the support table (`layerfs-platform` `support.rs`, `control/SUPPORT.json`) - allows, and refused elsewhere with the table's reason. -- **Workers** listen on loopback only, behind a secret; one attempt per call, - no retry and no replay; an uncertain outcome is reported, never resent. -- **Secrets:** a PostgreSQL password is resolved only in the caller and travels - only in one worker request and the Sandbox's private daemon setup file. -- **Plugin-neutral** (owner, 2026-10-24): LayerFS reads `LAYERFS_HOME` and the - trace settings only; no adapter name, integration check or code that names a - plugin. An integration maps its own prefixed names (such as `DSH_*`). -- **Removed stays removed** (owner, 2026-11-08): Firecracker, Microsandbox and - SSH machines are gone with their code; no setting or flag brings one back - without a new owner decision and source change. -- **One database per Store, one writer, short holds** (owner, 2026-10-18). A - Store's committed state lives in one database (a SQLite file, or one - PostgreSQL database, #506): no sharding, second database, concurrent-writer - engine or objects outside it. Writes go one at a time through SQLite's - single-writer rule, the Linux directory lock across writer processes, the - in-process admission queue and the publication lane (head check, merge, - publish as one step). These locks stay; they replace `Busy` failures under - the no-retry rule. Heavy work happens before the lane, only the atomic - publish holds it, and reads never take it. Concurrent Commits are expected - to be uncommon: optimize the uncontended Commit and keep contention correct - and bounded. Work inside the lane that grows with tree size, history or - Branch count is a defect. See the - [Store concurrency model](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/83-store-concurrency-model.md). -- Design references: the - [integration contract](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/303/06-cluster-one-integration.md), - [direct Store access](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/352/DIRECT_STORE.md), - [#533](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/533/README.md), - [#535](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/535/README.md) +- Target (owner direction 2026-10-07, Store calls revised 2026-10-18): every + daemon opens the global Store directly from a volume the daemons share and + reads, saves and publishes in-process. Project Init adds a project to an + existing Store as a live add (2.0, #533). **sqlite Store calls run in a + process on the Store's kernel; postgresql Store calls, and bucket (s3) I/O, + run in the caller's process on any OS (owner, 2026-11-02, #533 G2).** A + sqlite Store's openers share one kernel and a local filesystem holding the + Store (ext4, xfs, btrfs on Linux; apfs, hfs on macOS); a process on another + kernel reaches it only through that machine's worker. Anywhere else sqlite + Store calls fail `Unsupported`, with no fallback; the daemon does not serve + Store calls. Workspace calls (mount, Exec, Commit, + status, unmount) go to the daemon. Do not revive `layerfs-server` or build a + host/server adapter in the data path; the host-mediated SDK runtime is + retired, not extended. See the + [integration contract](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/303/06-cluster-one-integration.md) + and [direct Store access](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/352/DIRECT_STORE.md). + **Exception (owner, 2026-10-20, revised the same day): dsh Live on macOS + only.** The dsh-layerfs plugin may give macOS processes a ported SDK with + the SDK's API whose calls run in one long-lived worker per LayerFS box: a + Linux container running the real SDK, which opens each project's Store + directly and keeps it and its daemon connections open while the project is + in use (closed after a quiet minute). The worker listens on loopback only, + behind a secret. The product SDK and daemon do not change. (Widened to any + integration on 2026-10-24; see below.) +- **Additional exception (owner, 2026-10-22): dsh Live on Windows.** The + Windows dsh-layerfs adapter may forward its SDK binding calls to one + authenticated loopback worker per LayerFS home in a selected WSL2 Linux + distribution. The worker opens the shared Store directly on that + distribution's local ext4/xfs/btrfs filesystem and uses its Docker Engine + for Sandbox daemons. Windows owns the UI, bindings and traces; Linux owns + native handles and project discovery. This is independent of the macOS + adapter and changes neither the product SDK nor the daemon. A lost reply + is never replayed, and an uncertain Init retains its Linux home and volume. +- **Additional exception (owner, 2026-11-01, #527 D5; renamed 2026-11-02, + #533 G2): the `native` machine on macOS.** For a Store on the `native` + machine on macOS, the library runs in the caller's own process and opens the project's Store directly on a local apfs or hfs + directory (`kernel_guard` admits those two there, #427). Its Sandboxes are + daemon processes serving loopback NFS to this Mac's own client, one user, + no container (see the agent guide's native Sandboxes). Every opener is a + process on this one Mac, so the one-kernel, local-filesystem rule holds; + network and other filesystems are still refused. The Docker, worker and + `vm:` routes on macOS are unchanged. +- **Plugin-neutral LayerFS (owner, 2026-10-24; revised 2026-11-02, #533 + G2).** LayerFS is agnostic to dsh and every other plugin. The `layerfs` + package routes by the home's records: a call's route comes from its + Store's and machine's records, so one process uses Stores on several + machines at once, and the worker routes above are open to any caller of + the package. LayerFS reads `LAYERFS_HOME` and the trace settings only. + There is no adapter name, no integration check and no code that names a + plugin. An integration that can set only its own prefixed names, such as + dsh's `DSH_*`, maps them itself. The worker's rules above (loopback, + secret, one attempt, no replay) are unchanged. +- **Machines (owner 2026-11-02, #533 G2; replaces the 2026-10-31 VM + placement, V1).** A VM machine holds many Stores, with one worker per + machine. Machines are created, removed and started by the `machine` calls, + and the routes come from the home's records (`machine//record.json`, + `store//record.json`). `native` and `docker` are built in; VM kinds + (`apple-container`, `lima`) are created by name. Each VM + machine's data disk is mounted at + `/layerfs/data` and holds `store//store.sqlite` per Store. Its + worker runs as root behind its own secret, reached through one loopback + port on the host, with one attempt per call and no replay, the same rules + as the macOS and Windows routes. Guests never read the home: the caller + sends each worker call the settings it needs and writes every record. + **Every machine uses both Store kinds (owner, 2026-11-03, #535 D9, G1, + G3):** a machine holds any number of sqlite Stores, and every PostgreSQL + Store is usable from it. A sqlite Store is on exactly one machine; a + PostgreSQL Store's calls still run in the caller's process, and it is + usable from every machine where the support table (`layerfs-platform` + `support.rs`, `control/SUPPORT.json`) marks the platform supported; + elsewhere it is refused with the table's reason. The password is resolved only in the + caller and travels only in one worker request and the Sandbox's private + daemon setup file. This supersedes #533 O3/G13 ("VMs and ssh later"). + See [#533](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/533/README.md), [#535](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/535/README.md) and the [proposal](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/proposals/host-platform-connections.md). - -## Read first - -| Task | Read | -| --- | --- | -| Any implementation | the two cluster-one handbooks and the [architecture guide](docs/architecture/README.md): the layer page and every topic the change touches | -| Cluster two | also [Workspace](docs/architecture/engine/workspace/README.md), [Overlay](docs/architecture/engine/overlay/README.md), [Commit](docs/architecture/engine/commit/README.md), [Kernel routes](docs/architecture/engine/kernel-routes/README.md), [Daemon](docs/architecture/engine/daemon/README.md), [Bridge](docs/architecture/engine/bridge/README.md) | -| Documentation or a release | [documentation policy](docs/general/documentation-policy.md), [release policy](docs/general/release-policy.md) | -| A pull request or issue | [code review and triage policy](docs/policy/code-review.md) | -| A measurement | [measurement workflow](docs/general/agent-measurement-policy.md), [benchmark rules](docs/general/benchmark_rules.md), [report template](docs/general/benchmark_agent_report.md), the owning harness contract | - -## Measurements - -The [measurement workflow](docs/general/agent-measurement-policy.md) owns these -rules under the same numbers; moving them out of this file does not weaken -them. In short: - -1. **A warm cache never credits a measured phase.** Each phase pays for its - own work from an equally declared and enforced cache state; unknown or - mismatched cache state is INCOMPLETE/INELIGIBLE, not PASS. -2. **Reuse setup, never measurement.** Use `--setup clone` for - post-initialization cases where supported; a clone is an independent - writable copy, not a cold claim. Never reuse a mutated sample. -3. **Run once, pinned and bounded.** One sample per case and arm; fresh - append-only outputs, keeping failed, ineligible and unrun selections; pinned - identities; worktree-local locks and targets; a complete performance - command within 15 s (declared exceptions up to 25 s, independent proofs - under 10 s), with no timeout, workload or cache change to turn a miss into - PASS. Export `LAYERFS_CONSTRUCTION_WORKERS=1`: one construction producer per - Commit, capture or snapshot (Namespace Init keeps its parallel profile). A - Commit's one producer runs on its own thread and hands objects through one - bounded queue to the calling thread, which keeps the one Save and publishes - (owner approval, 2026-11-07; [Commit construction](docs/architecture/engine/commit/construction.md)). - Measure speed and storage; reject about 50% speed loss for about 5% storage. - -The workflow's §5 keeps the cache-credit failure these rules came from. +- **Removed platforms (owner, 2026-11-08; supersedes the layerfs-project#7 + restriction of 2026-11-06): Firecracker, Microsandbox and SSH machines are + removed.** Their code is gone and no platform is disabled with its code + kept. An old record of one is shown as unsupported with the reason + (``platform `` was removed in LayerFS 2.0``), every other call on it + is refused, and `machine remove` only forgets it. No runtime setting or + feature flag brings one back; that requires a later explicit owner + decision and source change. Historical evidence is unchanged. Native, + Docker, Lima and Apple Container retain their existing support rules. See + the [restriction contract](docs/architecture/control/machines/platforms.md#removed-platforms-platform_policyrs). +- **One global database, one writer, short holds (owner decision 2026-10-18).** + All committed state lives in one SQLite Store file; no sharding, second + database, concurrent-writer engine or objects outside it. Writes go one at a + time: SQLite's single-writer rule, the Linux directory lock across writer + processes, the in-process admission queue and the publication lane (head + check, merge, publish as one step). These locks stay; they replace `Busy` + failures under the no-retry rule. Performance comes from short holds: heavy + work happens before the lane, only the atomic publish step holds it, reads + never take it. Agents' tool calls are separated by model latency, so + concurrent Commits are expected to be uncommon; optimize the uncontended + Commit and keep contention correct and bounded. Work that grows with tree + size, history or Branch count inside the lane is a defect. See the + [Store concurrency model](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/83-store-concurrency-model.md) + and the [global SQLite Store](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/84-global-sqlite-store.md) + design reference. + Immutable objects support reuse/distribution; authority, reference closure, + mutable history, durability and safe GC still require exact contracts. + Filesystem history is not a process, memory, socket or stdout/stderr + checkpoint. + +## Read the current contract for the task + +Before implementation or integration, read both root handbooks and the +[architecture guide](docs/architecture/README.md): the layer page and every +topic the change touches (for cluster two: [Workspace](docs/architecture/engine/workspace/README.md), +[Overlay](docs/architecture/engine/overlay/README.md), [Commit](docs/architecture/engine/commit/README.md), +[Kernel routes](docs/architecture/engine/kernel-routes/README.md), [Daemon](docs/architecture/engine/daemon/README.md) +and [Bridge](docs/architecture/engine/bridge/README.md)). The former #303 contracts and the +[optimization investigation](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/303/fuse-optimization-investigation.md) +are archived research; they do not silently select new algorithms, profiles or capabilities. + +Completed/superseded Stage 0–6 prompts are historical references, not default +routing. Preserve canonical compatibility and evidence, but do not resume old +loops, reopen closed rows or run old campaigns unless the current task selects +that work. Do not choose authority by issue number alone. + +For documentation/release work, read the +[documentation policy](docs/general/documentation-policy.md) and +[release policy](docs/general/release-policy.md). +For opening, reviewing or triaging a pull request or issue, read the +[code review and triage policy](docs/policy/code-review.md). +For measurements, read the [agent measurement workflow](docs/general/agent-measurement-policy.md), +[benchmark rules](docs/general/benchmark_rules.md), +[report template](docs/general/benchmark_agent_report.md) and owning harness/family contract. +Benchmark suites, harnesses and released data live in the +[layerfs-benchmark](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark) repository, moved out of +`benchmark/` on 2026-10-23. Benchmark routing is its +[fs-bench-pro/AGENTS.md](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark/blob/main/fs-bench-pro/AGENTS.md). +**fs-bench-pro is frozen and left broken (owner, 2026-10-18).** Do not edit, +build, run or repair it, and leave it out of workspace builds and checks. Its +call sites broken by #352 F-020 (`ProjectApi` fork and commits, +`ForkRequest`, a `SandboxCreate` without `connect_host`; listed in the F-020 +fix record) stay broken; a product change never adapts it. Only an +explicit owner instruction reopens it. +The root `benchmark/` harness that built and measured the retired reference was +removed from HEAD; read it at tag `reference-v0.1.6-final`. Released +fs-bench-pro results (v0.1.4–v0.1.6) are in layerfs-benchmark's +[data/fs-bench-pro](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark/blob/main/data/fs-bench-pro/README.md). +Older documents here still link to `benchmark/` paths; read those files in +layerfs-benchmark at the same path without the `benchmark/` prefix. + +## 1. A warm cache must never credit a measured phase + +Each measured phase pays for its own work from an equally declared/enforced +cache state. No setup/earlier-phase warmth, pre-touching, own-write cache credit, +lifetime-peak substitution or file-sized backing/page-cache growth disguised by a +bounded heap. Unknown or mismatched cache state is INCOMPLETE/INELIGIBLE, not PASS. +Preserve failures and historical verdicts. Full rules and the retained example: +[measurement workflow §1](docs/general/agent-measurement-policy.md#1-a-warm-cache-must-never-credit-a-measured-phase). + +## 2. Reuse setup (`--setup clone`); never reuse measurement + +Reuse closed prepared inputs, sealed builds/images and qualifying proof receipts +through the declared mechanisms. Use `--setup clone` for post-initialization +cases where supported; fresh is for initialization/fresh-output cases. +A clone is an independent writable byte copy, not a cold claim. Never reuse a +mutated sample or remove timed product work through setup. Record all reuse and +enforce residency for a cold claim. See +[measurement workflow §2](docs/general/agent-measurement-policy.md#2-reuse-setup---setup-clone-never-reuse-measurement). + +## 3. Running a measurement + +The [measurement workflow](docs/general/agent-measurement-policy.md#3-running-a-measurement) +owns detailed procedures, scoped SDK rules and budget exceptions. Its requirements +remain binding; moving them out of this file does not weaken them. + +1. One sample per case/arm, no best-of or repeated unchanged treatment. + Diagnose retained receipts or labeled count-driven causes. The separately + scoped regression-screen exception is not treatment resampling. +2. Fresh append-only outputs; retain failed, ineligible and unrun selections. +3. Pin source/product/compilation/dependency/binary/image/harness/workload/cache + identities. No dirty seal compared as a sealed arm. +4. Exploratory timing is diagnostic; verification is separate. At final identity, + run covering proof once. Reuse unaffected earlier-family evidence; rerun only + the necessary affected checkpoint, without relabeling old receipts. +5. Use worktree-local measurement locks and Cargo targets; no same-worktree + overlap. Declare cross-worktree interference; never interrupt another owner. +6. Read the report template before each invocation; record exact metrics, limits, + arithmetic, commands and all outcomes in the campaign-owned ledger/receipts. +7. Default complete performance command ≤15 s; declared exceptions up to 25 s; + default independent proof <10 s. Frozen family/profile limits retain their + declared scope. No timeout/workload/cache changes to turn a miss into PASS. +8. Commit/capture/snapshot have one construction producer in normal wiring and + each measured operation; export `LAYERFS_CONSTRUCTION_WORKERS=1`. + Namespace Init alone retains its supported parallel construction profile. + A Commit's one producer runs on its own thread and hands objects through + one bounded queue to the calling thread, which keeps the one Save and + publishes (owner approval, 2026-11-07); see + [Commit construction](docs/architecture/engine/commit/construction.md). + No other helper/lane to pass a gate; FUSE dispatch is a separate concern. +9. Measure both speed and storage. Reject about 50% speed loss for about 5% + storage benefit; report raw deltas and preserve frozen-gate failures. ## 4. Code, build and docs -- **One attempted operation.** No automatic retry, busy handler, - refresh/reprepare or failed-operation replay; readiness waits are not - retries. Preserve exact failure, uncertainty and custody: no guessed resend, - deletion or success. -- **No test command runs longer than 2 minutes.** Build first (`--no-run`) so - compilation is not mistaken for a slow test, then run each selection under - an explicit wall timeout of at most 120 s, per package when the suite cannot - fit. Never leave a test running, background it to wait it out or wrap it in - a repeat loop. Reaching the ceiling is a FAILED hang: diagnose it from source - and bounded output before any rerun, and report it. Write tests that cannot - wait forever (bounded waits; a thread's exit must not depend on another - thread finishing without panicking). The §3 budgets stay stricter. -- **CI reports; it never gates** (owner, 2026-10-23). `.github/workflows/ci.yml` - runs fmt, guards, Clippy and the fast tests after a push or pull request, - `nightly.yml` the slow and FUSE mount tests, `format.yml` the Ruff check; - [tools/ci_tests.py](tools/ci_tests.py) picks the lanes. Neither `ci.yml` nor - `format.yml` runs for a pull request into `layerfs_v2_0_0` (owner, - 2026-11-07). Nothing runs before a push and nothing is required: do not wait - for CI or treat a green run as verification. Verify the changed scope with - the [product checks](engine/AGENTS.md#checks-and-completion) and report - checks and gaps. `tools/preflight.sh` stays retired; restore no equivalent - wrapper. An empty guard scan proves no implementation. -- **Refactors delete tests rather than nurse them** (owner, 2026-10-18). A test +- [The parallel worktree launcher](docs/general/parallel-worktrees.md) and + [the cleanup script](docs/general/cleanup.md) are optional local tools. Disk + thresholds, check cadence and standing cleanup authorization depend on the + machine; they belong in the user's own agent instructions, not in this file. +- Independent E2E runs own their writable Stores, SDK homes, containers and + traces. Preserve a test's intentional multi-daemon shared Store. +- Preserve unrelated work. Build the current core implementation, not legacy + aliases, source includes or error-driven substitutes. Keep platform cfgs. +- No new dependency if an existing crate supplies the capability. Never patch, + fork, vendor, replace or edit third-party code/registry packages. The explicit + exception is the owner's selected [fuser Git fork](engine/AGENTS.md#fuser-git-source): + use its pinned revision, not a local vendor, patch or registry substitute. + Use locked builds and report an incompatible required dependency with evidence. +- One attempted operation; no automatic retry/busy handler, refresh/reprepare + or failed-operation replay. Readiness waits are not retries. Preserve exact + failure/uncertainty and custody; no guessed resend, deletion or success. +- **CI reports; it never gates (owner, 2026-10-23).** GitHub Actions runs a + fast lane after each push or pull request (`.github/workflows/ci.yml`: fmt, + guards, Clippy and the fast tests) and a nightly lane (`nightly.yml`: slow and + FUSE mount tests); `format.yml` checks the Ruff formatting below. + Neither `ci.yml` nor `format.yml` runs for a pull request into + `layerfs_v2_0_0` (owner, 2026-11-07). + [tools/ci_tests.py](tools/ci_tests.py) decides which tests go in + which lane. None is a required check, and nothing runs before a push. Do + not wait for CI, and do not treat a green run as + verification of your change: verify the changed scope yourself with + [product checks](engine/AGENTS.md#checks-and-completion) and report checks/gaps. + There is still no pre-push gate: `tools/preflight.sh` stays retired; do not + restore it or an equivalent wrapper. An empty guard scan proves no + implementation. +- **Migrations and refactors delete tests rather than nurse them (owner, + 2026-10-18).** When code is moved, replaced or refactored, a test that is tricky to adapt (it drives a removed route, internal type or retired model, - or needs scaffolding the new design lacks) is deleted, not patched; keep or - move a test only when it checks surviving behaviour cheaply. Where a deleted - test guarded a fix or contract that still holds, cover it on the new code. - List deleted tests in the commit message and the pull request or issue. - Never weaken a surviving assertion to make it pass. -- **Dependencies.** No new dependency when an existing crate covers the need. - Never patch, fork, vendor, replace or edit third-party code or registry - packages; the one exception is the owner's - [fuser Git fork](engine/AGENTS.md#fuser-git-source) at its pinned revision. - Use locked builds; report an incompatible required dependency with evidence. -- **Build the current product.** Preserve unrelated work. Build the current - implementation, not legacy aliases, source includes or error-driven - substitutes; keep platform cfgs. Keep the - [repository ARM64 build inputs](.cargo/config.toml): explicit RUSTFLAGS - repeat the profile. -- **Claim only real guarantees.** Persistence profiles are scoped to their - Store. No `fsync`/`fdatasync`/`sync_data`/`sync_all` on disposable Workspace - backing and no space reserved ahead of use on it. Memory hints are not - evidence of resident bounds. -- **Independent E2E runs** own their writable Stores, SDK homes, containers and - traces; keep a test's intentional multi-daemon shared Store. -- **Source shape.** New core, engine, control and API production files obey - the 999-line and 200-line `lib.rs`/`mod.rs` ceilings in the - [engine guide](engine/AGENTS.md#production-file-size-and-responsibility). -- **Docs.** Update affected architecture and API documentation in the same - commit, as the [architecture doc update policy](docs/policy/architecture-doc-update.md) - sets out; keep proposal, research, implemented and measured claims distinct. - Format changed Python tools with Ruff (`ruff.toml` names the version, scope - and command). -- **Local tools are optional.** The - [parallel worktree launcher](docs/general/parallel-worktrees.md) and - [cleanup script](docs/general/cleanup.md) are local tools; disk thresholds, - check cadence and cleanup authorization belong in the user's own agent - instructions, not here. + or needs scaffolding the new design does not have) is deleted, not patched. + Keep or move a test only when it still checks surviving behaviour cheaply; + where a deleted test guarded a fix or contract that still holds, cover that + behaviour with a test on the new code. List deleted tests in the commit + message and the fix record (the pull request or issue; `core/docs/issues/` + no longer holds records). Never weaken a surviving test's assertion to + make it pass. +- **No test command runs longer than 2 minutes.** Give every test invocation an + explicit wall timeout of at most 120 s and stop it when it expires; never + leave one running, background it to wait it out, or wrap it in a repeat loop. + Build first (`--no-run`) so compilation is not mistaken for a slow test, and + select by package/test when the whole suite cannot fit. A test that reaches + the ceiling has FAILED as a hang: diagnose it from source and bounded output + before any rerun, and report it. Write tests so they cannot wait forever: + bounded waits, and a spawned thread's exit must not depend on another thread + finishing without panicking. This is a ceiling, not a target; the scoped + measurement and proof budgets in §3 stay stricter. +- Preserve [repository ARM64 build inputs](.cargo/config.toml); explicit + RUSTFLAGS must repeat the profile. Details are in the core guide. +- Persistence profiles are scoped to the store. Claim only their guarantees; + no `fsync`/`fdatasync`/`sync_data`/`sync_all` on disposable Workspace backing, + and no space is reserved ahead of use on it. + Memory hints are hints, not evidence of resident bounds. +- New core/engine/API production files obey the 999-line ceiling and 200-line + declaration/delegation ceiling for `lib.rs`/`mod.rs`. Product-only source, + external tests and guard coverage are detailed in the layer guides. +- Format changed Python tools with Ruff; `ruff.toml` names the pinned version, + scope and command. `format.yml` reports formatting drift after a push; + nothing runs before one. +- Update affected source architecture/API documentation with implementation + changes, in the same commit, as the + [architecture doc update policy](docs/policy/architecture-doc-update.md) + sets out. Keep proposal, research, implemented and measured claims distinct. ### Production LOC comparison for every commit -Every commit records **production lines of code before, after and the signed -delta**. It is a source-size comparison, not a performance claim. - -- **What counts:** nonblank, non-comment lines of first-party product - implementation, including shipped runtime SQL and other shipped - implementation outside Rust `src/`; imports, declarations and forwarding - count, and a line with code and a comment counts once. Tests (including - inline test modules and test-only branches), fixtures, mocks, examples, - benchmark harnesses, tools, docs, manifests, lockfiles, third-party code and - generated artifacts do not. Never use raw line totals or Git statistics. -- **What is compared:** the first parent against the committed tree (an empty - tree for an initial commit; the first parent for a merge, declared). Prepare - it from the parent and the final staged tree before committing, confirm the - commit matches, and exclude unstaged and untracked work. Recompute after an - amendment, rebase or any change to the staged source. -- **Same method both sides:** the same counter and version, scope, exclusions - and handling of inline test code; record the command. Review classification - when files move or new product paths appear; never drop code silently. -- **Honest migration:** while old and new implementations coexist, report each - total and the combined one; include application-adapter code. Label - relocation, duplication and retirement; a scope change or the reference's - deletion is not an algorithmic simplification. Report the reference as - `reference absent (retired R9c; last counted 65,417 at tree 498dd1917812)`, - never as a bare 0. -- **Report:** in the commit message and handoff, the headline - `Production LOC: -> (delta )`, then one - line for each of `core`, `engine`, `control` and `api` in that order, even - when unchanged, so they sum to the headline; after a changed scope, each - crate or package whose count moved with its delta. Then the reference line - and the method. Scopes and crates are the ones - `tools/production_loc.py --detail` prints. A move between scopes or crates - is labelled relocation. Several commits give one block each, plus one for - the range. A test or docs-only commit still reports the unchanged total and - delta 0. - - ```text - Production LOC: 163,645 -> 163,685 (delta +40) - core 39,787 -> 39,795 (+8) layerfs-history +8 - engine 74,997 -> 75,029 (+32) layerfs-persistence +7, layerfs-store-service +25 - control 42,777 -> 42,777 (0) - api 6,084 -> 6,084 (0) - reference absent (retired R9c; last counted 65,417 at tree 498dd1917812) - Method: tools/production_loc.py --detail on parent 99ffd262a3 and the staged tree - ``` - -Growth is allowed when the product change justifies it. Never remove required -validation, compress code into dense lines or move implementation out of scope -to improve the number, and never estimate it. +Every Git commit must record **production source lines of code before, after, +and the signed delta**. Test, documentation and tooling changes do not contribute +to this number. This is a source-size comparison, not a performance claim. + +- **Count production code only.** Count nonblank, non-comment source lines in + first-party LayerFS product implementation, including required runtime SQL or + other shipped implementation outside Rust src/ directories. Imports, declarations + and forwarding code count. Exclude tests (including legacy inline test modules + and test-only branches), fixtures, mocks, examples, benchmark harnesses, development + tools, docs, manifests/lockfiles, third-party code and generated build artifacts. + A line with both code and a comment counts once. Do not substitute raw file-line + totals or Git insertion/deletion statistics for production LOC. +- **Compare the exact commit snapshots.** Before is the commit's first parent; + after is the committed tree. Prepare the comparison from the parent and final + staged tree before committing, then confirm the resulting commit matches it. + Exclude unstaged/untracked work. Use an empty tree for an initial commit. For + merges declare the first-parent comparison; recompute after amendments/rebases + or any change to the staged source. +- **Keep counting reproducible.** Use the same counter/version, source scope, + exclusions and handling of inline test code for both snapshots. Record the + command/method with the comparison. Review source classification when files + move or new product paths appear; do not silently drop code from the count. + A counter that includes legacy inline tests does not satisfy this rule. +- **Report migration honestly.** While old and replacement implementations + coexist, report their production totals separately as well as the combined + total. Include application-adapter production code when introduced. Label + relocation, duplication and legacy retirement; do not call a scope change or + deletion of the reference an algorithmic simplification. Since R9c the + reference scope is absent: report it as `reference absent (retired R9c; last + counted 65,417 at tree 498dd1917812)`, never as a bare 0. +- **Put the result in the commit message and handoff.** Use + `Production LOC: -> (delta )`, with scope + and counting method, plus migration subtotals when applicable. For multiple + commits, give a comparison for each. A test/docs-only commit still reports + the unchanged production total and delta 0; it does not report a fictitious + zero-sized product or add test/documentation LOC to the headline. + +LOC growth is allowed when justified by the product change; this rule does not +require every commit to shrink. Never remove required validation, compress code +into dense lines, or move implementation outside the declared scope to improve +the number. Complete the comparison before committing; do not invent estimates. ### File and folder layout listings -A plan, handoff, review or reply that shows a source layout uses one vertical -listing per crate in a fenced `diff` block: +When a plan, handoff, review or reply shows a source layout, current or +planned, use one vertical listing per crate in a fenced `diff` block, so the +renderer highlights what changes: ```diff construction/ [793] @@ -402,20 +460,60 @@ listing per crate in a fenced `diff` block: + records.rs — ``` -- Column 1 is the marker: `+` a path that does not exist yet, `-` one this - change removes, a space one that stays (unchanged, edited or moved in; say - where from). A listing of the current tree has a space on every line. -- One path per line, two spaces per directory level; directories end in `/` - and list their files before their subdirectories; no joined siblings or - brace groups. -- Each existing file shows its production LOC from - `tools/production_loc.py --files` at a stated commit, right-aligned; each - directory shows the bracketed sum of the files listed beneath it, removed - files included (say so when only part is shown). A file that does not exist - shows `—` with `new` or `cond.` (added only if existing code cannot cover - the need); never an estimate. -- Annotations are short, in parentheses, after the number. State the commit, - counter and included crates above the listing. - -A listing is a snapshot: it does not make a planned name a requirement, and -the source and `Cargo.toml` still decide what is built. +- **Column 1 is the change marker, then one space, then the path.** `+` marks + a file or directory that does not exist yet (green); `-` marks one this + change removes (red); a space marks one that stays, whether unchanged, + edited in place or moved in (say where from in its annotation). A listing of + the current tree alone has a space on every line. +- **One path per line.** Indent two spaces per directory level. Directories end + in `/`; list a directory's own files before its subdirectories. Do not join + siblings on one line or use brace groups such as `{mod,cursor}.rs`. +- **Every existing file carries its production LOC**, right-aligned in one + column, from the pinned `tools/production_loc.py --files` at a stated commit. + This is the `prod` column, never physical lines or Git statistics. +- **Every directory carries its subtotal in brackets**, summing all listed + production files beneath it as they are at the stated commit, removed files + included. If only part of a directory is shown, say so in its annotation; + the bracketed number then covers only the files shown. +- **A file that does not exist yet shows `—`**, followed by `new` (planned) or + `cond.` (added only if existing code cannot cover the need). Never print an + estimated LOC for it. +- **Annotations are short, in parentheses, after the number**: what changes in + this step, or why the file is listed. Keep ownership rationale in prose. +- **State the scope above the listing**: the commit, the counter, and which + crates or directories are included. Tests live outside `src/` and are not + counted; name their directory in prose if it matters. + +A listing is a snapshot. It does not make a planned name a scaffolding +requirement, and an existing source file or `Cargo.toml` still decides +what is built. + +## 5. Why these rules exist (worked example) + +The historical cache-credit failure and its immutable ledger remain linked in +[the measurement workflow](docs/general/agent-measurement-policy.md#5-why-these-rules-exist-worked-example). +Historical explanation is retained outside default implementation routing. + + +All product layers follow the detailed +[production source rules](engine/AGENTS.md#production-file-size-and-responsibility) +and [checks and completion rules](engine/AGENTS.md#checks-and-completion). +The root manifest builds four core crates, ten engine crates, eight control +crates under `control/crates` (the entity crates `layerfs-home`, +`layerfs-machine`, `layerfs-store` and `layerfs-sandbox` with its +`workspace/` module; the drivers `layerfs-platform`, `layerfs-bucket` and +`layerfs-sandbox-backend`; and `layerfs-control`) and four API crates under +`api/crates`: the call surface `layerfs-api`, the `layerfs` command +`layerfs-cli`, the Node binding `layerfs-node` and the PyO3 module +`layerfs-python`. `api/` also holds the published JavaScript and Python +packages. The control layer (`control/crates`, renamed from `connect/` by the +owner 2026-11-06, layerfs-project#101 D-6; #535 D4) holds the management code +and the crates that reach a machine or the network; see the +[control guide](control/AGENTS.md). The dependency +direction is `core < engine < control < api`, including dev dependencies and +test includes; nothing in engine depends on control. Workstream names do not change this layering. +After rebasing across #463, update each selected worktree's own target registration and prepare again +for the root `target/` path; never migrate another worktree's resource record. +After rebasing across #686 (fuser from its Git fork), or any later fuser `rev` change, run +`tools/worktree.py prepare` again for each platform before offline builds; a Cargo +home prepared earlier has no checkout of that revision and fails `--offline`. diff --git a/Cargo.lock b/Cargo.lock index 3ba6ad4ac3..94c8fbe9fe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -999,6 +999,7 @@ dependencies = [ "layerfs-telemetry", "libc", "nix", + "postgres", ] [[package]] diff --git a/api/AGENTS.md b/api/AGENTS.md index 98364bacbb..195063987f 100644 --- a/api/AGENTS.md +++ b/api/AGENTS.md @@ -21,9 +21,7 @@ public surface: `node/layerfs.node` by `scripts/build-native.mjs`; the package loads that file or the one `LAYERFS_NATIVE` names, nothing else. - `crates/layerfs-python`: the PyO3 module `layerfs._native`. -- `node/`: the SDK for Node, `@layerfs/node`. -- `cli/`: the `layerfs` command's package, `@layerfs/cli`. -- `mcp/`: the MCP server over stdio, `@layerfs/mcp` (private). +- `node/`: the one published JavaScript package, `layerfs`. - `python/`: the Python package `layerfs`. The packages are thin shells over the table: each function is one library @@ -43,12 +41,12 @@ ordinary daemon binary before running tests that launch it. `LAYERFS_TEST_DAEMON` may select an explicit binary; otherwise the tests locate the sibling Cargo output. The owner keeps `layerfs-node` out of CI. -API code follows the engine guide's +All API product code follows the [production size and responsibility rules](../engine/AGENTS.md#production-file-size-and-responsibility) -and [checks](../engine/AGENTS.md#checks-and-completion), and the root guide's -[rules you must not break](../AGENTS.md#rules-you-must-not-break). Preserve the -existing unsafe-code boundaries; do not add test hooks or inline tests to -production src. +and [checks and completion rules](../engine/AGENTS.md#checks-and-completion), +including bounded test commands, build-before-run, locked dependencies, ARM64 +flags, per-commit LOC and the Disposable-only profile. Preserve the existing +unsafe-code boundaries; do not add test hooks or inline tests to production src. Do not add a call, argument or result name in JavaScript: change the call's entry in `crates/layerfs-api/src//.rs` and the package follows. `layerfs-api/src` holds only `lib.rs`, the call machinery `calls/` (table @@ -56,4 +54,5 @@ shape, checks, scope, keys, dispatcher, `Context`; layerfs-project#107) and one folder per family: its `mod.rs` (the family's calls in help order) and one file per call (its table entry and the function that runs it: one call of a control crate's per-op function, never an op name as a string). A -test pins this shape (`tests/calls_table.rs`). +test pins this shape (`tests/calls_table.rs`). CI reports and does not gate a +push. diff --git a/api/README.md b/api/README.md index c7329db066..ae3d5d2bc8 100644 --- a/api/README.md +++ b/api/README.md @@ -10,7 +10,7 @@ CLI package `@layerfs/cli` (in [`cli/`](cli)), the Python package (in the private stdio MCP server [`mcp/`](mcp) (`@layerfs/mcp`: one generated tool per call, `work` and `admin` profiles). The design is in [docs/architecture/api](../docs/architecture/api/README.md). The package is the -library's call table as ten families of functions, 73 calls in all: +library's call table as ten families of functions, 76 calls in all: | Family | Calls | | --- | --- | diff --git a/api/crates/layerfs-api/src/branch/mod.rs b/api/crates/layerfs-api/src/branch/mod.rs index d4e4632dd6..bc4b6b5b7c 100644 --- a/api/crates/layerfs-api/src/branch/mod.rs +++ b/api/crates/layerfs-api/src/branch/mod.rs @@ -1,4 +1,4 @@ -//! The `branch` family: 8 calls, one file each. +//! The `branch` family: 9 calls, one file each. mod commits; mod diff; mod fork; @@ -7,6 +7,7 @@ mod get_commit; mod list; mod merge; mod publish; +mod remove; use crate::calls::Calls; @@ -21,5 +22,6 @@ pub(crate) fn calls() -> Calls { merge::CALL, publish::CALL, diff::CALL, + remove::CALL, ] } diff --git a/api/crates/layerfs-api/src/branch/publish.rs b/api/crates/layerfs-api/src/branch/publish.rs index 521fc4bad4..97faa7cfaf 100644 --- a/api/crates/layerfs-api/src/branch/publish.rs +++ b/api/crates/layerfs-api/src/branch/publish.rs @@ -1,5 +1,5 @@ //! `branch.publish`: a Branch's head or Commit as main's next Layer. -use crate::calls::table::Kind::{Bool, Name, Project}; +use crate::calls::table::Kind::{Name, Project}; use crate::calls::table::{a, call, opt, Call}; use crate::calls::Context; use layerfs_bridge::control::SdkValue; @@ -15,12 +15,8 @@ pub(crate) const CALL: Call = call( a("branch", Name), opt("commit", Name), ], - &[ - opt("expected_base", Name), - opt("expected_head", Name), - opt("force", Bool), - ], - "a Branch's head or Commit as main's next Layer, refusing a stale base", + &[], + "a Branch's head or Commit as main's next Layer", run, ); @@ -31,9 +27,6 @@ fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { project: text("project").unwrap_or_default(), branch: text("branch").unwrap_or_default(), commit: text("commit"), - expected_base: text("expected_base"), - expected_head: text("expected_head"), - force: args.get("force").map(|_| args.get_bool("force")), }; let (home, events) = context.parts(); publish(home, events, &request) diff --git a/api/crates/layerfs-api/src/branch/remove.rs b/api/crates/layerfs-api/src/branch/remove.rs new file mode 100644 index 0000000000..e9279cbd84 --- /dev/null +++ b/api/crates/layerfs-api/src/branch/remove.rs @@ -0,0 +1,28 @@ +//! `branch.remove`: soft-remove one Branch through its Store marker. +use crate::calls::table::Kind::{Name, Project}; +use crate::calls::table::{a, call, Call}; +use crate::calls::Context; +use layerfs_bridge::control::SdkValue; +use layerfs_home::outcome::Outcome; +use layerfs_store::calls::branch::{remove, BranchRemove}; + +/// Its table entry. +pub(crate) const CALL: Call = call( + "branch", + "remove", + &[a("project", Project), a("branch", Name)], + &[], + "soft-remove one Branch; its name stays taken until compaction", + run, +); + +/// Runs `branch.remove`. +fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { + let text = |name: &str| args.get_text(name).map(str::to_owned); + let request = BranchRemove { + project: text("project").unwrap_or_default(), + branch: text("branch").unwrap_or_default(), + }; + let (home, events) = context.parts(); + remove(home, events, &request) +} diff --git a/api/crates/layerfs-api/src/calls/mod.rs b/api/crates/layerfs-api/src/calls/mod.rs index 45c32f6583..e90eae9b74 100644 --- a/api/crates/layerfs-api/src/calls/mod.rs +++ b/api/crates/layerfs-api/src/calls/mod.rs @@ -2,7 +2,7 @@ //! table's shape, argument checks, folder scope, result keys and the one //! dispatcher with its call log line (`render`, #659); moved back from //! `layerfs-control` by layerfs-project#107. -//! The 70 entries in ten families live beside it, one folder per family and +//! The 76 entries in ten families live beside it, one folder per family and //! one file per call; each function here that needs them takes that list. mod check; mod context; @@ -18,6 +18,7 @@ pub use check::size; pub use context::Context; pub use dispatch::{call, call_scoped, home, Client}; pub use layerfs_home::json; +pub use render::REDACTED; pub use scope::Scope; pub use table::{find, table_json, Arg, Call, CallRef, Calls, Families, Family, Kind, Run}; pub use text::call_json; diff --git a/api/crates/layerfs-api/src/calls/render.rs b/api/crates/layerfs-api/src/calls/render.rs index 87d904246a..c82fc1054d 100644 --- a/api/crates/layerfs-api/src/calls/render.rs +++ b/api/crates/layerfs-api/src/calls/render.rs @@ -9,9 +9,46 @@ use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::outcome::Outcome; /// The `Text` arguments logged only as ``: exec command text, -/// Commit messages, edit strings, Store passwords and connection URLs that -/// may embed `user:pass@`. A new call with such an argument adds its name. -pub const REDACTED: [&str; 6] = ["command", "message", "old", "new", "password", "url"]; +/// Commit messages, edit strings, Store passwords, connection URLs that may +/// embed `user:pass@`, every path argument (`path`, `left_path`, +/// `right_path`, `from_path`, `to_path`, `path_prefix`) and a glob or grep +/// `pattern`. A path is counted in its normalized form ([`PATHS`]), so a +/// `project.remove_file` or `file.*` path never enters the call log (#41 +/// §4.3). A new call with such an argument adds its name. +pub const REDACTED: [&str; 13] = [ + "command", + "message", + "old", + "new", + "password", + "url", + "path", + "left_path", + "right_path", + "from_path", + "to_path", + "path_prefix", + "pattern", +]; + +/// The arguments that name a path: they log the length of the normalized +/// path, one leading `/` stripped, so `/a` and `a` count the same and a root +/// `/` counts as 0 (#41 §4.3). A `pattern` is not a path and keeps every +/// byte it has. +const PATHS: [&str; 6] = [ + "path", + "left_path", + "right_path", + "from_path", + "to_path", + "path_prefix", +]; + +/// A path argument's logged byte length: the §4.3 normalization (strip one +/// leading `/`) applied before counting. +fn path_len(text: &str) -> usize { + text.strip_prefix('/').unwrap_or(text).len() +} /// The most characters a logged value keeps. const CUT: usize = 200; @@ -46,6 +83,7 @@ fn word(name: &str, kind: Kind, value: &SdkValue) -> Option { (Kind::Content, SdkValue::Text(text)) => bytes(text.len()), (Kind::Content, SdkValue::Bytes(raw)) => bytes(raw.len()), (Kind::Content | Kind::Json, value) => bytes(layerfs_home::json::print(value).len()), + (Kind::Text, SdkValue::Text(text)) if PATHS.contains(&name) => bytes(path_len(text)), (Kind::Text, SdkValue::Text(text)) if REDACTED.contains(&name) => bytes(text.len()), (_, SdkValue::Text(text)) => SdkValue::Text(cut(text)), (_, SdkValue::Int(n)) => SdkValue::Text(n.to_string()), @@ -187,3 +225,56 @@ pub fn line( } SdkValue::Map(fields) } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn every_path_argument_name_is_redacted() { + for name in [ + "path", + "left_path", + "right_path", + "from_path", + "to_path", + "path_prefix", + "pattern", + ] { + assert!(REDACTED.contains(&name), "{name} is not redacted"); + } + for name in ["project", "branch", "name", "commit", "content", "changes"] { + assert!(!REDACTED.contains(&name), "{name} is redacted"); + } + } + + #[test] + fn a_path_logs_the_byte_length_of_its_normalized_form() { + // `/a` and `a` are the same path (§4.3), so they log the same count; + // the root `/` normalizes to the empty relative path. + for (text, len) in [ + ("/base.txt", 8), + ("base.txt", 8), + ("/a", 1), + ("a", 1), + ("/", 0), + ] { + let value = SdkValue::text(text); + assert_eq!( + word("path", Kind::Text, &value), + Some(SdkValue::text(format!("<{len} bytes>"))), + "{text}" + ); + } + // A glob pattern is not a path and keeps every byte it has. + assert_eq!( + word("pattern", Kind::Text, &SdkValue::text("*.txt")), + Some(SdkValue::text("<5 bytes>")) + ); + // Text that is not a path is still its own (cut) text. + assert_eq!( + word("branch", Kind::Text, &SdkValue::text("/main")), + Some(SdkValue::text("/main")) + ); + } +} diff --git a/api/crates/layerfs-api/src/calls/scope.rs b/api/crates/layerfs-api/src/calls/scope.rs index c7c81b6b2c..bdb139bf60 100644 --- a/api/crates/layerfs-api/src/calls/scope.rs +++ b/api/crates/layerfs-api/src/calls/scope.rs @@ -151,6 +151,11 @@ impl Scope { | ("file", "revision") => { return Err(out("history")); } + // GC retires or compacts a whole entity, never one folder: + // a scope refuses these instead of widening them (§10). + ("branch", "remove") | ("project", "delete" | "remove_file") | ("store", "compact") => { + return Err(out(name)); + } ("file", _) => { bound(&args)?; let paths: &[&str] = match call { diff --git a/api/crates/layerfs-api/src/lib.rs b/api/crates/layerfs-api/src/lib.rs index 0d2b610fe9..83c1d4676b 100644 --- a/api/crates/layerfs-api/src/lib.rs +++ b/api/crates/layerfs-api/src/lib.rs @@ -71,7 +71,7 @@ pub use layerfs_sandbox::{ BoundWorkspace, MountFailure, MountedWorkspace, Unmounted, WorkspaceApi, }; -/// The ten families, in the order help lists them: 73 calls, the same +/// The ten families, in the order help lists them: 76 calls, the same /// from the `layerfs` binary, Node and Python. pub fn families() -> Families { &[ diff --git a/api/crates/layerfs-api/src/project/delete.rs b/api/crates/layerfs-api/src/project/delete.rs new file mode 100644 index 0000000000..9afba64e3f --- /dev/null +++ b/api/crates/layerfs-api/src/project/delete.rs @@ -0,0 +1,24 @@ +//! `project.delete`: retire one project in its Store and remove its home entry. +use crate::calls::table::Kind::Project; +use crate::calls::table::{a, call, Call}; +use crate::calls::Context; +use layerfs_bridge::control::SdkValue; +use layerfs_home::names::ProjectRef; +use layerfs_home::outcome::Outcome; + +/// Its table entry. +pub(crate) const CALL: Call = call( + "project", + "delete", + &[a("project", Project)], + &[], + "retire one project in its Store and remove its home entry", + run, +); + +/// Runs `project.delete`. +fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { + let project = ProjectRef::parse(args.get_text("project").unwrap_or(""))?; + let (home, events) = context.parts(); + layerfs_control::project::delete(home, events, &project) +} diff --git a/api/crates/layerfs-api/src/project/mod.rs b/api/crates/layerfs-api/src/project/mod.rs index 03b79a3597..caee164cb7 100644 --- a/api/crates/layerfs-api/src/project/mod.rs +++ b/api/crates/layerfs-api/src/project/mod.rs @@ -1,9 +1,10 @@ -//! The `project` family: 6 calls, one file each. +//! The `project` family: 7 calls, one file each. +mod delete; mod export; mod get; mod init; mod list; -mod remove; +mod remove_file; mod stats; use crate::calls::Calls; @@ -16,6 +17,7 @@ pub(crate) fn calls() -> Calls { get::CALL, stats::CALL, export::CALL, - remove::CALL, + delete::CALL, + remove_file::CALL, ] } diff --git a/api/crates/layerfs-api/src/project/remove_file.rs b/api/crates/layerfs-api/src/project/remove_file.rs new file mode 100644 index 0000000000..3c8d4f2176 --- /dev/null +++ b/api/crates/layerfs-api/src/project/remove_file.rs @@ -0,0 +1,29 @@ +//! `project.remove_file`: hide one absolute path from every node at or below +//! its marker frontier. +use crate::calls::table::Kind::{Project, Text}; +use crate::calls::table::{a, call, Call}; +use crate::calls::Context; +use layerfs_bridge::control::SdkValue; +use layerfs_home::outcome::Outcome; +use layerfs_store::calls::project::{remove_file, ProjectRemoveFile}; + +/// Its table entry. +pub(crate) const CALL: Call = call( + "project", + "remove_file", + &[a("project", Project), a("path", Text)], + &[], + "hide one absolute path from every node at or below its marker frontier", + run, +); + +/// Runs `project.remove_file`. +fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { + let text = |name: &str| args.get_text(name).map(str::to_owned); + let request = ProjectRemoveFile { + project: text("project").unwrap_or_default(), + path: text("path").unwrap_or_default(), + }; + let (home, events) = context.parts(); + remove_file(home, events, &request) +} diff --git a/api/crates/layerfs-api/src/store/compact.rs b/api/crates/layerfs-api/src/store/compact.rs new file mode 100644 index 0000000000..dc8a044d3b --- /dev/null +++ b/api/crates/layerfs-api/src/store/compact.rs @@ -0,0 +1,24 @@ +//! `store.compact`: reclaim dead bytes from one sqlite Store. +use crate::calls::table::Kind::Name; +use crate::calls::table::{a, call, Call}; +use crate::calls::Context; +use layerfs_bridge::control::SdkValue; +use layerfs_home::names::StoreName; +use layerfs_home::outcome::Outcome; + +/// Its table entry. +pub(crate) const CALL: Call = call( + "store", + "compact", + &[a("name", Name)], + &[], + "reclaim dead bytes from one sqlite Store", + run, +); + +/// Runs `store.compact`. +fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { + let name = StoreName::parse(args.get_text("name").unwrap_or(""))?; + let (home, events) = context.parts(); + layerfs_control::store::compact(home, events, &name) +} diff --git a/api/crates/layerfs-api/src/store/mod.rs b/api/crates/layerfs-api/src/store/mod.rs index 8c0df7b57c..2142e041ea 100644 --- a/api/crates/layerfs-api/src/store/mod.rs +++ b/api/crates/layerfs-api/src/store/mod.rs @@ -1,6 +1,7 @@ -//! The `store` family: 12 calls, one file each (H1: push and pull replace +//! The `store` family: 13 calls, one file each (H1: push and pull replace //! move; attach and detach supersede #536 C4). mod attach; +mod compact; mod connect; mod create; mod detach; @@ -29,6 +30,7 @@ pub(crate) fn calls() -> Calls { push::CALL, pull::CALL, remove::CALL, + compact::CALL, disconnect::CALL, ] } diff --git a/api/crates/layerfs-api/tests/calls_scope.rs b/api/crates/layerfs-api/tests/calls_scope.rs index 11d9b26286..28d19e6e6d 100644 --- a/api/crates/layerfs-api/tests/calls_scope.rs +++ b/api/crates/layerfs-api/tests/calls_scope.rs @@ -114,7 +114,16 @@ fn a_scope_refuses_every_call_it_does_not_cover() { let uncovered: &[(&str, &[(&str, SdkValue)])] = &[ ("store.remove", &[("name", t("shop"))]), ("store.list", &[]), - ("project.remove", &[("project", t("shop/api"))]), + ( + "branch.remove", + &[("project", t("shop/api")), ("branch", t("main"))], + ), + ("project.delete", &[("project", t("shop/api"))]), + ( + "project.remove_file", + &[("project", t("shop/api")), ("path", t("/web/a"))], + ), + ("store.compact", &[("name", t("shop"))]), ( "project.init", &[("project", t("shop/x")), ("folder", t("/tmp"))], diff --git a/api/crates/layerfs-api/tests/calls_table.rs b/api/crates/layerfs-api/tests/calls_table.rs index bdebadb78d..0f329039b2 100644 --- a/api/crates/layerfs-api/tests/calls_table.rs +++ b/api/crates/layerfs-api/tests/calls_table.rs @@ -1,4 +1,4 @@ -//! The call table and its dispatcher (#533 step 2): 73 calls in ten +//! The call table and its dispatcher (#533 step 2): 76 calls in ten //! families, arguments checked before any effect, one test per family that //! a valid call reaches its family function and a wrong one is refused. use layerfs_api::{families, json, keys, size, Call, Kind}; @@ -51,9 +51,9 @@ fn code(name: &str, args: SdkValue) -> String { } #[test] -fn the_table_has_ten_families_and_73_calls() { +fn the_table_has_ten_families_and_76_calls() { let all: Vec<&Call> = layerfs_api::calls(); - assert_eq!(all.len(), 73); + assert_eq!(all.len(), 76); // each family holds only its own calls, and has at least one for family in families() { assert!(!family.calls().is_empty(), "{}", family.name); @@ -66,7 +66,7 @@ fn the_table_has_ten_families_and_73_calls() { let mut names: Vec<_> = all.iter().map(|c| c.name()).collect(); names.sort(); names.dedup(); - assert_eq!(names.len(), 73, "call names are unique"); + assert_eq!(names.len(), 76, "call names are unique"); // an optional positional is only ever followed by optional ones (D7) for c in &all { let first_optional = c.args.iter().position(|a| a.optional); @@ -75,7 +75,7 @@ fn the_table_has_ten_families_and_73_calls() { } } let counts: Vec = families().iter().map(|f| f.calls().len()).collect(); - assert_eq!(counts, [6, 8, 3, 15, 4, 6, 12, 12, 5, 2]); + assert_eq!(counts, [7, 9, 3, 15, 4, 6, 12, 13, 5, 2]); } #[test] @@ -98,6 +98,17 @@ fn unknown_calls_and_arguments_are_refused_before_any_effect() { .starts_with("InvalidInput")); } +#[test] +fn project_remove_is_retired() { + // spec 4: the hard delete leaves the table; a caller gets `InvalidInput` + // naming it, never a silent hard delete + assert!(layerfs_api::find("project.remove").is_none()); + assert_eq!( + code("project.remove", map(&[("project", t("shop/api"))])), + "InvalidInput: no call named `project.remove`" + ); +} + #[test] fn project_family() { assert!(code("project.get", map(&[("project", t("api"))])) @@ -139,97 +150,6 @@ fn branch_family() { assert!(!reached.starts_with("InvalidInput"), "{reached}"); } -#[test] -fn branch_publish_declares_its_expected_base_options() { - // The shell, Node and Python front ends build their arguments from this - // table, so these options (and their shapes) are the CLI's and SDK's. - let call = layerfs_api::calls() - .into_iter() - .find(|call| call.family == "branch" && call.call == "publish") - .expect("branch.publish is in the table"); - let declared: Vec<(&str, Kind, bool)> = call - .options - .iter() - .map(|option| (option.name, option.kind, option.optional)) - .collect(); - assert_eq!( - declared, - vec![ - ("expected_base", Kind::Name, true), - ("expected_head", Kind::Name, true), - ("force", Kind::Bool, true), - ] - ); - assert_eq!( - call.help, - "a Branch's head or Commit as main's next Layer, refusing a stale base" - ); -} - -#[test] -fn branch_publish_expectations_are_plumbed() { - for (name, value, why) in [ - ( - "expected_base", - SdkValue::Int(1), - "`expected_base` must be text", - ), - ( - "expected_base", - SdkValue::Bool(true), - "`expected_base` must be text", - ), - ( - "expected_head", - SdkValue::Bool(true), - "`expected_head` must be text", - ), - ( - "expected_head", - SdkValue::Int(1), - "`expected_head` must be text", - ), - ("force", t("yes"), "`force` must be true or false"), - ("force", SdkValue::Int(1), "`force` must be true or false"), - ] { - let refused = code( - "branch.publish", - map(&[ - ("project", t("shop/api")), - ("branch", t("work")), - (name, value), - ]), - ); - assert!(refused.contains(why), "{name}: {refused}"); - } - // A misspelled option is not read as an argument of the call. - let typo = code( - "branch.publish", - map(&[ - ("project", t("shop/api")), - ("branch", t("work")), - ("expectedBase", t("00")), - ]), - ); - assert!( - typo.starts_with("InvalidInput: branch.publish: unknown argument `expectedBase`"), - "{typo}" - ); - // A well-shaped expectation reaches the call instead of being refused by - // argument checking. - let reached = code( - "branch.publish", - map(&[ - ("project", t("shop/api")), - ("branch", t("work")), - ("expected_base", t("00")), - ("expected_head", t("00")), - ("force", SdkValue::Bool(true)), - ]), - ); - assert!(!reached.starts_with("InvalidInput"), "{reached}"); -} - #[test] fn commit_family() { assert!(code( @@ -535,3 +455,28 @@ fn sandbox_images_are_named_by_the_image_kind() { assert!(prune.args[1].optional); assert_eq!(prune.options[0].name, "unused"); } + +#[test] +fn the_four_gc_calls_take_only_ids() { + // T11.1: the four GC calls, each one resource identifier and no option. + use layerfs_api::Kind; + let expected: &[(&str, &[(&str, Kind)])] = &[ + ( + "branch.remove", + &[("project", Kind::Project), ("branch", Kind::Name)], + ), + ("project.delete", &[("project", Kind::Project)]), + ( + "project.remove_file", + &[("project", Kind::Project), ("path", Kind::Text)], + ), + ("store.compact", &[("name", Kind::Name)]), + ]; + for &(name, args) in expected { + let spec = layerfs_api::find(name).unwrap_or_else(|| panic!("{name} is missing")); + let given: Vec<(&str, Kind)> = spec.args.iter().map(|arg| (arg.name, arg.kind)).collect(); + assert_eq!(given.as_slice(), args, "{name}"); + assert!(spec.args.iter().all(|arg| !arg.optional), "{name}"); + assert!(spec.options.is_empty(), "{name} takes no option"); + } +} diff --git a/api/crates/layerfs-api/tests/gc_calls.rs b/api/crates/layerfs-api/tests/gc_calls.rs new file mode 100644 index 0000000000..ad390c8eab --- /dev/null +++ b/api/crates/layerfs-api/tests/gc_calls.rs @@ -0,0 +1,351 @@ +//! T11.1: the four GC calls in the API call table — their ids-only arguments, +//! typed refusals before any effect, and the result shapes of one reachable +//! refusal per call plus the three removal results and the §11 report. +use layerfs_api::Kind; +use layerfs_bridge::control::SdkValue; +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "layerfs-gc-calls-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap(); + dir +} + +fn t(s: &str) -> SdkValue { + SdkValue::text(s) +} + +fn map(fields: &[(&str, SdkValue)]) -> SdkValue { + SdkValue::Map( + fields + .iter() + .map(|(name, value)| ((*name).to_owned(), value.clone())) + .collect(), + ) +} + +fn call( + home: &Path, + name: &str, + fields: &[(&str, SdkValue)], +) -> Result { + layerfs_api::call(Some(home), name, map(fields), &mut |_| {}) + .map_err(|refusal| (refusal.code, refusal.message)) +} + +fn ok(home: &Path, name: &str, fields: &[(&str, SdkValue)]) -> SdkValue { + call(home, name, fields).unwrap_or_else(|refusal| panic!("{name}: {refusal:?}")) +} + +fn refused(home: &Path, name: &str, fields: &[(&str, SdkValue)]) -> (String, String) { + call(home, name, fields).expect_err("the call is refused") +} + +/// A home with Store `shop` and project `shop/api` imported from a folder. +fn project() -> (PathBuf, PathBuf) { + let home = tempdir("home"); + layerfs_api::home::open(&home).unwrap(); + let folder = tempdir("folder"); + std::fs::write(folder.join("base.txt"), "hello\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + (home, folder) +} + +fn p() -> (&'static str, SdkValue) { + ("project", t("shop/api")) +} + +#[test] +fn the_four_gc_calls_take_ids_only() { + let expected: &[(&str, &[(&str, Kind)])] = &[ + ( + "branch.remove", + &[("project", Kind::Project), ("branch", Kind::Name)], + ), + ("project.delete", &[("project", Kind::Project)]), + ( + "project.remove_file", + &[("project", Kind::Project), ("path", Kind::Text)], + ), + ("store.compact", &[("name", Kind::Name)]), + ]; + for &(name, args) in expected { + let spec = layerfs_api::find(name).unwrap_or_else(|| panic!("{name} is missing")); + let given: Vec<(&str, Kind)> = spec.args.iter().map(|arg| (arg.name, arg.kind)).collect(); + assert_eq!(given.as_slice(), args, "{name} arguments"); + assert!(spec.args.iter().all(|arg| !arg.optional), "{name} required"); + assert!(spec.options.is_empty(), "{name} has no options"); + } +} + +#[test] +fn wrong_kinds_and_unknown_options_are_refused_before_any_effect() { + let home = tempdir("types"); + layerfs_api::home::open(&home).unwrap(); + let wrong: &[(&str, &[(&str, SdkValue)])] = &[ + ( + "branch.remove", + &[("project", t("shop/api")), ("branch", SdkValue::Int(1))], + ), + ("project.delete", &[("project", SdkValue::Int(1))]), + ( + "project.remove_file", + &[("project", t("shop/api")), ("path", SdkValue::Int(1))], + ), + ("store.compact", &[("name", SdkValue::Int(1))]), + ]; + for &(name, fields) in wrong { + let (code, message) = refused(&home, name, fields); + assert_eq!(code, "InvalidInput", "{name}: {message}"); + assert!(message.starts_with(name), "{name}: {message}"); + } + let unknown: &[(&str, &[(&str, SdkValue)])] = &[ + ( + "branch.remove", + &[ + ("project", t("shop/api")), + ("branch", t("main")), + ("force", SdkValue::Bool(true)), + ], + ), + ( + "project.delete", + &[("project", t("shop/api")), ("force", SdkValue::Bool(true))], + ), + ( + "project.remove_file", + &[ + ("project", t("shop/api")), + ("path", t("/base.txt")), + ("force", SdkValue::Bool(true)), + ], + ), + ( + "store.compact", + &[("name", t("shop")), ("force", SdkValue::Bool(true))], + ), + ]; + for &(name, fields) in unknown { + let (code, message) = refused(&home, name, fields); + assert_eq!(code, "InvalidInput", "{name}: {message}"); + assert!( + message.contains("unknown argument `force`"), + "{name}: {message}" + ); + } + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn branch_remove_refuses_reserved_and_absent_branches() { + let (home, folder) = project(); + let (code, message) = refused(&home, "branch.remove", &[p(), ("branch", t("main"))]); + assert_eq!(code, "ReservedName", "{message}"); + // nothing ran: main is still there + ok(&home, "branch.get", &[p(), ("branch", t("main"))]); + let (code, message) = refused(&home, "branch.remove", &[p(), ("branch", t("ghost"))]); + assert_eq!(code, "NoSuchBranch", "{message}"); + // a live Branch is hidden by the marker and reported as `Removed` + ok( + &home, + "branch.fork", + &[p(), ("name", t("work")), ("from_branch", t("main"))], + ); + let removed = ok(&home, "branch.remove", &[p(), ("branch", t("work"))]); + assert_eq!(removed.get_text("kind"), Some("Removed")); + // the project is the caller's /, not the Store's inner name + assert_eq!(removed.get_text("project"), Some("shop/api")); + assert_eq!(removed.get_text("branch"), Some("work")); + assert!(removed.get_int("removed_ms").is_some_and(|ms| ms >= 0)); + let (code, message) = refused(&home, "branch.get", &[p(), ("branch", t("work"))]); + assert_eq!(code, "NoSuchBranch", "{message}"); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +#[test] +fn project_remove_file_checks_its_path_grammar_then_reports_markers() { + let (home, folder) = project(); + for bad in [ + "", "/", "//a", "a//b", "a/", "./a", "a/./b", ".", "..", "\\", + ] { + let (code, message) = refused(&home, "project.remove_file", &[p(), ("path", t(bad))]); + assert_eq!(code, "InvalidInput", "{bad:?}: {message}"); + } + // no effect: the file the bad calls named is still readable + let read = ok( + &home, + "file.read", + &[p(), ("branch", t("main")), ("path", t("/base.txt"))], + ); + assert_eq!(read.get_text("text"), Some("hello\n")); + + let removed = ok( + &home, + "project.remove_file", + &[p(), ("path", t("/base.txt"))], + ); + assert_eq!(removed.get_text("kind"), Some("Removed")); + // the same full project name the caller passed + assert_eq!(removed.get_text("project"), Some("shop/api")); + assert!(removed.get_int("frontier_serial").is_some()); + assert!(removed.get_int("removed_ms").is_some_and(|ms| ms >= 0)); + // a repeat at the same frontier is UpToDate + let repeat = ok( + &home, + "project.remove_file", + &[p(), ("path", t("/base.txt"))], + ); + assert_eq!(repeat.get_text("kind"), Some("UpToDate")); + assert_eq!( + repeat.get_int("frontier_serial"), + removed.get_int("frontier_serial") + ); + // the marker hides it from reads + let (code, message) = refused( + &home, + "file.read", + &[p(), ("branch", t("main")), ("path", t("/base.txt"))], + ); + assert_eq!(code, "Removed", "{message}"); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +#[test] +fn project_delete_reports_removal_and_retires_the_entry() { + let (home, folder) = project(); + let (code, message) = refused(&home, "project.delete", &[("project", t("shop/ghost"))]); + assert_eq!(code, "NoSuchProject", "{message}"); + let removed = ok(&home, "project.delete", &[p()]); + assert_eq!(removed.get_text("kind"), Some("Removed")); + assert_eq!(removed.get_text("project"), Some("shop/api")); + assert!(removed.get_int("deleted_ms").is_some_and(|ms| ms >= 0)); + assert!(removed.get_bool("home_entry_removed")); + let (code, _) = refused(&home, "project.get", &[p()]); + assert_eq!(code, "NoSuchProject"); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +/// A project name a `project.delete` retired is still held: a second +/// `project.init` is `NameTaken` with the `deleted` holder, refused before +/// the folder is scanned. +#[test] +fn project_init_after_delete_is_nametaken_deleted() { + let (home, folder) = project(); + ok(&home, "project.delete", &[p()]); + let refusal = layerfs_api::call( + Some(&home), + "project.init", + map(&[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ]), + &mut |_| {}, + ) + .unwrap_err(); + assert_eq!(refusal.code, "NameTaken", "{}", refusal.message); + let holder = refusal.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project"), "{refusal:?}"); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("deleted")); + assert_eq!(refusal.detail.get_text("source"), Some("store")); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +#[test] +fn store_compact_refuses_an_unknown_store_and_reports_a_run() { + let home = tempdir("compact-none"); + layerfs_api::home::open(&home).unwrap(); + let (code, message) = refused(&home, "store.compact", &[("name", t("ghost"))]); + assert_eq!(code, "NoSuchStore", "{message}"); + std::fs::remove_dir_all(home).unwrap(); + + let (home, folder) = project(); + let report = ok(&home, "store.compact", &[("name", t("shop"))]); + assert_eq!(report.get_text("kind"), Some("Compacted")); + let path = report.get_text("path").expect("path"); + assert!(matches!(path, "none" | "rebuild"), "{path}"); + let generation = report.get("generation").expect("generation"); + let before = generation.get_int("before").unwrap(); + let after = generation.get_int("after").unwrap(); + if path == "none" { + assert_eq!(before, after); + } else { + assert_eq!(after, before + 1); + } + for field in [ + "dead_bytes_bound", + "dead_bytes_refined", + "logical_discarded", + "backend_reusable", + "physical_shrink", + "peak_temp_bytes", + "estimate", + "zero_reasons", + "kept_waste", + "residue", + ] { + assert!(report.get(field).is_some(), "missing {field}"); + } + let kept = report.get("kept_waste").expect("kept_waste"); + for field in [ + "dead_in_retained_packs_bytes", + "delta_bases", + "inode_blocks_bytes", + ] { + assert!(kept.get(field).is_some(), "missing kept_waste.{field}"); + } + let residue = report.get("residue").expect("residue"); + assert!(residue.get("bytes").is_some()); + assert!(residue.get("artifacts").is_some()); + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +#[test] +fn a_bare_project_name_is_refused_by_every_project_call() { + let home = tempdir("bare-names"); + layerfs_api::home::open(&home).unwrap(); + let bare: &[(&str, &[(&str, SdkValue)])] = &[ + ( + "branch.remove", + &[("project", t("api")), ("branch", t("main"))], + ), + ("project.delete", &[("project", t("api"))]), + ( + "project.remove_file", + &[("project", t("api")), ("path", t("/base.txt"))], + ), + ]; + for &(name, fields) in bare { + let (code, message) = refused(&home, name, fields); + assert_eq!(code, "InvalidInput", "{name}: {message}"); + assert!(message.contains("with its Store"), "{name}: {message}"); + } + // store.compact takes a Store name; a project path is not one + let (code, message) = refused(&home, "store.compact", &[("name", t("shop/api"))]); + assert_eq!(code, "InvalidInput", "{message}"); + assert!(message.contains("store name"), "{message}"); + std::fs::remove_dir_all(home).unwrap(); +} diff --git a/api/crates/layerfs-api/tests/gc_trace.rs b/api/crates/layerfs-api/tests/gc_trace.rs new file mode 100644 index 0000000000..a3cb2144c2 --- /dev/null +++ b/api/crates/layerfs-api/tests/gc_trace.rs @@ -0,0 +1,309 @@ +//! T-G2: the call log redacts every path argument (#41 §4.3). A +//! `project.remove_file` or a hidden `file.read`/`stat`/`list`/`glob` path is +//! logged as `` of its normalized form (one leading `/` stripped), +//! the `Removed` refusal still echoes the request path, the salted trace key +//! changes with the salt, and a `store.compact` report's artifact names never +//! reach the log. +use layerfs_api::calls::REDACTED; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_history::path::{path_key, trace_key}; +use layerfs_history::LayerStackId; +use layerfs_home::home::paths; +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Mutex, MutexGuard}; + +static ENV: Mutex<()> = Mutex::new(()); +static NEXT: AtomicU64 = AtomicU64::new(0); + +/// The tests share the process environment, so each one holds this lock. +fn serial() -> MutexGuard<'static, ()> { + let guard = ENV.lock().unwrap_or_else(|poison| poison.into_inner()); + std::env::remove_var("LAYERFS_LOGS"); + std::env::remove_var("LAYERFS_LOGS_TAG"); + guard +} + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "layerfs-gc-trace-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap(); + dir +} + +fn t(s: &str) -> SdkValue { + SdkValue::text(s) +} + +fn map(fields: &[(&str, SdkValue)]) -> SdkValue { + SdkValue::Map( + fields + .iter() + .map(|(name, value)| ((*name).to_owned(), value.clone())) + .collect(), + ) +} + +fn call(home: &Path, name: &str, fields: &[(&str, SdkValue)]) -> Result { + layerfs_api::call(Some(home), name, map(fields), &mut |_| {}) +} + +fn ok(home: &Path, name: &str, fields: &[(&str, SdkValue)]) -> SdkValue { + call(home, name, fields).unwrap_or_else(|refusal| panic!("{name}: {refusal:?}")) +} + +fn refused(home: &Path, name: &str, fields: &[(&str, SdkValue)]) -> SdkRefusal { + call(home, name, fields).expect_err("the call is refused") +} + +fn p() -> (&'static str, SdkValue) { + ("project", t("shop/api")) +} + +/// A home with Store `shop` and project `shop/api` imported from a folder +/// holding `base.txt`. +fn project() -> (PathBuf, PathBuf) { + let home = tempdir("home"); + layerfs_api::home::open(&home).unwrap(); + let folder = tempdir("folder"); + std::fs::write(folder.join("base.txt"), "hello\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + (home, folder) +} + +/// Every line of the call log, oldest first. +fn lines(home: &Path) -> Vec { + match std::fs::read_to_string(paths::calls_file(home)) { + Ok(text) => text + .lines() + .map(|line| layerfs_api::json::parse(line).unwrap()) + .collect(), + Err(_) => Vec::new(), + } +} + +fn last(home: &Path) -> SdkValue { + lines(home).pop().expect("a line") +} + +fn log_text(home: &Path) -> String { + std::fs::read_to_string(paths::calls_file(home)).unwrap_or_default() +} + +fn argv(line: &SdkValue) -> Vec { + match line.get("argv") { + Some(SdkValue::List(words)) => words + .iter() + .map(|word| match word { + SdkValue::Text(text) => text.clone(), + other => panic!("argv word {other:?}"), + }) + .collect(), + other => panic!("no argv: {other:?}"), + } +} + +fn bytes(n: usize) -> String { + format!("<{n} bytes>") +} + +/// The one path a `Removed` refusal details. +fn removed_path(refusal: &SdkRefusal) -> &str { + let Some(SdkValue::List(paths)) = refusal.detail.get("paths") else { + panic!("no paths detail: {:?}", refusal.detail); + }; + paths + .first() + .and_then(|path| path.get_text("path")) + .expect("one path") +} + +#[test] +fn path_arguments_are_byte_counts_in_the_call_log() { + let _env = serial(); + let (home, folder) = project(); + let removed = ok( + &home, + "project.remove_file", + &[p(), ("path", t("/base.txt"))], + ); + assert_eq!(removed.get_text("kind"), Some("Removed")); + assert_eq!( + argv(&last(&home)), + [ + "project".to_owned(), + "remove-file".into(), + "shop/api".into(), + bytes("base.txt".len()), + ] + ); + + // Hidden reads, stats, listings and globs: a path is a byte count. + let read = refused( + &home, + "file.read", + &[p(), ("branch", t("main")), ("path", t("/base.txt"))], + ); + assert_eq!(read.code, "Removed"); + assert_eq!( + argv(&last(&home)), + [ + "file".to_owned(), + "read".into(), + "shop/api".into(), + "main".into(), + bytes("base.txt".len()), + ] + ); + let stat = refused( + &home, + "file.stat", + &[p(), ("branch", t("main")), ("path", t("/base.txt"))], + ); + assert_eq!(stat.code, "Removed"); + assert_eq!(argv(&last(&home))[4], bytes("base.txt".len())); + + let listed = ok( + &home, + "file.list", + &[p(), ("branch", t("main")), ("path", t("/"))], + ); + assert_eq!(listed.get_int("removed_count"), Some(1)); + assert_eq!(argv(&last(&home))[4], bytes(0)); + + let globbed = ok( + &home, + "file.glob", + &[ + p(), + ("branch", t("main")), + ("path", t("/")), + ("pattern", t("*.txt")), + ], + ); + assert_eq!(globbed.get_int("removed_count"), Some(1)); + let words = argv(&last(&home)); + assert_eq!(words[4], bytes(0)); + assert_eq!(words[5], bytes("*.txt".len())); + + let text = log_text(&home); + assert!(!text.contains("/base.txt"), "raw path in the log:\n{text}"); + assert!(!text.contains("base.txt"), "raw path in the log:\n{text}"); + std::fs::remove_dir_all(home).unwrap(); + std::fs::remove_dir_all(folder).unwrap(); +} + +#[test] +fn a_removed_refusal_echoes_the_path_the_log_does_not() { + let _env = serial(); + let (home, folder) = project(); + ok( + &home, + "project.remove_file", + &[p(), ("path", t("/base.txt"))], + ); + let refusal = refused( + &home, + "file.read", + &[p(), ("branch", t("main")), ("path", t("/base.txt"))], + ); + assert_eq!(refusal.code, "Removed"); + assert_eq!(removed_path(&refusal), "/base.txt"); + let line = last(&home); + assert_eq!(line.get_text("outcome"), Some("Removed")); + assert!(line.get("detail").is_none(), "a detail reached the log"); + let text = log_text(&home); + assert!(!text.contains("/base.txt")); + assert!(!text.contains("base.txt")); + std::fs::remove_dir_all(home).unwrap(); + std::fs::remove_dir_all(folder).unwrap(); +} + +#[test] +fn the_redacted_set_covers_every_path_bearing_call() { + for name in [ + "path", + "left_path", + "right_path", + "from_path", + "to_path", + "path_prefix", + "pattern", + ] { + assert!(REDACTED.contains(&name), "{name} is not redacted"); + } + for (name, args) in [ + ("project.remove_file", &["path"][..]), + ("file.read", &["path"][..]), + ("file.stat", &["path"][..]), + ("file.list", &["path"][..]), + ("file.glob", &["path", "pattern"][..]), + ("file.diff", &["left_path", "right_path"][..]), + ("file.cp", &["from_path", "to_path"][..]), + ("file.mv", &["from_path", "to_path"][..]), + ("branch.diff", &["path_prefix"][..]), + ] { + let spec = layerfs_api::find(name).unwrap_or_else(|| panic!("{name} is missing")); + for arg in args { + assert!(spec.arg(arg).is_some(), "{name} has no {arg}"); + assert!(REDACTED.contains(arg), "{name}'s {arg} is not redacted"); + } + } + // text that is not a path stays visible + for name in ["project", "branch", "name", "commit", "content", "changes"] { + assert!(!REDACTED.contains(&name), "{name} is redacted"); + } +} + +#[test] +fn the_trace_key_is_salted_by_the_store_policy_salt() { + let _env = serial(); + let stack = LayerStackId::from_authority([7; 16]); + let path = b"a/b"; + let first = trace_key(&[1; 32], stack, path); + assert_eq!(first, trace_key(&[1; 32], stack, path), "stable salt"); + let second = trace_key(&[2; 32], stack, path); + assert_ne!(first, second, "a different salt changes the keyed hash"); + assert_eq!(first.len(), 32); + // the keyed hash is not the marker's plain BLAKE3(normalized path) + assert_ne!(first, path_key(path)); + // the stack is part of the key + let other = LayerStackId::from_authority([9; 16]); + assert_ne!(first, trace_key(&[1; 32], other, path)); +} + +#[test] +fn store_compact_artifact_names_never_reach_the_log() { + let _env = serial(); + let (home, folder) = project(); + let report = ok(&home, "store.compact", &[("name", t("shop"))]); + assert_eq!(report.get_text("kind"), Some("Compacted")); + assert_eq!( + argv(&last(&home)), + ["store".to_owned(), "compact".into(), "shop".into()] + ); + let text = log_text(&home); + assert!( + !text.contains(".compact"), + "an artifact name reached the log:\n{text}" + ); + let store = paths::store_file(&home, "shop"); + let name = store.file_name().unwrap().to_string_lossy().into_owned(); + assert!(!text.contains(&name), "the Store file name reached the log"); + std::fs::remove_dir_all(home).unwrap(); + std::fs::remove_dir_all(folder).unwrap(); +} diff --git a/api/crates/layerfs-api/tests/home_layout_3.rs b/api/crates/layerfs-api/tests/home_layout_3.rs index 63eade8633..b9ff16fe24 100644 --- a/api/crates/layerfs-api/tests/home_layout_3.rs +++ b/api/crates/layerfs-api/tests/home_layout_3.rs @@ -87,11 +87,20 @@ fn home_with(tag: &str, extra: &[(&str, SdkValue)]) -> PathBuf { let home = tempdir(tag); home::open(&home).unwrap(); call(&home, "store.create", &[("name", t("shop"))]).unwrap(); - write_record( - &paths::project_record(&home, "shop", "app"), - &SdkValue::map([("name", t("app")), ("created", SdkValue::Int(1))]), + // a real project, so the §4.2 home↔Store intersection lists and gets it + // across the conversion + let source = tempdir(&format!("{tag}-source")); + std::fs::write(source.join("README.md"), "app\n").unwrap(); + call( + &home, + "project.init", + &[ + ("project", t("shop/app")), + ("folder", t(&source.display().to_string())), + ], ) .unwrap(); + let _ = std::fs::remove_dir_all(source); write_record( &paths::machine_record(&home, "dev"), &SdkValue::map([ diff --git a/api/crates/layerfs-api/tests/logs.rs b/api/crates/layerfs-api/tests/logs.rs index 5fdbf68dbf..cbb0f9cc44 100644 --- a/api/crates/layerfs-api/tests/logs.rs +++ b/api/crates/layerfs-api/tests/logs.rs @@ -181,21 +181,19 @@ fn argv_has_positionals_options_flags_and_the_scope_before_it_rewrites() { ("page_size", SdkValue::Int(5)), ], ); - assert_eq!( - argv(&last(&home)), - [ - "file", - "diff", - "shop/api", - "main", - "/README.md", - "main", - "/README.md", - "--allow-missing", - "--page-size", - "5" - ] - ); + let want: Vec = vec![ + "file".into(), + "diff".into(), + "shop/api".into(), + "main".into(), + bytes("README.md".len()), + "main".into(), + bytes("README.md".len()), + "--allow-missing".into(), + "--page-size".into(), + "5".into(), + ]; + assert_eq!(argv(&last(&home)), want); // optional positionals stop at the first absent one let _ = call(&home, "backup.list", &[]); assert_eq!(argv(&last(&home)), ["backup", "list"]); @@ -266,7 +264,7 @@ fn free_text_credentials_content_and_json_are_byte_counts() { "write".into(), "shop/api".into(), "dev".into(), - "/a.ts".into(), + bytes("a.ts".len()), bytes(5321), "--message".into(), bytes(5) @@ -283,16 +281,22 @@ fn free_text_credentials_content_and_json_are_byte_counts() { ], ); assert_eq!(argv(&last(&home))[5], bytes(7)); - // text is cut at 200 characters + // a path argument is logged as its byte length, never its text let long = format!("/{}", "é".repeat(300)); let _ = call( &home, "file.stat", &[p(), ("branch", t("main")), ("path", t(&long))], ); - let path = &argv(&last(&home))[4]; - assert_eq!(path.chars().count(), 201); - assert!(path.ends_with('…')); + // a path logs the length of its normalized form: one leading `/` is + // stripped, so this path counts 600 bytes, not 601 + assert_eq!(argv(&last(&home))[4], bytes(long.len() - 1)); + // text that is not redacted is cut at 200 characters + let long = "n".repeat(300); + let _ = call(&home, "store.get", &[("name", t(&long))]); + let name = &argv(&last(&home))[2]; + assert_eq!(name.chars().count(), 201); + assert!(name.ends_with('…')); // each named text argument let _ = call( &home, diff --git a/api/crates/layerfs-api/tests/project_export.rs b/api/crates/layerfs-api/tests/project_export.rs index 85ef103334..07a79b982c 100644 --- a/api/crates/layerfs-api/tests/project_export.rs +++ b/api/crates/layerfs-api/tests/project_export.rs @@ -1283,7 +1283,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { // 2. During an in-flight `project.export`: // - same-Store `file.read` and a second concurrent `project.export` succeed; // - exclusive Store operations (`store.remove`, `store.push`) are refused `InUse`; - // - `project.remove` drops the catalog stack while packs stay (`packs_kept: true`), + // - `project.delete` retires the Stack (its marker keeps packs/objects), // leaving the in-flight pinned export intact while refusing later exports. let first_dest = area.join("first"); let second_dest = area.join("second"); @@ -1336,10 +1336,14 @@ fn shared_store_lease_and_concurrent_remove_admission() { .unwrap_err(); assert_eq!(push_code, "InUse", "{push_msg}"); - // `project.remove` drops the LayerStack while keeping packs/objects; - // the already-pinned export continues without corruption. - let removed = ok(&home, "project.remove", &[("project", t("shop/app"))]); - assert_eq!(removed.get("packs_kept"), Some(&SdkValue::Bool(true))); + // `project.delete` retires the LayerStack and removes the home + // entry; the already-pinned export continues without corruption. + let removed = ok(&home, "project.delete", &[("project", t("shop/app"))]); + assert_eq!(removed.get_text("kind"), Some("Removed")); + assert_eq!( + removed.get("home_entry_removed"), + Some(&SdkValue::Bool(true)) + ); } }, ) @@ -1350,7 +1354,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { assert_same_tree(&source, &second_dest); let _ = std::fs::remove_file(&other_lease); - // After `project.remove`, a new export is refused `NoSuchProject` + // After `project.delete`, a new export is refused `NoSuchProject` let after_rm_dest = area.join("after-rm"); let (code, _) = call( &home, @@ -1364,12 +1368,13 @@ fn shared_store_lease_and_concurrent_remove_admission() { assert_eq!(code, "NoSuchProject"); assert!(!after_rm_dest.exists()); - // Re-init `shop/app` and verify Store-level `Busy` and `Unresolved` admission + // Re-init a new project (`shop/app` stays a retired name) and verify + // Store-level `Busy` and `Unresolved` admission. ok( &home, "project.init", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("folder", t(&source.display().to_string())), ], ); @@ -1394,7 +1399,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { &home, "project.export", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("destination", t(&busy_dest.display().to_string())), ], ) @@ -1419,7 +1424,7 @@ fn shared_store_lease_and_concurrent_remove_admission() { &home, "project.export", &[ - ("project", t("shop/app")), + ("project", t("shop/app2")), ("destination", t(&busy_dest.display().to_string())), ], ) @@ -1600,3 +1605,73 @@ fn export_progress_events_follow_time_not_entry_count() { let _ = std::fs::remove_dir_all(d); } } + +#[test] +fn export_omits_a_path_hidden_by_remove_file() { + let home = private_home("removed-home"); + ok(&home, "store.create", &[("name", t("shop"))]); + let source = tempdir("removed-src"); + std::fs::write(source.join("a.txt"), "a\n").unwrap(); + std::fs::write(source.join("b.txt"), "b\n").unwrap(); + std::fs::create_dir(source.join("dir")).unwrap(); + std::fs::write(source.join("dir/c.txt"), "c\n").unwrap(); + ok( + &home, + "project.init", + &[ + ("project", t("shop/app")), + ("folder", t(&source.display().to_string())), + ], + ); + + // The marker is written through the Store engine, the route the fs calls + // use; `project.remove_file` is not on this crate's call table yet. + layerfs_store::service::with_service( + &layerfs_store::open_args::OpenArgs { + home: Some(home.clone()), + store: Some("shop".to_owned()), + store_path: Some(paths::store_file(&home, "shop").display().to_string()), + ..Default::default() + }, + |service| { + let call = layerfs_bridge::control::SdkCall { + method: "project.remove_file".to_owned(), + args: SdkValue::map([ + ("project", t("app")), + ("path", t("/a.txt")), + ]), + }; + layerfs_store_service::methods::call(service, &call) + }, + ) + .unwrap(); + + let out_parent = tempdir("removed-out"); + let dest = out_parent.join("exported"); + let res = ok( + &home, + "project.export", + &[ + ("project", t("shop/app")), + ("destination", t(&dest.display().to_string())), + ], + ); + + // §4.3: a hidden entry is omitted from the exported folder and counts. + assert!( + !dest.join("a.txt").exists(), + "a hidden path must not be exported" + ); + assert_eq!(std::fs::read_to_string(dest.join("b.txt")).unwrap(), "b\n"); + assert_eq!( + std::fs::read_to_string(dest.join("dir/c.txt")).unwrap(), + "c\n" + ); + assert_eq!(res.get_int("files"), Some(2)); + assert_eq!(res.get_int("directories"), Some(1)); + assert_eq!(res.get_int("symlinks"), Some(0)); + + for d in [home, source, out_parent] { + let _ = std::fs::remove_dir_all(d); + } +} diff --git a/api/crates/layerfs-api/tests/project_family.rs b/api/crates/layerfs-api/tests/project_family.rs index fc4ba41bc0..3039230e5a 100644 --- a/api/crates/layerfs-api/tests/project_family.rs +++ b/api/crates/layerfs-api/tests/project_family.rs @@ -3,7 +3,7 @@ //! it, the Store pushed to a worker machine and read there, then the project //! removed. use layerfs_api::home::{self, paths, write_record}; -use layerfs_bridge::control::SdkValue; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; use std::net::TcpListener; use std::path::{Path, PathBuf}; @@ -335,7 +335,15 @@ fn init_files_branches_move_and_remove() { ); assert_eq!(content(&read), "newer\n", "read through the worker"); - ok(&home, "project.remove", &[p()]); + // `project.delete` retires the project in the Store under `box` and + // removes both entries; its history stays until a compaction. + let deleted = ok(&home, "project.delete", &[p()]); + assert_eq!(deleted.get_text("kind"), Some("Removed")); + assert_eq!(deleted.get_text("project"), Some("shop/api")); + assert_eq!( + deleted.get("home_entry_removed"), + Some(&SdkValue::Bool(true)) + ); assert_eq!( call(&home, "project.get", &[p()]).unwrap_err().0, "NoSuchProject" @@ -389,3 +397,174 @@ fn a_private_home_may_be_passable_and_nothing_more() { std::fs::remove_dir_all(home).unwrap(); let _ = std::fs::remove_dir_all(folder); } + +fn refused(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> SdkRefusal { + let args = SdkValue::Map( + args.iter() + .map(|(n, v)| ((*n).to_owned(), v.clone())) + .collect(), + ); + layerfs_api::call(Some(home), name, args, &mut |_| {}).expect_err("the call is refused") +} + +fn private_home(tag: &str) -> PathBuf { + let home = tempdir(tag); + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(&home, std::fs::Permissions::from_mode(0o700)).unwrap(); + home::open(&home).unwrap(); + home +} + +/// A `project.init` name collision is the typed `NameTaken`: the home record +/// first, and the Store's own holder when the home has no record for it. +#[test] +fn project_init_name_collision_reports_holder_and_source() { + let home = private_home("name-taken"); + let folder = tempdir("name-taken-folder"); + std::fs::write(folder.join("README"), b"held\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + + let home_taken = refused( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + assert_eq!(home_taken.code, "NameTaken", "{}", home_taken.message); + let holder = home_taken.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project")); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(home_taken.detail.get_text("source"), Some("home")); + + // A home that no longer records the project meets the Store's own holder. + std::fs::remove_dir_all(paths::project_dir(&home, "shop", "api")).unwrap(); + let store_taken = refused( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + assert_eq!(store_taken.code, "NameTaken", "{}", store_taken.message); + let holder = store_taken.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project")); + assert_eq!(holder.get_text("name"), Some("api")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(store_taken.detail.get_text("source"), Some("store")); + + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} + +/// A Layer keeps the name of the Branch it was published from after that +/// Branch is retired: provenance rendering is not a caller-facing lookup. +#[test] +fn a_retired_source_branch_still_renders_on_its_layers() { + let home = private_home("retired-source"); + let folder = tempdir("retired-source-folder"); + std::fs::write(folder.join("base.txt"), b"base\n").unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + ok( + &home, + "project.init", + &[ + ("project", t("shop/api")), + ("folder", t(&folder.display().to_string())), + ], + ); + ok( + &home, + "branch.fork", + &[ + ("project", t("shop/api")), + ("name", t("work")), + ("from_branch", t("main")), + ], + ); + ok( + &home, + "file.write", + &[ + ("project", t("shop/api")), + ("branch", t("work")), + ("path", t("/new.txt")), + ("content", t("new\n")), + ("message", t("new")), + ], + ); + ok( + &home, + "branch.publish", + &[("project", t("shop/api")), ("branch", t("work"))], + ); + + let main = ok( + &home, + "commit.list", + &[("project", t("shop/api")), ("branch", t("main"))], + ); + let SdkValue::List(layers) = main.get("items").expect("items") else { + panic!("{main:?}") + }; + let id = layers[0].get_text("id").expect("layer id").to_owned(); + assert_eq!(layers[0].get_text("source_branch"), Some("work"), "{main:?}"); + + ok( + &home, + "branch.remove", + &[("project", t("shop/api")), ("branch", t("work"))], + ); + + // `layer.list` still renders the provenance ... + let main = ok( + &home, + "commit.list", + &[("project", t("shop/api")), ("branch", t("main"))], + ); + let SdkValue::List(layers) = main.get("items").expect("items") else { + panic!("{main:?}") + }; + assert_eq!( + layers[0].get_text("source_branch"), + Some("work"), + "layer.list: {main:?}" + ); + // ... and so does `layer.get` ... + let got = ok( + &home, + "commit.get", + &[ + ("project", t("shop/api")), + ("branch", t("main")), + ("commit", t(&id)), + ], + ); + assert_eq!( + got.get_text("source_branch"), + Some("work"), + "layer.get: {got:?}" + ); + // ... while a caller-facing lookup of the retired Branch stays refused. + let (code, message) = call( + &home, + "branch.get", + &[("project", t("shop/api")), ("branch", t("work"))], + ) + .unwrap_err(); + assert_eq!(code, "NoSuchBranch", "{message}"); + + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(folder); +} diff --git a/api/crates/layerfs-api/tests/project_init_worker.rs b/api/crates/layerfs-api/tests/project_init_worker.rs index d0f3900c4b..07b805b32d 100644 --- a/api/crates/layerfs-api/tests/project_init_worker.rs +++ b/api/crates/layerfs-api/tests/project_init_worker.rs @@ -231,14 +231,19 @@ fn init_into_a_worker_s_store_copies_the_caller_s_folder() { let stat = store_call(&home, "file.stat", "shop/web", "/link"); assert_eq!(stat.get_text("type"), Some("symlink"), "{stat:?}"); - let again = call( - &home, + let again = layerfs_api::call( + Some(&home), "project.init", init_args("shop/web", &folder), &mut |_| {}, ) .unwrap_err(); - assert_eq!(again.0, "Exists", "{}", again.1); + assert_eq!(again.code, "NameTaken", "{}", again.message); + let holder = again.detail.get("holder").expect("holder detail"); + assert_eq!(holder.get_text("kind"), Some("project"), "{again:?}"); + assert_eq!(holder.get_text("name"), Some("web")); + assert_eq!(holder.get_text("state"), Some("live")); + assert_eq!(again.detail.get_text("source"), Some("home")); open_up(&folder); let (missing, plain) = (missing.parent().unwrap(), plain.parent().unwrap()); diff --git a/api/crates/layerfs-api/tests/project_list_intersection.rs b/api/crates/layerfs-api/tests/project_list_intersection.rs new file mode 100644 index 0000000000..64532d6cbc --- /dev/null +++ b/api/crates/layerfs-api/tests/project_list_intersection.rs @@ -0,0 +1,141 @@ +//! project.list and project.get intersect the home's project entries with +//! the Store's filtered listing (spec §4.2): a home entry whose Store +//! project is retired (hidden) or absent is not listed, and project.get +//! answers it `NoSuchProject`; a live project still lists and gets. +use layerfs_api::home::{self, paths, write_record}; +use layerfs_bridge::control::SdkValue; +use layerfs_bridge::sdk_values::{hex, unhex}; +use layerfs_history::LayerStackId; +use layerfs_store::open_args::OpenArgs; +use layerfs_store::project::record::ProjectRecord; +use layerfs_store::record::StoreRecord; +use layerfs_store::service::with_service; +use layerfs_store_service::history::deletion::delete_stack; +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; + +static NEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "layerfs-project-intersection-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, std::sync::atomic::Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +fn t(s: &str) -> SdkValue { + SdkValue::text(s) +} + +fn call(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> Result { + let args = SdkValue::Map( + args.iter() + .map(|(n, v)| ((*n).to_owned(), v.clone())) + .collect(), + ); + layerfs_api::call(Some(home), name, args, &mut |_| {}).map_err(|r| (r.code, r.message)) +} + +fn ok(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> SdkValue { + call(home, name, args).unwrap_or_else(|e| panic!("{name}: {e:?}")) +} + +/// Marks Store project `name` hidden, as the project.delete write path will +/// (T4.5b); the home entry stays, exactly the stale case §4.2 hides. +fn retire(home: &Path, store: &str, name: &str, stack: &str) { + let record = StoreRecord::read(home, store).unwrap().unwrap(); + let open = OpenArgs { + home: Some(home.to_path_buf()), + store: Some(store.to_owned()), + project: Some(name.to_owned()), + store_path: Some(paths::store_file(home, store).display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + }; + let stack = LayerStackId::from_slice(&unhex(stack).unwrap()).unwrap(); + with_service(&open, |service| { + delete_stack(&service.store, stack, 1234).unwrap(); + Ok(SdkValue::Null) + }) + .unwrap(); +} + +#[test] +fn a_retired_or_absent_store_project_is_not_listed_or_got() { + let home = tempdir("home"); + std::fs::set_permissions(&home, std::fs::Permissions::from_mode(0o700)).unwrap(); + home::open(&home).unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + let source = tempdir("folder"); + std::fs::write(source.join("README.md"), "live\n").unwrap(); + let init = |name: &str| { + ok( + &home, + "project.init", + &[ + ("project", t(&format!("shop/{name}"))), + ("folder", t(&source.display().to_string())), + ], + ) + }; + init("live"); + init("retired"); + let retired = ProjectRecord::read(&home, "shop", "retired") + .unwrap() + .expect("the retired entry"); + let retired_stack = hex(&retired.stack().expect("the entry's manifest stack")); + retire(&home, "shop", "retired", &retired_stack); + + // A home entry whose Store project is absent: a second home's stale + // record, or a failed home-entry removal. Its stack is not in the Store. + let absent = LayerStackId::from_authority([9; 16]).to_bytes(); + write_record( + &paths::project_record(&home, "shop", "absent"), + &SdkValue::map([ + ("name", t("absent")), + ("stack", t(&hex(&absent))), + ("created", SdkValue::Int(1)), + ]), + ) + .unwrap(); + + // Only the live project lists; the retired and absent entries do not. + let list = ok(&home, "project.list", &[]); + let SdkValue::List(items) = list.get("items").unwrap() else { + panic!("{list:?}") + }; + let names: Vec<&str> = items.iter().filter_map(|i| i.get_text("name")).collect(); + assert_eq!(names, vec!["live"]); + // the named listing intersects the same way + let one = ok(&home, "project.list", &[("store", t("shop"))]); + let SdkValue::List(items) = one.get("items").unwrap() else { + panic!("{one:?}") + }; + let names: Vec<&str> = items.iter().filter_map(|i| i.get_text("name")).collect(); + assert_eq!(names, vec!["live"]); + // both stale home entries are still there; the Store, not the home, hides them + for name in ["retired", "absent"] { + assert!(paths::project_record(&home, "shop", name).exists(), "{name}"); + } + + // project.get refuses a hidden project even with its home entry present, + // and an entry the Store does not hold. + for name in ["retired", "absent"] { + let (code, message) = call( + &home, + "project.get", + &[("project", t(&format!("shop/{name}")))], + ) + .unwrap_err(); + assert_eq!(code, "NoSuchProject", "{name}: {message}"); + } + let live = ok(&home, "project.get", &[("project", t("shop/live"))]); + assert_eq!(live.get_text("project"), Some("shop/live")); + + std::fs::remove_dir_all(home).unwrap(); + let _ = std::fs::remove_dir_all(source); +} diff --git a/api/crates/layerfs-api/tests/project_list_worker.rs b/api/crates/layerfs-api/tests/project_list_worker.rs new file mode 100644 index 0000000000..484c17b261 --- /dev/null +++ b/api/crates/layerfs-api/tests/project_list_worker.rs @@ -0,0 +1,296 @@ +//! project.list and project.get on a worker-backed Store (T4.5c): the +//! listing is the Store's own filtered one, read in the machine's worker +//! (the same `layerfs_project::store::projects` a local Store uses), so a +//! project retired there is not listed and is `NoSuchProject` from +//! project.get; a live project still lists and gets, and a worker's refusal +//! is the call's. +use layerfs_api::home::{self, paths, write_record}; +use layerfs_bridge::control::SdkValue; +use layerfs_bridge::sdk_values::hex; +use layerfs_history::LayerStackId; +use layerfs_machine::worker::{self, read_frame, read_frame_within, write_frame, Hello, MAX_HELLO}; +use layerfs_store::open_args::OpenArgs; +use layerfs_store::project::record::ProjectRecord; +use layerfs_store::record::StoreRecord; +use layerfs_store::service::with_service; +use layerfs_store_service::history::deletion::delete_stack; +use std::net::TcpListener; +use std::os::unix::fs::PermissionsExt; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "lfs-list-worker-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +fn t(s: &str) -> SdkValue { + SdkValue::text(s) +} + +fn call(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> Result { + let args = SdkValue::Map( + args.iter() + .map(|(n, v)| ((*n).to_owned(), v.clone())) + .collect(), + ); + layerfs_api::call(Some(home), name, args, &mut |_| {}).map_err(|r| (r.code, r.message)) +} + +fn ok(home: &Path, name: &str, args: &[(&str, SdkValue)]) -> SdkValue { + call(home, name, args).unwrap_or_else(|e| panic!("{name}: {e:?}")) +} + +fn names(list: &SdkValue) -> Vec { + let SdkValue::List(items) = list.get("items").unwrap() else { + panic!("{list:?}") + }; + items + .iter() + .filter_map(|item| item.get_text("name")) + .map(str::to_owned) + .collect() +} + +/// Marks Store project `stack` retired (the `project.delete` write path, +/// T4.5b): the Store hides it, its home entry stays. +fn retire(home: &Path, store: &str, stack: &[u8]) { + let record = StoreRecord::read(home, store).unwrap().unwrap(); + let open = OpenArgs { + home: Some(home.to_path_buf()), + store: Some(store.to_owned()), + project: None, + store_path: Some(paths::store_file(home, store).display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + }; + let stack = LayerStackId::from_slice(stack).unwrap(); + with_service(&open, |service| { + delete_stack(&service.store, stack, 1234).unwrap(); + Ok(SdkValue::Null) + }) + .unwrap(); +} + +/// Moves Store `store`'s file from `from`'s Store folder to `to`'s. +fn move_store_file(from: &Path, to: &Path, store: &str) { + let source = paths::store_dir(from, store); + let target = paths::store_dir(to, store); + home::private_dir(&target).unwrap(); + for entry in std::fs::read_dir(&source).unwrap() { + let entry = entry.unwrap(); + let name = entry.file_name().to_string_lossy().into_owned(); + if name.starts_with("store.sqlite") { + std::fs::rename(entry.path(), target.join(&name)).unwrap(); + } + } +} + +/// The Store record of `store` places it on machine `machine`. +fn place_store(home: &Path, store: &str, machine: &str) { + let record_path = paths::store_record(home, store); + let record = home::read_record(&record_path).unwrap().unwrap(); + let record = home::with_field(record, "machine", t(machine)); + write_record(&record_path, &record).unwrap(); +} + +/// A home whose Store `shop` holds `live` and `retired`, the latter retired +/// in the Store, and whose machine `box` record names `listener` as its +/// worker; `shop`'s calls run on `box`. With `root`, the Store's file is +/// moved under the worker's root. +fn shop_on_box(tag: &str, listener: &TcpListener, root: Option<&Path>) -> PathBuf { + let home = tempdir(tag); + std::fs::set_permissions(&home, std::fs::Permissions::from_mode(0o700)).unwrap(); + home::open(&home).unwrap(); + ok(&home, "store.create", &[("name", t("shop"))]); + let source = tempdir(&format!("{tag}-folder")); + std::fs::write(source.join("README.md"), "live\n").unwrap(); + for name in ["live", "retired"] { + ok( + &home, + "project.init", + &[ + ("project", t(&format!("shop/{name}"))), + ("folder", t(&source.display().to_string())), + ], + ); + } + let retired = ProjectRecord::read(&home, "shop", "retired") + .unwrap() + .expect("the retired entry"); + retire( + &home, + "shop", + &retired.stack().expect("the entry's manifest stack"), + ); + write_record( + &paths::machine_record(&home, "box"), + &SdkValue::map([("name", t("box")), ("platform", t("lima"))]), + ) + .unwrap(); + let address = listener.local_addr().unwrap().to_string(); + write_record( + &paths::worker_record(&home, "box"), + &SdkValue::map([("address", t(&address)), ("secret", t("k"))]), + ) + .unwrap(); + if let Some(root) = root { + move_store_file(&home, root, "shop"); + } + place_store(&home, "shop", "box"); + home +} + +type Seen = Arc>>; + +/// A fake worker: answers its secret, reads each request and answers +/// `reply`'s frame; the requests it read are shared back. +fn fake_worker( + listener: TcpListener, + reply: impl Fn(&SdkValue) -> SdkValue + Send + 'static, +) -> Seen { + let seen: Seen = Arc::default(); + let requests = seen.clone(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { + return; + }; + let Some(_hello) = read_frame_within(&mut stream, MAX_HELLO).ok().flatten() else { + continue; + }; + let ready = Hello { + protocol: Some(worker::PROTOCOL), + bundle: None, + }; + if write_frame(&mut stream, &ready.to_frame()).is_err() { + continue; + } + let Some(request) = read_frame(&mut stream).ok().flatten() else { + continue; + }; + let answer = reply(&request); + requests.lock().unwrap().push(request); + let _ = write_frame(&mut stream, &answer); + } + }); + seen +} + +#[test] +fn a_worker_s_filtered_listing_hides_a_retired_project() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let home = shop_on_box("fake-list", &listener, None); + let live = ProjectRecord::read(&home, "shop", "live") + .unwrap() + .expect("the live entry"); + let live_stack = hex(&live.stack().expect("the live entry's stack")); + let seen = fake_worker(listener, move |_| { + // The worker's answer envelope is `{ value }`; its value is the + // `project.list` reply. + SdkValue::map([( + "value", + SdkValue::map([ + ("kind", t("Listed")), + ( + "projects", + SdkValue::List(vec![SdkValue::map([ + ("name", t("live")), + ("stack_id", t(&live_stack)), + ])]), + ), + ]), + )]) + }); + + // The worker's listing names only `live`: the retired entry is hidden. + assert_eq!(names(&ok(&home, "project.list", &[])), vec!["live"]); + assert_eq!( + names(&ok(&home, "project.list", &[("store", t("shop"))])), + vec!["live"] + ); + // project.get refuses the retired entry and gets the live one. + let (code, message) = + call(&home, "project.get", &[("project", t("shop/retired"))]).unwrap_err(); + assert_eq!(code, "NoSuchProject", "{message}"); + let live = ok(&home, "project.get", &[("project", t("shop/live"))]); + assert_eq!(live.get_text("project"), Some("shop/live")); + // Both home entries are still there; the Store, not the home, hides one. + for name in ["live", "retired"] { + assert!( + paths::project_record(&home, "shop", name).exists(), + "{name}" + ); + } + + // Every read went to the worker, as the Store listing's own frame. + let requests = seen.lock().unwrap(); + assert_eq!(requests.len(), 4, "{requests:?}"); + for request in requests.iter() { + assert_eq!(request.get_text("op"), Some("project.list")); + let args = request.get("args").expect("args"); + assert_eq!(args.get_text("store"), Some("shop")); + assert!(args.get("store_record").is_some()); + } + drop(requests); + let _ = std::fs::remove_dir_all(home); +} + +#[test] +fn a_worker_refusal_is_the_calls_refusal() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let home = shop_on_box("fake-refusal", &listener, None); + let _seen = fake_worker(listener, |_| { + SdkValue::map([( + "refused", + SdkValue::map([ + ("code", t("Busy")), + ("message", t("the Store is held")), + ("detail", SdkValue::Null), + ]), + )]) + }); + + // project.get propagates the refusal, never the unfiltered record. + let (code, message) = call(&home, "project.get", &[("project", t("shop/live"))]).unwrap_err(); + assert_eq!(code, "Busy"); + assert_eq!(message, "the Store is held"); + // The named listing reports it; the all-Stores one omits the Store. + let (code, _) = call(&home, "project.list", &[("store", t("shop"))]).unwrap_err(); + assert_eq!(code, "Busy"); + let list = ok(&home, "project.list", &[]); + assert!(names(&list).is_empty(), "{list:?}"); + let _ = std::fs::remove_dir_all(home); +} + +#[test] +fn a_worker_store_lists_only_its_live_projects() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let root = tempdir("worker-root"); + let home = shop_on_box("real-list", &listener, Some(&root)); + let guest = root.clone(); + std::thread::spawn(move || { + layerfs_control::worker_server::serve(listener, "k".to_owned(), guest) + }); + + // The Store under the worker's root hides its retired project; the + // caller's home entry for it stays but is not listed. + assert_eq!(names(&ok(&home, "project.list", &[])), vec!["live"]); + let (code, message) = + call(&home, "project.get", &[("project", t("shop/retired"))]).unwrap_err(); + assert_eq!(code, "NoSuchProject", "{message}"); + let live = ok(&home, "project.get", &[("project", t("shop/live"))]); + assert_eq!(live.get_text("project"), Some("shop/live")); + assert!(paths::project_record(&home, "shop", "retired").exists()); + let _ = std::fs::remove_dir_all(home); + let _ = std::fs::remove_dir_all(root); +} diff --git a/api/crates/layerfs-api/tests/store_projects.rs b/api/crates/layerfs-api/tests/store_projects.rs index 8961aaf5f8..9f3875af36 100644 --- a/api/crates/layerfs-api/tests/store_projects.rs +++ b/api/crates/layerfs-api/tests/store_projects.rs @@ -7,7 +7,10 @@ use layerfs_content::{ file::FileView, filesystem::{FilesystemRead, FilesystemRootId, LogicalPath}, }; -use layerfs_history::{BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId}; +use layerfs_history::{ + error::{HolderKind, HolderState, NameSource}, + BranchId, HistoryCatalog, HistoryCatalogConfig, HistoryName, LayerStackId, +}; use layerfs_persistence::{PersistenceConfig, SqliteHandles, SqlitePersistenceProfile}; use layerfs_storage::StoragePolicy; use layerfs_telemetry::timer::Timing; @@ -124,7 +127,13 @@ fn an_empty_store_holds_two_projects_and_refuses_a_taken_name() { assert_ne!(shop.initialized.root, api.initialized.root); assert_eq!(shop.branch.effective_root, shop.initialized.root); let taken = add(&path, source(&directory, "again", b"x"), "shop", 30); - assert!(matches!(taken, Err(InitError::Exists)), "{taken:?}"); + let Err(InitError::NameTaken(state)) = taken else { + panic!("a held project name is NameTaken: {taken:?}"); + }; + assert_eq!(state.holder.kind, HolderKind::Project); + assert_eq!(state.holder.name, "shop"); + assert_eq!(state.holder.state, HolderState::Live); + assert_eq!(state.source, NameSource::Store); let handles = SqliteHandles::open_writable(store(&path), BINDING, CURSOR).unwrap(); let names: Vec<_> = projects(&handles.history) diff --git a/api/crates/layerfs-api/tests/store_stats.rs b/api/crates/layerfs-api/tests/store_stats.rs index dcb2fceded..54cfc0f3a5 100644 --- a/api/crates/layerfs-api/tests/store_stats.rs +++ b/api/crates/layerfs-api/tests/store_stats.rs @@ -26,28 +26,31 @@ fn call(home: &Path, method: &str, fields: &[(&str, SdkValue)]) -> SdkValue { layerfs_api::call(Some(home), method, args, &mut |_| {}) .unwrap_or_else(|r| panic!("{method}: {r:?}")) } -fn check(home: &Path, kind: &str) { +fn check(home: &Path, kind: &str, test: &str) { let stats = || call(home, "store.stats", &[("name", t("stats"))]); let empty = stats(); assert_eq!(empty.get_text("kind"), Some(kind)); - assert_eq!(empty.get_int("history_logical"), Some(0)); + // a previous project's bytes stay after its soft delete, so later runs + // measure from the Store's current history + let base = empty.get_int("history_logical").unwrap(); assert_eq!( empty.get("free") == Some(&SdkValue::Null), kind == "postgresql" ); assert!(empty.get("dedupe").is_none()); - let source = folder(&format!("input-{kind}")); + let name = format!("stats/{test}"); + let source = folder(&format!("input-{kind}-{test}")); std::fs::write(source.join("file"), "hello").unwrap(); call( home, "project.init", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("folder", t(source.to_str().unwrap())), ], ); let initial = stats(); - assert_eq!(initial.get_int("history_logical"), Some(5)); + assert_eq!(initial.get_int("history_logical"), Some(base + 5)); assert!(initial.get_int("canonical").unwrap() > 0); assert!(initial.get_int("stored").unwrap() > 0); assert!(initial.get_int("file").unwrap() > 0); @@ -55,7 +58,7 @@ fn check(home: &Path, kind: &str) { home, "branch.fork", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("name", t("dev")), ("from_branch", t("main")), ], @@ -64,7 +67,7 @@ fn check(home: &Path, kind: &str) { home, "file.write", &[ - ("project", t("stats/p")), + ("project", t(&name)), ("branch", t("dev")), ("path", t("/file")), ("content", t("abcdef")), @@ -73,30 +76,31 @@ fn check(home: &Path, kind: &str) { call( home, "branch.publish", - &[("project", t("stats/p")), ("branch", t("dev"))], + &[("project", t(&name)), ("branch", t("dev"))], ); let published = stats(); assert_eq!( published.get_int("history_logical"), - Some(17), + Some(base + 17), "Commit and Layer count their snapshots" ); - if kind == "postgresql" { - let refused = layerfs_api::call( - Some(home), - "project.remove", - SdkValue::map([("project", t("stats/p"))]), - &mut |_| {}, - ) - .unwrap_err(); - assert_eq!(refused.code, "Unsupported"); - } else { - call(home, "project.remove", &[("project", t("stats/p"))]); - let removed = stats(); - assert_eq!(removed.get_int("history_logical"), Some(0)); - assert_eq!(removed.get("canonical"), published.get("canonical")); - assert_eq!(removed.get("stored"), published.get("stored")); - } + // `project.delete` retires the Stack and removes the home entry; the + // marker is the commit point, so the history bytes stay until a + // `store.compact` collects them and the counters do not drop. + call(home, "project.delete", &[("project", t(&name))]); + let removed = stats(); + assert_eq!(removed.get_int("history_logical"), Some(base + 17)); + assert_eq!(removed.get("canonical"), published.get("canonical")); + assert_eq!(removed.get("stored"), published.get("stored")); + let gone = layerfs_api::call( + Some(home), + "project.get", + SdkValue::map([("project", t(&name))]), + &mut |_| {}, + ) + .unwrap_err(); + assert_eq!(gone.code, "NoSuchProject"); + assert!(!paths::project_record(home, "stats", test).exists()); layerfs_api::close_idle(std::time::Duration::ZERO); std::fs::remove_dir_all(source).unwrap(); } @@ -105,7 +109,7 @@ fn check(home: &Path, kind: &str) { fn native_sqlite_and_worker_statistics_use_the_same_counters() { let home = folder("sqlite-home"); call(&home, "store.create", &[("name", t("stats"))]); - check(&home, "sqlite"); + check(&home, "sqlite", "p"); let root = folder("worker-root"); let listener = TcpListener::bind("127.0.0.1:0").unwrap(); let address = listener.local_addr().unwrap().to_string(); @@ -126,7 +130,7 @@ fn native_sqlite_and_worker_statistics_use_the_same_counters() { "store.push", &[("name", t("stats")), ("machine", t("box"))], ); - check(&home, "sqlite"); + check(&home, "sqlite", "w"); // A stopped worker refuses rather than starting anything. layerfs_api::close_idle(std::time::Duration::ZERO); std::fs::remove_file(paths::worker_record(&home, "box")).unwrap(); @@ -159,6 +163,6 @@ fn postgresql_statistics_have_null_free_and_count_publications() { ("synchronous_commit", t("off")), ], ); - check(&home, "postgresql"); + check(&home, "postgresql", "p"); std::fs::remove_dir_all(home).unwrap(); } diff --git a/api/crates/layerfs-cli/tests/concurrent_reads.rs b/api/crates/layerfs-cli/tests/concurrent_reads.rs index 9dc2db39d5..605eb7bc3a 100644 --- a/api/crates/layerfs-cli/tests/concurrent_reads.rs +++ b/api/crates/layerfs-cli/tests/concurrent_reads.rs @@ -16,7 +16,11 @@ fn parallel_branch_lists_never_trip_over_a_dropped_lease() { vec!["project", "init", "s/p", source.to_str().unwrap()], ] { let out = run(&mut layerfs(&home, &words)); - assert!(out.status.success(), "layerfs {words:?}: {}", text(&out.stderr)); + assert!( + out.status.success(), + "layerfs {words:?}: {}", + text(&out.stderr) + ); } for round in 0..6 { let children: Vec<_> = (0..8) diff --git a/api/crates/layerfs-cli/tests/gc.rs b/api/crates/layerfs-cli/tests/gc.rs new file mode 100644 index 0000000000..0b2096f0d6 --- /dev/null +++ b/api/crates/layerfs-cli/tests/gc.rs @@ -0,0 +1,180 @@ +//! T11.2: the four GC calls on the shell. Each has one command, the call +//! that it names and the arguments the table gives it: a wrong arity or an +//! option the call does not take is exit 2 before any call, a well-formed +//! command line reaches the library, and the help is the table's. +mod common; +use common::{layerfs, run, tempdir, text}; +use std::path::Path; + +fn run_code(home: &Path, words: &[&str]) -> (Option, String, String) { + let out = run(&mut layerfs(home, words)); + (out.status.code(), text(&out.stdout), text(&out.stderr)) +} + +/// The help line of each call, as the table renders it: remove-file is the +/// shell spelling of remove_file. +const CALLS: &[(&[&str], &str, &str)] = &[ + ( + &["branch", "remove"], + "layerfs branch remove ", + "soft-remove one Branch", + ), + ( + &["project", "delete"], + "layerfs project delete ", + "retire one project", + ), + ( + &["project", "remove-file"], + "layerfs project remove-file ", + "hide one absolute path", + ), + ( + &["store", "compact"], + "layerfs store compact ", + "reclaim dead bytes", + ), +]; + +#[test] +fn project_remove_is_a_usage_error() { + let home = tempdir("gc-remove"); + let (code, out, err) = run_code(&home, &["project", "remove", "shop/api"]); + assert_eq!(code, Some(2), "{out} {err}"); + assert!(err.contains("no call `project remove`"), "{err}"); + assert!(out.is_empty(), "{out}"); + assert!(!home.join("store").exists(), "no call reached a home"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn help_lists_each_gc_call_with_its_usage() { + let home = tempdir("gc-help"); + let (code, out, err) = run_code(&home, &["help"]); + assert_eq!(code, Some(0), "{err}"); + assert!(err.is_empty(), "{err}"); + let line = |family: &str| { + out.lines() + .find(|line| line.split_whitespace().next() == Some(family)) + .unwrap_or_else(|| panic!("no {family} line in {out}")) + }; + assert!(line("branch").contains("remove"), "{}", line("branch")); + assert!( + line("project").contains("delete") && line("project").contains("remove-file"), + "{}", + line("project") + ); + assert!(line("store").contains("compact"), "{}", line("store")); + + for (words, usage, help) in CALLS { + let topic: Vec<&str> = std::iter::once("help") + .chain(words.iter().copied()) + .collect(); + let (code, out, err) = run_code(&home, &topic); + assert_eq!(code, Some(0), "{words:?}: {err}"); + assert!(err.is_empty(), "{words:?}: {err}"); + assert!(out.starts_with(usage), "{words:?}: {out}"); + assert!(out.contains(help), "{words:?}: {out}"); + // the same help after the call, through -h and --help + for flag in ["-h", "--help"] { + let with_flag: Vec<&str> = words.iter().copied().chain([flag]).collect(); + let (code, more, err) = run_code(&home, &with_flag); + assert_eq!(code, Some(0), "{with_flag:?}: {err}"); + assert_eq!(more, out, "{with_flag:?}"); + } + } + assert!(!home.join("store").exists(), "help made no home"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn wrong_arity_and_options_are_usage_errors() { + let home = tempdir("gc-usage"); + let wrong: &[&[&str]] = &[ + &["branch", "remove"], + &["branch", "remove", "shop/api"], + &["branch", "remove", "shop/api", "work", "extra"], + &["branch", "remove", "shop/api", "work", "--force"], + &["project", "delete"], + &["project", "delete", "shop/api", "extra"], + &["project", "delete", "shop/api", "--force"], + &["project", "remove-file", "shop/api"], + &["project", "remove-file", "shop/api", "/a", "extra"], + &["project", "remove-file", "shop/api", "/a", "--force"], + &["store", "compact"], + &["store", "compact", "shop", "extra"], + &["store", "compact", "shop", "--force"], + ]; + for words in wrong { + let (code, out, err) = run_code(&home, words); + assert_eq!(code, Some(2), "{words:?}: {err}"); + assert!(out.is_empty(), "{words:?}: {out}"); + assert!(err.starts_with("layerfs: "), "{words:?}: {err}"); + } + // no positional was called: a usage error makes no home + assert!(!home.join("store").exists(), "a usage error made a home"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn well_formed_lines_reach_the_library() { + let home = tempdir("gc-reach"); + let well_formed: &[&[&str]] = &[ + &["branch", "remove", "shop/api", "work"], + &["project", "delete", "shop/api"], + &["project", "remove-file", "shop/api", "/a"], + &["store", "compact", "shop"], + ]; + for words in well_formed { + let (code, out, err) = run_code(&home, words); + // no Store in the home: the library refused after reading the line + assert_eq!(code, Some(125), "{words:?}: {err}"); + assert!(out.is_empty(), "{words:?}: {out}"); + assert!(err.starts_with("{"), "{words:?}: {err}"); + assert!(err.contains("\"code\":\"NoSuchStore\""), "{words:?}: {err}"); + } + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn a_bare_project_is_refused_and_the_four_are_out_of_scope() { + let home = tempdir("gc-names"); + // the library, not the parser, refuses a project without its Store + for words in [ + &["branch", "remove", "api", "main"][..], + &["project", "delete", "api"], + &["project", "remove-file", "api", "/a"], + ] { + let (code, out, err) = run_code(&home, words); + assert_eq!(code, Some(125), "{words:?}: {err}"); + assert!(out.is_empty(), "{words:?}: {out}"); + assert!(err.starts_with("{"), "{words:?}: {err}"); + assert!( + err.contains("\"code\":\"InvalidInput\""), + "{words:?}: {err}" + ); + assert!(err.contains("with its Store"), "{words:?}: {err}"); + } + + // a folder scope guards one folder and one Branch: none of the four is a + // folder operation, so every one is refused, never widened + let scoped: &[(&[&str], &str)] = &[ + (&["branch", "remove", "shop/api", "main"], "branch.remove"), + (&["project", "delete", "shop/api"], "project.delete"), + ( + &["project", "remove-file", "shop/api", "/web/a"], + "project.remove_file", + ), + (&["store", "compact", "shop"], "store.compact"), + ]; + for (words, call) in scoped { + let mut command: Vec<&str> = words.to_vec(); + command.extend(["--scope", "/web", "--scope-project", "shop/api"]); + let (code, out, err) = run_code(&home, &command); + assert_eq!(code, Some(125), "{call}: {err}"); + assert!(out.is_empty(), "{call}: {out}"); + assert!(err.contains("out of scope: "), "{call}: {err}"); + assert!(err.contains(call), "{call}: {err}"); + } + std::fs::remove_dir_all(home).unwrap(); +} diff --git a/api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs b/api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs new file mode 100644 index 0000000000..9e53c90749 --- /dev/null +++ b/api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs @@ -0,0 +1,426 @@ +//! AC-01 (§12 crash injection, §9): `kill -9` the **real process** that +//! carries `store.compact`, not a re-execution of this test binary. +//! +//! The in-process matrix (`engine/crates/layerfs-persistence/tests/ +//! sqlite_compact_crash.rs`) stops at a failpoint inside the test process, and +//! its `real_process` arm re-executes the *test binary*, so the killed process +//! is still a test child. This test starts the built `layerfs` command with +//! `store compact`, waits through the SQLite engine's Unix-socket gate until +//! that process stands inside the run, and `SIGKILL`s it there. Per #352 +//! F-020 no daemon serves Store calls: the caller's process performs the +//! compaction, so this is the process the §9 crash describes. (It is still not +//! a long-lived `layerfs worker` serving a machine's Store.) +//! +//! Every arm reopens the Store through the CLI and asserts the §9 crash state: +//! wholly old at `G` or wholly new at `G + 1`, the exact artifact set, the +//! sidecars a killed session leaves, the `store.status` projection (phase, +//! `uncertain`, `unresolved`), the next `store.compact` settling the leftover, +//! the retained layer still readable, and a clean `doctor`. The `G` baseline +//! is the §3 `none` run before the dead pack exists, so the crash arms start +//! from a Store with exactly one wholly dead pack. +//! +//! Linux only: the arm asserts `SIGKILL` delivery through +//! `ExitStatusExt::signal`. A macOS build has no gate in the engine, so the +//! hook is inert there by construction. +#![cfg(target_os = "linux")] +mod common; + +use common::{layerfs, run, run_with_stdin, tempdir, text, LAYERFS}; +use layerfs_api::json; +use layerfs_bridge::control::SdkValue; +use std::io::Read; +use std::os::unix::net::UnixListener; +use std::os::unix::process::ExitStatusExt; +use std::path::{Path, PathBuf}; +use std::process::{Command, Stdio}; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::time::{Duration, Instant}; + +/// The engine's gate: a run that reaches the named failpoint connects to this +/// socket and blocks there. Both variables are read by the production +/// `store.compact` path only when the gate is present. +const GATE_ENV: &str = "LAYERFS_COMPACT_CRASH_GATE"; +const FAILPOINT_ENV: &str = "LAYERFS_COMPACT_CRASH_FAILPOINT"; + +/// A short socket path: the sandbox's own root is longer than `SUN_LEN`. +fn gate_socket() -> PathBuf { + static NEXT: AtomicU64 = AtomicU64::new(0); + PathBuf::from(format!( + "/tmp/layerfs-g65-gate-{}-{}.sock", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )) +} + +/// One crash point: the failpoint, the phase `store.status` must project, +/// whether the rebuild is already installed at `G + 1`, and which staged +/// artifacts the kill leaves beside the Store. +#[derive(Clone, Copy, Debug)] +struct Arm { + failpoint: &'static str, + phase: &'static str, + installed: bool, + target: bool, + visited: bool, + /// A kill before the seal ends the process with the writer session's WAL + /// on disk (`-wal`, `-shm`); every later point has closed it. + live_sidecars: bool, +} + +/// `layerfs ` on `home`, parsing the one-line JSON result. +fn call(home: &Path, words: &[&str]) -> SdkValue { + let out = run(&mut layerfs(home, words)); + assert_eq!( + out.status.code(), + Some(0), + "{words:?}: {}", + text(&out.stderr) + ); + json::parse(text(&out.stdout).trim()).unwrap_or_else(|error| { + panic!("{words:?}: {error:?}: {}", text(&out.stdout)); + }) +} + +/// `store.compact s`, the call whose process the crash arms kill. +fn compact(home: &Path) -> SdkValue { + call(home, &["store", "compact", "s"]) +} + +fn generations(report: &SdkValue) -> (u64, u64) { + let generation = report.get("generation").expect("the report's generation"); + let before = generation.get_int("before").expect("generation.before"); + let after = generation.get_int("after").expect("generation.after"); + (before as u64, after as u64) +} + +fn with_suffix(path: &Path, suffix: &str) -> PathBuf { + let mut name = path.as_os_str().to_os_string(); + name.push(suffix); + PathBuf::from(name) +} + +/// Kills `store.compact` for real: waits until the process is stopped inside +/// the run at `failpoint`, then `SIGKILL`s it. The gate keeps the wait from +/// being a sleep, and a process that ends early (a refusal) fails the arm with +/// its own stderr. +fn crash_and_kill(home: &Path, failpoint: &'static str) { + let gate = gate_socket(); + let _ = std::fs::remove_file(&gate); + let listener = UnixListener::bind(&gate).expect("the crash gate socket"); + listener + .set_nonblocking(true) + .expect("a nonblocking crash gate"); + let mut child = Command::new(LAYERFS) + .args(["store", "compact", "s"]) + .env("LAYERFS_HOME", home) + .env(GATE_ENV, &gate) + .env(FAILPOINT_ENV, failpoint) + .stdin(Stdio::null()) + .stdout(Stdio::null()) + .stderr(Stdio::piped()) + .spawn() + .expect("the real store.compact process"); + + let deadline = Instant::now() + Duration::from_secs(60); + let stream = loop { + match listener.accept() { + Ok((stream, _)) => break stream, + Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { + if let Some(status) = child.try_wait().expect("the child's status") { + let mut stderr = String::new(); + if let Some(mut pipe) = child.stderr.take() { + let _ = pipe.read_to_string(&mut stderr); + } + panic!("store.compact ended before the gate ({failpoint}): {status}: {stderr}"); + } + assert!( + Instant::now() < deadline, + "store.compact never reached the gate ({failpoint})" + ); + std::thread::yield_now(); + } + Err(error) => panic!("crash gate accept: {error}"), + } + }; + stream + .set_read_timeout(Some(Duration::from_secs(60))) + .expect("a bounded gate read"); + let mut ready = [0u8; 1]; + let mut reader = &stream; + reader + .read_exact(&mut ready) + .expect("the child reached the crash gate"); + assert_eq!(ready[0], b'R', "the child stopped at the crash gate"); + + // The real §9 crash: SIGKILL the process that performs the compaction. + child.kill().expect("SIGKILL the store.compact process"); + let status = child.wait().expect("the killed process exits"); + assert_eq!( + status.signal(), + Some(9), + "the store.compact process was SIGKILLed: {status:?}" + ); + drop(stream); + let _ = std::fs::remove_file(&gate); +} + +/// The fixture: a Store, one project, a Branch whose commit writes a large +/// blob, and then a `§3 none` baseline that names `G` without moving it. +fn fixture(tag: &str) -> (PathBuf, PathBuf, u64) { + let home = tempdir(&format!("g65-home-{tag}")); + let source = tempdir(&format!("g65-src-{tag}")); + std::fs::write(source.join("a.txt"), b"the retained bytes\n").unwrap(); + call(&home, &["store", "create", "s"]); + call(&home, &["project", "init", "s/p", source.to_str().unwrap()]); + call(&home, &["branch", "fork", "s/p", "dev", "main"]); + // A large blob so its pack is wholly dead once `dev` is soft-removed, and + // large enough that the rebuild threshold (`dead >= 10% of total`) holds. + let big: Vec = (0..256 * 1024).map(|at| (at % 251) as u8).collect(); + let written = run_with_stdin( + &mut layerfs(&home, &["file", "write", "s/p", "dev", "/big"]), + &big, + ); + assert!(written.status.success(), "{}", text(&written.stderr)); + + // Nothing is dead yet: §3 `none`, so the generation does not move. This + // names `G`, the generation every crash arm starts from. + let baseline = compact(&home); + assert_eq!(baseline.get_text("path"), Some("none"), "{baseline:?}"); + let (before, after) = generations(&baseline); + assert_eq!(before, after, "a `none` run moves no generation"); + + // One wholly dead pack: the Branch that wrote `/big` is soft-removed and + // its objects become unreachable; the next run must reclaim them. + call(&home, &["branch", "remove", "s/p", "dev"]); + (home, source, before) +} + +fn exercise(arm: Arm) { + let (home, source, generation) = fixture(&arm.failpoint.to_lowercase()); + let store = home.join("store/s/store.sqlite"); + assert!(store.is_file(), "{}", store.display()); + + crash_and_kill(&home, arm.failpoint); + + // §9 crash state, read before any handle opens the Store: the exact + // artifact set beside the live file, and the sidecars the kill leaves. + assert_eq!( + with_suffix(&store, ".compact").exists(), + arm.target, + "staged Store at {}", + arm.failpoint + ); + assert_eq!( + with_suffix(&store, ".compact-visited").exists(), + arm.visited, + "visited scratch at {}", + arm.failpoint + ); + assert!( + with_suffix(&store, ".compact-op").exists(), + "op record at {}", + arm.failpoint + ); + if arm.live_sidecars { + assert!( + with_suffix(&store, "-wal").exists(), + "the killed session's WAL at {}", + arm.failpoint + ); + assert!( + with_suffix(&store, "-shm").exists(), + "the killed session's shared memory at {}", + arm.failpoint + ); + } + for suffix in ["-wal", "-shm", "-journal"] { + if arm.live_sidecars && suffix != "-journal" { + continue; + } + assert!( + !with_suffix(&store, suffix).exists(), + "sidecar {suffix} beside the Store at {}", + arm.failpoint + ); + assert!( + !with_suffix(&with_suffix(&store, ".compact"), suffix).exists(), + "sidecar {suffix} beside the staged Store at {}", + arm.failpoint + ); + } + + // `store.status` (§11) projects the recorded run: the phase it stood in, + // an uncertain outcome, and an unresolved state because its owner died. + let observed = call(&home, &["store", "status", "s"]); + let op = observed.get("op").expect("the op projection"); + assert!(op.get("id").is_some(), "{observed:?}"); + assert_eq!(op.get_text("phase"), Some(arm.phase), "{observed:?}"); + assert_eq!( + op.get("uncertain"), + Some(&SdkValue::Bool(true)), + "{observed:?}" + ); + assert_eq!( + observed.get_text("state"), + Some("unresolved"), + "{observed:?}" + ); + + // The next run judges the leftover: a rebuild from `G` before install, a + // settle at `G + 1` after it, and no residue either way. + let recovered = compact(&home); + if arm.installed { + assert_eq!(recovered.get_text("path"), Some("none"), "{recovered:?}"); + assert_eq!( + generations(&recovered), + (generation + 1, generation + 1), + "{recovered:?}" + ); + } else { + assert_eq!(recovered.get_text("path"), Some("rebuild"), "{recovered:?}"); + assert_eq!( + generations(&recovered), + (generation, generation + 1), + "{recovered:?}" + ); + } + let residue = recovered.get("residue").expect("the residue"); + assert_eq!(residue.get_int("bytes"), Some(0), "{recovered:?}"); + assert!( + matches!(residue.get("artifacts"), Some(SdkValue::List(items)) if items.is_empty()), + "{recovered:?}" + ); + + // Nothing is left beside the Store, and the op record is settled. + for path in [ + with_suffix(&store, ".compact"), + with_suffix(&store, ".compact-visited"), + with_suffix(&store, ".compact-op"), + ] { + assert!( + !path.exists(), + "{} left at {}", + path.display(), + arm.failpoint + ); + } + for suffix in ["-wal", "-shm", "-journal"] { + assert!( + !with_suffix(&store, suffix).exists(), + "sidecar {suffix} left at {}", + arm.failpoint + ); + } + let settled = call(&home, &["store", "status", "s"]); + assert!( + settled.get("op").and_then(|op| op.get("id")).is_none(), + "{settled:?}" + ); + assert_ne!(settled.get_text("state"), Some("unresolved"), "{settled:?}"); + + // The retained layer still reads, and the home passes the doctor: the + // dead pack is collected while the live one is intact. + let stats = call(&home, &["project", "stats", "s/p"]); + assert!(stats.get_int("files").unwrap_or(0) >= 1, "{stats:?}"); + call(&home, &["file", "stat", "s/p", "main", "/a.txt"]); + let doctor = call(&home, &["doctor"]); + assert_eq!(doctor.get("ok"), Some(&SdkValue::Bool(true)), "{doctor:?}"); + + std::fs::remove_dir_all(&home).unwrap(); + std::fs::remove_dir_all(&source).unwrap(); +} + +macro_rules! sigkill_at { + ($name:ident, $failpoint:literal, $phase:literal, $installed:literal, $target:literal, $visited:literal, $live_sidecars:literal) => { + #[test] + fn $name() { + exercise(Arm { + failpoint: $failpoint, + phase: $phase, + installed: $installed, + target: $target, + visited: $visited, + live_sidecars: $live_sidecars, + }); + } + }; +} + +// The mark phase: the open session and admission intent at `BeforeSeal` (the +// kill leaves the writer's WAL sidecars), the sealed Store at `AfterSeal`. +sigkill_at!( + sigkill_before_seal, + "BeforeSeal", + "mark", + false, + false, + false, + true +); +sigkill_at!( + sigkill_after_seal, + "AfterSeal", + "mark", + false, + false, + false, + false +); +// The build: immediately before `VACUUM INTO` (SQLite runs that copy as one +// uninterruptible call), and after the staged Store is built. +sigkill_at!( + sigkill_before_vacuum, + "BeforeVacuum", + "build", + false, + false, + true, + false +); +sigkill_at!( + sigkill_after_build, + "AfterBuild", + "build", + false, + true, + true, + false +); +// The verification and the install boundary. +sigkill_at!( + sigkill_during_verify, + "DuringVerify", + "verify", + false, + true, + true, + false +); +sigkill_at!( + sigkill_before_install, + "BeforeInstall", + "verify", + false, + true, + true, + false +); +// Installed at `G + 1`: after the rename, and partway through the settle. +sigkill_at!( + sigkill_after_install, + "AfterInstall", + "install", + true, + false, + true, + false +); +sigkill_at!( + sigkill_during_settle, + "DuringSettle", + "install", + true, + false, + false, + false +); diff --git a/api/mcp/src/profiles.js b/api/mcp/src/profiles.js index 495a83bff4..cec2810f13 100644 --- a/api/mcp/src/profiles.js +++ b/api/mcp/src/profiles.js @@ -6,7 +6,8 @@ // Assignment rule (each call lands in exactly one bucket, none excluded): // work the families an agent works in (branch, commit, file, workspace) // plus the read-only project and Sandbox calls named below -// admin every other call: project create/remove, Sandbox create/close, +// admin every other call: project create/delete/remove_file, Branch +// remove, Sandbox create/close, // and the machine, store, backup and logs families // The `admin` launch profile exposes the union, so `admin` adds the // administrative calls to the `work` set. @@ -20,15 +21,15 @@ const WORK_FAMILIES = new Set(["branch", "commit", "file", "workspace"]); /** Read-only calls of families that are otherwise administration. */ const WORK_CALLS = new Set(["project.list", "project.get", "project.stats", "project.export", "sandbox.list", "sandbox.get"]); -/** Administrative calls of the project and sandbox families. */ -const ADMIN_CALLS = new Set(["project.init", "project.remove", "sandbox.create", "sandbox.close"]); +/** Administrative calls outside the admin families. */ +const ADMIN_CALLS = new Set(["project.init", "project.delete", "project.remove_file", "branch.remove", "sandbox.create", "sandbox.close"]); /** Families whose every call belongs to the `admin` profile. */ const ADMIN_FAMILIES = new Set(["machine", "store", "backup", "logs"]); /** Why a family's calls sit where they do; one line per family, in the doc. */ const WHY = { - project: "read a project's record or its entry counts, or export one (work); importing and removing a project are administration", + project: "read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration", branch: "work on Branches: list, read, fork, merge, publish and diff", commit: "read a Branch's Commit history", file: "read and change files in a Branch; each write is one explicit Commit", @@ -48,9 +49,11 @@ const nameOf = (spec) => `${spec.family}.${spec.call}`; */ export function bucketOf(spec) { const name = nameOf(spec); + // The admin exception list is checked before the work families: a retired + // entity in a work family (`branch.remove`) is still administration (§10). + if (ADMIN_CALLS.has(name)) return "admin"; if (WORK_CALLS.has(name)) return "work"; if (WORK_FAMILIES.has(spec.family)) return "work"; - if (ADMIN_CALLS.has(name)) return "admin"; if (ADMIN_FAMILIES.has(spec.family)) return "admin"; return null; } @@ -58,7 +61,10 @@ export function bucketOf(spec) { /** Why this call is in its bucket: a line for the generated documentation table. */ export function whyOf(spec) { if (spec.family === "project" && spec.call === "init") return "import a host folder into a Store; administration"; - if (spec.family === "project" && spec.call === "remove") return "remove a project from its Store; administration"; + if (spec.family === "project" && spec.call === "delete") return "retire a project in its Store and remove its home entry; administration; a folder scope refuses it"; + if (spec.family === "project" && spec.call === "remove_file") return "hide one absolute path from every node at or below its marker frontier; administration; a folder scope refuses it"; + if (spec.family === "branch" && spec.call === "remove") return "retire one Branch in its Store; administration; a folder scope refuses it"; + if (spec.family === "store" && spec.call === "compact") return "reclaim one sqlite Store's dead bytes; administration; a folder scope refuses it"; if (spec.family === "sandbox" && spec.call === "create") return "start a Sandbox process; administration"; if (spec.family === "sandbox" && spec.call === "close") return "stop a Sandbox; administration"; if (spec.family === "project" && spec.call === "export") return "export a Branch snapshot to a local folder under a launch-time --export-root; a folder scope refuses it"; diff --git a/api/mcp/src/tools.js b/api/mcp/src/tools.js index c8fc065b52..8f7635a9b0 100644 --- a/api/mcp/src/tools.js +++ b/api/mcp/src/tools.js @@ -31,6 +31,11 @@ const COMMON = { description: "a whole number; send a decimal string to keep one beyond ±(2^53-1) exact", }, bool: { type: "boolean" }, + image: { + type: "string", + minLength: 1, + description: "a sha256: image digest, a Docker image id, or a Docker reference such as postgres:17-bookworm", + }, size: { oneOf: [{ type: "integer" }, { type: "string", minLength: 1 }], description: "a size in bytes, or text such as \"512M\" or \"8G\"", diff --git a/api/mcp/test/profiles.test.mjs b/api/mcp/test/profiles.test.mjs index 39752837d6..fce4272a92 100644 --- a/api/mcp/test/profiles.test.mjs +++ b/api/mcp/test/profiles.test.mjs @@ -13,20 +13,28 @@ const nameOf = (spec) => `${spec.family}.${spec.call}`; test("every call is in exactly one bucket, and admin adds the work bucket", () => { assert.deepEqual(check(table), []); - assert.equal(table.length, 73); + assert.equal(table.length, 76); const buckets = table.map(bucketOf); assert.equal(buckets.filter((bucket) => bucket === "work").length, 38); - assert.equal(buckets.filter((bucket) => bucket === "admin").length, 35); + assert.equal(buckets.filter((bucket) => bucket === "admin").length, 38); assert.ok(buckets.every((bucket) => bucket === "work" || bucket === "admin")); const work = tools(table, "work").map(nameOf); const admin = tools(table, "admin").map(nameOf); assert.equal(work.length, 38); - assert.equal(admin.length, 73); + assert.equal(admin.length, 76); for (const name of work) assert.ok(admin.includes(name), `${name} is in work but not admin`); assert.throws(() => tools(table, "root"), /unknown profile/); }); +test("the admin exception list is checked before the work families", () => { + // `branch` is a work family, but retiring one is administration (§10) + const retire = { family: "branch", call: "remove" }; + assert.equal(bucketOf(retire), "admin"); + assert.ok(!tools([...table, retire], "work").includes(retire)); + assert.ok(tools([...table, retire], "admin").includes(retire)); +}); + test("every generated tool is a valid MCP tool with the table's arguments and options", () => { const generated = toolsOf(table); assert.equal(generated.length, table.length); diff --git a/api/mcp/test/workflow.test.mjs b/api/mcp/test/workflow.test.mjs index 6c26d40b46..9b5f2f8b28 100644 --- a/api/mcp/test/workflow.test.mjs +++ b/api/mcp/test/workflow.test.mjs @@ -92,6 +92,11 @@ test("a real workflow, refusals, progress, scope and the two profiles", async () server.client.callTool({ name: "not_a_tool", arguments: {} }), (error) => error.code === -32602 && /unknown tool/.test(error.message), ); + // retired in 2.0 (spec 4): the old tool name does not exist + await assert.rejects( + server.client.callTool({ name: "project_remove", arguments: { project: "shop/api" } }), + (error) => error.code === -32602 && /unknown tool/.test(error.message), + ); await assert.rejects( server.client.callTool({ name: "store_create", arguments: { name: 5 } }), (error) => error.code === -32602 && /name.*must be text/.test(error.message), @@ -122,7 +127,7 @@ test("a real workflow, refusals, progress, scope and the two profiles", async () for (const name of names("admin").filter((name) => !names("work").includes(name))) { assert.ok(!workNames.has(name), `${name} is an admin tool in the work profile`); } - for (const prefix of ["store_", "machine_", "backup_", "project_init", "project_remove", "sandbox_create", "sandbox_close"]) { + for (const prefix of ["store_", "machine_", "backup_", "project_init", "project_delete", "project_remove_file", "branch_remove", "sandbox_create", "sandbox_close"]) { assert.ok(![...workNames].some((name) => name.startsWith(prefix)), `${prefix} in the work profile`); } const scopedRead = await call(work.client, "file_read", { project: "shop/api", branch: "feat", path: "/sub/b.txt" }); diff --git a/api/node/README.md b/api/node/README.md index 44af7efcda..6a9d49edc9 100644 --- a/api/node/README.md +++ b/api/node/README.md @@ -2,7 +2,7 @@ The LayerFS SDK for Node: ten families — `project`, `branch`, `commit`, `file`, `sandbox`, `workspace`, `machine`, `store`, `backup`, `logs` — over one call -table of 73 calls into one native library. Each function makes one call; it +table of 76 calls into one native library. Each function makes one call; it does not retry, replay or commit on its own. Results are plain objects with snake_case keys, whole numbers are exact (`bigint` beyond `Number.MAX_SAFE_INTEGER`), bytes are `Buffer`s, and the TypeScript typings diff --git a/api/node/src/index.d.ts b/api/node/src/index.d.ts index a37703ec6d..9fcdf3a9f4 100644 --- a/api/node/src/index.d.ts +++ b/api/node/src/index.d.ts @@ -131,13 +131,6 @@ export interface BranchMergeOptions extends CallOptions { units?: Value; } -/** Options of `branch.publish`; an unknown option is refused. */ -export interface BranchPublishOptions extends CallOptions { - expected_base?: string; - expected_head?: string; - force?: boolean; -} - /** Options of `branch.diff`; an unknown option is refused. */ export interface BranchDiffOptions extends CallOptions { paths_only?: boolean; @@ -327,11 +320,6 @@ export interface MachineStartOptions extends CallOptions { on_progress?: ProgressHandler; } -/** Options of `machine.stop`; an unknown option is refused. */ -export interface MachineStopOptions extends CallOptions { - force?: boolean; -} - /** Options of `machine.create`; an unknown option is refused. */ export interface MachineCreateOptions extends CallOptions { cpus?: WholeNumber; @@ -435,9 +423,9 @@ export interface BranchFamily { fork(project: string, name: string, from_branch: string, from_commit?: string | null, options?: CallOptions): Promise; /** merge two Branches into a new one */ merge(project: string, name: string, a: string, b: string, options?: BranchMergeOptions): Promise; - /** a Branch's head or Commit as main's next Layer, refusing a stale base */ - publish(project: string, branch: string, options: BranchPublishOptions): Promise; - publish(project: string, branch: string, commit?: string | null, options?: BranchPublishOptions): Promise; + /** a Branch's head or Commit as main's next Layer */ + publish(project: string, branch: string, options: CallOptions): Promise; + publish(project: string, branch: string, commit?: string | null, options?: CallOptions): Promise; /** files that differ between two Branches' heads */ diff(project: string, from_branch: string, to_branch: string, options?: BranchDiffOptions): Promise; } @@ -537,7 +525,7 @@ export interface MachineFamily { /** start a stopped machine and its worker; a running one answers at once */ start(name: string, options?: MachineStartOptions): Promise; /** stop a machine's worker and VM; its disks stay */ - stop(name: string, options?: MachineStopOptions): Promise; + stop(name: string, options?: CallOptions): Promise; /** create an enabled VM machine (apple-container, lima) */ create(name: string, platform: string, options?: MachineCreateOptions): Promise; /** delete a VM machine and its disk; one of a removed platform is only forgotten */ diff --git a/api/node/test/branch-file/inventory.mjs b/api/node/test/branch-file/inventory.mjs index 39debc4c41..a16f8d05c3 100644 --- a/api/node/test/branch-file/inventory.mjs +++ b/api/node/test/branch-file/inventory.mjs @@ -11,8 +11,8 @@ const root = fileURLToPath(new URL("../../../../", import.meta.url)); const command = process.env.LAYERFS_CLI ?? join(root, "target/debug/layerfs"); const docs = join(root, "docs/architecture/api/sdk"); -test("the SDK pages name all 73 current calls, one `### family.call` heading each", () => { - assert.equal(table.length, 73); +test("the SDK pages name all 76 current calls, one `### family.call` heading each", () => { + assert.equal(table.length, 76); const families = [...new Set(table.map((spec) => spec.family))]; assert.equal(families.length, 10); const index = readFileSync(join(docs, "README.md"), "utf8"); diff --git a/api/node/test/calls.mjs b/api/node/test/calls.mjs index f417bcab15..5eb15f49a5 100644 --- a/api/node/test/calls.mjs +++ b/api/node/test/calls.mjs @@ -14,9 +14,9 @@ const temp = (tag) => { return dir; }; -test("the table: ten families, 73 calls, each a function", () => { +test("the table: ten families, 76 calls, each a function", () => { assert.deepEqual(families, ["project", "branch", "commit", "file", "sandbox", "workspace", "machine", "store", "backup", "logs"]); - assert.equal(table.length, 73); + assert.equal(table.length, 76); for (const spec of table) assert.equal(typeof layerfs[spec.family][spec.call], "function", `${spec.family}.${spec.call}`); }); diff --git a/api/node/test/package.mjs b/api/node/test/package.mjs index d9a91b46f0..b94739a0d6 100644 --- a/api/node/test/package.mjs +++ b/api/node/test/package.mjs @@ -42,14 +42,6 @@ test("index.d.ts is exactly what the call table generates", () => { test("every call, argument and option of the table is in the typings", () => { const types = readFileSync(here("../src/index.d.ts"), "utf8"); const pascal = (word) => word.replace(/(^|_)([a-z])/g, (_, __, letter) => letter.toUpperCase()); - // the annotation each table kind is written as; a call's own options - // interface must name its options with exactly these (#691: `branch.publish` - // takes `expected_base`, `expected_head` and `force`). - const ARGUMENT = { - project: "string", name: "string", text: "string", int: "WholeNumber", bool: "boolean", - size: "Size", content: "Content", json: "Value", image: "string", - }; - const FUNCTION = { on_progress: "ProgressHandler", stdout: "OutputHandler", stderr: "OutputHandler" }; for (const spec of table) { const block = types.split(`export interface ${pascal(spec.family)}Family {\n`)[1].split("\n}\n")[0]; // the overloads that take the options right after the required positionals @@ -59,22 +51,6 @@ test("every call, argument and option of the table is in the typings", () => { assert.ok(lines.length > 0 && lines.every((text) => text.endsWith("): Promise;")), `${spec.family}.${spec.call}`); assert.ok(block.includes(` /** ${spec.help} */\n${lines[0]}`), `${spec.family}.${spec.call} help`); for (const arg of spec.args) assert.ok(line.includes(`${arg.name}${arg.optional ? "?" : ""}: `), `${spec.family}.${spec.call}(${arg.name})`); - if (spec.options.length === 0) { - assert.ok(line.endsWith("options?: CallOptions): Promise;"), `${spec.family}.${spec.call}: CallOptions`); - continue; - } - const name = `${pascal(spec.family)}${pascal(spec.call)}Options`; - assert.ok(line.endsWith(`options?: ${name}): Promise;`), `${spec.family}.${spec.call}: options?.${name}`); - const declaration = `export interface ${name} extends CallOptions {\n`; - const at = types.indexOf(declaration); - assert.ok(at >= 0, `${spec.family}.${spec.call}: no ${name} interface`); - const declared = types.slice(at + declaration.length).split("\n}\n")[0]; - const wanted = spec.options.map((opt) => { - const type = opt.kind === "function" ? FUNCTION[opt.name] : ARGUMENT[opt.kind]; - assert.ok(type, `${spec.family}.${spec.call}: no typings for ${opt.kind} option ${opt.name}`); - return ` ${opt.name}?: ${type};`; - }); - assert.equal(declared, wanted.join("\n"), `${spec.family}.${spec.call}: ${name} options`); for (const opt of spec.options) assert.ok(types.includes(` ${opt.name}?: `), `${spec.family}.${spec.call} ${opt.name}`); } }); diff --git a/api/python/src/layerfs/_client.pyi b/api/python/src/layerfs/_client.pyi index 6f24e42735..21fb65aa65 100644 --- a/api/python/src/layerfs/_client.pyi +++ b/api/python/src/layerfs/_client.pyi @@ -101,18 +101,8 @@ class BranchFamily: log_tag: str | None = None, ) -> Result: """merge two Branches into a new one""" - def publish( - self, - project: str, - branch: str, - commit: str | None = None, - *, - expected_base: str | None = None, - expected_head: str | None = None, - force: bool | None = None, - log_tag: str | None = None, - ) -> Result: - """a Branch's head or Commit as main's next Layer, refusing a stale base""" + def publish(self, project: str, branch: str, commit: str | None = None, *, log_tag: str | None = None) -> Result: + """a Branch's head or Commit as main's next Layer""" def diff( self, project: str, @@ -455,7 +445,7 @@ class MachineFamily: log_tag: str | None = None, ) -> Result: """start a stopped machine and its worker; a running one answers at once""" - def stop(self, name: str, *, force: bool | None = None, log_tag: str | None = None) -> Result: + def stop(self, name: str, *, log_tag: str | None = None) -> Result: """stop a machine's worker and VM; its disks stay""" def create( self, diff --git a/api/python/src/layerfs/aio.pyi b/api/python/src/layerfs/aio.pyi index f2ae365f06..2fc6d18ff7 100644 --- a/api/python/src/layerfs/aio.pyi +++ b/api/python/src/layerfs/aio.pyi @@ -105,12 +105,9 @@ class AsyncBranchFamily: branch: str, commit: str | None = None, *, - expected_base: str | None = None, - expected_head: str | None = None, - force: bool | None = None, log_tag: str | None = None, ) -> Result: - """a Branch's head or Commit as main's next Layer, refusing a stale base""" + """a Branch's head or Commit as main's next Layer""" async def diff( self, project: str, @@ -460,7 +457,7 @@ class AsyncMachineFamily: log_tag: str | None = None, ) -> Result: """start a stopped machine and its worker; a running one answers at once""" - async def stop(self, name: str, *, force: bool | None = None, log_tag: str | None = None) -> Result: + async def stop(self, name: str, *, log_tag: str | None = None) -> Result: """stop a machine's worker and VM; its disks stay""" async def create( self, diff --git a/api/python/test/test_calls.py b/api/python/test/test_calls.py index 03245d70b8..e8fc9793a3 100644 --- a/api/python/test/test_calls.py +++ b/api/python/test/test_calls.py @@ -340,25 +340,9 @@ def test_the_table(self): layerfs.FAMILIES, ["project", "branch", "commit", "file", "sandbox", "workspace", "machine", "store", "backup", "logs"], ) - self.assertEqual(len(layerfs.TABLE), 73) + self.assertEqual(len(layerfs.TABLE), 76) for spec in layerfs.TABLE: self.assertTrue(callable(getattr(getattr(layerfs, spec["family"]), spec["call"]))) - # the options the Publish change added are in the table the Python - # front end is built from, so `publish(expected_base=...)` is a keyword - # option rather than an unknown one (#691) - publish = next( - spec - for spec in layerfs.TABLE - if (spec["family"], spec["call"]) == ("branch", "publish") - ) - self.assertEqual( - [(opt["name"], opt["kind"], opt["optional"]) for opt in publish["options"]], - [ - ("expected_base", "name", True), - ("expected_head", "name", True), - ("force", "bool", True), - ], - ) with self.assertRaises(layerfs.LayerFSError) as caught: layerfs.client(home=temp("bogus")).store.get("shop", bogus=1) self.assertEqual(caught.exception.code, "InvalidInput") diff --git a/api/scripts/gen-coverage.mjs b/api/scripts/gen-coverage.mjs index 03b36f7fca..55474981db 100644 --- a/api/scripts/gen-coverage.mjs +++ b/api/scripts/gen-coverage.mjs @@ -101,9 +101,12 @@ function usage(words) { /** What the command line of `spec` must be, by the table: a content or JSON positional is read from * stdin or `--from`, `on_progress` is `--progress`, the output functions are `--stream`. */ function expectedCli(spec) { + const options = spec.options.filter((o) => o.kind !== FUNCTION || o.name === "on_progress").map((o) => (o.name === "on_progress" ? "progress" : o.name)); + // the command frames a call with a stdout sink as events: `--events`, last + if (spec.options.some((o) => o.name === "stdout")) options.push("events"); return { positionals: spec.args.filter((a) => !piped(a)).map((a) => ({ name: a.name, optional: a.optional })), - options: spec.options.filter((o) => o.kind !== FUNCTION || o.name === "on_progress").map((o) => (o.name === "on_progress" ? "progress" : o.name)), + options, from: spec.args.some(piped), }; } diff --git a/control/AGENTS.md b/control/AGENTS.md index 02325fd53a..cfb0293736 100644 --- a/control/AGENTS.md +++ b/control/AGENTS.md @@ -88,19 +88,26 @@ from it and a test compares them. ## Rules that stay -- The routes, worker and Store-kind rules are the root guide's - [Where calls run](../AGENTS.md#where-calls-run); control code implements - them in `place.rs` and `support.rs`. -- A PostgreSQL password is never written into a record, log, trace or - `Debug` output. +- sqlite Store calls run in a process on the Store's kernel (in process on + `native`, else that machine's worker); PostgreSQL Store calls and bucket + I/O run in the caller's process (#533 G2). A sqlite Store is on exactly one + machine; a PostgreSQL Store's Sandboxes run on the machines it is attached to + (`store.attach`, each checked from that machine; supersedes #535 G3). +- Workers listen on loopback behind a secret; one attempt per call, no + retry, no replay; an uncertain outcome is reported, never resent. +- A PostgreSQL password is resolved only in the caller, travels only in one + worker request and the Sandbox's private daemon setup file, and is never + written into a record, log, trace or `Debug` output. - Stored and displayed values do not follow internal renames: the `host_process` backend is stored and shown as `"native"` (#535 G6). -Control follows the engine guide's +All control product code follows the [production size and responsibility rules](../engine/AGENTS.md#production-file-size-and-responsibility) -and [checks](../engine/AGENTS.md#checks-and-completion), and the root guide's -[rules you must not break](../AGENTS.md#rules-you-must-not-break). The unsafe -allowance in control stays the one file +and [checks and completion rules](../engine/AGENTS.md#checks-and-completion): +production files at most 999 lines, `lib.rs`/`mod.rs` at most 200 lines of +declarations and re-exports, no tests or fixtures in `src/`, bounded test +commands, locked dependencies, per-commit production LOC and the +Disposable-only profile. The unsafe allowance in control stays the one file the guard names: the Linux `local/os/linux/seccomp.rs` of `layerfs-sandbox-backend`. The macOS process facts (`proc_pidinfo`) moved with `LocalProcess` to the bridge's audited `process/darwin.rs` (#112). diff --git a/control/crates/layerfs-control/src/inventory.rs b/control/crates/layerfs-control/src/inventory.rs index d84ff2afdb..38256c129c 100644 --- a/control/crates/layerfs-control/src/inventory.rs +++ b/control/crates/layerfs-control/src/inventory.rs @@ -216,15 +216,3 @@ pub fn store_idle(home: &Path, store: &str) -> Result<()> { held.extend(related("sandbox", &sandboxes)); Err(in_use(why.join("; "), held)) } - -/// `project.remove`: refused `InUse` while a Sandbox of `project` is -/// recorded; `detail.related` lists them as `{kind: "sandbox", name}`. -pub fn can_remove_project(home: &Path, project: &str) -> Result<()> { - let sandboxes = sandboxes_of_project(home, project)?; - let message = match sandboxes.as_slice() { - [] => return Ok(()), - [sandbox] => format!("Sandbox {sandbox} of {project} is running"), - many => format!("Sandboxes {} of {project} are running", many.join(", ")), - }; - Err(in_use(message, related("sandbox", &sandboxes))) -} diff --git a/control/crates/layerfs-control/src/project.rs b/control/crates/layerfs-control/src/project.rs index c3505c5d13..af30e384f6 100644 --- a/control/crates/layerfs-control/src/project.rs +++ b/control/crates/layerfs-control/src/project.rs @@ -1,13 +1,13 @@ -//! The `project` call that checks who uses a project, `project.remove` -//! (layerfs-project#105); the other `project` calls are `layerfs-store`'s -//! own. +//! The `project` call that retires a project in its Store and removes the +//! caller's home entry (`project.delete`, spec §4); the other `project` +//! calls are `layerfs-store`'s own. use layerfs_home::events::Events; use layerfs_home::names::ProjectRef; use layerfs_home::outcome::Outcome; use std::path::Path; -/// `project.remove`: a project's history dropped from its Store, once its -/// Sandboxes are closed. -pub fn remove(home: &Path, events: &mut Events<'_>, project: &ProjectRef) -> Outcome { - layerfs_store::project::family::remove(home, events, project, crate::store::RELATED) +/// `project.delete(project)`: retires the project in its Store and removes +/// the caller home entry (spec §4). +pub fn delete(home: &Path, events: &mut Events<'_>, project: &ProjectRef) -> Outcome { + layerfs_store::project::delete::delete(home, events, project) } diff --git a/control/crates/layerfs-control/src/store.rs b/control/crates/layerfs-control/src/store.rs index d67e04a111..4dd9903e85 100644 --- a/control/crates/layerfs-control/src/store.rs +++ b/control/crates/layerfs-control/src/store.rs @@ -18,10 +18,15 @@ use std::path::Path; pub use layerfs_store::close_idle; +/// `store.compact`: reclaim one sqlite Store's dead bytes, answering the +/// §11 report. +pub fn compact(home: &Path, events: &mut Events<'_>, name: &StoreName) -> Outcome { + layerfs_store::compact::compact(home, events, name.as_str()) +} + /// Who uses a Store or a project, read from the Sandbox records. pub const RELATED: Related = Related { store_idle: inventory::store_idle, - can_remove_project: inventory::can_remove_project, }; /// `store.remove`: a sqlite Store no Sandbox uses, with its file. diff --git a/control/crates/layerfs-control/src/worker_server.rs b/control/crates/layerfs-control/src/worker_server.rs index aaa0206567..b768955acb 100644 --- a/control/crates/layerfs-control/src/worker_server.rs +++ b/control/crates/layerfs-control/src/worker_server.rs @@ -10,8 +10,8 @@ //! build sends nothing more and closes. Then a request `{ op, args }`, read with at most //! [`REQUEST_WAIT`] between bytes. `worker.ping` answers who it is; //! `store.call`, `store.file`, `store.reach`, `sandbox.host`, `project.stage`, -//! `project.init`, `project.export` and `project.remove` run one operation on -//! this machine, +//! `project.init`, `project.export`, `project.delete` and `project.list` run +//! one operation on this machine, //! with `home` set to the worker's own root (the machine's data disk), //! never a path the caller sends. Answers are //! `{ value }` or `{ refused }`, after any `{ event }` frames. @@ -28,10 +28,15 @@ use layerfs_home::outcome::{refused, Outcome}; use layerfs_machine::worker::{ read_frame, read_frame_within, write_frame, Hello, HELLO_WAIT, MAX_HELLO, }; +use layerfs_store::project::delete::{admit_project, delete_project, release_project}; use layerfs_store::project::discovery::home_of; use layerfs_store::project::export::in_worker as export_in_worker; -use layerfs_store::project::frame::{ExportFrame, InitFrame, RemoveFrame, StageFrame}; -use layerfs_store::project::{init::in_worker, remove::remove_project, staged}; +use layerfs_store::project::frame::{ + DeleteAdmitFrame, DeleteFrame, DeleteReleaseFrame, ExportFrame, InitFrame, ListingFrame, + StageFrame, +}; +use layerfs_store::project::listing::list_projects; +use layerfs_store::project::{init::in_worker, staged}; use std::net::{TcpListener, TcpStream}; use std::path::{Path, PathBuf}; use std::sync::atomic::{AtomicU64, Ordering}; @@ -268,12 +273,29 @@ fn run( }, layerfs_sandbox::workspace::dispatch::call, ), - // drops one project from the Store under this worker's root (2.0): - // `{ store, project, store_record }` - "project.remove" => { + // retires one project in the Store under this worker root and + // removes the worker own entry (2.0, T4.5b): `{ store, stack_id, + // deleted_ms?, project?, op_id?, store_record? }` + "project.delete" => { + let root = home_of(Some(root))?; + delete_project(&root, &DeleteFrame::decode(&args)?) + } + // registers the caller's project-scope admission before its sidecar + // and marker (2.0, T4.6): `{ store, stack_id, op_id, store_record? }` + "project.delete.admit" => { + let root = home_of(Some(root))?; + admit_project(&root, &DeleteAdmitFrame::decode(&args)?) + } + // releases the caller's project-scope admission after the marker + // (2.0, T4.6): `{ store, op_id, store_record? }` + "project.delete.release" => { let root = home_of(Some(root))?; - remove_project(&root, &RemoveFrame::decode(&args)?) + release_project(&root, &DeleteReleaseFrame::decode(&args)?) } + // reads the Store's own filtered project listing under this worker + // root, the same `layerfs_project::store::projects` a local Store + // uses (2.0, T4.5c): `{ store, store_record? }` + "project.list" => list_projects(root, &ListingFrame::decode(&args)?), // writes or discards one part of a caller's folder copy under this // worker's root (#536 H11a) "project.stage" => staged::run(root, &StageFrame::decode(args)?), diff --git a/control/crates/layerfs-control/tests/in_use_detail.rs b/control/crates/layerfs-control/tests/in_use_detail.rs index e83e63c43c..be250e38ae 100644 --- a/control/crates/layerfs-control/tests/in_use_detail.rs +++ b/control/crates/layerfs-control/tests/in_use_detail.rs @@ -1,9 +1,9 @@ -//! `InUse` from `project.remove` and `store.disconnect` fills -//! `detail.related` with `{kind, name}` entries (#536 §10b refusal detail): -//! the project's Sandboxes, and another process's lease on the Store. +//! `InUse` from `store.disconnect` fills `detail.related` with +//! `{kind, name}` entries (#536 §10b refusal detail): another process's +//! lease on the Store. use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::events::Events; -use layerfs_home::home::{paths, private_dir, write_entity, write_record}; +use layerfs_home::home::{paths, private_dir, write_entity}; use std::path::PathBuf; fn t(s: &str) -> SdkValue { @@ -34,36 +34,6 @@ fn refused(run: impl FnOnce(&mut Events<'_>) -> layerfs_home::outcome::Outcome) run(&mut Events::new(&mut sink)).unwrap_err() } -#[test] -fn project_remove_names_the_project_s_sandboxes() { - let home = home("project"); - let store = SdkValue::map([ - ("name", t("shop")), - ("kind", t("sqlite")), - ("machine", t("native")), - ]); - write_entity(&paths::store_record(&home, "shop"), &store).unwrap(); - let project = SdkValue::map([("name", t("api"))]); - write_entity(&paths::project_record(&home, "shop", "api"), &project).unwrap(); - for name in ["sa", "sb"] { - let sandbox = SdkValue::map([ - ("v", SdkValue::Int(1)), - ("name", t(name)), - ("project", t("shop/api")), - ("machine", t("native")), - ]); - write_record(&paths::sandbox_record(&home, name), &sandbox).unwrap(); - } - let project = layerfs_home::names::ProjectRef::parse("shop/api").unwrap(); - let refusal = refused(|events| layerfs_control::project::remove(&home, events, &project)); - assert_eq!(refusal.code, "InUse", "{refusal:?}"); - let sandbox = |n: &str| ("sandbox".to_owned(), n.to_owned()); - assert_eq!(related(&refusal), [sandbox("sa"), sandbox("sb")]); - // nothing was removed - assert!(paths::project_record(&home, "shop", "api").is_file()); - let _ = std::fs::remove_dir_all(&home); -} - #[test] fn store_disconnect_names_another_process_s_lease() { let home = home("disconnect"); diff --git a/control/crates/layerfs-control/tests/inventory.rs b/control/crates/layerfs-control/tests/inventory.rs index d72f18ba2a..a2d8d91c4a 100644 --- a/control/crates/layerfs-control/tests/inventory.rs +++ b/control/crates/layerfs-control/tests/inventory.rs @@ -216,13 +216,6 @@ fn the_checks_refuse_in_use_with_the_same_texts() { }; assert_eq!(names(refusal.detail.get("related").unwrap()), ["a", "c"]); assert!(inventory::store_idle(&home, "pg").is_ok()); - let refusal = inventory::can_remove_project(&home, "docs/web").unwrap_err(); - assert_eq!(refusal.message, "Sandbox b of docs/web is running"); - assert_eq!(names(refusal.detail.get("related").unwrap()), ["b"]); - let refusal = inventory::can_remove_project(&home, "shop/api").unwrap_err(); - assert_eq!(refusal.message, "Sandboxes a, c of shop/api are running"); - assert_eq!(names(refusal.detail.get("related").unwrap()), ["a", "c"]); - assert!(inventory::can_remove_project(&home, "shop/web").is_ok()); let _ = std::fs::remove_dir_all(&home); } diff --git a/control/crates/layerfs-control/tests/project_delete_call.rs b/control/crates/layerfs-control/tests/project_delete_call.rs new file mode 100644 index 0000000000..cc88aabe6b --- /dev/null +++ b/control/crates/layerfs-control/tests/project_delete_call.rs @@ -0,0 +1,17 @@ +//! `project.delete` is reachable at the control layer behind the call +//! dispatch T11 will add (the API/MCP call table itself is unchanged here). +use layerfs_home::events::Events; +use layerfs_home::names::ProjectRef; + +#[test] +fn project_delete_is_reachable_from_control_and_refuses_an_unknown_store() { + let home = std::env::temp_dir().join(format!("layerfs-control-delete-{}", std::process::id())); + let _ = std::fs::remove_dir_all(&home); + layerfs_home::home::layout::create(&home).unwrap(); + let project = ProjectRef::parse("shop/app").unwrap(); + let mut sink = |_| {}; + let refused = + layerfs_control::project::delete(&home, &mut Events::new(&mut sink), &project).unwrap_err(); + assert_eq!(refused.code, "NoSuchStore"); + let _ = std::fs::remove_dir_all(&home); +} diff --git a/control/crates/layerfs-control/tests/project_delete_worker.rs b/control/crates/layerfs-control/tests/project_delete_worker.rs new file mode 100644 index 0000000000..6e301384a5 --- /dev/null +++ b/control/crates/layerfs-control/tests/project_delete_worker.rs @@ -0,0 +1,652 @@ +//! `project.delete` on a worker-backed Store (T4.6): the caller admits the +//! project scope through the worker before it writes its sidecar and sends +//! the marker. A live mount in the worker's Store refuses the call with +//! `MountsActive` (holders reported) and a live operation with `Busy`, with +//! no sidecar, no marker and no leaked admission row; the successful path +//! releases the admission after the marker. +use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_bridge::sdk_values::hex; +use layerfs_history::records::{GcIntent, GcIntentKind, GcScopeKind}; +use layerfs_history::{HistoryName, LayerStackId, NamedSnapshot}; +use layerfs_home::events::Events; +use layerfs_home::home::{self, paths}; +use layerfs_home::names::{ProjectRef, StoreName}; +use layerfs_machine::worker::{self, read_frame, read_frame_within, write_frame, Hello, MAX_HELLO}; +use layerfs_store::open_args::OpenArgs; +use layerfs_store::project::add::{add_project, ProjectAdd}; +use layerfs_store::record::StoreRecord; +use layerfs_store::service::with_service; +use layerfs_store::sqlite::create::create; +use layerfs_store_service::history::lookup; +use std::net::TcpListener; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU32, AtomicU64, Ordering}; +use std::sync::{Arc, Mutex}; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let directory = std::env::temp_dir().join(format!( + "layerfs-delete-worker-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&directory); + layerfs_home::home::layout::create(&directory).unwrap(); + directory +} + +fn text(value: &str) -> SdkValue { + SdkValue::text(value) +} + +/// A folder to initialize a project from: no home layout inside it. +fn plaindir(tag: &str) -> PathBuf { + let directory = std::env::temp_dir().join(format!( + "layerfs-delete-worker-folder-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&directory); + std::fs::create_dir_all(&directory).unwrap(); + directory +} + +/// Moves Store `store`'s file from `from`'s Store folder to `to`'s. +fn move_store_file(from: &Path, to: &Path, store: &str) { + let source = paths::store_dir(from, store); + let target = paths::store_dir(to, store); + home::private_dir(&target).unwrap(); + for entry in std::fs::read_dir(&source).unwrap() { + let entry = entry.unwrap(); + let name = entry.file_name().to_string_lossy().into_owned(); + if name.starts_with("store.sqlite") { + std::fs::rename(entry.path(), target.join(&name)).unwrap(); + } + } +} + +/// The Store record of `store` places it on machine `machine`. +fn place_store(home: &Path, store: &str, machine: &str) { + let record_path = paths::store_record(home, store); + let record = home::read_record(&record_path).unwrap().unwrap(); + write_record( + &record_path, + &home::with_field(record, "machine", text(machine)), + ); +} + +fn write_record(path: &Path, value: &SdkValue) { + home::write_record(path, value).unwrap(); +} + +/// A worker's `OpenArgs` for Store `shop` under `root`, with the caller's +/// Store record (the same context every `project.delete*` frame carries). +fn worker_open(root: &Path, record: &StoreRecord) -> OpenArgs { + OpenArgs { + home: Some(root.to_path_buf()), + store: Some("shop".to_owned()), + project: Some("app".to_owned()), + store_path: Some(paths::store_file(root, "shop").display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + } +} + +fn intents(open: &OpenArgs, stack: LayerStackId) -> Vec { + with_service(open, |service| { + Ok(service + .store + .history() + .gc_intents(GcScopeKind::Project, stack.as_slice()) + .unwrap()) + }) + .unwrap() +} + +fn project_names(open: &OpenArgs) -> Vec { + with_service(open, |service| { + let listed = service + .store + .published(layerfs_project::store::projects) + .unwrap(); + Ok(listed + .into_iter() + .map(|stack| stack.name.as_str().to_owned()) + .collect()) + }) + .unwrap() +} + +fn remove(home: &Path) -> Result { + let mut sink = |_| {}; + layerfs_control::project::delete( + home, + &mut Events::new(&mut sink), + &ProjectRef::parse("shop/app").unwrap(), + ) +} + +#[test] +fn the_worker_path_admits_before_the_sidecar_and_releases_after_the_marker() { + // a home with Store `shop` and project `app`, created locally. A + // sandbox filesystem cannot hold a directly opened Store; the fake-home + // cases in the `layerfs-store` tests cover the same home path, and this + // case runs where the Store's filesystem carries SQLite locks. + let home = tempdir("home"); + match create(&home, &StoreName::parse("shop").unwrap()) { + Ok(_) => {} + Err(refusal) + if refusal.code == "Unsupported" + && refusal.message.contains("does not carry SQLite locks") => + { + eprintln!("NOT RUN: this filesystem cannot hold a directly opened Store: {refusal:?}"); + let _ = std::fs::remove_dir_all(&home); + return; + } + Err(refusal) => panic!("store.create: {refusal:?}"), + } + let source = plaindir("folder"); + std::fs::write(source.join("a.txt"), b"a\n").unwrap(); + add_project(&ProjectAdd { + home: home.clone(), + store: StoreName::parse("shop").unwrap(), + name: "app".to_owned(), + source, + timeout_ms: Some(60_000), + store_record: None, + }) + .unwrap(); + let record = StoreRecord::read(&home, "shop").unwrap().unwrap(); + let caller_open = OpenArgs { + home: Some(home.clone()), + store: Some("shop".to_owned()), + project: Some("app".to_owned()), + store_path: Some(paths::store_file(&home, "shop").display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + }; + let (stack, branch) = with_service(&caller_open, |service| { + let stack = lookup::project(&service.store, "app").unwrap(); + let project = HistoryName::new("app").unwrap(); + let main = HistoryName::new("main").unwrap(); + let NamedSnapshot::Found(snapshot) = service + .store + .published(|history| history.branch_snapshot_named(&project, &main)) + .unwrap() + else { + panic!("no main Branch"); + }; + Ok((stack.id, snapshot.branch.id)) + }) + .unwrap(); + + // the Store belongs to machine `box`; its file is under the worker's root + let root = tempdir("root"); + move_store_file(&home, &root, "shop"); + home::write_record( + &paths::machine_record(&home, "box"), + &SdkValue::map([("name", text("box")), ("platform", text("lima"))]), + ) + .unwrap(); + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap().to_string(); + home::write_record( + &paths::worker_record(&home, "box"), + &SdkValue::map([("address", text(&address)), ("secret", text("k"))]), + ) + .unwrap(); + place_store(&home, "shop", "box"); + let served = root.clone(); + std::thread::spawn(move || { + layerfs_control::worker_server::serve(listener, "k".to_owned(), served) + }); + + let worker = worker_open(&root, &record); + + // a live mount in the worker's Store: `MountsActive`, no sidecar, no marker + let mount = GcIntent::shared( + [9; 16], + GcIntentKind::Mount, + GcScopeKind::Branch, + branch.as_slice(), + ) + .in_project(stack.as_slice()) + .named(Some("app"), Some("main")) + .placed(Some([9; 32]), Some("sandbox-9"), Some("machine-9")); + with_service(&worker, |service| { + service.store.history().gc_register(&mount).unwrap(); + Ok(()) + }) + .unwrap(); + let refusal = remove(&home).expect_err("a live mount holds the project"); + assert_eq!(refusal.code, "MountsActive", "{refusal:?}"); + assert!( + intents(&worker, stack).is_empty(), + "no project-scope row yet" + ); + let SdkValue::List(holders) = refusal.detail.get("holders").expect("holders") else { + panic!("{refusal:?}"); + }; + assert_eq!(holders[0].get_text("kind"), Some("mount")); + assert_eq!(holders[0].get_text("sandbox"), Some("sandbox-9")); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None, + "no sidecar was written" + ); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + assert_eq!(project_names(&worker), vec!["app".to_owned()], "no marker"); + assert!( + intents(&worker, stack).is_empty(), + "the refused admission left no project-scope row" + ); + + // the mount ends; a live removal at project scope is `Busy` + with_service(&worker, |service| { + service.store.history().gc_release(&[9; 16]).unwrap(); + Ok(()) + }) + .unwrap(); + let holder = GcIntent::operation( + [7; 16], + GcIntentKind::Removal, + GcScopeKind::Project, + stack.as_slice(), + ) + .named(Some("app"), None); + with_service(&worker, |service| { + service.store.history().gc_register(&holder).unwrap(); + Ok(()) + }) + .unwrap(); + let refusal = remove(&home).expect_err("another removal holds the project"); + assert_eq!(refusal.code, "Busy", "{refusal:?}"); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None + ); + assert_eq!( + intents(&worker, stack).len(), + 1, + "only the test's own holder" + ); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + + // the holder ends: the delete succeeds through the worker and releases + // the admission it took, with the sidecar unlinked + with_service(&worker, |service| { + service.store.history().gc_release(&[7; 16]).unwrap(); + Ok(()) + }) + .unwrap(); + let outcome = remove(&home).unwrap(); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, "shop", "app").exists()); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None + ); + assert!( + intents(&worker, stack).is_empty(), + "the admission was released" + ); + assert!(project_names(&worker).is_empty(), "the project is retired"); + let _ = std::fs::remove_dir_all(&home); + let _ = std::fs::remove_dir_all(&root); +} + +/// A fake worker on `listener`: answers its secret, answers each request with +/// `reply`, and shares back the requests it read. A `None` answer drops the +/// connection without a reply, as a lost answer does. +fn fake_worker_with( + listener: TcpListener, + reply: impl Fn(&SdkValue) -> Option + Send + 'static, +) -> Arc>> { + let seen: Arc>> = Arc::default(); + let requests = seen.clone(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { + return; + }; + let Some(_hello) = read_frame_within(&mut stream, MAX_HELLO).ok().flatten() else { + continue; + }; + let ready = Hello { + protocol: Some(worker::PROTOCOL), + bundle: None, + }; + if write_frame(&mut stream, &ready.to_frame()).is_err() { + continue; + } + let Some(request) = read_frame(&mut stream).ok().flatten() else { + continue; + }; + let answer = reply(&request); + requests.lock().unwrap().push(request); + if let Some(answer) = answer { + let _ = write_frame(&mut stream, &answer); + } + } + }); + seen +} + +/// [`fake_worker_with`] of a worker that always answers. +fn fake_worker( + listener: TcpListener, + reply: impl Fn(&SdkValue) -> SdkValue + Send + 'static, +) -> Arc>> { + fake_worker_with(listener, move |request| Some(reply(request))) +} + +/// The `op` of one request the fake worker read. +fn op_of(request: &SdkValue) -> &str { + request.get_text("op").unwrap_or("") +} + +/// A frame's `args`. +fn args_of(request: &SdkValue) -> &SdkValue { + request.get("args").expect("args") +} + +/// The `op_id` a request's args carry. +fn sent_op(request: &SdkValue) -> String { + args_of(request) + .get_text("op_id") + .expect("the frame names its admission") + .to_owned() +} + +fn admitted_for(stack: LayerStackId) -> SdkValue { + SdkValue::map([( + "value", + SdkValue::map([ + ("kind", text("Admitted")), + ("stack_id", text(&hex(&stack.to_bytes()))), + ]), + )]) +} + +fn removed_for(stack: LayerStackId, deleted_ms: i64) -> SdkValue { + SdkValue::map([( + "value", + SdkValue::map([ + ("kind", text("Removed")), + ("project", text("app")), + ("stack_id", text(&hex(&stack.to_bytes()))), + ("deleted_ms", SdkValue::Int(deleted_ms)), + ]), + )]) +} + +fn released_for(request: &SdkValue) -> SdkValue { + SdkValue::map([( + "value", + SdkValue::map([ + ("kind", text("Released")), + ("op_id", text(&sent_op(request))), + ]), + )]) +} + +fn refused(code: &str, detail: SdkValue) -> SdkValue { + SdkValue::map([( + "refused", + SdkValue::map([ + ("code", text(code)), + ("message", text("the fake worker refused")), + ("detail", detail), + ]), + )]) +} + +/// A caller's home naming Store `shop` on machine `box`, whose project `app` +/// records `stack`, with the fake worker's address. +fn caller_home(tag: &str, address: &str, stack: LayerStackId) -> PathBuf { + let home = tempdir(tag); + home::write_record( + &paths::store_record(&home, "shop"), + &SdkValue::map([ + ("v", SdkValue::Int(1)), + ("kind", text("sqlite")), + ("name", text("shop")), + ("machine", text("box")), + ]), + ) + .unwrap(); + home::write_record( + &paths::project_record(&home, "shop", "app"), + &SdkValue::map([ + ("v", SdkValue::Int(1)), + ("name", text("app")), + ("stack", text(&hex(&stack.to_bytes()))), + ("created", SdkValue::Int(1)), + ]), + ) + .unwrap(); + home::write_record( + &paths::worker_record(&home, "box"), + &SdkValue::map([("address", text(address)), ("secret", text("k"))]), + ) + .unwrap(); + home +} + +#[test] +fn a_fake_workers_mounts_active_refusal_writes_no_sidecar_and_no_marker() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap().to_string(); + let stack = LayerStackId::from_authority([3; 16]); + let home = caller_home("fake-mount", &address, stack); + let holders = SdkValue::map([( + "holders", + SdkValue::List(vec![SdkValue::map([ + ("kind", text("mount")), + ("entity", text("main")), + ])]), + )]); + let seen = fake_worker(listener, move |request| { + assert_eq!(op_of(request), "project.delete.admit"); + refused("MountsActive", holders.clone()) + }); + + let refusal = remove(&home).expect_err("the fake worker's Store has a live mount"); + assert_eq!(refusal.code, "MountsActive", "{refusal:?}"); + // the caller wrote no sidecar and sent no marker: only the admission frame + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None + ); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + let requests = seen.lock().unwrap(); + assert_eq!(requests.len(), 1, "{requests:?}"); + assert_eq!(op_of(&requests[0]), "project.delete.admit"); + drop(requests); + let _ = std::fs::remove_dir_all(home); +} + +#[test] +fn a_fake_workers_marker_refusal_releases_the_admission_it_took() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap().to_string(); + let stack = LayerStackId::from_authority([4; 16]); + let home = caller_home("fake-busy", &address, stack); + let seen = fake_worker(listener, move |request| match op_of(request) { + "project.delete.admit" => admitted_for(stack), + "project.delete" => refused("Busy", SdkValue::Null), + "project.delete.release" => released_for(request), + other => panic!("unexpected op {other}"), + }); + + let refusal = remove(&home).expect_err("a live operation holds the project"); + assert_eq!(refusal.code, "Busy", "{refusal:?}"); + // the admission was taken, named in the sidecar, used by the marker and + // released after the marker's refusal + let requests = seen.lock().unwrap(); + let ops: Vec<&str> = requests.iter().map(op_of).collect(); + assert_eq!( + ops, + [ + "project.delete.admit", + "project.delete", + "project.delete.release" + ], + "{requests:?}" + ); + let op = sent_op(&requests[0]); + assert_eq!(sent_op(&requests[1]), op); + assert_eq!(sent_op(&requests[2]), op); + drop(requests); + let body: [u8; 16] = hex_decode(&op).try_into().unwrap(); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app") + .unwrap() + .expect("the pending sidecar stays for a retry") + .op, + Some(body) + ); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + let _ = std::fs::remove_dir_all(home); +} + +#[test] +fn a_fake_workers_success_removes_the_entry_and_releases_the_admission() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap().to_string(); + let stack = LayerStackId::from_authority([5; 16]); + let home = caller_home("fake-ok", &address, stack); + let seen = fake_worker(listener, move |request| match op_of(request) { + "project.delete.admit" => admitted_for(stack), + "project.delete" => removed_for(stack, 42), + "project.delete.release" => released_for(request), + other => panic!("unexpected op {other}"), + }); + + let outcome = remove(&home).unwrap(); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert_eq!(outcome.get_int("deleted_ms"), Some(42)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, "shop", "app").exists()); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None + ); + let requests = seen.lock().unwrap(); + let ops: Vec<&str> = requests.iter().map(op_of).collect(); + assert_eq!( + ops, + [ + "project.delete.admit", + "project.delete", + "project.delete.release" + ], + "{requests:?}" + ); + let op = sent_op(&requests[0]); + assert_eq!(sent_op(&requests[1]), op); + assert_eq!(sent_op(&requests[2]), op); + drop(requests); + let _ = std::fs::remove_dir_all(home); +} + +/// The bytes of a lowercase hex string. +fn hex_decode(text: &str) -> Vec { + (0..text.len()) + .step_by(2) + .map(|at| u8::from_str_radix(&text[at..at + 2], 16).unwrap()) + .collect() +} + +#[test] +fn a_lost_worker_reply_is_unknown_and_keeps_the_sidecar_for_the_retry() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let address = listener.local_addr().unwrap().to_string(); + let stack = LayerStackId::from_authority([6; 16]); + let home = caller_home("fake-lost", &address, stack); + // The first marker attempt loses its answer; the second (the retry) + // retires the Stack with the sidecar's `deleted_ms`. + let attempts = Arc::new(AtomicU32::new(0)); + let count = attempts.clone(); + let seen = fake_worker_with(listener, move |request| match op_of(request) { + "project.delete.admit" => Some(admitted_for(stack)), + "project.delete" => { + if count.fetch_add(1, Ordering::SeqCst) == 0 { + None + } else { + Some(removed_for(stack, 42)) + } + } + "project.delete.release" => Some(released_for(request)), + other => panic!("unexpected op {other}"), + }); + + let refusal = remove(&home).expect_err("the marker answer was lost"); + assert_eq!(refusal.code, "Unknown", "{refusal:?}"); + // The sidecar stays `pending`, naming the admission, and the entry stays + // for the retry: an unknown outcome is never reported clean. + let intent = layerfs_store::project::delete::Intent::read(&home, "shop", "app") + .unwrap() + .expect("the pending sidecar stays"); + assert_eq!( + intent.state, + layerfs_store::project::delete::IntentState::Pending + ); + let op = intent.op.expect("the sidecar names its admission"); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + let requests = seen.lock().unwrap(); + let ops: Vec<&str> = requests.iter().map(op_of).collect(); + assert_eq!( + ops, + [ + "project.delete.admit", + "project.delete", + "project.delete.release" + ], + "{requests:?}" + ); + let first = sent_op(&requests[0]); + assert_eq!(sent_op(&requests[1]), first); + assert_eq!(sent_op(&requests[2]), first); + assert_eq!(hex_decode(&first), op.to_vec()); + drop(requests); + + // The retry re-registers the same identity and finishes the entry. + let outcome = remove(&home).expect("the retry settles the unknown outcome"); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert_eq!(outcome.get_int("deleted_ms"), Some(42)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, "shop", "app").exists()); + assert_eq!( + layerfs_store::project::delete::Intent::read(&home, "shop", "app").unwrap(), + None, + "the retry unlinked the sidecar" + ); + let requests = seen.lock().unwrap(); + let ops: Vec<&str> = requests.iter().map(op_of).collect(); + assert_eq!( + ops, + [ + "project.delete.admit", + "project.delete", + "project.delete.release", + "project.delete.admit", + "project.delete", + "project.delete.release" + ], + "{requests:?}" + ); + let same: Vec<&str> = requests[3..].iter().map(sent_op_ref).collect(); + assert_eq!(same, [first.as_str(), first.as_str(), first.as_str()]); + drop(requests); + let _ = std::fs::remove_dir_all(home); +} + +/// The `op_id` a request's args carry, borrowed. +fn sent_op_ref(request: &SdkValue) -> &str { + args_of(request) + .get_text("op_id") + .expect("the frame names its admission") +} diff --git a/control/crates/layerfs-control/tests/store_transfer_recovery.rs b/control/crates/layerfs-control/tests/store_transfer_recovery.rs index c122aa6b8e..0dea8ba5d7 100644 --- a/control/crates/layerfs-control/tests/store_transfer_recovery.rs +++ b/control/crates/layerfs-control/tests/store_transfer_recovery.rs @@ -41,7 +41,6 @@ fn idle(_home: &Path, _name: &str) -> Result<(), SdkRefusal> { fn related() -> Related { Related { store_idle: idle, - can_remove_project: idle, } } diff --git a/control/crates/layerfs-sandbox/src/daemon/channel.rs b/control/crates/layerfs-sandbox/src/daemon/channel.rs index 49c161ef81..4aad4a659e 100644 --- a/control/crates/layerfs-sandbox/src/daemon/channel.rs +++ b/control/crates/layerfs-sandbox/src/daemon/channel.rs @@ -291,6 +291,19 @@ fn matches_reply(request: &Request, reply: &Reply) -> bool { Reply::Bound { token, binding }, ) => token.workspace == *workspace && binding.branch.name.as_str() == branch, (Request::MountNamed { .. }, Reply::SdkRefused(_)) => true, + ( + Request::MountPlaced { + workspace, branch, .. + }, + Reply::Bound { token, binding }, + ) => token.workspace == *workspace && binding.branch.id == *branch, + ( + Request::MountNamedPlaced { + workspace, branch, .. + }, + Reply::Bound { token, binding }, + ) => token.workspace == *workspace && binding.branch.name.as_str() == branch, + (Request::MountNamedPlaced { .. }, Reply::SdkRefused(_)) => true, ( Request::Commit(_), Reply::Committed(_) | Reply::MergeCommitted(_) | Reply::Conflict(_), diff --git a/control/crates/layerfs-sandbox/src/daemon/internal.rs b/control/crates/layerfs-sandbox/src/daemon/internal.rs index 3188e6d448..58b6a0ace2 100644 --- a/control/crates/layerfs-sandbox/src/daemon/internal.rs +++ b/control/crates/layerfs-sandbox/src/daemon/internal.rs @@ -2,7 +2,7 @@ pub use super::channel::{Control, ControlCause, ControlFailure, ControlPhase}; use crate::{BoundWorkspace, OperationFailure, WorkspaceApi}; use layerfs_bridge::{ - control::{CleanupObservation, ReadyMount, WorkspaceStatus, WorkspaceToken}, + control::{CleanupObservation, MountPlace, ReadyMount, WorkspaceStatus, WorkspaceToken}, duplex::Connection, }; use layerfs_history::{BranchId, WorkspaceId}; @@ -16,6 +16,7 @@ pub fn workspace(control: &mut Control) -> InternalWorkspaceApi<'_> { InternalWorkspaceApi(WorkspaceApi { control, observation_scope: None, + place: MountPlace::default(), }) } /// Applies explicit observation scope only to this borrow's filesystem calls. @@ -26,6 +27,7 @@ pub fn with_observations<'a>( InternalWorkspaceApi(WorkspaceApi { control, observation_scope: Some(scope), + place: MountPlace::default(), }) } impl<'a> Deref for InternalWorkspaceApi<'a> { @@ -40,6 +42,13 @@ impl DerefMut for InternalWorkspaceApi<'_> { } } impl InternalWorkspaceApi<'_> { + /// Names the Sandbox and machine a mount through this channel belongs + /// to; a mount then registers them beside its Workspace. + #[must_use] + pub fn placed(mut self, sandbox: Option<&str>, machine: Option<&str>) -> Self { + self.0.place = MountPlace::new(sandbox, machine); + self + } /// Original logical bind for component proofs; kernel mount still uses both steps. pub fn bind( &mut self, diff --git a/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs b/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs index 038cf2245f..9c5e86e90f 100644 --- a/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs +++ b/control/crates/layerfs-sandbox/src/daemon/workspace/mount.rs @@ -1,6 +1,6 @@ //! Logical binding and kernel mount acknowledgements. use crate::{internal::Control, OperationFailure}; -use layerfs_bridge::control::{ReadyMount, Reply, Request, WorkspaceToken}; +use layerfs_bridge::control::{MountPlace, ReadyMount, Reply, Request, WorkspaceToken}; use layerfs_history::{BranchId, BranchSnapshot, WorkspaceId}; /// Explicit filesystem operations on one caller-owned sequential control channel. @@ -8,6 +8,10 @@ use layerfs_history::{BranchId, BranchSnapshot, WorkspaceId}; pub struct WorkspaceApi<'a> { pub control: &'a mut Control, pub observation_scope: Option<&'a [u8; 32]>, + /// The Sandbox and machine a mount through this channel belongs to, + /// when its caller knows them: the daemon registers the holder with + /// them. Both absent when the caller knows neither. + pub place: MountPlace, } impl<'a> WorkspaceApi<'a> { /// Borrows this Sandbox's original authenticated filesystem control owner. @@ -21,8 +25,16 @@ impl<'a> WorkspaceApi<'a> { Self { control, observation_scope: None, + place: MountPlace::default(), } } + /// Names the Sandbox and machine a mount through this channel belongs + /// to; a mount then registers them beside its Workspace. + #[must_use] + pub fn placed(mut self, sandbox: Option<&str>, machine: Option<&str>) -> Self { + self.place = MountPlace::new(sandbox, machine); + self + } pub fn exchange(&mut self, request: Request) -> Result> { let request = match self.observation_scope { Some(scope) => Request::Observed { diff --git a/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs b/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs index 1c6836649b..25ab47ebce 100644 --- a/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs +++ b/control/crates/layerfs-sandbox/src/daemon/workspace/recovery.rs @@ -12,7 +12,15 @@ impl WorkspaceApi<'_> { workspace: WorkspaceId, branch: BranchId, ) -> Result> { - let request = Request::Mount { workspace, branch }; + let request = if self.place.known() { + Request::MountPlaced { + workspace, + branch, + place: self.place.clone(), + } + } else { + Request::Mount { workspace, branch } + }; match self.exchange(request.clone())? { Reply::Bound { token, binding } => Ok(BoundWorkspace { token, binding }), reply => Err(OperationFailure::unexpected(request, reply)), @@ -27,10 +35,19 @@ impl WorkspaceApi<'_> { project: &str, branch: &str, ) -> Result> { - let request = Request::MountNamed { - workspace, - project: project.to_owned(), - branch: branch.to_owned(), + let request = if self.place.known() { + Request::MountNamedPlaced { + workspace, + project: project.to_owned(), + branch: branch.to_owned(), + place: self.place.clone(), + } + } else { + Request::MountNamed { + workspace, + project: project.to_owned(), + branch: branch.to_owned(), + } }; match self.exchange(request.clone())? { Reply::Bound { token, binding } => Ok(BoundWorkspace { token, binding }), diff --git a/control/crates/layerfs-sandbox/src/registry.rs b/control/crates/layerfs-sandbox/src/registry.rs index 6864944940..91d407a8d7 100644 --- a/control/crates/layerfs-sandbox/src/registry.rs +++ b/control/crates/layerfs-sandbox/src/registry.rs @@ -1,6 +1,6 @@ //! What this process owns: its running Inits and its live Sandboxes. A -//! project itself is only its home entry, so a project removed there can be -//! initialized again without a restart. +//! project itself is only its home entry, so a project deleted there can be +//! initialized again (under another name, until a compaction frees the name). //! //! A Sandbox is one daemon process (`runtime`: native, or namespaces with //! its init stage), known by its name. Its runtime runs diff --git a/control/crates/layerfs-sandbox/src/workspace/serve.rs b/control/crates/layerfs-sandbox/src/workspace/serve.rs index 457cfb1356..c878cde8c0 100644 --- a/control/crates/layerfs-sandbox/src/workspace/serve.rs +++ b/control/crates/layerfs-sandbox/src/workspace/serve.rs @@ -13,11 +13,11 @@ use crate::daemon::values; use crate::host::Host; use crate::internal::workspace; use crate::lifecycle::{operation, WORKSPACES}; -use crate::record::{DaemonRecord, WorkspaceRecord}; +use crate::record::{DaemonRecord, SandboxRecord, WorkspaceRecord}; use crate::registry::{sandbox, sandbox_live, Mount}; use crate::OperationCause; use crate::Unmounted; -use layerfs_bridge::control::{CommitControl, Reply, SdkRefusal, SdkValue}; +use layerfs_bridge::control::{CommitControl, MountPlace, Reply, SdkRefusal, SdkValue}; use layerfs_history::{BranchId, CommitId, WorkspaceId}; use layerfs_home::helpers::{lock, random, required}; use layerfs_home::names::WorkspaceName; @@ -102,7 +102,14 @@ pub fn mount(host: &Host, branch: Option<&str>, name: Option<&str>) -> Outcome { let id = WorkspaceId::from_authority(random()?).map_err(failed)?; let mounted = { let mut control = crate::daemon::trace::control(&state.controls)?; - workspace(&mut control).mount_named(id, (project, branch)) + // This Sandbox's record names the machine it runs on; the daemon + // that binds the mount registers both names beside its Workspace. + let machine = + SandboxRecord::read_in(&directory, sandbox)?.map(|record| record.machine().to_owned()); + let place = MountPlace::new(Some(state.id.as_str()), machine.as_deref()); + workspace(&mut control) + .placed(place.sandbox.as_deref(), place.machine.as_deref()) + .mount_named(id, (project, branch)) }; let mounted = mounted.map_err(|failure| match (&failure.bound, &failure.failure.cause) { // the daemon's lookup refusal, nothing bound: the call's answer diff --git a/control/crates/layerfs-store/Cargo.toml b/control/crates/layerfs-store/Cargo.toml index 0c2a6ad807..830dbf4cd3 100644 --- a/control/crates/layerfs-store/Cargo.toml +++ b/control/crates/layerfs-store/Cargo.toml @@ -31,3 +31,9 @@ postgresql = [ ] # https:// remotes: Cloudflare R2, MinIO behind TLS. tls = ["layerfs-bucket/tls"] + +# The control-level PostgreSQL `store.status` test drives a real server and +# inserts the rows a compaction leaves; this is the pinned client the +# persistence PostgreSQL feature already locks, no new version. +[dev-dependencies] +postgres = "=0.19.14" diff --git a/control/crates/layerfs-store/src/calls/branch.rs b/control/crates/layerfs-store/src/calls/branch.rs index 023d276bb2..a37bdee913 100644 --- a/control/crates/layerfs-store/src/calls/branch.rs +++ b/control/crates/layerfs-store/src/calls/branch.rs @@ -106,8 +106,7 @@ pub struct BranchMerge { pub units: Option, } -/// `branch.publish(project, branch, commit, { expected_base, expected_head, -/// force })`. +/// `branch.publish(project, branch, commit)`. #[derive(Clone, Debug, Default)] pub struct BranchPublish { /// The project. @@ -116,12 +115,15 @@ pub struct BranchPublish { pub branch: String, /// The Commit, else its head. pub commit: Option, - /// The base Layer the caller expects the Branch and main to be at. - pub expected_base: Option, - /// The Branch head Commit the caller expects. - pub expected_head: Option, - /// Publish over a moved main, as before. - pub force: Option, +} + +/// `branch.remove(project, branch)`. +#[derive(Clone, Debug, Default)] +pub struct BranchRemove { + /// The project. + pub project: String, + /// The Branch. + pub branch: String, } /// `branch.diff(project, from_branch, to_branch, { paths_only, page_size, @@ -187,6 +189,23 @@ pub fn publish(home: &Path, events: &mut Events<'_>, request: &BranchPublish) -> on_project(home, events, &request.project, StoreOp::Publish(request)) } +/// `branch.remove`: one Branch hidden by its Store marker. The result names +/// the project as the caller gave it, `/`: the Store sees +/// only the project's name within it and echoes that alone. +pub fn remove(home: &Path, events: &mut Events<'_>, request: &BranchRemove) -> Outcome { + let value = on_project( + home, + events, + &request.project, + StoreOp::BranchRemove(request), + )?; + Ok(layerfs_home::home::with_field( + value, + "project", + SdkValue::text(&request.project), + )) +} + /// `branch.diff`: the changes between two Branches. pub fn diff(home: &Path, events: &mut Events<'_>, request: &BranchDiff) -> Outcome { on_project( diff --git a/control/crates/layerfs-store/src/calls/op.rs b/control/crates/layerfs-store/src/calls/op.rs index e8bdd8f653..4e43f6cd81 100644 --- a/control/crates/layerfs-store/src/calls/op.rs +++ b/control/crates/layerfs-store/src/calls/op.rs @@ -4,6 +4,7 @@ //! a `store.call` frame to the Store's worker). use super::branch::{ BranchCommits, BranchDiff, BranchFork, BranchGetCommit, BranchMerge, BranchPublish, + BranchRemove, }; use super::commit::CommitDiff; use super::file::{ @@ -62,6 +63,9 @@ pub enum StoreOp<'a> { Statistics, /// Entry counts at one project pin. ProjectStats(&'a super::project::ProjectStats), + /// `project.remove_file`: hide one path from every node at or below its + /// marker frontier. + RemoveFile(&'a super::project::ProjectRemoveFile), /// `project.list_branches`: the Branch `name`, or one page. ListBranches { /// The one Branch it lists. @@ -88,6 +92,8 @@ pub enum StoreOp<'a> { Merge(&'a BranchMerge), /// `branch.publish`. Publish(&'a BranchPublish), + /// `branch.remove`. + BranchRemove(&'a BranchRemove), /// `branch.diff_branches`. DiffBranches(&'a BranchDiff), /// `branch.diff_commits`. @@ -236,6 +242,7 @@ impl StoreOp<'_> { match self { Self::Statistics => "store.stats", Self::ProjectStats(_) => "project.stats", + Self::RemoveFile(_) => "project.remove_file", Self::ListBranches { .. } => "project.list_branches", Self::ListCommits { .. } => "branch.list_commits", Self::BranchCommits(_) => "branch.commits", @@ -244,6 +251,7 @@ impl StoreOp<'_> { Self::Fork(_) => "branch.fork", Self::Merge(_) => "branch.merge", Self::Publish(_) => "branch.publish", + Self::BranchRemove(_) => "branch.remove", Self::DiffBranches(_) => "branch.diff_branches", Self::DiffCommits(_) => "branch.diff_commits", Self::Read(_) => "fs.read", @@ -269,6 +277,7 @@ impl StoreOp<'_> { match self { Self::Statistics => &mut args, Self::ProjectStats(r) => args.at(&r.branch, r.commit.as_deref()), + Self::RemoveFile(r) => args.text("path", &r.path), Self::ListBranches { name, page } => args.opt("name", *name).page(*page), Self::ListCommits { branch, page } => args.text("branch", branch).page(*page), Self::BranchCommits(r) => args @@ -296,10 +305,8 @@ impl StoreOp<'_> { .json("units", r.units.as_ref()), Self::Publish(r) => args .text("branch", &r.branch) - .opt("commit", r.commit.as_deref()) - .opt("expectedBase", r.expected_base.as_deref()) - .opt("expectedHead", r.expected_head.as_deref()) - .boolean("force", r.force), + .opt("commit", r.commit.as_deref()), + Self::BranchRemove(r) => args.text("branch", &r.branch), Self::DiffBranches(r) => args .text("from", &r.from_branch) .text("to", &r.to_branch) diff --git a/control/crates/layerfs-store/src/calls/project.rs b/control/crates/layerfs-store/src/calls/project.rs index d61b25fb0f..baaeef1ee5 100644 --- a/control/crates/layerfs-store/src/calls/project.rs +++ b/control/crates/layerfs-store/src/calls/project.rs @@ -1,5 +1,6 @@ //! Saved-tree project statistics through the ordinary Store-call route. use super::op::{on_project, StoreOp}; +use layerfs_bridge::control::SdkValue; use layerfs_home::{events::Events, outcome::Outcome}; use std::path::Path; @@ -14,6 +15,15 @@ pub struct ProjectStats { pub commit: Option, } +/// `project.remove_file(project, path)`. +#[derive(Clone, Debug, Default)] +pub struct ProjectRemoveFile { + /// `/`. + pub project: String, + /// The absolute POSIX path. + pub path: String, +} + /// Count one immutable saved tree, excluding the root directory. pub fn stats(home: &Path, events: &mut Events<'_>, request: &ProjectStats) -> Outcome { on_project( @@ -23,3 +33,15 @@ pub fn stats(home: &Path, events: &mut Events<'_>, request: &ProjectStats) -> Ou StoreOp::ProjectStats(request), ) } + +/// `project.remove_file`: one path hidden from every node at or below +/// its marker frontier. The result names the project as the caller gave it, +/// `/`. +pub fn remove_file(home: &Path, events: &mut Events<'_>, request: &ProjectRemoveFile) -> Outcome { + let value = on_project(home, events, &request.project, StoreOp::RemoveFile(request))?; + Ok(layerfs_home::home::with_field( + value, + "project", + SdkValue::text(&request.project), + )) +} diff --git a/control/crates/layerfs-store/src/compact.rs b/control/crates/layerfs-store/src/compact.rs new file mode 100644 index 0000000000..0a20fc12c7 --- /dev/null +++ b/control/crates/layerfs-store/src/compact.rs @@ -0,0 +1,212 @@ +//! `store.compact`: one sqlite Store's §7 rebuild, run in this process. +//! +//! The call takes the Store's lease, so a move or remove cannot start, and +//! closes the Store this process holds open: a call still running on it is +//! `InUse`, before any effect. It then opens the Store's own session, runs +//! the §7 (SQLite) or §8 (PostgreSQL) compaction and answers the §11 report. +//! A SQLite Store on another machine is `Unsupported` here: its rebuild runs +//! in that machine's worker. +use crate::identity; +#[cfg(feature = "postgresql")] +use crate::identity::Kind; +use crate::lease; +use crate::open::close; +use crate::open_args::OpenArgs; +use crate::place::{self, Executor}; +#[cfg(feature = "postgresql")] +use crate::postgresql; +use crate::record::{StoreRecord, StoreRef}; +use layerfs_bridge::control::SdkRefusal; +use layerfs_home::events::Events; +use layerfs_home::home::paths; +use layerfs_home::outcome::{failed, refused, Outcome}; +use layerfs_persistence::compact_metrics::{self, CompactRefusal}; +#[cfg(feature = "postgresql")] +use layerfs_persistence::PostgresHandles; +use layerfs_persistence::{ + CompactFailpoint, CompactReport, CompactRequest, PersistenceConfig, SqliteHandles, + SqlitePersistenceProfile, +}; +use layerfs_store_service::history::{admission, lookup}; +use std::path::Path; + +/// The T-G65 crash harness's gate: the real `layerfs store compact` process it +/// starts carries this socket, and the SQLite engine stops at the failpoint +/// below instead of reporting an unknown outcome. Ordinary callers set +/// neither variable, so a run carries no failpoint. +const CRASH_GATE_ENV: &str = "LAYERFS_COMPACT_CRASH_GATE"; +/// The stop point the crash harness names; honored only beside the gate. +const CRASH_FAILPOINT_ENV: &str = "LAYERFS_COMPACT_CRASH_FAILPOINT"; + +/// The failpoint the crash harness named, or `None` in every ordinary run. +/// +/// A failpoint alone would stop the run in-process; the gate makes the stop +/// observable to the harness, which then `SIGKILL`s this process. Requiring +/// both keeps the hook inert for production callers and for builds without +/// the engine's Unix-socket gate. +#[cfg(unix)] +fn crash_failpoint() -> Option { + std::env::var_os(CRASH_GATE_ENV)?; + match std::env::var(CRASH_FAILPOINT_ENV).ok()?.as_str() { + "BeforeSeal" => Some(CompactFailpoint::BeforeSeal), + "AfterSeal" => Some(CompactFailpoint::AfterSeal), + "BeforeVacuum" => Some(CompactFailpoint::BeforeVacuum), + "AfterBuild" => Some(CompactFailpoint::AfterBuild), + "DuringVerify" => Some(CompactFailpoint::DuringVerify), + "BeforeInstall" => Some(CompactFailpoint::BeforeInstall), + "DuringRename" => Some(CompactFailpoint::DuringRename), + "AfterInstall" => Some(CompactFailpoint::AfterInstall), + "DuringSettle" => Some(CompactFailpoint::DuringSettle), + _ => None, + } +} + +/// No gate, no failpoint: a stop would hang the run in-process. +#[cfg(not(unix))] +fn crash_failpoint() -> Option { + None +} + +/// `store.compact(name)`: reclaim one sqlite Store's dead bytes, answering +/// the §11 report. +pub fn compact(home: &Path, _events: &mut Events<'_>, store: &str) -> Outcome { + let home = home.to_path_buf(); + // A live operation is `Busy`, a dead owner's record `Unresolved`; the + // refusal is a bounded metric label and never changes what is returned. + let (_lease, record) = match lease::claim(&home, store) { + Ok(claimed) => claimed, + Err(refusal) => { + note_refusal(&refusal); + return Err(refusal); + } + }; + let store_ref = record.store_ref()?.clone(); + if matches!(store_ref, StoreRef::Postgres { .. }) { + return compact_postgresql(&record, &home, store); + } + match place::plan(&home, &store_ref)? { + Executor::Local => {} + Executor::Worker(_) => { + return Err(refused( + "Unsupported", + format!("store.compact of Store {store} runs on its own machine, not this one"), + )) + } + } + let path = paths::store_file(&home, store); + // A cached open in this process must end first; a call running on it is + // `InUse`, before any effect. + close(&path)?; + let args = OpenArgs { + home: Some(home), + store: Some(store.to_owned()), + project: None, + store_path: Some(path.display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + }; + let identity = identity::identity(&args)?; + let handles = SqliteHandles::open_writable( + PersistenceConfig::sqlite(path).with_sqlite_profile(SqlitePersistenceProfile::Disposable), + &identity.binding, + identity.cursor_key, + ) + .map_err(open_refusal)?; + let (owner_pid_start, owner_pid_boot) = match layerfs_home::process::me() { + Some((start, boot)) => (Some(start), Some(boot)), + None => (None, None), + }; + let receipt = handles + .compact(&CompactRequest { + op_id: admission::op_id(), + owner_pid: Some(std::process::id()), + owner_pid_start, + owner_pid_boot, + failpoint: crash_failpoint(), + ..CompactRequest::default() + }) + .map_err(lookup::history)?; + // One serializer for the shared §11 report: the SQLite receipt projects + // into `CompactReport`, and T9's PostgreSQL receipt will do the same. + Ok(crate::report::compact_report(&CompactReport::from(receipt))) +} + +/// `store.compact` of a PostgreSQL Store in a build without the `postgresql` +/// feature: no engine is linked, so the call is `Unsupported`. +#[cfg(not(feature = "postgresql"))] +fn compact_postgresql(_record: &StoreRecord, _home: &Path, _store: &str) -> Outcome { + Err(refused( + "Unsupported", + "this LayerFS build has no PostgreSQL engine; build the binding with --features postgresql", + )) +} + +/// The §8 PostgreSQL path: dial the Store's recorded URL, open its schema as +/// this home's authority, and run Phase M/A/B/C. The Store is usable at +/// G + 1 from the swap on; a lost reply is judged by the next call (§9). +/// +/// Only built with the `postgresql` feature; the stub above answers +/// `Unsupported` without it. +#[cfg(feature = "postgresql")] +fn compact_postgresql(record: &StoreRecord, home: &Path, store: &str) -> Outcome { + let url = crate::record::url(record)?; + let id = identity::identity(&OpenArgs { + home: Some(home.to_path_buf()), + store: Some(store.to_owned()), + store_record: Some(record.to_record().clone()), + ..OpenArgs::default() + })?; + let Kind::Postgresql { + schema, + synchronous_commit, + } = &id.kind + else { + return Err(refused( + "Failed", + format!("Store {store} is not a PostgreSQL Store"), + )); + }; + let selection = postgresql::open::selection(&url, schema, synchronous_commit); + let handles = PostgresHandles::open_writable(&selection, &id.binding, id.cursor_key) + .map_err(open_refusal)?; + let (owner_pid_start, owner_pid_boot) = match layerfs_home::process::me() { + Some((start, boot)) => (Some(start), Some(boot)), + None => (None, None), + }; + let receipt = handles + .compact(&CompactRequest { + op_id: admission::op_id(), + owner_pid: Some(std::process::id()), + owner_pid_start, + owner_pid_boot, + ..CompactRequest::default() + }) + .map_err(lookup::history)?; + Ok(crate::report::compact_report(&CompactReport::from(receipt))) +} + +/// An open refusal before the run: `Busy` is definite, everything else a +/// failure with its own text. +fn open_refusal(error: layerfs_storage::port::PersistenceError) -> SdkRefusal { + use layerfs_storage::port::PersistenceError; + let refusal = match error { + PersistenceError::Busy => refused("Busy", "the Store is held by another writer"), + PersistenceError::Refused { status } => refused( + "Busy", + format!("the Store refused the compaction: {status}"), + ), + other => failed(other), + }; + note_refusal(&refusal); + refusal +} + +/// Counts a Busy/Unresolved refusal of a call that never reached a run; the +/// measured SQLite run records the refusals it produces itself. +fn note_refusal(refusal: &SdkRefusal) { + match refusal.code.as_str() { + "Busy" => compact_metrics::record_refusal(CompactRefusal::Busy), + "Unresolved" => compact_metrics::record_refusal(CompactRefusal::Unresolved), + _ => {} + } +} diff --git a/control/crates/layerfs-store/src/lib.rs b/control/crates/layerfs-store/src/lib.rs index 97fdd79303..449f106438 100644 --- a/control/crates/layerfs-store/src/lib.rs +++ b/control/crates/layerfs-store/src/lib.rs @@ -14,6 +14,7 @@ pub mod backup; pub mod call; #[doc(hidden)] pub mod calls; +pub mod compact; pub mod diagnostic; #[doc(hidden)] pub mod identity; @@ -26,6 +27,7 @@ pub mod open_args; #[doc(hidden)] pub mod place; pub mod postgresql; +pub mod report; #[doc(hidden)] pub mod project; #[doc(hidden)] diff --git a/control/crates/layerfs-store/src/postgresql/connect.rs b/control/crates/layerfs-store/src/postgresql/connect.rs index 67228c5731..f070ca35bc 100644 --- a/control/crates/layerfs-store/src/postgresql/connect.rs +++ b/control/crates/layerfs-store/src/postgresql/connect.rs @@ -313,3 +313,27 @@ pub fn status(record: &StoreRecord) -> SdkValue { crate::postgresql::open::status(&url, &[SCHEMA.to_owned()]) .unwrap_or_else(|refusal| SdkValue::map([("unavailable", SdkValue::Text(refusal.message))])) } + +/// The Store's compaction operation as `store.status` (T10.5) renders it: +/// `{id, name, phase, started, uncertain, state, phases}`, or null when the +/// Store has none. One status query reads the Store-side `gc_op` and the +/// compaction `gc_intent`; no Store session is opened, no schema is changed +/// and no artifact or scratch schema is read. An unreachable server or a +/// query failure is null here: the `server` field already reports reach. +pub fn compact_status(record: &StoreRecord) -> SdkValue { + #[cfg(feature = "postgresql")] + { + let Ok(url) = url(record) else { + return SdkValue::Null; + }; + match layerfs_persistence::postgresql_compact_status(&url, SCHEMA) { + Ok(Some(op)) => crate::report::compact_status(&op.status()), + _ => SdkValue::Null, + } + } + #[cfg(not(feature = "postgresql"))] + { + let _ = record; + SdkValue::Null + } +} diff --git a/control/crates/layerfs-store/src/project/add.rs b/control/crates/layerfs-store/src/project/add.rs index af7e24516f..5e4236eaf0 100644 --- a/control/crates/layerfs-store/src/project/add.rs +++ b/control/crates/layerfs-store/src/project/add.rs @@ -7,6 +7,7 @@ use crate::project::discovery::Project; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_bridge::provision::{ProviderKind, StoreManifest, StoreProfile}; use layerfs_bridge::sdk_values::hex; +use layerfs_history::error::{HolderKind, HolderState, NameHolder, NameSource, NameTakenState}; use layerfs_history::{BranchId, HistoryName, LayerStackId}; use layerfs_home::helpers::random; use layerfs_home::home::paths; @@ -14,6 +15,7 @@ use layerfs_home::names::StoreName; use layerfs_home::outcome::{failed, refused, Outcome}; use layerfs_persistence::{PersistenceConfig, SealedStore, SqlitePersistenceProfile}; use layerfs_project::store::{AddRequest, InitError, ProjectApi}; +use layerfs_store_service::history::lookup; use layerfs_project::{InitCounters, ProjectError}; use std::path::{Path, PathBuf}; use std::sync::Arc; @@ -75,7 +77,7 @@ pub fn make_entry(home: &Path, store: &str, name: &str) -> Result { let entry = layerfs_home::home::paths::project_dir(home, store, name); std::fs::create_dir(&entry).map_err(|error| { if error.kind() == std::io::ErrorKind::AlreadyExists { - refused("Exists", format!("project {name} exists in Store {store}")) + home_name_taken(store, name) } else { failed(error) } @@ -85,6 +87,20 @@ pub fn make_entry(home: &Path, store: &str, name: &str) -> Result { Ok(entry) } +/// A project name the caller's home already records: `NameTaken` with its +/// `home` source, decided before the Store is asked anything. +pub(crate) fn home_name_taken(store: &str, name: &str) -> SdkRefusal { + let state = NameTakenState::new( + NameHolder::new(HolderKind::Project, name, HolderState::Live), + NameSource::Home, + ); + lookup::refuse( + "NameTaken", + format!("project {name} exists in Store {store}"), + lookup::name_taken_detail(&state), + ) +} + /// `project.init`'s add of folder `source` as the new project `name` of /// Store `store` in `home` (the caller's, or a worker's root), whose file is /// `/store//store.sqlite`. @@ -143,10 +159,7 @@ pub fn add_project(request: &ProjectAdd) -> Outcome { } let home = discovery::home_of(Some(&request.home))?; if name == store && legacy(&home, store)? { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(home_name_taken(store, name)); } let entry = make_entry(&home, store, name)?; let _guard = discovery::guard(&entry)?; @@ -213,9 +226,10 @@ pub fn add_project(request: &ProjectAdd) -> Outcome { /// diagnosis. pub fn add_failure(error: InitError, entry: Option<&Path>, name: &str, store: &str) -> SdkRefusal { let refusal = match &error { - InitError::Exists => refused( - "Exists", + InitError::NameTaken(state) => lookup::refuse( + "NameTaken", format!("Store {store} already has a project named {name}"), + lookup::name_taken_detail(state), ), InitError::NoAcquisition => refused( "Unsupported", diff --git a/control/crates/layerfs-store/src/project/delete.rs b/control/crates/layerfs-store/src/project/delete.rs new file mode 100644 index 0000000000..49f5cda341 --- /dev/null +++ b/control/crates/layerfs-store/src/project/delete.rs @@ -0,0 +1,940 @@ +//! `project.delete`: a project is retired in its Store and its home entry is +//! removed (spec §4, §4.2, §5.1 and §10). +//! +//! The marker is the commit point. The caller first saves the legacy +//! own-project identity, then writes the durable intent +//! `store//delete/.json` with +//! `{store, project, stack_id, deleted_ms, attempt_ms, state}`, then marks the +//! Stack, then removes only its own home entry and unlinks the intent. A +//! retry reads the intent by the recorded Stack id, reuses its `deleted_ms` +//! and finishes the entry: `Marked` means this attempt marked a live Stack, +//! `Retired` means the marker was already there (including a hidden Store +//! project whose home entry is stale), and `Absent` means no live Stack is +//! there, so the stale entry goes. A lost worker reply is `Unknown`; the +//! intent stays and the retry classifies the Stack again. A home record whose +//! Stack differs from the intent is a project made again under the same name: +//! the stale intent is discarded and this call starts over against the record +//! that is there now. +//! +//! The worker op is `project.delete`; its frame is +//! `{store, stack_id, deleted_ms?, project?, op_id?, store_record?}`. The two +//! optional context fields are the ones the retired `project.remove` call sent: the +//! worker opens the Store under its own root with the caller's `store_record`, +//! and the project name lets its reply and its own home entry name the +//! project. The worker saves the legacy own-project identity, writes the +//! marker, removes its own entry and replies `{kind, project, stack_id, +//! deleted_ms}`; the caller removes its own entry and echoes +//! `home_entry_removed`. +//! +//! Before any of that, the home path admits the project scope (T4.6, +//! `project.delete.admit` on the worker route): the same `gc_register` the +//! Store-side removals rely on, taken before the identity save, the sidecar +//! and the marker. A live mount refuses `MountsActive` with its holders and a +//! live operation `Busy`, with no sidecar written and no marker. The marker +//! reuses the admission's operation identity, and the caller releases it on +//! every exit path (`project.delete.release`), so a refused or failed call +//! leaves no admission row behind. +use crate::open_args::OpenArgs; +use crate::place::{self, Executor, Worker}; +use crate::project::frame::{DeleteAdmitFrame, DeleteFrame, DeleteReleaseFrame, DeleteReply}; +use crate::project::record::ProjectRecord; +use crate::record::{StoreRecord, StoreRef}; +use crate::{identity, lease, service}; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_bridge::provision::StoreManifest; +use layerfs_bridge::sdk_values::{hex, unhex}; +use layerfs_history::HistoryError; +use layerfs_history::LayerStackId; +use layerfs_home::events::Events; +use layerfs_home::home::{now_ms, paths}; +use layerfs_home::names::{ProjectRef, StoreName}; +use layerfs_home::outcome::{failed, refused, Outcome}; +use layerfs_store_service::history::admission as store_admission; +use layerfs_store_service::history::deletion::{delete_stack_with, Deletion}; +use layerfs_store_service::history::lookup; +use std::fs::{self, File, OpenOptions}; +use std::io::Write; +use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +type Result = std::result::Result; + +/// The state the durable intent records (`pending`, `marked`, `done`). +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum IntentState { + /// The identity is saved and the intent is durable; the marker may or may + /// not have been written (a lost reply leaves this state). + Pending, + /// The marker is committed. The home entry may still be there. + Marked, + /// The home entry was removed. The intent is unlinked next; a crash + /// between the two leaves this state for the retry to settle. + Done, +} + +impl IntentState { + /// The state's file and frame text. + pub fn as_str(self) -> &'static str { + match self { + Self::Pending => "pending", + Self::Marked => "marked", + Self::Done => "done", + } + } + + /// The state `text` names, if any. + pub fn parse(text: &str) -> Option { + match text { + "pending" => Some(Self::Pending), + "marked" => Some(Self::Marked), + "done" => Some(Self::Done), + _ => None, + } + } +} + +/// The durable delete intent at `store//delete/.json`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct Intent { + /// The Store the project was in, as sent. + pub store: String, + /// The project's name in it, as sent. + pub project: String, + /// The LayerStack the home record held when the intent was written; a + /// retry resolves the Store by this id, never by name. + pub stack: LayerStackId, + /// The `deleted_ms` the marker holds, or is asked to hold. A retry reuses + /// this value; a `Retired` marker may replace it with its stored value. + pub deleted_ms: i64, + /// When the last attempt started, in milliseconds. + pub attempt_ms: i64, + /// Where the attempt got to. + pub state: IntentState, + /// The project-scope admission this attempt took, when it took one. A + /// retry re-registers the same identity, so a call whose reply was lost + /// settles its own row instead of meeting it as another operation. + pub op: Option<[u8; 16]>, +} + +static NEXT_TEMPORARY: AtomicU64 = AtomicU64::new(0); + +impl Intent { + /// The intent's path in `home`. + pub fn path(home: &Path, store: &str, project: &str) -> PathBuf { + paths::store_dir(home, store) + .join("delete") + .join(format!("{project}.json")) + } + + /// The intent of project `project` of Store `store`, or `None`. + pub fn read(home: &Path, store: &str, project: &str) -> Result> { + let path = Self::path(home, store, project); + let Some(value) = layerfs_home::home::read_record(&path)? else { + return Ok(None); + }; + let malformed = || { + refused( + "InvalidInput", + format!("project.delete intent {} is malformed", path.display()), + ) + }; + let store = value.get_text("store").ok_or_else(malformed)?.to_owned(); + let project = value.get_text("project").ok_or_else(malformed)?.to_owned(); + let stack = value + .get_text("stack_id") + .and_then(unhex) + .and_then(|bytes| LayerStackId::from_slice(&bytes).ok()) + .ok_or_else(malformed)?; + let deleted_ms = value.get_int("deleted_ms").ok_or_else(malformed)?; + let attempt_ms = value.get_int("attempt_ms").ok_or_else(malformed)?; + let state = value + .get_text("state") + .and_then(IntentState::parse) + .ok_or_else(malformed)?; + let op = match value.get_text("op_id") { + Some(text) => { + let bytes = unhex(text).ok_or_else(malformed)?; + let body: [u8; 16] = bytes.as_slice().try_into().map_err(|_| malformed())?; + Some(body) + } + None => None, + }; + Ok(Some(Self { + store, + project, + stack, + deleted_ms, + attempt_ms, + state, + op, + })) + } + + /// Writes the intent whole: a private temporary file, fsync, one rename, + /// then the directory's fsync. A reader sees the old intent or the new + /// one, never a part of either. + pub fn write(home: &Path, intent: &Self) -> Result<()> { + let path = Self::path(home, &intent.store, &intent.project); + let parent = path + .parent() + .ok_or_else(|| refused("Failed", "a delete intent needs a folder"))?; + fs::DirBuilder::new() + .recursive(true) + .mode(0o700) + .create(parent) + .map_err(failed)?; + let unique = NEXT_TEMPORARY.fetch_add(1, Ordering::Relaxed); + let temporary = parent.join(format!( + ".{}.{}.{}.tmp", + intent.project, + std::process::id(), + unique + )); + let mut fields: Vec<(String, SdkValue)> = vec![ + ("store".to_owned(), SdkValue::text(&intent.store)), + ("project".to_owned(), SdkValue::text(&intent.project)), + ( + "stack_id".to_owned(), + SdkValue::text(hex(&intent.stack.to_bytes())), + ), + ("deleted_ms".to_owned(), SdkValue::Int(intent.deleted_ms)), + ("attempt_ms".to_owned(), SdkValue::Int(intent.attempt_ms)), + ("state".to_owned(), SdkValue::text(intent.state.as_str())), + ]; + if let Some(op) = intent.op { + fields.push(("op_id".to_owned(), SdkValue::text(hex(&op)))); + } + let value = SdkValue::Map(fields); + let mut text = layerfs_home::json::print(&value); + text.push('\n'); + let mut file = OpenOptions::new() + .write(true) + .create_new(true) + .mode(0o600) + .open(&temporary) + .map_err(failed)?; + let written = file + .write_all(text.as_bytes()) + .and_then(|()| file.sync_all()) + .map_err(failed); + drop(file); + let renamed = written.and_then(|()| fs::rename(&temporary, &path).map_err(failed)); + if let Err(refusal) = renamed { + let _ = fs::remove_file(&temporary); + return Err(refusal); + } + // the directory entry is durable too; a filesystem that cannot + // fsync a directory has already made the rename durable + let _ = File::open(parent).and_then(|folder| folder.sync_all()); + Ok(()) + } + + /// Removes the intent, if it is there. + pub fn unlink(home: &Path, store: &str, project: &str) -> Result<()> { + let path = Self::path(home, store, project); + match fs::remove_file(&path) { + Ok(()) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(failed(error)), + } + if let Some(parent) = path.parent() { + let _ = File::open(parent).and_then(|folder| folder.sync_all()); + } + Ok(()) + } + + /// Drops an intent that no longer describes the home record (a project + /// made again under the same name). + pub fn discard(home: &Path, store: &str, project: &str) -> Result<()> { + Self::unlink(home, store, project) + } +} + +/// The project-scope admission `project.delete` takes before its sidecar and +/// marker: the admission row's operation identity, reused by the marker so the +/// one row is excluded from its own scan and released once. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct Admission { + /// The `gc_intent` operation identity. + pub op: [u8; 16], + /// The project scope it holds. + pub stack: LayerStackId, +} + +impl Admission { + /// One admission of `stack` under operation `op`. + pub const fn new(stack: LayerStackId, op: [u8; 16]) -> Self { + Self { op, stack } + } +} + +/// The Store side of one `project.delete` attempt and the caller's entry +/// removal, as one seam so the home path is testable without a Store. +pub trait Effects { + /// Saves the legacy own-project identity before the intent and the + /// marker; idempotent on a retry. + fn prepare(&mut self) -> Result<()>; + + /// Takes the project-scope admission before the sidecar and the marker: + /// a live mount is `MountsActive` with its holders, a live operation + /// `Busy`, an uncertain owner `Unresolved`. A refusal registers nothing. + /// `reuse` is the identity the sidecar recorded for a retry; the same row + /// is re-registered under it, so a lost reply is settled, never met as a + /// second operation. + fn admit(&mut self, stack: LayerStackId, reuse: Option<[u8; 16]>) -> Result; + + /// Releases `admission` on every exit path: success, refusal and an + /// unknown Store outcome. A provider without admission releases nothing. + fn release(&mut self, admission: Admission) -> Result<()>; + + /// Marks (or reclassifies) `admission`'s Stack, reusing the admission's + /// operation identity. A retry passes the intent's `deleted_ms`. + fn mark(&mut self, admission: Admission, deleted_ms: i64) -> Result; + + /// Removes the caller's home entry; `Ok(())` when nothing remains. + fn remove_entry(&mut self, entry: &Path) -> Result<()>; +} + +/// The `project` part of a Stack record from a home record: the `manifest`'s +/// Stack for a local sqlite record, the record's `stack` for a PostgreSQL or +/// worker record. +fn stack_of_value(value: &SdkValue) -> Option { + if let Some(SdkValue::Bytes(bytes)) = value.get("manifest") { + if let Ok(manifest) = StoreManifest::decode(bytes) { + if let Ok(stack) = LayerStackId::from_slice(&manifest.stack) { + return Some(stack); + } + } + } + value + .get_text("stack") + .and_then(unhex) + .and_then(|bytes| LayerStackId::from_slice(&bytes).ok()) +} + +/// The Stack a home record names, if it names one. +fn stack_of(record: &ProjectRecord) -> Option { + stack_of_value(record.to_record()) +} + +/// `{kind: "Removed", project, deleted_ms, home_entry_removed}` (spec §10; +/// `home_entry_removed: false` is still success, the marker being the commit +/// point). +fn removed(store: &str, project: &str, deleted_ms: i64, home_entry_removed: bool) -> SdkValue { + SdkValue::map([ + ("kind", SdkValue::text("Removed")), + ("project", SdkValue::text(format!("{store}/{project}"))), + ("deleted_ms", SdkValue::Int(deleted_ms)), + ("home_entry_removed", SdkValue::Bool(home_entry_removed)), + ]) +} + +/// The side effects and the project-scope admission one finishing attempt +/// runs against: together, so `mark_and_finish` stays a small call. +struct Finish<'a> { + effects: &'a mut dyn Effects, + admission: Admission, +} + +/// The mutating part of `delete_with` after the project scope is admitted: +/// the identity save, the sidecar, the marker and the entry removal (spec §4). +fn mark_and_finish( + home: &Path, + store: &str, + project: &str, + stack: LayerStackId, + intent: Option, + mut deleted_ms: i64, + finish: Finish<'_>, +) -> Outcome { + let Finish { + effects, + admission, + } = finish; + effects.prepare()?; + let mut current = match intent { + Some(intent) => intent, + None => Intent { + store: store.to_owned(), + project: project.to_owned(), + stack, + deleted_ms, + attempt_ms: now_ms(), + state: IntentState::Pending, + op: None, + }, + }; + // the sidecar names the admission, so a retry reuses it + current.op = Some(admission.op); + if current.state == IntentState::Pending { + current.attempt_ms = now_ms(); + Intent::write(home, ¤t)?; + } + + let deletion = effects.mark(admission, deleted_ms)?; + deleted_ms = deletion.deleted_ms(deleted_ms); + current.deleted_ms = deleted_ms; + current.state = IntentState::Marked; + current.attempt_ms = now_ms(); + Intent::write(home, ¤t)?; + + let home_entry_removed = effects + .remove_entry(&paths::project_dir(home, store, project)) + .is_ok(); + if home_entry_removed { + current.state = IntentState::Done; + Intent::write(home, ¤t)?; + Intent::unlink(home, store, project)?; + } + Ok(removed(store, project, deleted_ms, home_entry_removed)) +} + +/// Runs `project.delete` for a home entry whose Store side is `effects`. +/// +/// `stack` is the Stack id resolved from the record or the Store listing; a +/// record without one whose Store does not list it is a stale entry and is +/// removed without a marker. The same function serves the local and worker +/// routes, and a fake in tests. +/// +/// The project scope is admitted before the identity save, the sidecar and +/// the marker: a live mount is `MountsActive` with its holders and a live +/// operation `Busy`, reported with no sidecar written and no marker. The +/// admission is released on every exit path. +pub fn delete_with( + home: &Path, + store: &str, + project: &str, + stack: Option, + effects: &mut impl Effects, +) -> Outcome { + let record = ProjectRecord::read(home, store, project)?; + let record_stack = record.as_ref().and_then(stack_of); + let mut intent = Intent::read(home, store, project)?; + + // A different Stack id for the same name is a project made again: the + // stale intent must not touch its entry, so it is discarded and this + // call starts over against the record that is there now. + if let (Some(stale), Some(current)) = (&intent, record_stack) { + if stale.stack != current { + Intent::discard(home, store, project)?; + intent = None; + } + } + + let (stack, deleted_ms) = match &intent { + Some(intent) => (intent.stack, intent.deleted_ms), + None => { + let Some(stack) = stack.or(record_stack) else { + if record.is_none() { + return Err(refused( + "NoSuchProject", + format!("no project {store}/{project}"), + )); + } + // An untracked stale entry: save a legacy identity before it + // goes, then remove it. There is no Stack id to mark. + effects.prepare()?; + let deleted_ms = now_ms(); + let removed_entry = effects + .remove_entry(&paths::project_dir(home, store, project)) + .is_ok(); + return Ok(removed(store, project, deleted_ms, removed_entry)); + }; + (stack, now_ms()) + } + }; + + if let Some(done) = &intent { + if done.state == IntentState::Done { + // The retired-row entry-removal retry needs no admission: the + // marker is already there and only the home entry is removed. + effects.prepare()?; + let removed_entry = effects + .remove_entry(&paths::project_dir(home, store, project)) + .is_ok(); + let mut settled = done.clone(); + settled.attempt_ms = now_ms(); + let _ = Intent::write(home, &settled); + let _ = Intent::unlink(home, store, project); + return Ok(removed(store, project, deleted_ms, removed_entry)); + } + } + + // Admission before the identity save, the sidecar and the marker. A + // refusal returns here, so neither the sidecar nor the marker is written. + // A retry re-registers the identity its sidecar recorded; a refusal then + // releases that identity, never adopting it as a live operation. + let reuse = intent.as_ref().and_then(|intent| intent.op); + let admission = match effects.admit(stack, reuse) { + Ok(admission) => admission, + Err(refusal) => { + if let Some(op) = reuse { + let _ = effects.release(Admission::new(stack, op)); + } + return Err(refusal); + } + }; + let attempt = mark_and_finish( + home, + store, + project, + stack, + intent, + deleted_ms, + Finish { + effects: &mut *effects, + admission, + }, + ); + let released = effects.release(admission); + match attempt { + Ok(outcome) => { + released?; + Ok(outcome) + } + // The original failure is the reported one; a failed release is named + // so a leaked admission row is not silent. + Err(error) => Err(match released { + Ok(()) => error, + Err(cause) => SdkRefusal { + message: format!( + "{}; releasing the project admission: {}", + error.message, cause.message + ), + ..error + }, + }), + } +} + +/// Removes a directory tree, treating an absent entry as removed. +fn remove_tree(entry: &Path) -> Result<()> { + match fs::remove_dir_all(entry) { + Ok(()) => Ok(()), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()), + Err(error) => Err(failed(format!("removing {}: {error}", entry.display()))), + } +} + +/// The Store-side opens of `project.delete` in this process. +struct Local { + home: PathBuf, + store: String, + project: String, + open: OpenArgs, +} + +impl Effects for Local { + fn prepare(&mut self) -> Result<()> { + if self.project != self.store || !identity::legacy(&self.home, &self.store)? { + return Ok(()); + } + let id = identity::identity(&self.open)?; + layerfs_home::home::private_dir(&identity::store_dir(&self.home, &self.store)?)?; + identity::save_record(&self.home, &self.store, &id) + } + + fn admit(&mut self, stack: LayerStackId, reuse: Option<[u8; 16]>) -> Result { + let intent = match reuse { + Some(op) => store_admission::project_removal_at(stack, op), + None => store_admission::project_removal_from_id(stack), + }; + let op = intent.op_id; + service::with_service(&self.open, |service| { + match service.store.history().gc_register(&intent) { + Ok(()) => Ok(Admission::new(stack, op)), + // A provider without admission cannot exclude a removal; the + // marker's own admission still runs, as it did before T6. + Err(HistoryError::Unsupported(_)) => Ok(Admission::new(stack, op)), + Err(error) => Err(lookup::history(error)), + } + }) + } + + fn release(&mut self, admission: Admission) -> Result<()> { + service::with_service(&self.open, |service| { + match service.store.history().gc_release(&admission.op) { + Ok(()) | Err(HistoryError::Unsupported(_)) => Ok(()), + Err(error) => Err(lookup::history(error)), + } + }) + } + + fn mark(&mut self, admission: Admission, deleted_ms: i64) -> Result { + let intent = store_admission::project_removal_at(admission.stack, admission.op); + service::with_service(&self.open, |service| { + delete_stack_with(&service.store, admission.stack, deleted_ms, &intent) + }) + } + + fn remove_entry(&mut self, entry: &Path) -> Result<()> { + remove_tree(entry) + } +} + +/// The Store-side opens of `project.delete` in a sqlite Store's worker. +struct Remote { + worker: Worker, + store: String, + project: String, + store_record: SdkValue, +} + +impl Effects for Remote { + fn prepare(&mut self) -> Result<()> { + // the worker saves its own legacy identity before its marker + Ok(()) + } + + fn admit(&mut self, stack: LayerStackId, reuse: Option<[u8; 16]>) -> Result { + let op = reuse.unwrap_or_else(store_admission::op_id); + let frame = DeleteAdmitFrame { + store: StoreName::parse(&self.store)?, + stack, + op, + store_record: Some(self.store_record.clone()), + }; + let answer = match self + .worker + .call("project.delete.admit", frame.encode(), &mut |_| {}) + { + Ok(answer) => answer, + Err(refusal) => { + // The request went out, so the worker may have registered the + // row before its answer was lost: settle the identity before + // reporting the unknown outcome. + if refusal.code == "Unknown" { + let _ = self.release(Admission::new(stack, op)); + } + return Err(refusal); + } + }; + if let Err(refusal) = admit_reply(&answer, stack) { + let _ = self.release(Admission::new(stack, op)); + return Err(refusal); + } + Ok(Admission::new(stack, op)) + } + + fn release(&mut self, admission: Admission) -> Result<()> { + let frame = DeleteReleaseFrame { + store: StoreName::parse(&self.store)?, + op: admission.op, + store_record: Some(self.store_record.clone()), + }; + self.worker + .call("project.delete.release", frame.encode(), &mut |_| {})?; + Ok(()) + } + + fn mark(&mut self, admission: Admission, deleted_ms: i64) -> Result { + let frame = DeleteFrame { + store: StoreName::parse(&self.store)?, + project: Some(self.project.clone()), + stack: admission.stack, + deleted_ms: Some(deleted_ms), + op_id: Some(admission.op), + store_record: Some(self.store_record.clone()), + }; + let answer = self + .worker + .call("project.delete", frame.encode(), &mut |_| {})?; + let reply = DeleteReply::decode(&answer)?; + if reply.stack != admission.stack { + return Err(refused( + "Failed", + "the worker answered for another LayerStack", + )); + } + Ok(Deletion::Marked { + deleted_ms: reply.deleted_ms, + }) + } + + fn remove_entry(&mut self, entry: &Path) -> Result<()> { + remove_tree(entry) + } +} + +/// Checks the worker's `project.delete.admit` answer. +fn admit_reply(answer: &SdkValue, stack: LayerStackId) -> Result<()> { + if answer.get_text("kind") != Some("Admitted") { + return Err(refused( + "Failed", + "the worker project.delete admission is not `Admitted`", + )); + } + let answered = answer + .get_text("stack_id") + .and_then(unhex) + .and_then(|bytes| LayerStackId::from_slice(&bytes).ok()); + if answered != Some(stack) { + return Err(refused("Failed", "the worker admitted another LayerStack")); + } + Ok(()) +} + +/// The `OpenArgs` a local Store call opens with. `record` is absent for a +/// Store made by its own project Init, whose identity is the project entry. +fn open_args( + home: &Path, + store: &str, + project: &str, + record: Option<&StoreRecord>, +) -> Result { + let (store_path, postgresql) = match record { + Some(record) => match record.store_ref()? { + StoreRef::Postgres { .. } => ( + record.postgresql_key(home, store), + Some(crate::postgresql::connect::selection(record)?), + ), + StoreRef::Sqlite { .. } => (paths::store_file(home, store), None), + }, + None => (paths::store_file(home, store), None), + }; + Ok(OpenArgs { + home: Some(home.to_path_buf()), + store: Some(store.to_owned()), + project: Some(project.to_owned()), + store_path: Some(store_path.display().to_string()), + store_record: record.map(|record| record.to_record().clone()), + postgresql, + }) +} + +/// The Stack id a Store lists for project `name`, for a record that does +/// not name one (spec §4.2 fills it from the filtered listing by name). +fn listed_stack(open: &OpenArgs, name: &str) -> Result> { + service::with_service(open, |service| { + let stacks = service + .store + .published(layerfs_project::store::projects) + .map_err(failed)?; + Ok(stacks + .into_iter() + .find(|stack| stack.name.as_str() == name) + .map(|stack| stack.id)) + }) +} + +/// `project.delete(project)`: retires project `project` in its Store and +/// removes the caller's home entry. The marker is the commit point; a home +/// removal failure is success with `home_entry_removed: false`, and the +/// durable intent lets a same-home retry finish it. +pub fn delete(home: &Path, events: &mut Events<'_>, project: &ProjectRef) -> Outcome { + let _ = events; + let home = home.to_path_buf(); + let store = project.store.as_str(); + let name = project.project.as_str(); + let record = StoreRecord::read(&home, store)?; + let project_record = ProjectRecord::read(&home, store, name)?; + let stack = project_record.as_ref().and_then(stack_of); + match record { + Some(record) => { + record.unblocked()?; + let store_ref = record.store_ref()?.clone(); + // the caller holds the Store's lease while it sends the call + // there, as every call that runs in a worker does + let _lease = lease::hold(&home, store)?; + match place::plan(&home, &store_ref)? { + Executor::Local => { + let open = open_args(&home, store, name, Some(&record))?; + let stack = match stack { + Some(stack) => Some(stack), + None if project_record.is_some() => listed_stack(&open, name)?, + None => None, + }; + let mut effects = Local { + home: home.clone(), + store: store.to_owned(), + project: name.to_owned(), + open, + }; + delete_with(&home, store, name, stack, &mut effects) + } + Executor::Worker(worker) => { + if stack.is_none() && project_record.is_some() { + return Err(refused( + "Unsupported", + format!( + "project {store}/{name} has no recorded LayerStack id and its Store is on another machine; \ + list it on that machine first" + ), + )); + } + let mut effects = Remote { + worker, + store: store.to_owned(), + project: name.to_owned(), + store_record: record.to_record().clone(), + }; + delete_with(&home, store, name, stack, &mut effects) + } + } + } + None => { + // A Store made by its own project's Init has no Store record: its + // identity lives in the project entry, and saving it before that + // entry goes is exactly the legacy own-project identity save. + if name != store || project_record.is_none() { + return Err(refused("NoSuchStore", format!("no Store named {store}"))); + } + let open = open_args(&home, store, name, None)?; + let stack = match stack { + Some(stack) => Some(stack), + None => listed_stack(&open, name)?, + }; + let mut effects = Local { + home: home.clone(), + store: store.to_owned(), + project: name.to_owned(), + open, + }; + delete_with(&home, store, name, stack, &mut effects) + } + } +} + +/// The `OpenArgs` a worker's `project.delete` ops open the Store with: the +/// Store file under the worker's own root and the caller's Store record. +fn worker_open( + root: &Path, + store: &str, + project: Option, + store_record: SdkValue, +) -> OpenArgs { + OpenArgs { + home: Some(root.to_path_buf()), + store: Some(store.to_owned()), + project, + store_path: Some(paths::store_file(root, store).display().to_string()), + store_record: Some(store_record), + postgresql: None, + } +} + +/// The `{kind: "Admitted", stack_id}` answer. +fn admitted(stack: LayerStackId) -> SdkValue { + SdkValue::map([ + ("kind", SdkValue::text("Admitted")), + ("stack_id", SdkValue::text(hex(&stack.to_bytes()))), + ]) +} + +/// The `{kind: "Released", op_id}` answer. +fn released(op: [u8; 16]) -> SdkValue { + SdkValue::map([ + ("kind", SdkValue::text("Released")), + ("op_id", SdkValue::text(hex(&op))), + ]) +} + +/// The worker's `project.delete.admit`: registers the caller's project-scope +/// admission before the caller writes its sidecar and before the marker, so a +/// live mount refuses with `MountsActive` (its holders reported) and a live +/// operation with `Busy`, with no sidecar written. +pub fn admit_project(root: &Path, frame: &DeleteAdmitFrame) -> Outcome { + let store_record = frame.store_record.clone().ok_or_else(|| { + refused( + "InvalidInput", + "project.delete.admit needs the Store's record", + ) + })?; + let open = worker_open(root, frame.store.as_str(), None, store_record); + let intent = store_admission::project_removal_at(frame.stack, frame.op); + service::with_service(&open, |service| { + match service.store.history().gc_register(&intent) { + Ok(()) => Ok(admitted(frame.stack)), + // A provider without admission cannot exclude a removal; the + // marker still admits, as it did before T6. + Err(HistoryError::Unsupported(_)) => Ok(admitted(frame.stack)), + Err(error) => Err(lookup::history(error)), + } + }) +} + +/// The worker's `project.delete.release`: deletes the caller's admission row +/// after the marker, on every exit path. +pub fn release_project(root: &Path, frame: &DeleteReleaseFrame) -> Outcome { + let store_record = frame.store_record.clone().ok_or_else(|| { + refused( + "InvalidInput", + "project.delete.release needs the Store's record", + ) + })?; + let open = worker_open(root, frame.store.as_str(), None, store_record); + service::with_service(&open, |service| { + match service.store.history().gc_release(&frame.op) { + Ok(()) | Err(HistoryError::Unsupported(_)) => Ok(released(frame.op)), + Err(error) => Err(lookup::history(error)), + } + }) +} + +/// The worker's `project.delete` on a Store under `root`: save the legacy +/// own-project identity, write the marker, remove the worker's own entry and +/// answer `{kind, project, stack_id, deleted_ms}`. The marker reuses the +/// caller's admission operation identity when its frame carries one, so the +/// caller's admitted row is excluded from its own scan; without one the +/// marker takes a fresh identity and its own admission, as before. +pub fn delete_project(root: &Path, frame: &DeleteFrame) -> Outcome { + let store = frame.store.as_str(); + let store_record = frame + .store_record + .clone() + .ok_or_else(|| refused("InvalidInput", "project.delete needs the Store's record"))?; + let open = worker_open(root, store, frame.project.clone(), store_record); + // The legacy own-project entry carries the Store's identity until the + // marker; save it first, idempotently. + let own = frame.project.as_deref() == Some(store) && identity::legacy(root, store)?; + if own { + let id = identity::identity(&open)?; + layerfs_home::home::private_dir(&identity::store_dir(root, store)?)?; + identity::save_record(root, store, &id)?; + } + let op = frame.op_id.unwrap_or_else(store_admission::op_id); + let intent = store_admission::project_removal_at(frame.stack, op); + let requested = frame.deleted_ms.unwrap_or_else(now_ms); + let deletion = service::with_service(&open, |service| { + delete_stack_with(&service.store, frame.stack, requested, &intent) + })?; + let deleted_ms = deletion.deleted_ms(requested); + let project = remove_worker_entry(root, store, frame.stack, frame.project.as_deref())? + .or_else(|| frame.project.clone()) + .unwrap_or_else(|| store.to_owned()); + Ok(DeleteReply { + project, + stack: frame.stack, + deleted_ms, + } + .encode()) +} + +/// Removes the worker's own home entry for `stack`; returns the project name +/// it removed, if any. +#[doc(hidden)] +pub fn remove_worker_entry( + root: &Path, + store: &str, + stack: LayerStackId, + hint: Option<&str>, +) -> Result> { + let names = match hint { + Some(name) => vec![name.to_owned()], + None => paths::names(&paths::store_dir(root, store).join("project")).map_err(failed)?, + }; + let mut removed = None; + for name in names { + let record = paths::project_record(root, store, &name); + let Some(value) = layerfs_home::home::read_record(&record)? else { + continue; + }; + let matches = stack_of_value(&value) == Some(stack) || name == store; + if matches { + remove_tree(&paths::project_dir(root, store, &name))?; + removed.get_or_insert(name); + } + } + Ok(removed) +} diff --git a/control/crates/layerfs-store/src/project/export/walk.rs b/control/crates/layerfs-store/src/project/export/walk.rs index d97f2d4dee..6cd6ab29eb 100644 --- a/control/crates/layerfs-store/src/project/export/walk.rs +++ b/control/crates/layerfs-store/src/project/export/walk.rs @@ -19,6 +19,7 @@ use layerfs_history::NodeId; use layerfs_home::outcome::refused; use layerfs_store_service::history::{lookup, MAIN}; use layerfs_store_service::read::cached::Cached; +use layerfs_store_service::read::visibility::Visibility; use layerfs_store_service::store::StorePorts; use layerfs_store_service::StoreService; use layerfs_telemetry::timer::Timing; @@ -45,6 +46,9 @@ pub(super) struct PinnedSnapshot { pub(super) node: String, pub(super) root: String, tree: TreeTable, + /// §4.3: the pinned node's marker visibility. Hidden entries are omitted + /// from the exported folder and from its counts. + visibility: Visibility, } /// Resolves `(project, branch)` once into an immutable `(NodeId, ObjectId, @@ -65,12 +69,21 @@ pub(super) fn pin_snapshot( let root = lookup::root(&service.store, node)?; let reader = service.store.ports(stack.scope); let tree = TreeTable::open(reader.as_ref(), FilesystemRootId(root)).map_err(lookup::content)?; + let serial = match service + .store + .published(|history| history.node_history_serial(node)) + { + Ok(Some(serial)) => serial, + _ => 0, + }; + let visibility = Visibility::for_stack(&service.store, stack.id, serial); Ok(PinnedSnapshot { reader, label, node: node_text(node), root: hex(root.as_bytes()), tree, + visibility, }) } @@ -163,6 +176,11 @@ pub(super) fn stream_snapshot( rel.push(b'/'); } rel.extend_from_slice(name.as_bytes()); + // A hidden entry is omitted; a hidden directory's subtree with it, as + // the read surface omits it and the marker hides everything below it. + if pinned.visibility.hidden_relative(&rel).is_some() { + continue; + } match value.kind { InodeKind::Directory => { counts.directories += 1; diff --git a/control/crates/layerfs-store/src/project/family.rs b/control/crates/layerfs-store/src/project/family.rs index 6ed7a2c2b6..6b1cf8985b 100644 --- a/control/crates/layerfs-store/src/project/family.rs +++ b/control/crates/layerfs-store/src/project/family.rs @@ -5,21 +5,20 @@ //! `native` or a PostgreSQL Store, in the machine's worker for a sqlite //! Store on any other machine (#536 H11). The folder is always on the //! caller's host: for a worker this process copies it to the machine -//! first (H11a). Records in the home list projects; `remove` drops one -//! project's history from its Store. +//! first (H11a). Records in the home list projects. use crate::calls::Page; use crate::lease; -use crate::place::{self, Executor}; +use crate::open_args::OpenArgs; +use crate::place::{self, Executor, Worker}; use crate::project::add::{add_project, ProjectAdd}; -use crate::project::discovery::home_of; -use crate::project::frame::{InitFrame, RemoveFrame}; +use crate::project::frame::{InitFrame, ListingFrame, ListingReply}; use crate::project::postgres_init::PgProjectAdd; use crate::project::record::ProjectRecord; use crate::record::{StoreRecord, StoreRef}; use crate::resolve; +use crate::service; use crate::sqlite::family::progress; -use crate::Related; -use layerfs_bridge::control::SdkValue; +use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_home::events::Events; use layerfs_home::home::paths; use layerfs_home::names::{ProjectRef, StoreName}; @@ -49,6 +48,90 @@ pub struct ProjectInit { pub timeout: Option, } +/// One project a Store's filtered listing names: its name and LayerStack. +struct LiveProject { + name: String, + stack: Vec, +} + +/// The live projects Store `store` lists, after the retired/hidden ones are +/// filtered out (spec §4.2). Every route reads the listing where the +/// Store's calls run (T4.5c): in this process for a sqlite Store on this +/// machine and for a PostgreSQL Store, in the machine's worker for a sqlite +/// Store on another machine. A Store that cannot be listed is `Err`. +fn live_projects( + home: &Path, + store: &str, + record: &StoreRecord, +) -> std::result::Result, SdkRefusal> { + let store_ref = record.store_ref()?; + record.unblocked()?; + if let Executor::Worker(mut worker) = place::plan(home, store_ref)? { + return live_projects_on_worker(&mut worker, store, record); + } + let (store_path, postgresql) = match store_ref { + StoreRef::Postgres { .. } => ( + record.postgresql_key(home, store), + Some(crate::postgresql::connect::selection(record)?), + ), + StoreRef::Sqlite { .. } => (paths::store_file(home, store), None), + }; + let open = OpenArgs { + home: Some(home.to_path_buf()), + store: Some(store.to_owned()), + store_path: Some(store_path.display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql, + ..OpenArgs::default() + }; + let stacks = service::with_service(&open, |service| { + service + .store + .published(layerfs_project::store::projects) + .map_err(failed) + })?; + Ok(stacks + .into_iter() + .map(|stack| LiveProject { + name: stack.name.as_str().to_owned(), + stack: stack.id.to_bytes().to_vec(), + }) + .collect()) +} + +/// The listing a worker-backed Store sends (T4.5c): the worker runs the +/// same `layerfs_project::store::projects` under its own root, so a project +/// retired in the Store is hidden here as it is for a local one. +fn live_projects_on_worker( + worker: &mut Worker, + store: &str, + record: &StoreRecord, +) -> std::result::Result, SdkRefusal> { + let frame = ListingFrame { + store: StoreName::parse(store)?, + store_record: Some(record.to_record().clone()), + }; + let answer = worker.call("project.list", frame.encode(), &mut |_| {})?; + let reply = ListingReply::decode(&answer)?; + Ok(reply + .projects + .into_iter() + .map(|project| LiveProject { + name: project.name, + stack: project.stack.to_bytes().to_vec(), + }) + .collect()) +} + +/// Whether `project` is in `live`: by the stack id its record holds, or, +/// for a record without one, by its name (spec §4.2). +fn listed(project: &ProjectRecord, name: &str, live: &[LiveProject]) -> bool { + match project.stack() { + Some(stack) => live.iter().any(|item| item.stack == stack), + None => live.iter().any(|item| item.name == name), + } +} + /// One project as callers see it; a record that does not read shows no /// `created`. fn summary(home: &Path, store: &str, name: &str, record: &StoreRecord, view: View) -> SdkValue { @@ -58,9 +141,17 @@ fn summary(home: &Path, store: &str, name: &str, record: &StoreRecord, view: Vie project.to_sdk(view, record) } -/// `project.get(project)`: one project's record. +/// `project.get(project)`: one project's record. A project its Store no +/// longer lists (retired, or absent) is `NoSuchProject` even when its home +/// entry remains (spec §4.2). pub fn get(home: &Path, project: &ProjectRef) -> Outcome { let target = resolve::target(home, &project.to_string())?; + let live = live_projects(home, &target.store, &target.record)?; + let record = ProjectRecord::read(home, &target.store, &target.project)? + .ok_or_else(|| refused("NoSuchProject", format!("no project {project}")))?; + if !listed(&record, &target.project, &live) { + return Err(refused("NoSuchProject", format!("no project {project}"))); + } Ok(summary( home, &target.store, @@ -86,7 +177,26 @@ pub fn list(home: &Path, request: &ProjectList) -> Outcome { let Some(record) = StoreRecord::read(home, &store)? else { continue; }; + // The listing is the Store's own filtered one (spec §4.2), read + // where its calls run (T4.5c): a home entry whose project is hidden + // or absent is not listed. An all-Stores listing omits a Store it + // cannot list; a named one reports the refusal. + let live = match live_projects(home, &store, &record) { + Ok(live) => live, + Err(refusal) => { + if request.store.is_some() { + return Err(refusal); + } + continue; + } + }; for name in paths::names(&paths::store_dir(home, &store).join("project")).map_err(failed)? { + let Some(project) = ProjectRecord::read(home, &store, &name)? else { + continue; + }; + if !listed(&project, &name, &live) { + continue; + } items.push(summary(home, &store, &name, &record, View::List)); } } @@ -218,10 +328,7 @@ fn init_on_worker( timeout, } = call; if paths::project_record(&home, store, name).exists() { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(crate::project::add::home_name_taken(store.as_str(), name)); } let total = send::measure(Path::new(folder), name)?; let copy = send::Copy { @@ -286,10 +393,7 @@ fn init_postgresql( let home = home.to_path_buf(); let path = paths::project_record(&home, store, name); if path.exists() { - return Err(refused( - "Exists", - format!("Store {store} already has a project named {name}"), - )); + return Err(crate::project::add::home_name_taken(store.as_str(), name)); } let add = PgProjectAdd { add: ProjectAdd { @@ -313,49 +417,3 @@ fn init_postgresql( } Ok(out) } - -/// `project.remove(project)`: drops the project's Layers, Branches and -/// Commits from its Store in one write, then its record. Its Sandboxes must -/// be closed first; the other projects stay. -pub fn remove( - home: &Path, - events: &mut Events<'_>, - project: &ProjectRef, - related: Related, -) -> Outcome { - let text = project.to_string(); - let home = home.to_path_buf(); - let target = resolve::target(&home, &text)?; - target.record.unblocked()?; - (related.can_remove_project)(&home, &text)?; - let request = RemoveFrame { - store: project.store.clone(), - project: target.project.clone(), - store_record: Some(target.record.to_record().clone()), - }; - if let StoreRef::Postgres { .. } = target.store_ref { - return Err(refused( - "Unsupported", - "removing a project from a PostgreSQL Store is not built", - )); - } - let removed = match place::plan(&home, &target.store_ref)? { - Executor::Local => { - let _lease = lease::hold(&home, &target.store)?; - crate::project::remove::remove_project(&home_of(Some(&home))?, &request)? - } - Executor::Worker(mut worker) => { - let _lease = lease::hold(&home, &target.store)?; - worker.call("project.remove", request.encode(), &mut |e| events.event(e))? - } - }; - let entry = paths::project_dir(&home, &target.store, &target.project); - if entry.exists() { - std::fs::remove_dir_all(&entry).map_err(failed)?; - } - Ok(layerfs_home::home::with_field( - removed, - "project", - SdkValue::text(text), - )) -} diff --git a/control/crates/layerfs-store/src/project/frame.rs b/control/crates/layerfs-store/src/project/frame.rs index 15850df28a..bcdfa67405 100644 --- a/control/crates/layerfs-store/src/project/frame.rs +++ b/control/crates/layerfs-store/src/project/frame.rs @@ -1,8 +1,12 @@ //! The `project` worker frames (layerfs-project#109): `project.init`, -//! `project.remove`, `project.stage` and `project.export`, each encoded by the caller and +//! `project.list` (T4.5c), `project.stage`, +//! `project.export`, `project.delete` (T4.5b) and its admission ops, each +//! encoded by the caller and //! decoded once in the worker, in the order the worker always refused them. //! The worker sets the home to its own root; a frame names none. use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_bridge::sdk_values::{hex, unhex}; +use layerfs_history::LayerStackId; use layerfs_home::helpers::required; use layerfs_home::names::StoreName; use layerfs_home::outcome::refused; @@ -26,18 +30,6 @@ pub struct InitFrame { pub store_record: Option, } -/// `project.remove`: drop project `project` from Store `store` (here, or in -/// its worker). -#[derive(Clone, Debug)] -pub struct RemoveFrame { - /// The Store. - pub store: StoreName, - /// The project's name in it. - pub project: String, - /// The Store's record. - pub store_record: Option, -} - /// `project.export` in a worker: stream Branch `branch` of project /// `project` of Store `store` back to the caller. #[derive(Clone, Debug)] @@ -93,6 +85,29 @@ fn staged_id(frame: &SdkValue) -> Result { Ok(id.to_owned()) } +/// The LayerStack identity a `stack_id` field holds: its 17 bytes in hex. +fn stack_id(text: &str) -> Result { + let bytes = + unhex(text).ok_or_else(|| refused("InvalidInput", "`stack_id` must be hex digits"))?; + LayerStackId::from_slice(&bytes).map_err(|_| { + refused( + "InvalidInput", + "`stack_id` must be a LayerStack identity (17 bytes)", + ) + }) +} + +/// The operation identity an `op_id` field holds: its 16 bytes in hex. +fn op_id(text: &str) -> Result<[u8; 16]> { + let bytes = unhex(text).ok_or_else(|| refused("InvalidInput", "`op_id` must be hex digits"))?; + bytes.as_slice().try_into().map_err(|_| { + refused( + "InvalidInput", + "`op_id` must be an operation identity (16 bytes)", + ) + }) +} + impl InitFrame { /// The `project.init` frame: `{ store, name, staged, timeoutMs, /// store_record }`, each sent when set. @@ -119,30 +134,6 @@ impl InitFrame { } } -impl RemoveFrame { - /// The `project.remove` frame: `{ store, project, store_record }`. - pub fn encode(&self) -> SdkValue { - let mut fields = vec![ - ("store", SdkValue::text(self.store.as_str())), - ("project", SdkValue::text(&self.project)), - ]; - fields.extend(self.store_record.clone().map(|r| ("store_record", r))); - map(fields) - } - - /// A `project.remove` frame: no Store, no project, then a bad Store - /// name are refused. - pub fn decode(frame: &SdkValue) -> Result { - let store = required(frame.get_text("store"), "store")?; - let project = required(frame.get_text("project"), "project")?.to_owned(); - Ok(Self { - store: StoreName::parse(store)?, - project, - store_record: frame.get("store_record").cloned(), - }) - } -} - impl StageFrame { /// The `project.stage` frame: `{ store, name, staged, step, part? }`. pub fn encode(self) -> SdkValue { @@ -226,3 +217,282 @@ impl ExportFrame { }) } } + +/// `project.delete`: retire Stack `stack` of Store `store` (here, or in its +/// worker, spec §4). The caller writes `deleted_ms` to its durable intent +/// before the call and resends it on a retry; `project` and `store_record` +/// are the caller context for the worker own entry and its Store open. +/// `op_id` is the admission the caller already took, so the marker reuses it +/// instead of scanning past a second row. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DeleteFrame { + /// The Store. + pub store: StoreName, + /// The project, as sent; the worker names its own entry with it. + pub project: Option, + /// The LayerStack id the caller recorded (never a name). + pub stack: LayerStackId, + /// The `deleted_ms` the marker should hold; `None` lets the worker take + /// the current time. + pub deleted_ms: Option, + /// The admission operation identity the marker reuses, when the caller + /// took one. + pub op_id: Option<[u8; 16]>, + /// The Store record. + pub store_record: Option, +} + +/// `project.delete.admit`: register the caller's project-scope admission +/// before it writes its sidecar and sends the marker (T4.6). The frame is +/// `{store, stack_id, op_id, store_record?}`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DeleteAdmitFrame { + /// The Store. + pub store: StoreName, + /// The LayerStack the caller recorded. + pub stack: LayerStackId, + /// The admission operation identity. + pub op: [u8; 16], + /// The Store record. + pub store_record: Option, +} + +/// `project.delete.release`: delete the caller's admission row after the +/// marker, on every exit path (T4.6). The frame is +/// `{store, op_id, store_record?}`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DeleteReleaseFrame { + /// The Store. + pub store: StoreName, + /// The admission operation identity. + pub op: [u8; 16], + /// The Store record. + pub store_record: Option, +} + +/// `project.delete` worker reply: `{kind: "Removed", project, stack_id, +/// deleted_ms}`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct DeleteReply { + /// The project the worker own entry named (or the Store name). + pub project: String, + /// The LayerStack the marker names. + pub stack: LayerStackId, + /// The stored `deleted_ms` (a retry reuses it). + pub deleted_ms: i64, +} + +impl DeleteFrame { + /// The `project.delete` frame: `{ store, stack_id, deleted_ms?, project?, + /// op_id?, store_record? }`, each optional field sent when set. + pub fn encode(&self) -> SdkValue { + let mut fields = vec![ + ("store", SdkValue::text(self.store.as_str())), + ("stack_id", SdkValue::text(hex(&self.stack.to_bytes()))), + ]; + fields.extend(self.deleted_ms.map(|ms| ("deleted_ms", SdkValue::Int(ms)))); + fields.extend( + self.project + .as_deref() + .map(|p| ("project", SdkValue::text(p))), + ); + fields.extend(self.op_id.map(|op| ("op_id", SdkValue::text(hex(&op))))); + fields.extend(self.store_record.clone().map(|r| ("store_record", r))); + map(fields) + } + + /// A `project.delete` frame: no Store, a bad Store name, no Stack id, a + /// Stack id that is not a LayerStack identity, or an `op_id` that is not + /// an operation identity are refused. + pub fn decode(frame: &SdkValue) -> Result { + let store = StoreName::parse(required(frame.get_text("store"), "store")?)?; + let stack = stack_id(required(frame.get_text("stack_id"), "stack_id")?)?; + Ok(Self { + store, + project: frame.get_text("project").map(str::to_owned), + stack, + deleted_ms: frame.get_int("deleted_ms"), + op_id: frame.get_text("op_id").map(op_id).transpose()?, + store_record: frame.get("store_record").cloned(), + }) + } +} + +impl DeleteAdmitFrame { + /// The `project.delete.admit` frame: `{store, stack_id, op_id, + /// store_record?}`. + pub fn encode(&self) -> SdkValue { + let mut fields = vec![ + ("store", SdkValue::text(self.store.as_str())), + ("stack_id", SdkValue::text(hex(&self.stack.to_bytes()))), + ("op_id", SdkValue::text(hex(&self.op))), + ]; + fields.extend(self.store_record.clone().map(|r| ("store_record", r))); + map(fields) + } + + /// A `project.delete.admit` frame: its Store, Stack and operation + /// identity are required and checked. + pub fn decode(frame: &SdkValue) -> Result { + let store = StoreName::parse(required(frame.get_text("store"), "store")?)?; + let stack = stack_id(required(frame.get_text("stack_id"), "stack_id")?)?; + let op = op_id(required(frame.get_text("op_id"), "op_id")?)?; + Ok(Self { + store, + stack, + op, + store_record: frame.get("store_record").cloned(), + }) + } +} + +impl DeleteReleaseFrame { + /// The `project.delete.release` frame: `{store, op_id, store_record?}`. + pub fn encode(&self) -> SdkValue { + let mut fields = vec![ + ("store", SdkValue::text(self.store.as_str())), + ("op_id", SdkValue::text(hex(&self.op))), + ]; + fields.extend(self.store_record.clone().map(|r| ("store_record", r))); + map(fields) + } + + /// A `project.delete.release` frame: its Store and operation identity + /// are required and checked. + pub fn decode(frame: &SdkValue) -> Result { + let store = StoreName::parse(required(frame.get_text("store"), "store")?)?; + let op = op_id(required(frame.get_text("op_id"), "op_id")?)?; + Ok(Self { + store, + op, + store_record: frame.get("store_record").cloned(), + }) + } +} + +impl DeleteReply { + /// The reply a worker sends. + pub fn encode(&self) -> SdkValue { + map(vec![ + ("kind", SdkValue::text("Removed")), + ("project", SdkValue::text(&self.project)), + ("stack_id", SdkValue::text(hex(&self.stack.to_bytes()))), + ("deleted_ms", SdkValue::Int(self.deleted_ms)), + ]) + } + + /// The reply fields; `kind` must be `Removed`. + pub fn decode(frame: &SdkValue) -> Result { + if frame.get_text("kind") != Some("Removed") { + return Err(refused( + "Failed", + "the worker project.delete reply is not `Removed`", + )); + } + let project = frame + .get_text("project") + .ok_or_else(|| refused("InvalidInput", "reply has no `project`"))? + .to_owned(); + let stack = stack_id(required(frame.get_text("stack_id"), "stack_id")?)?; + let deleted_ms = frame + .get_int("deleted_ms") + .ok_or_else(|| refused("InvalidInput", "reply has no `deleted_ms`"))?; + Ok(Self { + project, + stack, + deleted_ms, + }) + } +} + +/// `project.list` in a worker (T4.5c): Store `store`'s filtered project +/// listing, the same `layerfs_project::store::projects` a local or +/// PostgreSQL Store is read with, so a project retired in the Store is +/// hidden here too. A worker's root does not hold the caller's home +/// entries; the caller intersects this listing with them (`project.list`, +/// `project.get`). +#[derive(Clone, Debug)] +pub struct ListingFrame { + /// The Store to list. + pub store: StoreName, + /// The Store's record: it opens the Store under the worker's root. + pub store_record: Option, +} + +/// One project a worker's Store listing names. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct ListedProject { + /// Its name in the Store. + pub name: String, + /// Its LayerStack. + pub stack: LayerStackId, +} + +/// `project.list` worker reply: `{ kind: "Listed", projects: [{ name, +/// stack_id }] }`, in the Store's name order. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct ListingReply { + /// The Store's live projects. + pub projects: Vec, +} + +impl ListingFrame { + /// The `project.list` frame: `{ store, store_record? }`. + pub fn encode(&self) -> SdkValue { + let mut fields = vec![("store", SdkValue::text(self.store.as_str()))]; + fields.extend(self.store_record.clone().map(|r| ("store_record", r))); + map(fields) + } + + /// A `project.list` frame: no Store, then a bad Store name are refused. + pub fn decode(frame: &SdkValue) -> Result { + Ok(Self { + store: StoreName::parse(required(frame.get_text("store"), "store")?)?, + store_record: frame.get("store_record").cloned(), + }) + } +} + +impl ListingReply { + /// The reply a worker sends. + pub fn encode(&self) -> SdkValue { + let projects = self + .projects + .iter() + .map(|project| { + map(vec![ + ("name", SdkValue::text(&project.name)), + ("stack_id", SdkValue::text(hex(&project.stack.to_bytes()))), + ]) + }) + .collect(); + map(vec![ + ("kind", SdkValue::text("Listed")), + ("projects", SdkValue::List(projects)), + ]) + } + + /// The reply fields; `kind` must be `Listed`, and every project names + /// its Store name and its LayerStack identity. + pub fn decode(frame: &SdkValue) -> Result { + if frame.get_text("kind") != Some("Listed") { + return Err(refused( + "Failed", + "the worker project.list reply is not `Listed`", + )); + } + let Some(SdkValue::List(items)) = frame.get("projects") else { + return Err(refused("InvalidInput", "reply has no `projects` list")); + }; + let mut projects = Vec::with_capacity(items.len()); + for item in items { + let name = item + .get_text("name") + .ok_or_else(|| refused("InvalidInput", "reply project has no `name`"))? + .to_owned(); + let stack = stack_id(required(item.get_text("stack_id"), "stack_id")?)?; + projects.push(ListedProject { name, stack }); + } + Ok(Self { projects }) + } +} diff --git a/control/crates/layerfs-store/src/project/listing.rs b/control/crates/layerfs-store/src/project/listing.rs new file mode 100644 index 0000000000..99f3f2ac52 --- /dev/null +++ b/control/crates/layerfs-store/src/project/listing.rs @@ -0,0 +1,45 @@ +//! `project.list` in a worker (T4.5c): the Store's filtered project +//! listing, read under the worker's own root with the same +//! `layerfs_project::store::projects` a local or PostgreSQL Store uses, so +//! a project retired in the Store is hidden on that route too. +use crate::open_args::OpenArgs; +use crate::project::frame::{ListedProject, ListingFrame, ListingReply}; +use crate::service; +use layerfs_home::home::paths; +use layerfs_home::outcome::{failed, refused, Outcome}; +use std::path::Path; + +/// The `project.list` worker op: Store `store`'s live projects, in name +/// order, under `root` (the worker's own root). The caller intersects the +/// answer with its own home entries (`project.list`, `project.get`). +pub fn list_projects(root: &Path, frame: &ListingFrame) -> Outcome { + let store = frame.store.as_str(); + let store_record = frame + .store_record + .clone() + .ok_or_else(|| refused("InvalidInput", "project.list needs the Store's record"))?; + let open = OpenArgs { + home: Some(root.to_path_buf()), + store: Some(store.to_owned()), + store_path: Some(paths::store_file(root, store).display().to_string()), + store_record: Some(store_record), + postgresql: None, + ..OpenArgs::default() + }; + let stacks = service::with_service(&open, |service| { + service + .store + .published(layerfs_project::store::projects) + .map_err(failed) + })?; + Ok(ListingReply { + projects: stacks + .into_iter() + .map(|stack| ListedProject { + name: stack.name.as_str().to_owned(), + stack: stack.id, + }) + .collect(), + } + .encode()) +} diff --git a/control/crates/layerfs-store/src/project/mod.rs b/control/crates/layerfs-store/src/project/mod.rs index 127b636a79..1b35d9d8ca 100644 --- a/control/crates/layerfs-store/src/project/mod.rs +++ b/control/crates/layerfs-store/src/project/mod.rs @@ -1,17 +1,18 @@ //! Public Project organization over host Init, and a project's home entry //! and discovery records (`discovery`). pub mod add; +pub mod delete; pub mod discovery; pub mod export; #[doc(hidden)] pub mod family; pub mod frame; pub mod init; +pub mod listing; pub mod parts; pub mod postgres_init; #[doc(hidden)] pub mod record; -pub mod remove; pub mod send; pub mod staged; pub mod tree; diff --git a/control/crates/layerfs-store/src/project/record.rs b/control/crates/layerfs-store/src/project/record.rs index 02578ba974..7bddbd071b 100644 --- a/control/crates/layerfs-store/src/project/record.rs +++ b/control/crates/layerfs-store/src/project/record.rs @@ -4,6 +4,8 @@ //! `sandbox/files.rs` reads and writes with the rest kept. use crate::record::StoreRecord; use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_bridge::provision::StoreManifest; +use layerfs_bridge::sdk_values::unhex; use layerfs_home::home::{now_ms, paths, read_record, with_field, write_entity}; use layerfs_home::outcome::View; use std::path::Path; @@ -76,6 +78,19 @@ impl ProjectRecord { self.fields.get("created") } + /// The project's LayerStack identity as its record holds it (S §4.2): + /// the `manifest`'s stack for a local SQLite record, the record's + /// `stack` for a PostgreSQL or worker record. A record with neither has + /// none; its Store's filtered listing is then matched by name. + pub fn stack(&self) -> Option> { + if let Some(SdkValue::Bytes(bytes)) = self.fields.get("manifest") { + if let Ok(manifest) = StoreManifest::decode(bytes) { + return Some(manifest.stack.to_vec()); + } + } + self.fields.get_text("stack").and_then(unhex) + } + /// The record as written. pub fn to_record(&self) -> &SdkValue { &self.fields diff --git a/control/crates/layerfs-store/src/related.rs b/control/crates/layerfs-store/src/related.rs index 56b471049a..06e2bc9fcb 100644 --- a/control/crates/layerfs-store/src/related.rs +++ b/control/crates/layerfs-store/src/related.rs @@ -8,13 +8,11 @@ use std::path::Path; /// An `InUse` check on the Store or project `name` in home `home`. type Check = fn(home: &Path, name: &str) -> Result<(), SdkRefusal>; -/// The `InUse` checks over a Store's and a project's users. +/// The `InUse` checks over a Store's users. #[derive(Clone, Copy)] pub struct Related { /// `store.push`, `store.pull`, `store.remove`, `store.disconnect` and /// `backup.restore`: refused while another live process holds the Store /// or a Sandbox of one of its projects is recorded. pub store_idle: Check, - /// `project.remove`: refused while a Sandbox of the project is recorded. - pub can_remove_project: Check, } diff --git a/control/crates/layerfs-store/src/report.rs b/control/crates/layerfs-store/src/report.rs new file mode 100644 index 0000000000..cf6ad16ed8 --- /dev/null +++ b/control/crates/layerfs-store/src/report.rs @@ -0,0 +1,116 @@ +//! The wire rendering of the §11 compaction report and the `store.status` +//! compaction projection (T10). +//! +//! One serializer renders the shared [`CompactReport`], so the SQLite path and +//! T9's PostgreSQL path cannot disagree on a key: every key is snake_case (§10; +//! §11 names are logical), a zero field is named by its wire key, and +//! `residue.reason` appears only when something remains. +use layerfs_bridge::control::SdkValue; +use layerfs_persistence::{CompactReport, CompactStatus}; + +/// The §11 report as `store.compact` returns it: +/// `{kind: "Compacted", path, generation {before, after}, ...}`. +#[must_use] +pub fn compact_report(report: &CompactReport) -> SdkValue { + let int = |value: u64| SdkValue::Int(i64::try_from(value).unwrap_or(i64::MAX)); + let references = report + .kept_waste + .delta_base_references + .iter() + .map(|id| SdkValue::text(layerfs_bridge::sdk_values::hex(id))) + .collect(); + let mut residue = vec![ + ("bytes".to_owned(), int(report.residue.bytes)), + ( + "artifacts".to_owned(), + SdkValue::List( + report + .residue + .artifacts + .iter() + .map(SdkValue::text) + .collect(), + ), + ), + ]; + if let Some(reason) = &report.residue.reason { + residue.push(("reason".to_owned(), SdkValue::text(reason))); + } + let zero_reasons = report + .zero_reasons + .iter() + .map(|zero| { + SdkValue::map([ + ("field", SdkValue::text(zero.wire_field())), + ("reason", SdkValue::text(zero.reason)), + ]) + }) + .collect(); + SdkValue::Map( + [ + ("kind", SdkValue::text("Compacted")), + ("path", SdkValue::text(report.path.as_str())), + ( + "generation", + SdkValue::map([ + ("before", int(report.generation.before)), + ("after", int(report.generation.after)), + ]), + ), + ("dead_bytes_bound", int(report.dead_bytes_bound)), + ("dead_bytes_refined", int(report.dead_bytes_refined)), + ("logical_discarded", int(report.logical_discarded)), + ("backend_reusable", int(report.backend_reusable)), + ("physical_shrink", int(report.physical_shrink)), + ( + "kept_waste", + SdkValue::map([ + ( + "dead_in_retained_packs_bytes", + int(report.kept_waste.dead_in_retained_packs_bytes), + ), + ( + "delta_bases", + SdkValue::map([ + ("bytes", int(report.kept_waste.delta_bases_bytes)), + ("references", SdkValue::List(references)), + ]), + ), + ("inode_blocks_bytes", int(report.kept_waste.inode_blocks_bytes)), + ]), + ), + ("peak_temp_bytes", int(report.peak_temp_bytes)), + ("residue", SdkValue::Map(residue.into_iter().collect())), + ("estimate", SdkValue::Bool(report.estimate)), + ("zero_reasons", SdkValue::List(zero_reasons)), + ] + .into_iter() + .map(|(name, value)| (name.to_owned(), value)) + .collect(), + ) +} + +/// The `store.status` projection of a compaction: `{id, name, phase, started, +/// uncertain, state, phases}`. The caller splits the op fields into its `op` +/// and leaves `state`/`phases` beside them (§11). +#[must_use] +pub fn compact_status(status: &CompactStatus) -> SdkValue { + SdkValue::map([ + ("id", SdkValue::text(&status.id)), + ("name", SdkValue::text(status.name)), + ("phase", SdkValue::text(&status.phase)), + ("started", SdkValue::Int(status.started)), + ("uncertain", SdkValue::Bool(status.uncertain)), + ("state", SdkValue::text(status.state)), + ( + "phases", + SdkValue::List( + status + .phases + .iter() + .map(|phase| SdkValue::text(*phase)) + .collect(), + ), + ), + ]) +} diff --git a/control/crates/layerfs-store/src/sqlite/transfer/step.rs b/control/crates/layerfs-store/src/sqlite/transfer/step.rs index 50dca83651..98dc7021d0 100644 --- a/control/crates/layerfs-store/src/sqlite/transfer/step.rs +++ b/control/crates/layerfs-store/src/sqlite/transfer/step.rs @@ -12,6 +12,11 @@ type Result = std::result::Result; pub enum StoreStep { /// Whether the file is there, its size and the free bytes. Stat, + /// The compaction operation recorded beside the Store, for `store.status`. + /// + /// It reads only `.compact-op`; never the Store database, an + /// artifact or a directory listing. + CompactOp, /// The idle Store's bytes, sha256 and heads. Snapshot, /// A consistent snapshot of the live Store, staged beside it. @@ -68,6 +73,7 @@ impl StoreStep { pub fn name(&self) -> &'static str { match self { Self::Stat => "stat", + Self::CompactOp => "compact-op", Self::Snapshot => "snapshot", Self::Stage => "stage", Self::Unstage => "unstage", @@ -161,6 +167,7 @@ impl StepFrame { layerfs_home::names::StoreName::parse(store)?; let step = match op { "stat" => StoreStep::Stat, + "compact-op" => StoreStep::CompactOp, "snapshot" => StoreStep::Snapshot, "stage" => StoreStep::Stage, "unstage" => StoreStep::Unstage, diff --git a/control/crates/layerfs-store/src/sqlite/transfer/steps.rs b/control/crates/layerfs-store/src/sqlite/transfer/steps.rs index ef250836ef..fdca5f159a 100644 --- a/control/crates/layerfs-store/src/sqlite/transfer/steps.rs +++ b/control/crates/layerfs-store/src/sqlite/transfer/steps.rs @@ -25,6 +25,16 @@ fn with_suffix(path: &Path, suffix: &str) -> PathBuf { PathBuf::from(name) } +/// Whether the process a compaction record names still runs on this machine. +/// The kernel start time and boot id, when recorded, keep a reused id from +/// passing as the owner. +fn owner_alive(op: &layerfs_persistence::CompactOpStatus) -> bool { + let Some(pid) = op.owner_pid else { + return false; + }; + layerfs_home::process::alive_as(pid, op.owner_pid_start, op.owner_pid_boot) +} + fn length(path: &Path) -> Result { match std::fs::metadata(path) { Ok(meta) => Ok(meta.len()), @@ -124,6 +134,12 @@ pub fn run_observed(root: &Path, frame: &StepFrame, progress: &mut dyn FnMut(u64 ), ("incoming_bytes", SdkValue::Int(length(&incoming)? as i64)), ])), + // the compaction record beside the Store only: `store.status` shows + // its op and phase without opening the Store database or an artifact + StoreStep::CompactOp => match layerfs_persistence::compact_op_status(&file) { + None => Ok(SdkValue::Null), + Some(op) => Ok(crate::report::compact_status(&op.status(owner_alive(&op)))), + }, // snapshot: the idle Store's bytes, sha256 and history heads. A Store // nobody holds has no write-ahead log left unless a process crashed; // if a crashed opener left one, checkpoint and close it first. diff --git a/control/crates/layerfs-store/src/status.rs b/control/crates/layerfs-store/src/status.rs index e62157e506..664f7d4a87 100644 --- a/control/crates/layerfs-store/src/status.rs +++ b/control/crates/layerfs-store/src/status.rs @@ -6,33 +6,79 @@ use crate::sqlite::family::{fields_map, record_of, step_on}; use crate::sqlite::transfer::step::StoreStep; use layerfs_bridge::control::SdkValue; use layerfs_home::outcome::Outcome; +use layerfs_persistence::compact_metrics::{self, CompactStatusState}; use std::path::Path; -/// `store.status`: who holds it, the operation its record holds (`op`, as -/// H6 shows it), its size. It starts no machine: a Store whose machine is -/// not running is `down`, with the reason (O34). It changes nothing (#536 -/// §12 item 3): no lock, and a stale lease is ignored, not removed. +/// `store.status`: who holds it, the operation on it (`op`, as H6 shows it), +/// its size. It starts no machine: a Store whose machine is not running is +/// `down`, with the reason (O34). It changes nothing (#536 §12 item 3): no +/// lock, and a stale lease is ignored, not removed. +/// +/// While a compaction runs, or after a dead owner left one, `op` is that run's +/// projection and `state` is `busy`/`unresolved` (§11); `phases` names the +/// backend's ordered phases. A sqlite compaction record is read from +/// `.compact-op` alone, and a PostgreSQL one from the Store-side +/// `gc_op` with its `gc_intent` on one status query (T10.5): neither opens +/// the Store database, changes a schema, nor reads an artifact. pub fn status(home: &Path, name: &str) -> Outcome { let record = record_of(home, name)?; let (holders, _) = lease::read_holders(home, name)?; let mut down = None; let mut more = Vec::new(); let store_ref = record.store_ref()?; + let compaction: SdkValue; if let StoreRef::Postgres { .. } = store_ref { more.push(("server", crate::postgresql::connect::status(&record))); + // T10.5: a PostgreSQL compaction's op is the Store's `gc_op` row read + // with its `gc_intent`; this path opens no Store and reads no file. + compaction = crate::postgresql::connect::compact_status(&record); } else { more.push(("machine", SdkValue::text(store_ref.machine()?))); - // the file's size where it lives, starting nothing (P4); a machine - // that is down says why - let file = place::plan(home, store_ref) - .and_then(|mut executor| step_on(home, &mut executor, name, StoreStep::Stat)); + // the file's size where it lives, starting nothing (P4), and the + // compaction record beside it; a machine that is down says why + let mut placed = place::plan(home, store_ref); + let (file, op) = match placed.as_mut() { + Ok(executor) => ( + step_on(home, executor, name, StoreStep::Stat), + step_on(home, executor, name, StoreStep::CompactOp).unwrap_or_default(), + ), + Err(why) => (Err(why.clone()), SdkValue::Null), + }; + compaction = op; let file = file.unwrap_or_else(|why| { down = Some(why.message.clone()); SdkValue::map([("unavailable", SdkValue::Text(why.message))]) }); more.push(("file", file)); } - let state = record.state(down.is_some(), &holders).as_str(); + // A compaction's record is the operation the Store is running, even when + // some other process holds its lease; otherwise the record's own `op` + // (a push, pull or remove) is what `store.status` shows. + let op = if compaction.get("id").is_some() { + let field = |field: &str| compaction.get(field).cloned().unwrap_or_default(); + SdkValue::map([ + ("id", field("id")), + ("name", field("name")), + ("phase", field("phase")), + ("started", field("started")), + ("uncertain", field("uncertain")), + ]) + } else { + record.op().map(|op| op.to_sdk()).unwrap_or_default() + }; + let phases = compaction.get("phases").cloned().unwrap_or_default(); + let state = compaction + .get_text("state") + .unwrap_or_else(|| record.state(down.is_some(), &holders).as_str()); + // The status path observes an unsettled run by its bounded state label, + // never by a Store name or phase path. + if compaction.get("id").is_some() { + match state { + "busy" => compact_metrics::record_status(CompactStatusState::Busy), + "unresolved" => compact_metrics::record_status(CompactStatusState::Unresolved), + _ => {} + } + } let mut fields = vec![ ("name", SdkValue::text(name)), ("kind", SdkValue::text(store_ref.kind().as_str())), @@ -46,7 +92,8 @@ pub fn status(home: &Path, name: &str) -> Outcome { .collect(), ), ), - ("op", record.op().map(|op| op.to_sdk()).unwrap_or_default()), + ("op", op), + ("phases", phases), ("down_reason", down.map(SdkValue::Text).unwrap_or_default()), ]; fields.extend(more); diff --git a/control/crates/layerfs-store/tests/compact_report_status.rs b/control/crates/layerfs-store/tests/compact_report_status.rs new file mode 100644 index 0000000000..56a7a28068 --- /dev/null +++ b/control/crates/layerfs-store/tests/compact_report_status.rs @@ -0,0 +1,238 @@ +//! T10: the §11 report wire shape and the `store.status` compaction op +//! projection. The report renders snake_case from the shared `CompactReport`; +//! status reads only the `.compact-op` sidecar and never opens the +//! Store database. +use layerfs_bridge::control::SdkValue; +use layerfs_home::home::{paths, private_dir, write_entity}; +use layerfs_home::names::StoreName; +use layerfs_persistence::{ + CompactKeptWaste, CompactPath, CompactReceipt, CompactReport, CompactResidue, CompactZeroReason, +}; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "layerfs-t10-report-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +fn text(value: &SdkValue) -> &str { + match value { + SdkValue::Text(text) => text, + other => panic!("not text: {other:?}"), + } +} + +fn texts(value: &SdkValue) -> Vec { + let SdkValue::List(items) = value else { + return Vec::new(); + }; + items + .iter() + .filter_map(|item| match item { + SdkValue::Text(text) => Some(text.clone()), + _ => None, + }) + .collect() +} + +/// A home holding one empty sqlite Store `s` on native. +fn store_home() -> PathBuf { + let home = tempdir("home"); + let record = SdkValue::map([ + ("name", SdkValue::text("s")), + ("kind", SdkValue::text("sqlite")), + ("machine", SdkValue::text("native")), + ]); + write_entity(&paths::store_record(&home, "s"), &record).unwrap(); + private_dir(&paths::store_dir(&home, "s")).unwrap(); + std::fs::write(paths::store_file(&home, "s"), b"").unwrap(); + home +} + +/// A complete `.compact-op` record, as the persistence layer writes it. +fn sidecar(home: &Path, phase: &str, owner: u32) -> PathBuf { + let mut path = paths::store_file(home, "s").into_os_string(); + path.push(".compact-op"); + let path = PathBuf::from(path); + let zeros = "00".repeat(32); + std::fs::write( + &path, + format!( + "version=1\nop_id=00112233445566778899aabbccddeeff\ngeneration=3\n\ +phase={phase}\nstarted_ms=1234\nowner_pid={owner}\nowner_pid_start=\nowner_pid_boot=\n\ +catalog_id=0102030405060708090a0b0c0d0e0f10\nnext_history_serial=5\nnext_pack_id=6\n\ +next_ordinal=7\nmark_serial=4\nmark_pack_id=6\nmark_digest={zeros}\nmark_totals=1,2,3,4\n\ +mark_stamp=9\nhistory_rows=10\nlive_heads_digest={zeros}\n" + ), + ) + .unwrap(); + path +} + +fn receipt() -> CompactReceipt { + CompactReceipt { + path: CompactPath::Rebuild, + generation_before: 3, + generation_after: 4, + dead_bytes_bound: 100, + dead_bytes_refined: 80, + logical_discarded: 40, + backend_reusable: 4096, + physical_shrink: 8192, + kept_waste: CompactKeptWaste { + dead_in_retained_packs_bytes: 5, + delta_bases_bytes: 6, + delta_base_references: vec![[7; 32]], + inode_blocks_bytes: 8, + }, + peak_temp_bytes: 900, + residue: CompactResidue { + bytes: 0, + artifacts: Vec::new(), + reason: None, + }, + estimate: true, + zero_reasons: vec![ + CompactZeroReason { + field: "deadBytesBound", + reason: "no-waste", + }, + CompactZeroReason { + field: "logicalDiscarded", + reason: "no-history", + }, + ], + } +} + +#[test] +fn the_report_wire_is_the_snake_case_contract_shape() { + let wire = layerfs_store::report::compact_report(&CompactReport::from(&receipt())); + assert_eq!(text(wire.get("kind").unwrap()), "Compacted"); + assert_eq!(text(wire.get("path").unwrap()), "rebuild"); + let generation = wire.get("generation").unwrap(); + assert_eq!(generation.get_int("before"), Some(3)); + assert_eq!(generation.get_int("after"), Some(4)); + assert_eq!(wire.get_int("dead_bytes_bound"), Some(100)); + assert_eq!(wire.get_int("dead_bytes_refined"), Some(80)); + assert_eq!(wire.get_int("logical_discarded"), Some(40)); + assert_eq!(wire.get_int("backend_reusable"), Some(4096)); + assert_eq!(wire.get_int("physical_shrink"), Some(8192)); + assert_eq!(wire.get_int("peak_temp_bytes"), Some(900)); + assert_eq!(wire.get("estimate"), Some(&SdkValue::Bool(true))); + let waste = wire.get("kept_waste").unwrap(); + assert_eq!(waste.get_int("dead_in_retained_packs_bytes"), Some(5)); + assert_eq!(waste.get_int("inode_blocks_bytes"), Some(8)); + let bases = waste.get("delta_bases").unwrap(); + assert_eq!(bases.get_int("bytes"), Some(6)); + assert_eq!( + texts(bases.get("references").unwrap()), + vec!["0707070707070707070707070707070707070707070707070707070707070707"] + ); + let residue = wire.get("residue").unwrap(); + assert_eq!(residue.get_int("bytes"), Some(0)); + assert!(texts(residue.get("artifacts").unwrap()).is_empty()); + assert!(residue.get("reason").is_none()); + // One reason per zero field, named by its snake_case wire key (§10). + let SdkValue::List(zero) = wire.get("zero_reasons").unwrap() else { + panic!("zero_reasons is a list"); + }; + let fields: Vec<&str> = zero + .iter() + .map(|zero| text(zero.get("field").unwrap())) + .collect(); + assert_eq!(fields, ["dead_bytes_bound", "logical_discarded"]); + assert_eq!( + text(zero[0].get("reason").unwrap()), + "no-waste", + "the closed vocabulary passes through" + ); + assert!(wire.get("zeroReason").is_none(), "no camelCase key"); +} + +#[test] +fn status_emits_bounded_busy_and_unresolved_metrics() { + let home = store_home(); + let name = StoreName::parse("s").unwrap(); + let capture = layerfs_persistence::compact_metrics::CompactMetricsCapture::start(); + // Idle: no compaction record, so no `compact.status` sample. + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + // A live owner is `busy`; a gone one is `unresolved`. + sidecar(&home, "build", std::process::id()); + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + sidecar(&home, "build", 99_999_999); + let _ = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + let metrics = capture.finish(); + let value = |state: &str| { + metrics + .samples() + .iter() + .find(|sample| sample.name == "compact.status" && sample.label("state") == Some(state)) + .map_or(0, |sample| sample.value) + }; + assert_eq!(value("busy"), 1); + assert_eq!(value("unresolved"), 1); + assert_eq!(value("idle"), 0, "an idle status is not a compaction op"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn status_projects_the_sidecar_phase_and_state() { + let home = store_home(); + let name = StoreName::parse("s").unwrap(); + + // No op: the existing idle shape, no phases. + let idle = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + assert_eq!(idle.get("op"), Some(&SdkValue::Null)); + assert_eq!(idle.get("phases"), Some(&SdkValue::Null)); + assert_eq!(idle.get_text("state"), Some("idle")); + + // A live owner is busy and certain; `build` is the sidecar's phase. + let op_path = sidecar(&home, "build", std::process::id()); + let busy = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + assert_eq!(busy.get_text("state"), Some("busy")); + let op = busy.get("op").unwrap(); + assert_eq!( + text(op.get("id").unwrap()), + "op-00112233445566778899aabbccddeeff" + ); + assert_eq!(text(op.get("name").unwrap()), "store.compact"); + assert_eq!(text(op.get("phase").unwrap()), "build"); + assert_eq!(op.get_int("started"), Some(1234)); + // The record remains unsettled while it runs; `state` is what tells a + // live owner from a leftover. + assert_eq!(op.get("uncertain"), Some(&SdkValue::Bool(true))); + assert_eq!( + texts(busy.get("phases").unwrap()), + ["mark", "build", "verify", "install"] + ); + + // A gone owner leaves an uncertain op: unresolved, same phase, same id. + sidecar(&home, "build", 99_999_999); + let leftover = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + assert_eq!(leftover.get_text("state"), Some("unresolved")); + let op = leftover.get("op").unwrap(); + assert_eq!(text(op.get("phase").unwrap()), "build"); + assert_eq!(op.get("uncertain"), Some(&SdkValue::Bool(true))); + assert_eq!( + text(op.get("id").unwrap()), + "op-00112233445566778899aabbccddeeff" + ); + + // A settled run removes the record: the idle shape is back. + std::fs::remove_file(op_path).unwrap(); + let idle = layerfs_store::sqlite::family::status(&home, &name).unwrap(); + assert_eq!(idle.get("op"), Some(&SdkValue::Null)); + assert_eq!(idle.get("phases"), Some(&SdkValue::Null)); + assert_eq!(idle.get_text("state"), Some("idle")); + std::fs::remove_dir_all(home).unwrap(); +} diff --git a/control/crates/layerfs-store/tests/postgresql_status.rs b/control/crates/layerfs-store/tests/postgresql_status.rs new file mode 100644 index 0000000000..3d0d2e933b --- /dev/null +++ b/control/crates/layerfs-store/tests/postgresql_status.rs @@ -0,0 +1,405 @@ +//! T10.5: the PostgreSQL branch of `store.status`, through the control call. +//! +//! `store.status` of a PostgreSQL Store reads the Store-side `gc_op` row with +//! its compaction `gc_intent` in one status query, projects the operation +//! `{id, name, phase, started, uncertain}`, and separates a live owner +//! (`busy`) from a leftover (`unresolved`); `phases` is PostgreSQL's §8 order +//! `mark`, `build`, `swap`, `cleanup`. A Store with no row — never compacted, +//! or a run that settled and removed its row — is idle, with `op: null` and +//! `phases: null`. +//! +//! This is the control-level end-to-end case T10.5 was missing: the +//! persistence suite proves the reader, and this test drives the call the SDK +//! and CLI actually reach (`layerfs_store::sqlite::family::status`, the +//! kind-neutral `store.status` route) against a real PostgreSQL Store. The +//! rows a compaction leaves are written directly, so the test proves the +//! projection, not a failpoint: a live owner is a real non-idle backend +//! recorded in `pg_stat_activity`. +//! +//! Needs a writable PostgreSQL server: set `LAYERFS_TEST_POSTGRES_URL` to a +//! libpq connection string or URL (docs/architecture/engine/store/testing.md). +//! The test creates and drops its own database, because `store.status` reads +//! the one schema a 2.0 PostgreSQL Store uses (`layerfs`); a shared schema +//! would collide with another run. Without the variable it reports NOT_RUN. +#![cfg(feature = "postgresql")] + +use layerfs_bridge::control::SdkValue; +use layerfs_history::HistoryCatalogConfig; +use layerfs_home::home; +use layerfs_home::names::StoreName; +use layerfs_persistence::{PostgresHandles, PostgresSelection}; +use layerfs_storage::StoragePolicy; +use layerfs_store::record::StoreRecord; +use std::path::{Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +/// The §8 phases `store.status` names for a PostgreSQL compaction, in order. +const PHASES: [&str; 4] = ["mark", "build", "swap", "cleanup"]; + +const BINDING: &[u8] = b"t105-control-postgresql-status"; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn url() -> Option { + let url = std::env::var("LAYERFS_TEST_POSTGRES_URL").ok(); + if url.is_none() { + eprintln!("NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset"); + } + url +} + +fn tempdir(tag: &str) -> PathBuf { + let dir = std::env::temp_dir().join(format!( + "layerfs-t105-control-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).unwrap(); + dir +} + +/// The URL of `database` on the same server as `source`: a URL's path is +/// replaced; a libpq key/value string gains a final `dbname`, which wins. +fn database_url(source: &str, database: &str) -> String { + if source.starts_with("postgres://") || source.starts_with("postgresql://") { + let (base, query) = match source.split_once('?') { + Some((base, query)) => (base, format!("?{query}")), + None => (source, String::new()), + }; + let scheme = base.find("://").expect("a PostgreSQL URL") + 3; + match base[scheme..].find('/').map(|at| scheme + at) { + Some(at) => format!("{}/{database}{query}", &base[..at]), + None => format!("{base}/{database}{query}"), + } + } else { + format!("{source} dbname={database}") + } +} + +/// One disposable database: `store.status` reads the fixed `layerfs` schema, +/// so a test run needs a database nothing else uses. +struct Database { + source: String, + name: String, +} + +impl Database { + fn create(source: &str) -> Self { + let name = format!( + "lfs_t105_ctl_{}_{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + ); + let mut admin = postgres::Client::connect(source, postgres::NoTls).unwrap(); + admin + .batch_execute(&format!("DROP DATABASE IF EXISTS {name} WITH (FORCE)")) + .unwrap(); + admin + .batch_execute(&format!("CREATE DATABASE {name}")) + .unwrap(); + Self { + source: source.to_owned(), + name, + } + } + + fn url(&self) -> String { + database_url(&self.source, &self.name) + } +} + +impl Drop for Database { + fn drop(&mut self) { + if let Ok(mut admin) = postgres::Client::connect(&self.source, postgres::NoTls) { + let _ = admin.batch_execute(&format!( + "DROP DATABASE IF EXISTS {} WITH (FORCE)", + self.name + )); + } + } +} + +fn hex(bytes: &[u8]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(bytes.len() * 2); + for byte in bytes { + let _ = write!(out, "{byte:02x}"); + } + out +} + +fn op_id(byte: u8) -> String { + format!("op-{}", hex(&[byte; 16])) +} + +fn text(value: &SdkValue) -> &str { + match value { + SdkValue::Text(text) => text, + other => panic!("not text: {other:?}"), + } +} + +fn texts(value: &SdkValue) -> Vec { + match value { + SdkValue::List(items) => items + .iter() + .map(|item| { + if let SdkValue::Text(text) = item { + text.clone() + } else { + panic!("not text: {item:?}"); + } + }) + .collect(), + other => panic!("not a list: {other:?}"), + } +} + +/// What a compaction leaves in `gc_op`/`gc_intent`; `pid` and +/// `backend_start` name the owner the §9 rule tests for liveness. +struct OpRow<'a> { + op_id: [u8; 16], + phase: &'a str, + generation: i64, + started_ms: i64, + pid: i64, + backend_start: &'a str, +} + +fn insert(admin: &mut postgres::Client, row: &OpRow<'_>) { + let artifact = format!("lfs_gc_{}", hex(&row.op_id)); + admin + .execute( + "INSERT INTO layerfs.gc_op \ + (id,generation,phase,scratch_schema,mark_serial,mark_pack_id,mark_digest,\ + started_ms,artifact,pid,backend_start) \ + VALUES (1,$1,$2,$3,$4,$5,$6,$7,$3,$8,$9)", + &[ + &row.generation, + &row.phase, + &artifact, + &11i64, + &12i64, + &vec![9u8; 32], + &row.started_ms, + &row.pid, + &row.backend_start, + ], + ) + .unwrap(); + admin + .execute( + "INSERT INTO layerfs.gc_intent \ + (op_id,kind,scope_kind,owner_runtime,owner_boot,state,uncertain,phase,\ + generation,artifact,updated_ms) \ + VALUES ($1,'compaction','store',$2,$3,'live',FALSE,$4,$5,$6,$7)", + &[ + &row.op_id.to_vec(), + &"runtime-t105", + &"boot-t105", + &row.phase, + &row.generation, + &artifact, + &1_700_000_000_000i64, + ], + ) + .unwrap(); +} + +fn clear(admin: &mut postgres::Client) { + admin + .batch_execute( + "DELETE FROM layerfs.gc_op; \ + DELETE FROM layerfs.gc_intent WHERE kind='compaction'", + ) + .unwrap(); +} + +/// Waits until the recorded owner backend is gone from `pg_stat_activity`, +/// as the persistence fixture does. +fn wait_gone(admin: &mut postgres::Client, pid: i32, start: &str) { + for _ in 0..400 { + let live: bool = admin + .query_one( + "SELECT EXISTS (SELECT 1 FROM pg_stat_activity \ + WHERE pid=$1 AND backend_start::text=$2)", + &[&pid, &start], + ) + .unwrap() + .get(0); + if !live { + return; + } + std::thread::sleep(std::time::Duration::from_millis(25)); + } + panic!("the recorded owner backend never ended"); +} + +/// The real control entry point: `store.status` for the Store in `home`. +fn status(home: &Path) -> SdkValue { + let name = StoreName::parse("pgs").unwrap(); + layerfs_store::sqlite::family::status(home, &name).unwrap() +} + +#[test] +fn postgresql_store_status_projects_busy_leftover_and_idle() { + let Some(source) = url() else { + return; + }; + let database = Database::create(&source); + let url = database.url(); + let handles = PostgresHandles::create( + &PostgresSelection::new(&url, "layerfs"), + StoragePolicy::frozen_default(), + &HistoryCatalogConfig { + binding_key: BINDING.to_vec(), + cursor_key: [71; 32], + incarnation: 7, + }, + ) + .unwrap(); + + let home = tempdir("home"); + home::ensure(&home).unwrap(); + // `store.connect` records exactly this shape; `store.status` reads it. + StoreRecord::connected("pgs", &url, "layerfs", "off", None) + .write(&home) + .unwrap(); + let mut admin = postgres::Client::connect(&url, postgres::NoTls).unwrap(); + + // Idle: no compaction row, so no op and no phases. + let idle = status(&home); + assert_eq!(idle.get_text("name"), Some("pgs")); + assert_eq!(idle.get_text("kind"), Some("postgresql")); + assert_eq!(idle.get_text("state"), Some("idle")); + assert_eq!( + idle.get("op"), + Some(&SdkValue::Null), + "an idle Store has no op" + ); + assert_eq!( + idle.get("phases"), + Some(&SdkValue::Null), + "an idle Store has no phases" + ); + assert!( + matches!(idle.get("server"), Some(SdkValue::Map(_))), + "the server status is reported beside the op" + ); + + // A live owner: an open, non-idle backend is what the §9 dead-owner rule + // treats as still running the op. + let mut owner = postgres::Client::connect(&url, postgres::NoTls).unwrap(); + owner.batch_execute("BEGIN; SELECT 1").unwrap(); + let (pid, start): (i32, String) = { + let row = owner + .query_one( + "SELECT pg_backend_pid(),backend_start::text FROM pg_stat_activity \ + WHERE pid=pg_backend_pid()", + &[], + ) + .unwrap(); + (row.get(0), row.get(1)) + }; + let started_ms = 1_700_000_000_000i64; + let live = OpRow { + op_id: [0xab; 16], + phase: "build", + generation: 7, + started_ms, + pid: i64::from(pid), + backend_start: &start, + }; + insert(&mut admin, &live); + + let capture = layerfs_persistence::compact_metrics::CompactMetricsCapture::start(); + let busy = status(&home); + assert_eq!(busy.get_text("state"), Some("busy")); + let op = busy.get("op").unwrap(); + assert_eq!( + op, + &SdkValue::map([ + ("id", SdkValue::text(op_id(0xab))), + ("name", SdkValue::text("store.compact")), + ("phase", SdkValue::text("build")), + ("started", SdkValue::Int(started_ms)), + ("uncertain", SdkValue::Bool(true)), + ]), + "the op is exactly the five §11 fields" + ); + assert_eq!(texts(busy.get("phases").unwrap()), PHASES); + assert!( + op.get("state").is_none() && op.get("phases").is_none(), + "state and phases sit beside the op" + ); + + // A gone owner leaves the same row: uncertain, and now unresolved. + owner.close().unwrap(); + wait_gone(&mut admin, pid, &start); + let leftover = status(&home); + assert_eq!(leftover.get_text("state"), Some("unresolved")); + let op = leftover.get("op").unwrap(); + assert_eq!(text(op.get("id").unwrap()), op_id(0xab)); + assert_eq!(op.get_text("name"), Some("store.compact")); + assert_eq!(op.get_text("phase"), Some("build")); + assert_eq!(op.get_int("started"), Some(started_ms)); + assert_eq!(op.get("uncertain"), Some(&SdkValue::Bool(true))); + assert_eq!(texts(leftover.get("phases").unwrap()), PHASES); + + // The two observed states emit the bounded `compact.status{state}` sample + // once each; idle emits none. + let metrics = capture.finish(); + let sample = |state: &str| { + metrics + .samples() + .iter() + .find(|sample| sample.name == "compact.status" && sample.label("state") == Some(state)) + .map_or(0, |sample| sample.value) + }; + assert_eq!(sample("busy"), 1); + assert_eq!(sample("unresolved"), 1); + assert_eq!(sample("idle"), 0, "an idle status is not a compaction op"); + + // Every recorded phase is projected under its §8 name; a dead owner is + // an unresolved leftover for each. + for (index, phase) in PHASES.iter().enumerate() { + clear(&mut admin); + let byte = u8::try_from(index).unwrap(); + insert( + &mut admin, + &OpRow { + op_id: [byte; 16], + phase, + generation: 7, + started_ms, + pid: 99_999_999, + backend_start: "2000-01-01 00:00:00+00", + }, + ); + let projected = status(&home); + assert_eq!(projected.get_text("state"), Some("unresolved")); + assert_eq!( + projected.get("op").unwrap().get_text("phase"), + Some(*phase), + "{phase}: the row records the phase" + ); + let expected_id = op_id(byte); + assert_eq!( + projected.get("op").unwrap().get_text("id"), + Some(expected_id.as_str()) + ); + assert_eq!(texts(projected.get("phases").unwrap()), PHASES); + } + + // A settled run removes the row: idle again, with no op and no phases. + clear(&mut admin); + let idle = status(&home); + assert_eq!(idle.get_text("state"), Some("idle")); + assert_eq!(idle.get("op"), Some(&SdkValue::Null)); + assert_eq!(idle.get("phases"), Some(&SdkValue::Null)); + + drop(admin); + drop(handles); + std::fs::remove_dir_all(home).unwrap(); +} diff --git a/control/crates/layerfs-store/tests/project_delete.rs b/control/crates/layerfs-store/tests/project_delete.rs new file mode 100644 index 0000000000..727bcb981b --- /dev/null +++ b/control/crates/layerfs-store/tests/project_delete.rs @@ -0,0 +1,561 @@ +//! `project.delete`'s home path (T4.5b): the durable intent before the marker, +//! the retry classifications (`Marked`, `Retired`, `Absent`, a hidden Store +//! project), the `home_entry_removed` echo, and the worker's own entry. A fake +//! `Effects` stands in for the Store so the home state machine is tested +//! without opening one. +use layerfs_bridge::control::{SdkRefusal, SdkValue}; +use layerfs_bridge::sdk_values::hex; +use layerfs_history::LayerStackId; +use layerfs_home::home::{paths, write_record}; +use layerfs_home::outcome::{failed, refused}; +use layerfs_store::project::delete::{ + delete_with, remove_worker_entry, Admission, Effects, Intent, IntentState, +}; +use layerfs_store_service::history::deletion::Deletion; +use std::collections::VecDeque; +use std::path::{Path, PathBuf}; + +fn t(text: &str) -> SdkValue { + SdkValue::text(text) +} + +fn stack(body: u8) -> LayerStackId { + LayerStackId::from_authority([body; 16]) +} + +fn home(tag: &str) -> PathBuf { + let directory = std::env::temp_dir().join(format!( + "layerfs-project-delete-{tag}-{}", + std::process::id() + )); + let _ = std::fs::remove_dir_all(&directory); + layerfs_home::home::layout::create(&directory).unwrap(); + directory +} + +fn project_record(home: &Path, store: &str, project: &str, stack: LayerStackId) { + write_record( + &paths::project_record(home, store, project), + &SdkValue::map([ + ("v", SdkValue::Int(1)), + ("name", t(project)), + ("stack", t(&hex(&stack.to_bytes()))), + ("created", SdkValue::Int(1)), + ]), + ) + .unwrap(); +} + +fn intent(_home: &Path, store: &str, project: &str, stack: LayerStackId, id: i64) -> Intent { + Intent { + store: store.to_owned(), + project: project.to_owned(), + stack, + deleted_ms: id, + attempt_ms: 1, + state: IntentState::Pending, + op: None, + } +} + +/// A fake home/worker: the Store side and entry remover, with the project +/// scope admission a live mount or operation would refuse. `mark` reads the +/// intent as the marker would see it, so a test can see the state that +/// preceded it. +struct Fake { + home: PathBuf, + store: String, + project: String, + outcomes: VecDeque, + seen: Vec<(LayerStackId, i64)>, + states: Vec, + prepared: usize, + fail_removal: bool, + /// What `admit` refuses with, before registering anything. + refuse: Option, + /// What `mark` refuses with, before writing anything. + mark_refusal: Option, + /// Admissions taken, in order. + admitted: Vec, + /// Admissions released, in order. + released: Vec, +} + +impl Fake { + fn new(home: &Path, store: &str, project: &str, outcomes: Vec) -> Self { + Self { + home: home.to_path_buf(), + store: store.to_owned(), + project: project.to_owned(), + outcomes: outcomes.into(), + seen: Vec::new(), + states: Vec::new(), + prepared: 0, + fail_removal: false, + refuse: None, + mark_refusal: None, + admitted: Vec::new(), + released: Vec::new(), + } + } + + fn failing(mut self) -> Self { + self.fail_removal = true; + self + } + + /// A Store with a live mount (or another live operation) at the project + /// scope: `admit` refuses with the same code the Store's admission does. + fn refusing(mut self, code: &str, detail: SdkValue) -> Self { + self.refuse = Some(SdkRefusal { + code: code.to_owned(), + message: format!("test admission refusal: {code}"), + detail, + }); + self + } + + /// A fake whose admission refuses. + fn refused(&self) -> bool { + self.refuse.is_some() + } +} + +impl Effects for Fake { + fn prepare(&mut self) -> Result<(), SdkRefusal> { + self.prepared += 1; + Ok(()) + } + + fn admit( + &mut self, + stack: LayerStackId, + reuse: Option<[u8; 16]>, + ) -> Result { + if self.refused() { + return Err(self.refuse.clone().expect("refused above")); + } + let admission = Admission::new(stack, reuse.unwrap_or([0x5a; 16])); + self.admitted.push(admission); + Ok(admission) + } + + fn release(&mut self, admission: Admission) -> Result<(), SdkRefusal> { + self.released.push(admission); + Ok(()) + } + + fn mark(&mut self, admission: Admission, deleted_ms: i64) -> Result { + if let Some(refusal) = &self.mark_refusal { + return Err(refusal.clone()); + } + self.seen.push((admission.stack, deleted_ms)); + let state = Intent::read(&self.home, &self.store, &self.project) + .unwrap() + .expect("the intent is durable before the marker") + .state; + self.states.push(state); + Ok(self + .outcomes + .pop_front() + .expect("one fake outcome per marker attempt")) + } + + fn remove_entry(&mut self, entry: &Path) -> Result<(), SdkRefusal> { + if self.fail_removal { + return Err(refused("Failed", "test removal failure")); + } + match std::fs::remove_dir_all(entry) { + Ok(()) => Ok(()), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()), + Err(error) => Err(failed(error)), + } + } +} + +#[test] +fn a_fresh_delete_marks_then_removes_the_entry_and_unlinks_the_intent() { + let home = home("fresh"); + let (store, project, stack) = ("shop", "app", stack(1)); + project_record(&home, store, project, stack); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Marked { deleted_ms: 777 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert_eq!(outcome.get_text("project"), Some("shop/app")); + assert_eq!(outcome.get_int("deleted_ms"), Some(777)); + assert!(outcome.get_bool("home_entry_removed")); + assert_eq!(fake.seen.len(), 1); + assert_eq!(fake.seen[0].0, stack); + // the identity save precedes the intent, and the intent precedes the mark + assert_eq!(fake.prepared, 1); + assert_eq!(fake.states, [IntentState::Pending]); + // the project scope was admitted before the marker and released after + assert_eq!(fake.admitted.len(), 1); + assert_eq!(fake.released, fake.admitted); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_refused_admission_writes_no_sidecar_and_leaves_no_intent() { + let refused_home = home("refused"); + let (store, project, stack) = ("shop", "app", stack(20)); + project_record(&refused_home, store, project, stack); + let holders = SdkValue::map([( + "holders", + SdkValue::List(vec![SdkValue::map([ + ("kind", t("mount")), + ("entity", t("main")), + ])]), + )]); + let mut fake = + Fake::new(&refused_home, store, project, Vec::new()).refusing("MountsActive", holders); + let refusal = delete_with(&refused_home, store, project, Some(stack), &mut fake).unwrap_err(); + // the live mount's refusal is the call's, with its holders + assert_eq!(refusal.code, "MountsActive"); + assert!(refusal.detail.get("holders").is_some()); + // no identity save, no sidecar, no marker + assert_eq!(fake.prepared, 0); + assert!(fake.seen.is_empty(), "{:?}", fake.seen); + assert_eq!(Intent::read(&refused_home, store, project).unwrap(), None); + // the admission refused, so there is no admission to release + assert!(fake.admitted.is_empty()); + assert!(fake.released.is_empty()); + // the home entry and the project's record stay + assert!(paths::project_dir(&refused_home, store, project).is_dir()); + let _ = std::fs::remove_dir_all(&refused_home); + + // a live operation at the project scope is `Busy`, with the same rule + let busy_home = home("busy"); + project_record(&busy_home, store, project, stack); + let conflict = SdkValue::map([ + ("kind", t("removal")), + ("entity", t("app")), + ("phase", SdkValue::Null), + ("op", t("11")), + ("uncertain", SdkValue::Bool(false)), + ]); + let mut fake = Fake::new(&busy_home, store, project, Vec::new()).refusing("Busy", conflict); + let refusal = delete_with(&busy_home, store, project, Some(stack), &mut fake).unwrap_err(); + assert_eq!(refusal.code, "Busy"); + assert_eq!(fake.prepared, 0); + assert!(fake.seen.is_empty()); + assert_eq!(Intent::read(&busy_home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&busy_home); +} + +#[test] +fn a_retry_reuses_the_sidecar_admission_identity() { + let home = home("reuse"); + let (store, project, stack) = ("shop", "app", stack(22)); + project_record(&home, store, project, stack); + let mut pending = intent(&home, store, project, stack, 111); + pending.op = Some([3; 16]); + Intent::write(&home, &pending).unwrap(); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Retired { deleted_ms: 111 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + // the retry re-registers the recorded identity, then releases it + assert_eq!(fake.admitted, [Admission::new(stack, [3; 16])]); + assert_eq!(fake.released, fake.admitted); + assert_eq!(outcome.get_int("deleted_ms"), Some(111)); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_failed_marker_releases_the_admission_it_took() { + let home = home("marker-refused"); + let (store, project, stack) = ("shop", "app", stack(21)); + project_record(&home, store, project, stack); + let mut fake = Fake::new(&home, store, project, Vec::new()); + fake.mark_refusal = Some(refused("Busy", "the project is held")); + let refusal = delete_with(&home, store, project, Some(stack), &mut fake).unwrap_err(); + assert_eq!(refusal.code, "Busy"); + // the admission taken before the sidecar is released on the failure + assert_eq!(fake.admitted.len(), 1); + assert_eq!(fake.released, fake.admitted); + // the sidecar stays `pending` for the retry, and the entry stays + let left = Intent::read(&home, store, project).unwrap().unwrap(); + assert_eq!(left.state, IntentState::Pending); + assert!(paths::project_dir(&home, store, project).is_dir()); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_retired_retry_reuses_the_intent_deleted_ms_and_finishes_the_entry() { + let home = home("retired"); + let (store, project, stack) = ("shop", "app", stack(2)); + project_record(&home, store, project, stack); + Intent::write(&home, &intent(&home, store, project, stack, 111)).unwrap(); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Retired { deleted_ms: 222 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert_eq!(fake.seen, [(stack, 111)]); + assert_eq!(outcome.get_int("deleted_ms"), Some(222)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_live_row_with_a_live_intent_redoes_the_marker_then_finishes() { + let home = home("marked"); + let (store, project, stack) = ("shop", "app", stack(3)); + project_record(&home, store, project, stack); + Intent::write(&home, &intent(&home, store, project, stack, 111)).unwrap(); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Marked { deleted_ms: 111 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + // the live row has no marker, so the marker is redone with the same ms + assert_eq!(fake.seen, [(stack, 111)]); + assert_eq!(fake.states, [IntentState::Pending]); + assert_eq!(outcome.get_int("deleted_ms"), Some(111)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn an_absent_stack_finishes_a_stale_entry() { + let home = home("absent"); + let (store, project, stack) = ("shop", "app", stack(4)); + project_record(&home, store, project, stack); + Intent::write(&home, &intent(&home, store, project, stack, 111)).unwrap(); + let mut fake = Fake::new(&home, store, project, vec![Deletion::Absent]); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert_eq!(fake.seen, [(stack, 111)]); + assert_eq!(outcome.get_int("deleted_ms"), Some(111)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_hidden_store_project_still_has_its_stale_entry_removed() { + let home = home("hidden"); + let (store, project, stack) = ("shop", "app", stack(5)); + project_record(&home, store, project, stack); + // The Store listing filters the retired project out; the Store side + // classifies the retry by the recorded stack id as Retired. + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Retired { deleted_ms: 333 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert_eq!(outcome.get_int("deleted_ms"), Some(333)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_home_removal_failure_is_success_false_and_leaves_a_marked_intent() { + let home = home("residue"); + let (store, project, stack) = ("shop", "app", stack(6)); + project_record(&home, store, project, stack); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Marked { deleted_ms: 44 }], + ) + .failing(); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert_eq!(outcome.get_int("deleted_ms"), Some(44)); + assert!(!outcome.get_bool("home_entry_removed")); + // the marker is the commit point; the entry and intent stay for the retry + assert!(paths::project_dir(&home, store, project).is_dir()); + let left = Intent::read(&home, store, project).unwrap().unwrap(); + assert_eq!(left.state, IntentState::Marked); + assert_eq!(left.deleted_ms, 44); + + // a same-home retry reuses the stored ms, finishes the entry and returns + // `home_entry_removed: true` + let mut retry = Fake::new( + &home, + store, + project, + vec![Deletion::Retired { deleted_ms: 44 }], + ); + let outcome = delete_with(&home, store, project, Some(stack), &mut retry).unwrap(); + assert_eq!(retry.seen, [(stack, 44)]); + assert_eq!(outcome.get_int("deleted_ms"), Some(44)); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_done_intent_settles_the_entry_without_a_second_marker() { + let home = home("done"); + let (store, project, stack) = ("shop", "app", stack(7)); + project_record(&home, store, project, stack); + let mut done = intent(&home, store, project, stack, 44); + done.state = IntentState::Done; + Intent::write(&home, &done).unwrap(); + let mut fake = Fake::new(&home, store, project, Vec::new()); + let outcome = delete_with(&home, store, project, Some(stack), &mut fake).unwrap(); + assert!(fake.seen.is_empty(), "a done intent marks nothing"); + assert_eq!(outcome.get_int("deleted_ms"), Some(44)); + assert!(outcome.get_bool("home_entry_removed")); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_recreated_project_discards_the_stale_intent_and_starts_over() { + let home = home("recreated"); + let (store, project, old, new) = ("shop", "app", stack(8), stack(9)); + project_record(&home, store, project, new); + Intent::write(&home, &intent(&home, store, project, old, 111)).unwrap(); + let mut fake = Fake::new( + &home, + store, + project, + vec![Deletion::Marked { deleted_ms: 555 }], + ); + let outcome = delete_with(&home, store, project, Some(new), &mut fake).unwrap(); + assert_eq!(fake.seen.len(), 1); + assert_eq!(fake.seen[0].0, new, "the record that is there now wins"); + assert_ne!(fake.seen[0].1, 111, "the stale deleted_ms is not reused"); + assert_eq!(outcome.get_int("deleted_ms"), Some(555)); + assert!(outcome.get_bool("home_entry_removed")); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn an_untracked_record_with_no_stack_is_removed_without_a_marker() { + let home = home("untracked"); + let (store, project) = ("shop", "app"); + write_record( + &paths::project_record(&home, store, project), + &SdkValue::map([("v", SdkValue::Int(1)), ("name", t(project))]), + ) + .unwrap(); + let mut fake = Fake::new(&home, store, project, Vec::new()); + let outcome = delete_with(&home, store, project, None, &mut fake).unwrap(); + assert!(fake.seen.is_empty()); + assert_eq!(fake.prepared, 1, "a legacy identity is saved first"); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, store, project).exists()); + let _ = std::fs::remove_dir_all(&home); + + // no record and no intent is NoSuchProject + let refusal = delete_with(&home, "shop", "gone", None, &mut fake).unwrap_err(); + assert_eq!(refusal.code, "NoSuchProject"); +} + +#[test] +fn the_intent_moves_pending_marked_done_and_unlinks() { + let home = home("intent"); + let (store, project, stack) = ("shop", "app", stack(10)); + let mut value = intent(&home, store, project, stack, 5); + Intent::write(&home, &value).unwrap(); + let path = Intent::path(&home, store, project); + assert!(path.is_file()); + assert_eq!( + Intent::read(&home, store, project).unwrap().unwrap().state, + IntentState::Pending + ); + // no temporary file is left beside it + let mut names: Vec = std::fs::read_dir(path.parent().unwrap()) + .unwrap() + .map(|entry| entry.unwrap().file_name().into_string().unwrap()) + .collect(); + names.sort(); + assert_eq!(names, [format!("{project}.json")]); + + value.state = IntentState::Marked; + value.deleted_ms = 6; + value.op = Some([4; 16]); + Intent::write(&home, &value).unwrap(); + let read = Intent::read(&home, store, project).unwrap().unwrap(); + assert_eq!((read.state, read.deleted_ms), (IntentState::Marked, 6)); + assert_eq!(read.op, Some([4; 16]), "the admission identity persists"); + + value.state = IntentState::Done; + Intent::write(&home, &value).unwrap(); + assert_eq!( + Intent::read(&home, store, project).unwrap().unwrap().state, + IntentState::Done + ); + Intent::unlink(&home, store, project).unwrap(); + assert_eq!(Intent::read(&home, store, project).unwrap(), None); + // unlinking an absent intent is not an error + Intent::unlink(&home, store, project).unwrap(); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn the_worker_removes_only_its_entry_for_the_recorded_stack() { + let root = home("worker-entry"); + let (store, first) = ("shop", stack(11)); + project_record(&root, store, "app", first); + project_record(&root, store, "other", stack(12)); + // the hint names the caller's project; the other entry stays + let removed = remove_worker_entry(&root, store, first, Some("app")).unwrap(); + assert_eq!(removed.as_deref(), Some("app")); + assert!(!paths::project_dir(&root, store, "app").exists()); + assert!(paths::project_dir(&root, store, "other").is_dir()); + // without a hint the recorded stack id finds the entry + let removed = remove_worker_entry(&root, store, stack(12), None).unwrap(); + assert_eq!(removed.as_deref(), Some("other")); + assert!(!paths::project_dir(&root, store, "other").exists()); + let _ = std::fs::remove_dir_all(&root); +} + +#[test] +fn a_worker_reply_names_the_stack_and_deleted_ms() { + use layerfs_store::project::frame::DeleteReply; + let first = stack(13); + let reply = DeleteReply { + project: "app".to_owned(), + stack: first, + deleted_ms: 42, + }; + let encoded = reply.encode(); + assert_eq!(encoded.get_text("kind"), Some("Removed")); + assert_eq!( + encoded.get_text("stack_id"), + Some(hex(&first.to_bytes()).as_str()) + ); + assert_eq!( + DeleteReply::decode(&encoded).unwrap(), + reply, + "the worker reply round-trips" + ); + // a reply for a different Stack is detectable + let other = DeleteReply { + stack: stack(14), + ..reply.clone() + }; + assert_ne!(DeleteReply::decode(&other.encode()).unwrap().stack, first); +} diff --git a/control/crates/layerfs-store/tests/project_delete_frames.rs b/control/crates/layerfs-store/tests/project_delete_frames.rs new file mode 100644 index 0000000000..87b7178990 --- /dev/null +++ b/control/crates/layerfs-store/tests/project_delete_frames.rs @@ -0,0 +1,180 @@ +//! The `project.delete` worker frame and its reply: the map the caller +//! builds, the fields the worker decodes, and the reply it sends back. +use layerfs_bridge::control::SdkValue; +use layerfs_bridge::sdk_values::hex; +use layerfs_history::LayerStackId; +use layerfs_home::names::StoreName; +use layerfs_store::project::frame::{ + DeleteAdmitFrame, DeleteFrame, DeleteReleaseFrame, DeleteReply, +}; + +fn t(text: &str) -> SdkValue { + SdkValue::text(text) +} + +fn map(fields: Vec<(&str, SdkValue)>) -> SdkValue { + SdkValue::Map(fields.into_iter().map(|(n, v)| (n.to_owned(), v)).collect()) +} + +fn stack(body: u8) -> LayerStackId { + LayerStackId::from_authority([body; 16]) +} + +#[test] +fn the_frame_names_the_store_stack_and_optional_context() { + let stack = stack(1); + let op = [7u8; 16]; + let record = map(vec![("name", t("shop")), ("kind", t("sqlite"))]); + let frame = DeleteFrame { + store: StoreName::parse("shop").unwrap(), + project: Some("app".to_owned()), + stack, + deleted_ms: Some(5), + op_id: Some(op), + store_record: Some(record.clone()), + }; + let encoded = frame.encode(); + assert_eq!( + encoded, + map(vec![ + ("store", t("shop")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ("deleted_ms", SdkValue::Int(5)), + ("project", t("app")), + ("op_id", t(&hex(&op))), + ("store_record", record), + ]) + ); + let decoded = DeleteFrame::decode(&encoded).unwrap(); + assert_eq!(decoded.store, frame.store); + assert_eq!(decoded.project, frame.project); + assert_eq!(decoded.stack, stack); + assert_eq!(decoded.deleted_ms, Some(5)); + assert_eq!(decoded.op_id, Some(op)); + assert_eq!(decoded.store_record, frame.store_record); +} + +#[test] +fn a_frame_with_only_the_store_and_stack_decodes() { + let stack = stack(2); + let minimal = map(vec![ + ("store", t("shop")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ]); + let decoded = DeleteFrame::decode(&minimal).unwrap(); + assert_eq!((decoded.project, decoded.deleted_ms), (None, None)); + assert_eq!(decoded.op_id, None); + assert_eq!(decoded.store_record, None); + assert_eq!(decoded.stack, stack); +} + +#[test] +fn the_admission_and_release_frames_round_trip() { + let stack = stack(4); + let op = [9u8; 16]; + let record = map(vec![("name", t("shop")), ("kind", t("sqlite"))]); + let admit = DeleteAdmitFrame { + store: StoreName::parse("shop").unwrap(), + stack, + op, + store_record: Some(record.clone()), + }; + let encoded = admit.encode(); + assert_eq!( + encoded, + map(vec![ + ("store", t("shop")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ("op_id", t(&hex(&op))), + ("store_record", record.clone()), + ]) + ); + assert_eq!(DeleteAdmitFrame::decode(&encoded).unwrap(), admit); + + let release = DeleteReleaseFrame { + store: StoreName::parse("shop").unwrap(), + op, + store_record: None, + }; + let encoded = release.encode(); + assert_eq!( + encoded, + map(vec![("store", t("shop")), ("op_id", t(&hex(&op)))]) + ); + assert_eq!(DeleteReleaseFrame::decode(&encoded).unwrap(), release); +} + +#[test] +fn the_admission_frames_refuse_a_bad_operation_identity() { + let decode = |fields| DeleteAdmitFrame::decode(&map(fields)).unwrap_err().message; + let stack = stack(5); + assert_eq!( + decode(vec![ + ("store", t("shop")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ("op_id", t("zz")), + ]), + "`op_id` must be hex digits" + ); + assert_eq!( + decode(vec![ + ("store", t("shop")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ("op_id", t("ab")), + ]), + "`op_id` must be an operation identity (16 bytes)" + ); + assert_eq!( + delete_release_decode(&map(vec![("store", t("shop"))])), + "missing text argument `op_id`" + ); +} + +fn delete_release_decode(frame: &SdkValue) -> String { + DeleteReleaseFrame::decode(frame).unwrap_err().message +} + +#[test] +fn the_worker_refuses_a_bad_frame_in_order() { + let decode = |fields| DeleteFrame::decode(&map(fields)).unwrap_err().message; + assert_eq!(decode(vec![]), "missing text argument `store`"); + assert!(decode(vec![("store", t("../x"))]).starts_with("store name")); + assert_eq!( + decode(vec![("store", t("shop"))]), + "missing text argument `stack_id`" + ); + assert_eq!( + decode(vec![("store", t("shop")), ("stack_id", t("zz"))]), + "`stack_id` must be hex digits" + ); + assert_eq!( + decode(vec![("store", t("shop")), ("stack_id", t("ab"))]), + "`stack_id` must be a LayerStack identity (17 bytes)" + ); +} + +#[test] +fn the_reply_round_trips_and_requires_removed() { + let stack = stack(3); + let reply = DeleteReply { + project: "app".to_owned(), + stack, + deleted_ms: 42, + }; + let encoded = reply.encode(); + assert_eq!( + encoded, + map(vec![ + ("kind", t("Removed")), + ("project", t("app")), + ("stack_id", t(&hex(&stack.to_bytes()))), + ("deleted_ms", SdkValue::Int(42)), + ]) + ); + assert_eq!(DeleteReply::decode(&encoded).unwrap(), reply); + let other = map(vec![("kind", t("UpToDate"))]); + assert_eq!( + DeleteReply::decode(&other).unwrap_err().message, + "the worker project.delete reply is not `Removed`" + ); +} diff --git a/control/crates/layerfs-store/tests/project_delete_store.rs b/control/crates/layerfs-store/tests/project_delete_store.rs new file mode 100644 index 0000000000..fec3091bbb --- /dev/null +++ b/control/crates/layerfs-store/tests/project_delete_store.rs @@ -0,0 +1,238 @@ +//! `project.delete`'s home path against a real local Store (T4.6): the +//! control layer admits the project scope through `gc_register`/`gc_release` +//! before its sidecar and marker, so a live mount refuses with +//! `MountsActive` (its holders), a live operation with `Busy`, and a refusal +//! leaves no sidecar, no marker and no leaked admission intent. +use layerfs_bridge::control::SdkValue; +use layerfs_history::records::{GcIntent, GcIntentKind, GcScopeKind}; +use layerfs_history::{HistoryName, LayerStackId, NamedSnapshot}; +use layerfs_home::events::Events; +use layerfs_home::home::{layout, paths}; +use layerfs_home::names::{ProjectRef, StoreName}; +use layerfs_store::open_args::OpenArgs; +use layerfs_store::project::add::{add_project, ProjectAdd}; +use layerfs_store::project::delete::{delete, Intent}; +use layerfs_store::record::StoreRecord; +use layerfs_store::service::with_service; +use layerfs_store::sqlite::create::create; +use layerfs_store_service::history::lookup; +use std::path::PathBuf; +use std::sync::atomic::{AtomicU64, Ordering}; + +static NEXT: AtomicU64 = AtomicU64::new(0); + +fn tempdir(tag: &str) -> PathBuf { + let directory = std::env::temp_dir().join(format!( + "layerfs-delete-store-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&directory); + layout::create(&directory).unwrap(); + directory +} + +/// A folder to initialize a project from: no home layout inside it. +fn plaindir(tag: &str) -> PathBuf { + let directory = std::env::temp_dir().join(format!( + "layerfs-delete-store-folder-{tag}-{}-{}", + std::process::id(), + NEXT.fetch_add(1, Ordering::Relaxed) + )); + let _ = std::fs::remove_dir_all(&directory); + std::fs::create_dir_all(&directory).unwrap(); + directory +} + +/// True when the sandbox filesystem cannot hold a directly opened Store, so +/// these real-Store cases cannot run here. The fake-home cases in +/// `project_delete` cover the same home path without a Store. +fn no_direct_store(refusal: &layerfs_bridge::control::SdkRefusal) -> bool { + refusal.code == "Unsupported" && refusal.message.contains("does not carry SQLite locks") +} + +/// A home whose Store `shop` holds the live project `app`, and the +/// `OpenArgs` (with the Store record) that reach it. `None` when this +/// filesystem cannot hold a directly opened Store. +fn shop(tag: &str) -> Option<(PathBuf, OpenArgs, LayerStackId)> { + let home = tempdir(tag); + match create(&home, &StoreName::parse("shop").unwrap()) { + Ok(_) => {} + Err(refusal) if no_direct_store(&refusal) => { + eprintln!("NOT RUN: this filesystem cannot hold a directly opened Store: {refusal:?}"); + let _ = std::fs::remove_dir_all(&home); + return None; + } + Err(refusal) => panic!("store.create: {refusal:?}"), + } + let source = plaindir(tag); + std::fs::write(source.join("a.txt"), b"a\n").unwrap(); + add_project(&ProjectAdd { + home: home.clone(), + store: StoreName::parse("shop").unwrap(), + name: "app".to_owned(), + source, + timeout_ms: Some(60_000), + store_record: None, + }) + .unwrap(); + let record = StoreRecord::read(&home, "shop").unwrap().unwrap(); + let open = OpenArgs { + home: Some(home.clone()), + store: Some("shop".to_owned()), + project: Some("app".to_owned()), + store_path: Some(paths::store_file(&home, "shop").display().to_string()), + store_record: Some(record.to_record().clone()), + postgresql: None, + }; + let stack = with_service(&open, |service| { + Ok(lookup::project(&service.store, "app").unwrap().id) + }) + .unwrap(); + Some((home, open, stack)) +} + +/// `project.delete shop/app` through the control-layer home path. +fn remove(home: &std::path::Path) -> Result { + let mut sink = |_| {}; + delete( + home, + &mut Events::new(&mut sink), + &ProjectRef::parse("shop/app").unwrap(), + ) +} + +/// The live intents at the project scope. +fn intents(open: &OpenArgs, stack: LayerStackId) -> Vec { + with_service(open, |service| { + Ok(service + .store + .history() + .gc_intents(GcScopeKind::Project, stack.as_slice()) + .unwrap()) + }) + .unwrap() +} + +/// Registers a live mount of the project's `main` Branch, as a Workspace +/// bind does before it demands the root. +fn mount_main(open: &OpenArgs, stack: LayerStackId, op: [u8; 16]) { + // `lookup::branch` refuses `main` by design; the snapshot lookup names it + let branch = with_service(open, |service| { + let project = HistoryName::new("app").unwrap(); + let main = HistoryName::new("main").unwrap(); + match service + .store + .published(|history| history.branch_snapshot_named(&project, &main)) + .unwrap() + { + NamedSnapshot::Found(snapshot) => Ok(snapshot.branch.id), + other => panic!("no main Branch: {other:?}"), + } + }) + .unwrap(); + let intent = GcIntent::shared( + op, + GcIntentKind::Mount, + GcScopeKind::Branch, + branch.as_slice(), + ) + .in_project(stack.as_slice()) + .named(Some("app"), Some("main")) + .placed(Some([9; 32]), Some("sandbox-9"), Some("machine-9")); + with_service(open, |service| { + service.store.history().gc_register(&intent).unwrap(); + Ok(()) + }) + .unwrap(); +} + +fn release(open: &OpenArgs, op: [u8; 16]) { + with_service(open, |service| { + service.store.history().gc_release(&op).unwrap(); + Ok(()) + }) + .unwrap(); +} + +#[test] +fn a_live_mount_refuses_the_delete_before_the_sidecar_and_leaves_no_intent() { + let Some((home, open, stack)) = shop("mount") else { + return; + }; + mount_main(&open, stack, [9; 16]); + assert!(intents(&open, stack).is_empty(), "no project-scope row yet"); + + let refusal = remove(&home).expect_err("a live mount holds the project"); + assert_eq!(refusal.code, "MountsActive", "{refusal:?}"); + let SdkValue::List(holders) = refusal.detail.get("holders").expect("holders") else { + panic!("{refusal:?}"); + }; + assert_eq!(holders[0].get_text("kind"), Some("mount")); + assert_eq!(holders[0].get_text("sandbox"), Some("sandbox-9")); + + // no sidecar pending, no marker and no leaked admission intent + assert_eq!(Intent::read(&home, "shop", "app").unwrap(), None); + assert!(paths::project_dir(&home, "shop", "app").is_dir()); + assert!( + intents(&open, stack).is_empty(), + "the refused admission left no project-scope row" + ); + with_service(&open, |service| { + assert_eq!( + lookup::project(&service.store, "app") + .expect("still live") + .id, + stack + ); + Ok(()) + }) + .unwrap(); + + // the mount goes and the same home path succeeds, releasing its admission + release(&open, [9; 16]); + let outcome = remove(&home).unwrap(); + assert_eq!(outcome.get_text("kind"), Some("Removed")); + assert_eq!(outcome.get_text("project"), Some("shop/app")); + assert!(outcome.get_bool("home_entry_removed")); + assert!(!paths::project_dir(&home, "shop", "app").exists()); + assert_eq!(Intent::read(&home, "shop", "app").unwrap(), None); + assert!( + intents(&open, stack).is_empty(), + "the admission was released" + ); + let _ = std::fs::remove_dir_all(&home); +} + +#[test] +fn a_live_operation_at_the_project_scope_is_busy_and_writes_no_sidecar() { + let Some((home, open, stack)) = shop("busy") else { + return; + }; + assert!(intents(&open, stack).is_empty()); + let holder = GcIntent::operation( + [7; 16], + GcIntentKind::Removal, + GcScopeKind::Project, + stack.as_slice(), + ) + .named(Some("app"), None); + with_service(&open, |service| { + service.store.history().gc_register(&holder).unwrap(); + Ok(()) + }) + .unwrap(); + + let refusal = remove(&home).expect_err("another removal holds the project"); + assert_eq!(refusal.code, "Busy", "{refusal:?}"); + assert_eq!(Intent::read(&home, "shop", "app").unwrap(), None); + assert_eq!(intents(&open, stack).len(), 1, "only the test's own holder"); + assert_eq!(intents(&open, stack)[0].op_id, [7; 16]); + + // the operation ends: the delete proceeds and releases its own admission + release(&open, [7; 16]); + assert!(remove(&home).unwrap().get_bool("home_entry_removed")); + assert_eq!(Intent::read(&home, "shop", "app").unwrap(), None); + assert!(intents(&open, stack).is_empty()); + let _ = std::fs::remove_dir_all(&home); +} diff --git a/control/crates/layerfs-store/tests/project_frames.rs b/control/crates/layerfs-store/tests/project_frames.rs index e200d7f041..2afe04cff9 100644 --- a/control/crates/layerfs-store/tests/project_frames.rs +++ b/control/crates/layerfs-store/tests/project_frames.rs @@ -3,7 +3,7 @@ //! refuses in the order it always did. use layerfs_bridge::control::SdkValue; use layerfs_home::names::StoreName; -use layerfs_store::project::frame::{InitFrame, RemoveFrame, StageFrame, StageStep}; +use layerfs_store::project::frame::{InitFrame, StageFrame, StageStep}; fn t(text: &str) -> SdkValue { SdkValue::text(text) @@ -45,26 +45,6 @@ fn each_frame_encodes_the_map_its_caller_built() { assert_eq!((decoded.name, decoded.timeout_ms), (init.name, Some(5))); assert_eq!(decoded.store_record, init.store_record); - let remove = RemoveFrame { - store: store(), - project: "web".to_owned(), - store_record: Some(record.clone()), - }; - let encoded = remove.encode(); - assert_eq!( - encoded, - map(vec![ - ("store", t("shop")), - ("project", t("web")), - ("store_record", record), - ]) - ); - let decoded = RemoveFrame::decode(&encoded).unwrap(); - assert_eq!( - (decoded.store, decoded.project), - (store(), "web".to_owned()) - ); - let stage = |step| StageFrame { store: "shop".to_owned(), name: "web".to_owned(), @@ -98,15 +78,6 @@ fn the_worker_refuses_a_frame_in_its_old_order() { let bare = InitFrame::decode(&map(vec![("store", t("shop")), ("staged", t(ID))])).unwrap(); assert_eq!((bare.name, bare.timeout_ms), (None, None)); - let remove = |fields| RemoveFrame::decode(&map(fields)).unwrap_err().message; - assert_eq!(remove(vec![]), "missing text argument `store`"); - // no project before a bad Store name - assert_eq!( - remove(vec![("store", t("../x"))]), - "missing text argument `project`" - ); - assert!(remove(vec![("store", t("../x")), ("project", t("web"))]).starts_with("store name")); - let stage = |fields| StageFrame::decode(map(fields)).unwrap_err().message; // a bad id before an unknown step assert_eq!( diff --git a/control/crates/layerfs-store/tests/project_list_frames.rs b/control/crates/layerfs-store/tests/project_list_frames.rs new file mode 100644 index 0000000000..344f1ee3f8 --- /dev/null +++ b/control/crates/layerfs-store/tests/project_list_frames.rs @@ -0,0 +1,122 @@ +//! The `project.list` worker frame and its reply (T4.5c): the map the +//! caller builds, the fields the worker decodes, and the filtered listing +//! it sends back. +use layerfs_bridge::control::SdkValue; +use layerfs_bridge::sdk_values::hex; +use layerfs_history::LayerStackId; +use layerfs_home::names::StoreName; +use layerfs_store::project::frame::{ListedProject, ListingFrame, ListingReply}; + +fn t(text: &str) -> SdkValue { + SdkValue::text(text) +} + +fn map(fields: Vec<(&str, SdkValue)>) -> SdkValue { + SdkValue::Map(fields.into_iter().map(|(n, v)| (n.to_owned(), v)).collect()) +} + +fn stack(body: u8) -> LayerStackId { + LayerStackId::from_authority([body; 16]) +} + +#[test] +fn the_frame_names_the_store_and_carries_its_record() { + let record = map(vec![("name", t("shop")), ("kind", t("sqlite"))]); + let frame = ListingFrame { + store: StoreName::parse("shop").unwrap(), + store_record: Some(record.clone()), + }; + let encoded = frame.encode(); + assert_eq!( + encoded, + map(vec![("store", t("shop")), ("store_record", record.clone())]) + ); + let decoded = ListingFrame::decode(&encoded).unwrap(); + assert_eq!(decoded.store, frame.store); + assert_eq!(decoded.store_record, Some(record)); +} + +#[test] +fn a_frame_with_only_the_store_decodes() { + let decoded = ListingFrame::decode(&map(vec![("store", t("shop"))])).unwrap(); + assert_eq!(decoded.store.as_str(), "shop"); + assert_eq!(decoded.store_record, None); +} + +#[test] +fn the_worker_refuses_a_bad_frame_in_order() { + let decode = |fields| ListingFrame::decode(&map(fields)).unwrap_err().message; + assert_eq!(decode(vec![]), "missing text argument `store`"); + assert!(decode(vec![("store", t("../x"))]).starts_with("store name")); +} + +#[test] +fn the_reply_round_trips_and_requires_listed() { + let reply = ListingReply { + projects: vec![ + ListedProject { + name: "app".to_owned(), + stack: stack(1), + }, + ListedProject { + name: "web".to_owned(), + stack: stack(2), + }, + ], + }; + let listed = |name: &str, stack: &LayerStackId| { + map(vec![ + ("name", t(name)), + ("stack_id", t(&hex(&stack.to_bytes()))), + ]) + }; + let encoded = reply.encode(); + assert_eq!( + encoded, + map(vec![ + ("kind", t("Listed")), + ( + "projects", + SdkValue::List(vec![listed("app", &stack(1)), listed("web", &stack(2))]), + ), + ]) + ); + assert_eq!(ListingReply::decode(&encoded).unwrap(), reply); + + let wrong_kind = map(vec![("kind", t("Removed"))]); + assert_eq!( + ListingReply::decode(&wrong_kind).unwrap_err().message, + "the worker project.list reply is not `Listed`" + ); + let no_list = map(vec![("kind", t("Listed"))]); + assert_eq!( + ListingReply::decode(&no_list).unwrap_err().message, + "reply has no `projects` list" + ); + let no_name = map(vec![ + ("kind", t("Listed")), + ( + "projects", + SdkValue::List(vec![map(vec![("stack_id", t(&hex(&stack(3).to_bytes())))])]), + ), + ]); + assert_eq!( + ListingReply::decode(&no_name).unwrap_err().message, + "reply project has no `name`" + ); + let bad_stack = map(vec![ + ("kind", t("Listed")), + ( + "projects", + SdkValue::List(vec![map(vec![("name", t("app")), ("stack_id", t("zz"))])]), + ), + ]); + assert_eq!( + ListingReply::decode(&bad_stack).unwrap_err().message, + "`stack_id` must be hex digits" + ); + let empty = ListingReply { + projects: Vec::new(), + }; + assert_eq!(ListingReply::decode(&empty.encode()).unwrap(), empty); +} diff --git a/control/crates/layerfs-store/tests/restore_install.rs b/control/crates/layerfs-store/tests/restore_install.rs index 2364f2e8c3..688d62cd02 100644 --- a/control/crates/layerfs-store/tests/restore_install.rs +++ b/control/crates/layerfs-store/tests/restore_install.rs @@ -45,7 +45,6 @@ fn unused(home: &Path, name: &str) -> Result<(), SdkRefusal> { fn related() -> Related { Related { store_idle: unused, - can_remove_project: unused, } } diff --git a/control/crates/layerfs-store/tests/store_ops.rs b/control/crates/layerfs-store/tests/store_ops.rs index 3ecd237aec..93f6c28e27 100644 --- a/control/crates/layerfs-store/tests/store_ops.rs +++ b/control/crates/layerfs-store/tests/store_ops.rs @@ -2,7 +2,7 @@ //! the same names and order the call's args map gave before, an absent //! option not sent. use layerfs_bridge::control::SdkValue; -use layerfs_store::calls::branch::{BranchDiff, BranchFork, BranchMerge, BranchPublish}; +use layerfs_store::calls::branch::{BranchDiff, BranchFork, BranchMerge}; use layerfs_store::calls::file::{FileApply, FileDiff, FileRead, FileWrite, Side}; use layerfs_store::calls::{Change, Content, DiffOptions, Page, StoreOp}; @@ -265,37 +265,3 @@ fn saved_query_selectors_and_numbered_pages_are_forwarded_without_resolving_head ] ); } - -#[test] -fn a_publish_sends_its_expected_base_head_and_force() { - // The API layer's snake_case options reach the Store as the camelCase - // names its method reads (#691); an absent expectation is not sent. - let publish = BranchPublish { - branch: t("work"), - commit: Some(t("cc")), - expected_base: Some(t("aa")), - expected_head: Some(t("bb")), - force: Some(false), - ..BranchPublish::default() - }; - let op = StoreOp::Publish(&publish); - assert_eq!(op.method(), "branch.publish"); - assert_eq!( - op.engine_args(), - vec![ - (t("branch"), SdkValue::text("work")), - (t("commit"), SdkValue::text("cc")), - (t("expectedBase"), SdkValue::text("aa")), - (t("expectedHead"), SdkValue::text("bb")), - (t("force"), SdkValue::Bool(false)), - ] - ); - let plain = BranchPublish { - branch: t("work"), - ..BranchPublish::default() - }; - assert_eq!( - StoreOp::Publish(&plain).engine_args(), - vec![(t("branch"), SdkValue::text("work"))] - ); -} diff --git a/core/AGENTS.md b/core/AGENTS.md index 30fd045587..fe4cd89699 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -42,10 +42,16 @@ formats are introduced. No third-party source or dependency changes are implied. ## Checks and completion -Core follows the engine guide's +All product layers follow the [production size and responsibility rules](../engine/AGENTS.md#production-file-size-and-responsibility) -and [checks](../engine/AGENTS.md#checks-and-completion), and the root guide's -[rules you must not break](../AGENTS.md#rules-you-must-not-break). Build and -test through the selected worktree's registered private resources from the -root manifest. For docs-only changes verify local links/anchors, status, -claims and whitespace; Rust/runtime checks do not apply. +and [verification rules](../engine/AGENTS.md#checks-and-completion). Build and +test through the selected worktree's registered private resources from the root +manifest. Build tests first with `--no-run`, then execute each selection under an +explicit wall timeout of at most 120 seconds. Preserve repository ARM64 flags, +locked dependencies, exact failure custody, the Disposable-only execution policy +and per-commit production LOC comparisons. Migrations retain cheap tests of +surviving behavior and delete tests that require retired scaffolding, with the +root guide's required behavior coverage and deletion record. + +For docs-only changes verify local links/anchors, status, claims and whitespace; +Rust/runtime checks do not apply. CI reports after a push and never gates it. diff --git a/core/crates/layerfs-history/src/contract/catalog.rs b/core/crates/layerfs-history/src/contract/catalog.rs index 9a39d81c1f..da2364410c 100644 --- a/core/crates/layerfs-history/src/contract/catalog.rs +++ b/core/crates/layerfs-history/src/contract/catalog.rs @@ -20,9 +20,10 @@ use crate::error::HistoryResult; use crate::identity::{BranchId, CatalogId, CommitId, HistoryName, LayerId, LayerStackId, NodeId}; use crate::records::{ AddLayerOutcome, AddLayerRequest, BranchMergeRequest, BranchRecord, BranchSnapshot, - CommitHistoryRequest, CommitOutcome, CommitRecord, CommitRequest, ForkRequest, - LayerHistoryRequest, LayerRecord, LayerStackRecord, Page, PageResult, Reservation, - ReserveRequest, StackInitialization, + CommitHistoryRequest, CommitOutcome, CommitRecord, CommitRequest, ForkRequest, GcDeletion, + GcIntent, GcScopeKind, LayerHistoryRequest, LayerRecord, LayerStackRecord, Page, PageResult, + PathRemovalOutcome, PathRemovalRecord, PathRemovalRequest, Reservation, ReserveRequest, + StackInitialization, }; /// Checked inputs that establish one catalog binding. #[derive(Clone, Eq, PartialEq)] @@ -91,6 +92,17 @@ pub trait HistoryCatalog: Send + Sync { /// Stacks in name order. fn layer_stacks(&self, page: &Page) -> HistoryResult>; + /// The typed `NameTaken` state for a LayerStack (project) name, live or + /// deleted, read without resolving the Stack (spec 4.4). The default + /// reports none; a provider that keeps the collision query overrides it, + /// so `project.init` refuses a held name before it scans anything. + fn layer_stack_name_taken( + &self, + _name: &HistoryName, + ) -> HistoryResult> { + Ok(None) + } + /// The stack named `name`, if any. A provider answers through its name /// index; this default pages through the stacks in name order. fn layer_stack_named(&self, name: &HistoryName) -> HistoryResult> { @@ -113,6 +125,15 @@ pub trait HistoryCatalog: Send + Sync { /// One Branch by identity. fn branch(&self, id: BranchId) -> HistoryResult>; + /// One Branch by identity without the visibility filter (spec 4.2). Only + /// rendering and identity keep a retired Branch's name this way; every + /// caller-facing lookup resolves through [`HistoryCatalog::branch`]. A + /// provider that keeps retired rows overrides this; the default reads the + /// filtered row. + fn branch_any(&self, id: BranchId) -> HistoryResult> { + self.branch(id) + } + /// One Branch by its name in a stack, through the name index: the /// stack's other Branches are not read. fn branch_named( @@ -195,17 +216,6 @@ pub trait HistoryCatalog: Send + Sync { )) } - /// The Layer `commit` of `branch` was published as, if it was: the same - /// record `add_layer` answers `UpToDate` from. One bounded read. - fn published_layer( - &self, - branch: BranchId, - commit: CommitId, - ) -> HistoryResult> { - let _ = (branch, commit); - Err(crate::error::HistoryError::Unsupported("published Layer")) - } - /// Reads maintained Store totals; no full object/history scan. fn statistics(&self) -> HistoryResult { Err(crate::HistoryError::Unsupported("Store statistics")) @@ -287,6 +297,195 @@ pub trait HistoryCatalog: Send + Sync { /// Consumes one checked half-open inode range for a scope. fn reserve_inodes(&self, request: &ReserveRequest) -> HistoryResult; + + /// Records a `branch.remove` marker. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it keeps no removal markers; an implementation returns its own + /// [`crate::error::HistoryError`] when the marker cannot be recorded. + fn mark_branch_removed(&self, _branch: BranchId, _removed_ms: i64) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported( + "branch removal marker", + )) + } + + /// Records a `project.delete` marker. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it keeps no deletion markers; an implementation returns its own + /// [`crate::error::HistoryError`] when the marker cannot be recorded. + fn mark_stack_deleted(&self, _stack: LayerStackId, _deleted_ms: i64) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported( + "project deletion marker", + )) + } + + /// The deleted_ms a project.delete marker recorded, when the stack is + /// retired. A same-home retry reads it by the stack id its durable intent + /// recorded before the marker; a live or absent stack has none. The + /// default refuses. + fn stack_deleted_ms(&self, _stack: LayerStackId) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported( + "project deletion marker read", + )) + } + + /// Records a `project.remove_file` marker. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it keeps no path removal markers; an implementation returns its own + /// [`crate::error::HistoryError`] when the marker cannot be recorded. + fn mark_path_removed( + &self, + _stack: LayerStackId, + _path: &[u8], + _frontier_serial: u64, + _removed_ms: i64, + ) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported( + "path removal marker", + )) + } + + /// Applies one `project.remove_file` marker in one write transaction: + /// reads the Store high-water as the new frontier, returns `UpToDate` + /// when the path's marker already covers every project node, otherwise + /// advances the marker and the project epoch. The default refuses. + fn remove_path(&self, _request: &PathRemovalRequest) -> HistoryResult { + Err(crate::error::HistoryError::Unsupported("path removal")) + } + + /// Every `path_removed` marker of one Stack. The default refuses. + fn path_removals(&self, _stack: LayerStackId) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported( + "path removal markers", + )) + } + + /// The `history_serial` a Commit or Layer records, if it exists. The + /// default refuses. + fn node_history_serial(&self, _node: NodeId) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported( + "node history position", + )) + } + + /// The retained history roots of one Stack. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it retains no roots; an implementation returns its own + /// [`crate::error::HistoryError`] when the roots cannot be read. + fn retained_roots(&self, _stack: LayerStackId) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported("retained roots")) + } + + /// The retained history roots of one Stack, for a caller that resolves + /// them separately. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it retains no roots; an implementation returns its own + /// [`crate::error::HistoryError`] when the roots cannot be read. + fn get_retained_roots(&self, _stack: LayerStackId) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported("retained roots")) + } + + /// Removes the unreachable history rows of one Stack, or reports how many + /// a dry run would remove. The default refuses. + /// + /// # Errors + /// + /// The default returns [`crate::error::HistoryError::Unsupported`] + /// because it removes nothing; an implementation returns its own + /// [`crate::error::HistoryError`] when the rows cannot be removed. + fn remove_unreachable(&self, _stack: LayerStackId, _dry_run: bool) -> HistoryResult { + Err(crate::error::HistoryError::Unsupported( + "unreachable history removal", + )) + } + + /// Registers one admission intent (§5) in its own write transaction. + /// + /// The default refuses: a provider without admission cannot make the + /// `MountsActive`/`Busy`/`Unresolved` promise. + fn gc_register(&self, _intent: &GcIntent) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported("GC admission")) + } + + /// Releases one admission intent, deleting its row. + /// + /// The default refuses; a provider that never registered one is unaffected. + fn gc_release(&self, _op_id: &[u8; 16]) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported("GC admission")) + } + + /// Marks one admission intent uncertain, so a later call reports + /// `Unresolved` until its owner settles it. + fn gc_mark_uncertain(&self, _op_id: &[u8; 16]) -> HistoryResult<()> { + Err(crate::error::HistoryError::Unsupported("GC admission")) + } + + /// `branch.remove`: admits at Branch scope and writes the marker in one + /// write transaction. + fn gc_remove_branch( + &self, + branch: BranchId, + removed_ms: i64, + _intent: &GcIntent, + ) -> HistoryResult<()> { + // A provider without admission still writes the marker; the Store + // service only adds admission where the provider keeps intents. + self.mark_branch_removed(branch, removed_ms) + } + + /// `project.delete`: admits at project scope and writes the marker in one + /// write transaction, preserving the same-home retry classification. + fn gc_delete_stack( + &self, + stack: LayerStackId, + deleted_ms: i64, + _intent: &GcIntent, + ) -> HistoryResult { + if let Some(deleted_ms) = self.stack_deleted_ms(stack)? { + return Ok(GcDeletion::Retired { deleted_ms }); + } + if self.layer_stack(stack)?.is_some() { + self.mark_stack_deleted(stack, deleted_ms)?; + return Ok(GcDeletion::Marked { deleted_ms }); + } + Ok(match self.stack_deleted_ms(stack)? { + Some(deleted_ms) => GcDeletion::Retired { deleted_ms }, + None => GcDeletion::Absent, + }) + } + + /// `project.remove_file`: admits at project scope and advances the marker + /// in one write transaction. + fn gc_remove_path( + &self, + request: &PathRemovalRequest, + _intent: &GcIntent, + ) -> HistoryResult { + self.remove_path(request) + } + + /// The live intents recorded at one scope, for `store.status` and tests. + fn gc_intents( + &self, + _scope_kind: GcScopeKind, + _scope_id: &[u8], + ) -> HistoryResult> { + Err(crate::error::HistoryError::Unsupported("GC admission")) + } } impl std::fmt::Debug for HistoryCatalogConfig { diff --git a/core/crates/layerfs-history/src/contract/error.rs b/core/crates/layerfs-history/src/contract/error.rs index 3cede4537b..32ab59b264 100644 --- a/core/crates/layerfs-history/src/contract/error.rs +++ b/core/crates/layerfs-history/src/contract/error.rs @@ -7,6 +7,7 @@ //! that persistence did not answer and therefore proves nothing about rollback. use crate::identity::{CommitId, LayerId}; +use crate::records::GcIntentKind; /// A related record kind, used for a typed absence. #[derive(Clone, Copy, Debug, Eq, PartialEq)] @@ -25,6 +26,99 @@ pub enum Missing { Catalog, } +/// Which kind of record holds a name. +/// +/// A later release may add a holder kind, so the enum is non-exhaustive: a +/// caller matches it with a wildcard arm and never constructs it. +#[non_exhaustive] +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum HolderKind { + /// A Branch. + Branch, + /// A project (LayerStack). + Project, +} + +/// State of the record that holds a name. +/// +/// A later release may add a state, so the enum is non-exhaustive: a +/// caller matches it with a wildcard arm and never constructs it. +#[non_exhaustive] +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum HolderState { + /// The record is live. + Live, + /// The record is retired by `branch.remove`. + Retired, + /// The project is deleted. + Deleted, +} + +/// The record that holds a name. +/// +/// A later release may add a field, so the struct is non-exhaustive: +/// a caller reads its fields, and construction belongs to this crate. +#[non_exhaustive] +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct NameHolder { + /// Record kind. + pub kind: HolderKind, + /// Name held. + pub name: String, + /// Holder state. + pub state: HolderState, +} + +/// Where a name is held. +/// +/// A later release may add a source, so the enum is non-exhaustive: a +/// caller matches it with a wildcard arm and never constructs it. +#[non_exhaustive] +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum NameSource { + /// The Store's own records. + Store, + /// A home project record. + Home, +} + +/// Context for a `NameTaken` refusal. +/// +/// A later release may add a field, so the struct is non-exhaustive: +/// a caller reads its fields, and construction belongs to this crate. +#[non_exhaustive] +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct NameTakenState { + /// The holder. + pub holder: NameHolder, + /// Where it is held. + pub source: NameSource, +} + +/// One hidden path. +/// +/// A later release may add a field, so the struct is non-exhaustive: +/// a caller reads its fields, and construction belongs to this crate. +#[non_exhaustive] +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct RemovedPath { + /// The request path. + pub path: String, + /// The governing frontier serial. + pub frontier_serial: u64, +} + +/// Context for a `Removed` refusal. +/// +/// A later release may add a field, so the struct is non-exhaustive: +/// a caller reads its fields, and construction belongs to this crate. +#[non_exhaustive] +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct RemovedState { + /// The hidden paths. + pub paths: Vec, +} + /// Expected versus observed Branch publication state. /// /// Both sides are reported, so a caller can distinguish a moved head from a @@ -50,8 +144,24 @@ pub enum HistoryError { Missing(Missing), /// A required capability is not provided by this build or provider. Unsupported(&'static str), + /// A name is held by a live, retired or deleted record. + NameTaken(Box), + /// A path is hidden by `remove_file`. + Removed(Box), + /// A staged name or artifact already exists and no record names it. + Exists(&'static str), + /// A required marker or fence row is missing or contradicts the request. + Conflict(&'static str), + /// The Store was replaced or moved under this handle. + StaleStore, /// Immediate metadata admission was refused; the caller may retry later. Busy, + /// A mount or Sandbox holds the scope; the holders are the ones observed. + MountsActive(Box), + /// A live operation holds the scope; its entity, phase and op are reported. + BusyOp(Box), + /// A dead or uncertain owner's operation holds the scope. + Unresolved(Box), /// The content authority this catalog is bound to is not available. OwnershipUnavailable, /// A declared bound, count or counter is exhausted. @@ -89,11 +199,13 @@ pub enum HistoryError { impl HistoryError { /// True when the attempted mutation's persistence outcome is unknown. + #[must_use] pub fn unknown(&self) -> bool { matches!(self.cause(), Self::UnknownOutcome) } /// The typed failure itself; kept for callers that match through it. + #[must_use] pub fn cause(&self) -> &Self { self } @@ -105,7 +217,31 @@ impl std::fmt::Display for HistoryError { Self::InvalidInput(what) => write!(formatter, "invalid input: {what}"), Self::Missing(what) => write!(formatter, "missing {what:?}"), Self::Unsupported(what) => write!(formatter, "unsupported: {what}"), + Self::NameTaken(state) => write!(formatter, "name taken: {:?}", state.holder), + Self::Removed(state) => write!(formatter, "removed: {} paths", state.paths.len()), + Self::Exists(what) => write!(formatter, "exists: {what}"), + Self::Conflict(what) => write!(formatter, "conflict: {what}"), + Self::StaleStore => formatter.write_str("stale Store"), Self::Busy => formatter.write_str("busy"), + Self::MountsActive(state) => { + write!( + formatter, + "mounts active: {} holder(s)", + state.holders.len() + ) + } + Self::BusyOp(state) => write!( + formatter, + "busy: {} at {}", + state.kind.as_str(), + state.entity + ), + Self::Unresolved(state) => write!( + formatter, + "unresolved: {} at {}", + state.kind.as_str(), + state.entity + ), Self::OwnershipUnavailable => formatter.write_str("ownership unavailable"), Self::Capacity(what) => write!(formatter, "capacity: {what}"), Self::Integrity(what) => write!(formatter, "integrity: {what}"), @@ -128,3 +264,139 @@ impl std::error::Error for HistoryError {} /// Result of one history operation. pub type HistoryResult = Result; + +impl NameHolder { + /// Builds a holder for a typed `NameTaken` context. + pub fn new(kind: HolderKind, name: impl Into, state: HolderState) -> Self { + Self { + kind, + name: name.into(), + state, + } + } +} + +impl NameTakenState { + /// Builds the context of a `NameTaken` refusal. + pub fn new(holder: NameHolder, source: NameSource) -> Self { + Self { holder, source } + } +} + +impl RemovedPath { + /// Builds one hidden path for a `Removed` refusal. + pub fn new(path: impl Into, frontier_serial: u64) -> Self { + Self { + path: path.into(), + frontier_serial, + } + } +} + +impl RemovedState { + /// Builds the context of a `Removed` refusal. + pub fn new(paths: Vec) -> Self { + Self { paths } + } +} + +/// One admission holder: a live mount or operation in the scope. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct GcHolder { + /// What kind of holder it is (`mount`, `init`, `merge`, ...). + pub kind: GcIntentKind, + /// The project, Branch or Store the holder is on. + pub entity: String, + /// The holder's Workspace, when it has one. + pub workspace: Option, + /// The holder's Sandbox, when it has one. + pub sandbox: Option, + /// The holder's machine, when it has one. + pub machine: Option, + /// The holder operation identity, hex encoded. + pub op: String, +} + +impl GcHolder { + /// Builds one holder report. + #[must_use] + pub fn new(kind: GcIntentKind, entity: impl Into, op: impl Into) -> Self { + Self { + kind, + entity: entity.into(), + workspace: None, + sandbox: None, + machine: None, + op: op.into(), + } + } +} + +/// The holders that refuse a removal or compaction with `MountsActive`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct MountHolders { + /// Every live or uncertain holder observed in the scope. + pub holders: Vec, +} + +impl MountHolders { + /// Builds the refusal context. + #[must_use] + pub fn new(holders: Vec) -> Self { + Self { holders } + } +} + +/// The live or uncertain operation that refuses a call with `Busy` or +/// `Unresolved`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct OpConflict { + /// The conflicting operation kind. + pub kind: GcIntentKind, + /// The project, Branch or Store it is on. + pub entity: String, + /// Its phase, when recorded. + pub phase: Option, + /// Its operation identity, hex encoded. + pub op: String, + /// Whether its owner is uncertain. + pub uncertain: bool, +} + +impl OpConflict { + /// Builds the refusal context. + #[must_use] + pub fn new( + kind: GcIntentKind, + entity: impl Into, + phase: Option, + op: impl Into, + uncertain: bool, + ) -> Self { + Self { + kind, + entity: entity.into(), + phase, + op: op.into(), + uncertain, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn constructors_build_the_typed_context() { + let holder = NameHolder::new(HolderKind::Branch, "main", HolderState::Retired); + let taken = NameTakenState::new(holder, NameSource::Store); + assert_eq!(taken.holder.name, "main"); + assert_eq!(taken.holder.kind, HolderKind::Branch); + assert_eq!(taken.source, NameSource::Store); + + let removed = RemovedState::new(vec![RemovedPath::new("a.txt", 7)]); + assert_eq!(removed.paths[0].path, "a.txt"); + assert_eq!(removed.paths[0].frontier_serial, 7); + } +} diff --git a/core/crates/layerfs-history/src/contract/mod.rs b/core/crates/layerfs-history/src/contract/mod.rs index 37313bcbc2..520aebbe72 100644 --- a/core/crates/layerfs-history/src/contract/mod.rs +++ b/core/crates/layerfs-history/src/contract/mod.rs @@ -2,5 +2,6 @@ pub mod catalog; pub mod error; pub mod identity; +pub mod path; pub mod query; pub mod records; diff --git a/core/crates/layerfs-history/src/contract/path.rs b/core/crates/layerfs-history/src/contract/path.rs new file mode 100644 index 0000000000..dc751b0403 --- /dev/null +++ b/core/crates/layerfs-history/src/contract/path.rs @@ -0,0 +1,154 @@ +//! The `project.remove_file` path grammar and its keys. +//! +//! The call accepts an absolute POSIX path and stores it as the normalized +//! relative path (`/a` and `a` are the same). A path is refused when it is +//! empty, `/`, `//a`, has an empty, `.` or `..` component, a trailing `/`, a +//! `\` or NUL byte, is longer than 4096 bytes, or has more than 256 +//! components. The stored key is `BLAKE3(normalized path)`; the trace key is +//! keyed by the Store's `trace_salt` over the stack and the normalized path. + +use crate::identity::LayerStackId; + +/// The most bytes one normalized path may have. +pub const MAXIMUM_PATH_BYTES: usize = 4096; +/// The most components one normalized path may have. +pub const MAXIMUM_PATH_COMPONENTS: usize = 256; + +/// A checked, normalized relative path. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct NormalizedPath { + relative: String, +} + +impl NormalizedPath { + /// Checks `text` and returns its normalized relative path. + /// + /// One leading `/` is stripped; everything after it is the relative path. + /// The returned value never starts or ends with `/` and never holds an + /// empty, `.` or `..` component. + pub fn new(text: &str) -> Result { + if text.is_empty() { + return Err("path is empty"); + } + if text.as_bytes().contains(&0) { + return Err("path contains a NUL byte"); + } + if text.contains('\\') { + return Err("path contains a backslash"); + } + let relative = text.strip_prefix('/').unwrap_or(text); + if relative.is_empty() { + return Err("path is the root"); + } + if relative.starts_with('/') { + return Err("path has an empty component"); + } + let mut components = 0usize; + for component in relative.split('/') { + if component.is_empty() { + return Err("path has an empty component"); + } + if component == "." || component == ".." { + return Err("path has a dot component"); + } + components += 1; + } + if components > MAXIMUM_PATH_COMPONENTS { + return Err("path has too many components"); + } + if relative.len() > MAXIMUM_PATH_BYTES { + return Err("path is too long"); + } + Ok(Self { + relative: relative.to_owned(), + }) + } + + /// The normalized relative path, without a leading `/`. + pub fn as_str(&self) -> &str { + &self.relative + } + + /// The normalized path bytes as stored in the marker. + pub fn as_bytes(&self) -> &[u8] { + self.relative.as_bytes() + } + + /// `BLAKE3(normalized path)`, the marker key. + pub fn key(&self) -> [u8; 32] { + path_key(self.as_bytes()) + } +} + +/// `BLAKE3(path)` over already normalized path bytes, the marker key. +pub fn path_key(path: &[u8]) -> [u8; 32] { + *blake3::hash(path).as_bytes() +} + +/// True when `path` is `marker` or lies below it at a `/` boundary +/// (`p == m OR p begins m ++ b"/"`), compared over bytes, never `||`/`LIKE`. +pub fn governs(marker: &[u8], path: &[u8]) -> bool { + path == marker + || (path.len() > marker.len() && path.starts_with(marker) && path[marker.len()] == b'/') +} + +/// The key a trace hashes for one stack and path: keyed by the Store's +/// 32-byte `trace_salt` over the stack identity and the normalized path. +pub fn trace_key(salt: &[u8; 32], stack: LayerStackId, path: &[u8]) -> [u8; 32] { + let mut hasher = blake3::Hasher::new_keyed(salt); + hasher.update(stack.as_slice()); + hasher.update(path); + *hasher.finalize().as_bytes() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn accepts_one_leading_slash_and_relative_paths() { + assert_eq!(NormalizedPath::new("/a").unwrap().as_str(), "a"); + assert_eq!(NormalizedPath::new("a").unwrap().as_str(), "a"); + assert_eq!(NormalizedPath::new("/a/b").unwrap().as_str(), "a/b"); + assert_eq!(NormalizedPath::new("a-b_c.d").unwrap().as_str(), "a-b_c.d"); + } + + #[test] + fn refuses_the_bad_grammar() { + for text in [ + "", "/", "//a", "a//b", "a/", "./a", "a/./b", ".", "..", "/./a", "a\\b", "a\0b", + ] { + assert!(NormalizedPath::new(text).is_err(), "accepted {text:?}"); + } + } + + #[test] + fn refuses_long_paths_and_many_components() { + assert!(NormalizedPath::new(&"a".repeat(MAXIMUM_PATH_BYTES)).is_ok()); + assert!(NormalizedPath::new(&"a".repeat(MAXIMUM_PATH_BYTES + 1)).is_err()); + let many = vec!["a"; MAXIMUM_PATH_COMPONENTS].join("/"); + assert!(NormalizedPath::new(&many).is_ok()); + let more = vec!["a"; MAXIMUM_PATH_COMPONENTS + 1].join("/"); + assert!(NormalizedPath::new(&more).is_err()); + } + + #[test] + fn subtree_matches_only_at_a_slash_boundary() { + assert!(governs(b"a", b"a")); + assert!(governs(b"a", b"a/b")); + assert!(!governs(b"a", b"ab")); + assert!(!governs(b"ab", b"a")); + assert!(governs(b"a/b", b"a/b/c")); + assert!(!governs(b"a/b", b"a/bc")); + } + + #[test] + fn keys_are_stable_and_salted_traces_differ() { + let path = NormalizedPath::new("/a/b").unwrap(); + assert_eq!(path.key(), path_key(b"a/b")); + let stack = LayerStackId::from_authority([7; 16]); + let first = trace_key(&[1; 32], stack, path.as_bytes()); + let second = trace_key(&[2; 32], stack, path.as_bytes()); + assert_ne!(first, second); + } +} diff --git a/core/crates/layerfs-history/src/contract/records.rs b/core/crates/layerfs-history/src/contract/records.rs index 5027cc8d47..e90c475720 100644 --- a/core/crates/layerfs-history/src/contract/records.rs +++ b/core/crates/layerfs-history/src/contract/records.rs @@ -463,11 +463,10 @@ pub enum CommitOutcome { #[derive(Clone, Debug, Eq, PartialEq)] pub enum AddLayerOutcome { /// A new immutable Layer was inserted on the stack head and the stack - /// advanced. `add_layer` itself is overwrite-only (the SDK's - /// `branch.publish` refuses a stale base before calling it, unless - /// `force`): the Layer's `overwrote_count` counts the stack's Layers - /// since the Branch's base that the published Commit does not contain; - /// they stay in history and `HistoryCatalog::overwritten` lists them. + /// advanced. Publication is overwrite-only: the Layer's + /// `overwrote_count` counts the stack's Layers since the Branch's base + /// that the published Commit does not contain; they stay in history and + /// `HistoryCatalog::overwritten` lists them. Added { /// The new Layer. layer: LayerRecord, @@ -637,3 +636,273 @@ pub struct InitStatistics { /// Init's wall time in milliseconds, up to the first Branch. pub millis: u64, } + +/// One `path_removed` marker as stored for a project. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct PathRemovalRecord { + /// The normalized relative path the marker names. + pub path: Vec, + /// The Store high-water when the marker last advanced. + pub frontier_serial: u64, + /// When the marker last advanced, in milliseconds since the epoch. + pub removed_ms: i64, +} + +/// Whether a `project.remove_file` call advanced the marker or found it current. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum PathRemovalKind { + /// The marker advanced to a new frontier. + Removed, + /// No project node is above the marker's frontier; the stored values are returned. + UpToDate, +} + +/// One `project.remove_file` request: the project, the normalized path and the +/// time the caller observed. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct PathRemovalRequest { + /// Project (LayerStack) the path is removed in. + pub stack: LayerStackId, + /// The normalized relative path bytes; `BLAKE3` keys the marker. + pub path: Vec, + /// When the call was made, in milliseconds since the epoch. + pub removed_ms: i64, +} + +/// One `project.remove_file` result: the stored marker values. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct PathRemovalOutcome { + /// Whether the call advanced the marker or found it current. + pub kind: PathRemovalKind, + /// Project (LayerStack) the marker belongs to. + pub stack: LayerStackId, + /// The stored normalized relative path. + pub path: Vec, + /// The stored frontier serial. + pub frontier_serial: u64, + /// The stored `removed_ms`. + pub removed_ms: i64, +} + +/// One kind of operation admitted through the Store's `gc_intent` table (§5.1). +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum GcIntentKind { + /// A mounted or mounting Workspace. + Mount, + /// A project Init. + Init, + /// A Branch merge. + Merge, + /// A soft removal (`branch.remove`, `project.delete`, `project.remove_file`). + Removal, + /// A Store compaction. + Compaction, +} + +impl GcIntentKind { + /// The `gc_intent.kind` text. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Mount => "mount", + Self::Init => "init", + Self::Merge => "merge", + Self::Removal => "removal", + Self::Compaction => "compaction", + } + } + + /// True when the operation shares its scopes instead of excluding them. + #[must_use] + pub const fn shared(self) -> bool { + matches!(self, Self::Mount | Self::Init | Self::Merge) + } +} + +/// The scope an admission intent is taken at. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum GcScopeKind { + /// The whole Store (compaction). + Store, + /// One project (Init, merge, `project.delete`, `remove_file`). + Project, + /// One Branch (mount, `branch.remove`). + Branch, +} + +impl GcScopeKind { + /// The `gc_intent.scope_kind` text. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Store => "store", + Self::Project => "project", + Self::Branch => "branch", + } + } +} + +/// One durable admission row (§5.1), or the operation row a caller writes +/// before touching a Store. Ids are typed per kind: 32 bytes for the Store +/// catalog, 17 for a project or Branch. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct GcIntent { + /// 16-byte operation identity (`gc_intent.op_id`). + pub op_id: [u8; 16], + /// Operation kind. + pub kind: GcIntentKind, + /// Scope the intent is recorded at. + pub scope_kind: GcScopeKind, + /// Typed scope identity. + pub scope_id: Vec, + /// The owning project identity, when the scope is a Branch. It is not a + /// stored column: it lets the PostgreSQL key derivation name the project + /// scope of a Branch intent. + pub project_id: Option>, + /// Mounting Workspace identity, 32 bytes. + pub workspace: Option<[u8; 32]>, + /// Sandbox name, when the caller knows one. + pub sandbox: Option, + /// Machine name, when the caller knows one. + pub machine: Option, + /// Project name, when the caller knows it. + pub project: Option, + /// Branch name, when the caller knows it. + pub branch: Option, + /// Owning runtime token. + pub owner_runtime: Option, + /// Owning boot token; `UNIQUE(scope_kind, scope_id, owner_boot)`. + pub owner_boot: Option, + /// Operation phase, for a holder report. + pub phase: Option, + /// True when the owner is uncertain and only `Unresolved` may report it. + pub uncertain: bool, +} + +impl GcIntent { + /// A shared (`mount`, `init`, `merge`) intent at one scope. + #[must_use] + pub fn shared( + op_id: [u8; 16], + kind: GcIntentKind, + scope_kind: GcScopeKind, + scope_id: impl Into>, + ) -> Self { + Self::new(op_id, kind, scope_kind, scope_id) + } + + /// An exclusive (`removal`, `compaction`) intent at one scope. + #[must_use] + pub fn operation( + op_id: [u8; 16], + kind: GcIntentKind, + scope_kind: GcScopeKind, + scope_id: impl Into>, + ) -> Self { + Self::new(op_id, kind, scope_kind, scope_id) + } + + fn new( + op_id: [u8; 16], + kind: GcIntentKind, + scope_kind: GcScopeKind, + scope_id: impl Into>, + ) -> Self { + Self { + op_id, + kind, + scope_kind, + scope_id: scope_id.into(), + project_id: None, + workspace: None, + sandbox: None, + machine: None, + project: None, + branch: None, + owner_runtime: None, + owner_boot: None, + phase: None, + uncertain: false, + } + } + + /// Records the owning project identity of a Branch-scoped intent. + #[must_use] + pub fn in_project(mut self, project: impl Into>) -> Self { + self.project_id = Some(project.into()); + self + } + + /// Fills the project and Branch names a holder report shows. + #[must_use] + pub fn named(mut self, project: Option<&str>, branch: Option<&str>) -> Self { + self.project = project.map(str::to_owned); + self.branch = branch.map(str::to_owned); + self + } + + /// Fills the Workspace, Sandbox and machine a holder report shows. + #[must_use] + pub fn placed( + mut self, + workspace: Option<[u8; 32]>, + sandbox: Option<&str>, + machine: Option<&str>, + ) -> Self { + self.workspace = workspace; + self.sandbox = sandbox.map(str::to_owned); + self.machine = machine.map(str::to_owned); + self + } + + /// Fills the owner tokens. + #[must_use] + pub fn owned(mut self, runtime: Option<&str>, boot: Option<&str>) -> Self { + self.owner_runtime = runtime.map(str::to_owned); + self.owner_boot = boot.map(str::to_owned); + self + } + + /// Records the phase a holder report shows. + #[must_use] + pub fn with_phase(mut self, phase: Option<&str>) -> Self { + self.phase = phase.map(str::to_owned); + self + } + + /// Marks the owner uncertain: only `Unresolved` may report it. + #[must_use] + pub fn uncertain(mut self) -> Self { + self.uncertain = true; + self + } +} + +/// The outcome of the Store side of `project.delete`: a marker already there, +/// a marker written now, or neither a live stack nor a marker. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum GcDeletion { + /// The marker was already recorded; its `deleted_ms` is reused. + Retired { + /// The `deleted_ms` the marker holds. + deleted_ms: i64, + }, + /// A live stack was marked with the caller's `deleted_ms`. + Marked { + /// The `deleted_ms` written. + deleted_ms: i64, + }, + /// Neither a live stack nor a marker: the caller removes its stale entry. + Absent, +} + +impl GcDeletion { + /// The `deleted_ms` a `project.delete` result reports. + #[must_use] + pub fn deleted_ms(self, requested: i64) -> i64 { + match self { + Self::Retired { deleted_ms } | Self::Marked { deleted_ms } => deleted_ms, + Self::Absent => requested, + } + } +} diff --git a/core/crates/layerfs-history/src/lib.rs b/core/crates/layerfs-history/src/lib.rs index 0134a0e65d..1f9100c1bd 100644 --- a/core/crates/layerfs-history/src/lib.rs +++ b/core/crates/layerfs-history/src/lib.rs @@ -21,19 +21,22 @@ mod contract; pub use contract::catalog; pub use contract::error; pub use contract::identity; +pub use contract::path; pub use contract::query; pub use contract::records; pub use catalog::{HistoryCatalog, HistoryCatalogConfig, NamedSnapshot, PublishLane}; -pub use error::{HistoryError, HistoryResult}; +pub use error::{GcHolder, HistoryError, HistoryResult, MountHolders, OpConflict}; pub use identity::{ BranchId, CatalogId, CommitId, HistoryName, LayerId, LayerStackId, NodeId, WorkspaceId, }; pub use records::{ AddLayerOutcome, AddLayerRequest, BindingHint, BranchMergeRequest, BranchRecord, BranchSnapshot, CommitHistoryRequest, CommitMeta, CommitOutcome, CommitRecord, CommitRequest, - CommitStatistics, CommitVia, FileDigest, ForkRequest, ForkSource, InitStatistics, - LayerHistoryRequest, LayerRecord, LayerStackRecord, MergeCommit, MergeHead, MergeSide, Page, - PageResult, RecordKind, Reservation, ReserveRequest, StackInitialization, StoreStatistics, - FILE_DIGEST_WINDOW, MAXIMUM_MESSAGE_BYTES, MAXIMUM_PAGE_RECORDS, + CommitStatistics, CommitVia, FileDigest, ForkRequest, ForkSource, GcDeletion, GcIntent, + GcIntentKind, GcScopeKind, InitStatistics, LayerHistoryRequest, LayerRecord, LayerStackRecord, + MergeCommit, MergeHead, MergeSide, Page, PageResult, PathRemovalKind, PathRemovalOutcome, + PathRemovalRecord, PathRemovalRequest, RecordKind, Reservation, ReserveRequest, + StackInitialization, StoreStatistics, FILE_DIGEST_WINDOW, MAXIMUM_MESSAGE_BYTES, + MAXIMUM_PAGE_RECORDS, }; diff --git a/core/crates/layerfs-history/tests/contract_constructors.rs b/core/crates/layerfs-history/tests/contract_constructors.rs new file mode 100644 index 0000000000..94625590a7 --- /dev/null +++ b/core/crates/layerfs-history/tests/contract_constructors.rs @@ -0,0 +1,70 @@ +//! A provider outside this crate builds each refusal context through the +//! public constructors, and readers still reach the public fields. + +use layerfs_history::error::{ + HolderKind, HolderState, NameHolder, NameSource, NameTakenState, RemovedPath, RemovedState, +}; +use layerfs_history::HistoryError; + +#[test] +fn name_taken_context_is_constructed_and_read() { + let holder = NameHolder::new(HolderKind::Branch, "feature", HolderState::Retired); + assert_eq!(holder.kind, HolderKind::Branch); + assert_eq!(holder.name, "feature"); + assert_eq!(holder.state, HolderState::Retired); + + let state = NameTakenState::new(holder, NameSource::Home); + assert_eq!(state.source, NameSource::Home); + assert_eq!(state.holder.name, "feature"); + + let error = HistoryError::NameTaken(Box::new(state)); + match error.cause() { + HistoryError::NameTaken(state) => { + assert_eq!(state.holder.kind, HolderKind::Branch); + assert_eq!(state.holder.state, HolderState::Retired); + assert_eq!(state.source, NameSource::Home); + } + other => panic!("expected NameTaken, got {other:?}"), + } +} + +#[test] +fn removed_context_is_constructed_and_read() { + let path = RemovedPath::new("/gone.txt", 42); + assert_eq!(path.path, "/gone.txt"); + assert_eq!(path.frontier_serial, 42); + + let state = RemovedState::new(vec![path, RemovedPath::new("/other.txt", 7)]); + assert_eq!(state.paths.len(), 2); + assert_eq!(state.paths[1].path, "/other.txt"); + + let error = HistoryError::Removed(Box::new(state)); + match error.cause() { + HistoryError::Removed(state) => { + assert_eq!(state.paths[0].path, "/gone.txt"); + assert_eq!(state.paths[0].frontier_serial, 42); + assert_eq!(state.paths[1].frontier_serial, 7); + } + other => panic!("expected Removed, got {other:?}"), + } +} + +#[test] +fn every_holder_kind_and_state_builds() { + for kind in [HolderKind::Branch, HolderKind::Project] { + for state in [ + HolderState::Live, + HolderState::Retired, + HolderState::Deleted, + ] { + let holder = NameHolder::new(kind, "name", state); + assert_eq!(holder.kind, kind); + assert_eq!(holder.state, state); + } + } + for source in [NameSource::Store, NameSource::Home] { + let holder = NameHolder::new(HolderKind::Project, "project", HolderState::Live); + let state = NameTakenState::new(holder, source); + assert_eq!(state.source, source); + } +} diff --git a/core/crates/layerfs-storage/src/encoding/delta/select.rs b/core/crates/layerfs-storage/src/encoding/delta/select.rs index c293559691..65cadeb583 100644 --- a/core/crates/layerfs-storage/src/encoding/delta/select.rs +++ b/core/crates/layerfs-storage/src/encoding/delta/select.rs @@ -60,6 +60,9 @@ pub struct DeltaCounters { pub absent_candidates: u64, /// Candidates present but ineligible under the depth or role policy. pub ineligible_candidates: u64, + /// Candidates whose stored chain names the object being stored: a + /// concurrent writer's copy depends on it. Stored FULL by policy. + pub cyclic_candidates: u64, /// Candidates refused because the resulting chain would exceed its budget. pub work_exceeded: u64, /// Candidates whose chain already reached the role's depth cap. Their chain @@ -101,6 +104,7 @@ impl DeltaCounters { (&mut self.no_candidate, other.no_candidate), (&mut self.absent_candidates, other.absent_candidates), (&mut self.ineligible_candidates, other.ineligible_candidates), + (&mut self.cyclic_candidates, other.cyclic_candidates), (&mut self.work_exceeded, other.work_exceeded), (&mut self.depth_capped, other.depth_capped), (&mut self.rebased, other.rebased), @@ -154,6 +158,18 @@ pub struct ChainCost { pub encoded: u64, } +/// How a walk of one stored dependency chain ended. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum ChainWalk { + /// The object is stored and its chain costs this. + Cost(ChainCost), + /// The object, or a base it names, is not stored. + Absent, + /// The chain names the object the caller is storing: that object cannot be + /// its base without closing a dependency cycle. + Cycle, +} + /// Bounded per-save cache of dependency depths and chain costs. #[derive(Debug, Default)] pub struct DepthCache { @@ -205,8 +221,59 @@ impl DepthCache { connection: &dyn Source, workspace: &mut DecompressionWorkspace, id: ObjectId, - mut base_of: F, + base_of: F, ) -> StorageResult> + where + F: FnMut( + &dyn Source, + &mut DecompressionWorkspace, + &ObjectLocation, + ) -> StorageResult, + { + match self.walk(connection, workspace, id, None, base_of)? { + ChainWalk::Cost(cost) => Ok(Some(cost)), + ChainWalk::Absent => Ok(None), + // Without an object to avoid, a walk that names its own start is a + // cycle already stored. + ChainWalk::Cycle => Err(StorageError::Integrity("dependency cycle")), + } + } + + /// `id`'s chain cost, or [`ChainWalk::Cycle`] when the chain names `avoid` + /// (the object the caller is about to store against it). + /// + /// Two writers can store the same new object at once. One writer's copy can + /// name the other writer's object as its base, so the candidate a selection + /// is about to use can name the object that selection is storing. Storing + /// that candidate as the new object's base would close a dependency cycle, + /// so the caller stores the object whole instead. + pub fn cost_avoiding( + &mut self, + connection: &dyn Source, + workspace: &mut DecompressionWorkspace, + id: ObjectId, + avoid: ObjectId, + base_of: F, + ) -> StorageResult + where + F: FnMut( + &dyn Source, + &mut DecompressionWorkspace, + &ObjectLocation, + ) -> StorageResult, + { + self.walk(connection, workspace, id, Some(avoid), base_of) + } + + /// One iterative, bounded walk from `id` to the root of its stored chain. + fn walk( + &mut self, + connection: &dyn Source, + workspace: &mut DecompressionWorkspace, + id: ObjectId, + avoid: Option, + mut base_of: F, + ) -> StorageResult where F: FnMut( &dyn Source, @@ -226,9 +293,18 @@ impl DepthCache { if path.iter().any(|(id, _, _)| *id == current) { return Err(StorageError::Integrity("dependency cycle")); } - if let Some(cost) = self.costs.get(¤t).copied() { - cached_edge = 1; - break cost; + if Some(current) == avoid { + return Ok(ChainWalk::Cycle); + } + // An avoid walk reads the chain from storage: a cost cached + // earlier in this Save can come from a plan the first-wins + // registration later replaced, and only the stored edges decide + // whether this candidate names the object being stored. + if avoid.is_none() { + if let Some(cost) = self.costs.get(¤t).copied() { + cached_edge = 1; + break cost; + } } // Past the first element `current` is a base a stored record names. let location = if path.is_empty() { @@ -237,7 +313,7 @@ impl DepthCache { connection.base_location(current, i64::MAX)? }; let Some(location) = location else { - return Ok(None); + return Ok(ChainWalk::Absent); }; path.push((current, location.canonical_length as u64, 0)); // A chain of depth `d` has `d + 1` records, and the deepest supported @@ -252,6 +328,9 @@ impl DepthCache { last.2 = edge.width; } match edge.base { + // The record names the object being stored: its own copy may not + // be published yet, but the edge is already a cycle-to-be. + Some(base) if Some(base) == avoid => return Ok(ChainWalk::Cycle), Some(base) => current = base, None => { break ChainCost { @@ -291,7 +370,7 @@ impl DepthCache { self.record(*id, level); result = level; } - Ok(Some(result)) + Ok(ChainWalk::Cost(result)) } /// Records the depth and chain cost of one identity. @@ -542,13 +621,13 @@ pub fn select( input.counters.note_depth(role, 0); return Ok(full); } - Some(id) => match probe(input, id, role)? { - true => Some(id), + Some(candidate) => match probe(input, candidate, role, id)? { + true => Some(candidate), false => None, }, None => None, }, - _ => match acquisition(input, role, advisory)? { + _ => match acquisition(input, role, advisory, id)? { Some(id) => Some(id), // A payload no PREFIX record can beat asks the ring nothing: the // answer is FULL, as a trial would find (`prefix_cannot_win`). @@ -558,10 +637,10 @@ pub fn select( input.candidates.ensure_loaded(input.connection)?; let found = input.candidates.propose(id, &sig); match found { - Some(id) => match probe(input, id, role)? { + Some(proposal) => match probe(input, proposal, role, id)? { true => { - from_ring = Some((id, sig)); - Some(id) + from_ring = Some((proposal, sig)); + Some(proposal) } false => None, }, @@ -589,9 +668,21 @@ pub fn select( // A chunk's trial outcome is noted against the base it was offered, which // re-basing may replace (`LosingBases`). let offered = (role == ObjectRole::Chunk).then_some(base_id); - let base_cost = chain_cost(input, base_id)?; + let Some(base_cost) = chain_cost(input, base_id, id)? else { + // The candidate's chain names this object: a concurrent writer already + // stored a copy that depends on it, so using it as a base would close a + // cycle. Store FULL by policy (the concurrent copy keeps the object). + input.counters.cyclic_candidates = input.counters.cyclic_candidates.saturating_add(1); + if lane == PackLane::WholeFile { + let sig = prehashed.unwrap_or_else(|| signature(raw)); + input.candidates.ensure_loaded(input.connection)?; + input.candidates.insert(id, sig); + } + input.counters.note_depth(role, 0); + return Ok(full); + }; let Some((base_id, base_cost)) = - trial_base(input, base_id, base_cost, canonical.len() as u64, depth_cap)? + trial_base(input, base_id, base_cost, canonical.len() as u64, depth_cap, id)? else { return refused_by_budget(input, id, role, raw, prehashed, full); }; @@ -705,18 +796,29 @@ fn refused_by_budget( Ok(full) } -/// Depth and work cost of a stored candidate's chain, from its records' sizes. -fn chain_cost(input: &mut SelectInput<'_>, id: ObjectId) -> StorageResult { +/// Depth and work cost of a stored candidate's chain, from its records' sizes; +/// `None` when the chain names `avoid`, the object being stored. +fn chain_cost( + input: &mut SelectInput<'_>, + id: ObjectId, + avoid: ObjectId, +) -> StorageResult> { let mut bases = ChainBases::new(input.packs); let started = Instant::now(); - let cost = input.depths.cost_of( + let cost = input.depths.cost_avoiding( input.connection, input.decode, id, + avoid, |connection, workspace, location| bases.edge(connection, workspace, location), ); SaveProfile::charge(&mut input.profile.resolve.cost_ns, started); - cost?.ok_or(StorageError::Integrity("selected base is not stored")) + match cost? { + ChainWalk::Cost(cost) => Ok(Some(cost)), + // `probe` admitted the candidate as stored; a dangling base is corrupt. + ChainWalk::Absent => Err(StorageError::Integrity("selected base is not stored")), + ChainWalk::Cycle => Ok(None), + } } /// The base the one trial runs against, and its chain cost (#89). @@ -734,6 +836,7 @@ fn trial_base( cost: ChainCost, target: u64, depth_cap: u8, + avoid: ObjectId, ) -> StorageResult> { let capped = cost.depth >= depth_cap; if capped { @@ -748,7 +851,9 @@ fn trial_base( let root = chain_root(input.connection, input.packs, input.decode, id); SaveProfile::charge(&mut input.profile.resolve.cost_ns, started); let root = root?.object_id; - let root_cost = chain_cost(input, root)?; + let Some(root_cost) = chain_cost(input, root, avoid)? else { + return Ok(None); + }; if root_cost.depth >= depth_cap { return Ok(None); } @@ -804,8 +909,13 @@ fn note_stored(profile: &mut SaveProfile, record: &EncodedRecord) { /// Every rejected candidate is counted, whether it was absent or present but /// ineligible; neither ever becomes a failure of the operation. A candidate at /// the depth cap is eligible: selection re-bases it onto its chain root (#89). -fn probe(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> StorageResult { - if eligible(input, id, role)? { +fn probe( + input: &mut SelectInput<'_>, + id: ObjectId, + role: ObjectRole, + avoid: ObjectId, +) -> StorageResult { + if eligible(input, id, role, avoid)? { return Ok(true); } input.counters.ineligible_candidates = input.counters.ineligible_candidates.saturating_add(1); @@ -816,16 +926,22 @@ fn acquisition( input: &mut SelectInput<'_>, role: ObjectRole, advisory: &[ObjectId], + avoid: ObjectId, ) -> StorageResult> { for id in advisory { - if probe(input, *id, role)? { + if probe(input, *id, role, avoid)? { return Ok(Some(*id)); } } Ok(None) } -fn eligible(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> StorageResult { +fn eligible( + input: &mut SelectInput<'_>, + id: ObjectId, + role: ObjectRole, + avoid: ObjectId, +) -> StorageResult { let Some(location) = input.connection.location(id, i64::MAX)? else { input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); return Ok(false); @@ -835,18 +951,25 @@ fn eligible(input: &mut SelectInput<'_>, id: ObjectId, role: ObjectRole) -> Stor } let mut bases = ChainBases::new(input.packs); let started = Instant::now(); - let depth = input.depths.depth_of( + let walk = input.depths.cost_avoiding( input.connection, input.decode, id, + avoid, |connection, workspace, location| bases.edge(connection, workspace, location), ); SaveProfile::charge(&mut input.profile.resolve.eligible_ns, started); - if depth?.is_none() { - input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); - return Ok(false); + match walk? { + ChainWalk::Cost(_) => Ok(true), + ChainWalk::Absent => { + input.counters.absent_candidates = input.counters.absent_candidates.saturating_add(1); + Ok(false) + } + ChainWalk::Cycle => { + input.counters.cyclic_candidates = input.counters.cyclic_candidates.saturating_add(1); + Ok(false) + } } - Ok(true) } fn acquire(input: &mut SelectInput<'_>, id: ObjectId) -> StorageResult> { diff --git a/core/crates/layerfs-storage/src/save/pooled.rs b/core/crates/layerfs-storage/src/save/pooled.rs index f5b01ec28a..36a86ae156 100644 --- a/core/crates/layerfs-storage/src/save/pooled.rs +++ b/core/crates/layerfs-storage/src/save/pooled.rs @@ -9,6 +9,7 @@ use super::{source::WaveSource, state::State}; use crate::{ encoding::{ + delta::select::ChainWalk, pool::{delta, leaf}, EncodedRecord, }, @@ -57,7 +58,7 @@ impl State<'_> { ) -> StorageResult { let input = PoolingLeaf::decode(object.canonical())?; let mut known = BTreeMap::<[u8; INODE_VALUE_BYTES], u32>::new(); - let bases = self.pooled_bases(advisory, &mut known)?; + let bases = self.pooled_bases(object.id(), advisory, &mut known)?; // Values no base holds may still be ones this Save already assigned, // which is the common case while a whole tree is first saved. let mut candidates = BTreeSet::new(); @@ -180,6 +181,7 @@ impl State<'_> { /// another delta still gives its rows their ordinals. fn pooled_bases( &mut self, + target: ObjectId, advisory: &[ObjectId], known: &mut BTreeMap<[u8; INODE_VALUE_BYTES], u32>, ) -> StorageResult> { @@ -201,10 +203,11 @@ impl State<'_> { let reader = &mut self.pool; let groups = &mut self.groups; let packs = &mut self.packs; - let Some(cost) = self.depths.cost_of( + let walk = self.depths.cost_avoiding( &source, &mut self.decode, *id, + target, |source, workspace, location| { // The pool reader keeps the encoded account of a pooled chain // (`chain_encoded` below), so the walk measures no width. @@ -220,8 +223,10 @@ impl State<'_> { ) .map(|base| crate::encoding::delta::read::ChainEdge { base, width: 0 }) }, - )? - else { + )?; + let ChainWalk::Cost(cost) = walk else { + // A base whose chain names this leaf would close a cycle; an + // absent or dangling one cannot carry it. continue; }; let (body, canonical) = self.pool.leaf_parts_with_caches( diff --git a/core/docs/issues/project-41/LayerFS-GC-spec.md b/core/docs/issues/project-41/LayerFS-GC-spec.md index e54ced2101..1a8baa36cd 100644 --- a/core/docs/issues/project-41/LayerFS-GC-spec.md +++ b/core/docs/issues/project-41/LayerFS-GC-spec.md @@ -1,26 +1,36 @@ # LayerFS garbage collection: soft removal and Store compaction -> **Status:** Proposal; target LayerFS 2.0.0; not a released contract. +> **Status:** **Frozen for layerfs-project#41 (LayerFS 2.0.0) on 2026-11-15**, approved by the owner on layerfs-project#42. An amendment needs a new #42 decision entry. +> +> **Baseline.** Commit `ed14ed53b` (LayerFS project main layer +> `32770a67…`) is the frozen **2.0 GC implementation baseline**. Implementation +> starts here; residual review items are tracked as implementation/acceptance +> gaps on layerfs-project#41, not as contract changes. > **Authority.** This is the only GC design document in the tree. It replaces the > six-file set merged by #658 (removed by #671; last text in the #677 branch). -> The contract it states is the frozen set of layerfs-project#42 (items 1–13, -> 2026-11-13) as amended by #42 items 14–26 (2026-11-14) and 27–44 -> (2026-11-15, implementation choices). Where this file and an older document -> disagree, this file wins; a change to a contract sentence needs a new +> The contract it states is the frozen set of layerfs-project#42: S1–S11 +> and items 1–42 (2026-11-13 to 2026-11-15). Items 43–44 are recorded on +> layerfs-project#42 and are not contract text. Where this file and an older +> document disagree, this file wins; a change to a contract sentence needs a new > decision entry on #42 first. > +> **Sign-off.** S1–S11, items 1–42 and the amendments below were approved by +> the owner on layerfs-project#42; this file is the frozen text. The decision +> table indexes every decision that carries contract text here; the complete +> log is layerfs-project#42. +> > **Scope.** layerfs-project#41 and its sub-issues #42–#52. The durability > profile (#155 §7) is outside this contract (#42 item 26). GC is developed > and measured under the Disposable profile (#42 item 42). > > **Source.** Code references are to `layerfs_v2_0_0` at `e8fa0a7e00`; those -> added by items 27–44 were checked at `8cfb6e2734`. +> added by items 27–42 were checked at `8cfb6e2734`. ## 1. Requirements (owner policy, #41) -- Four operations, on SQLite and PostgreSQL: `branch.remove(name)`, - `project.delete(name)`, `project.remove_file(project, path)` and +- Four operations, on SQLite and PostgreSQL: `branch.remove(project, branch)`, + `project.delete(project)`, `project.remove_file(project, path)` and `store.compact(name)`. Each takes only a resource identifier: no confirm, force, dry-run, stop-Sandboxes, Store, URL or volume option. - The three removals are logical. They change visibility and retention and @@ -44,15 +54,21 @@ |---|---|---| | S1 | Reachability is computed per Store, over every project in it | §6 | | S2 | Exclusion reuses the Store lock, lease and op record; PostgreSQL adds advisory locks (#42 items 20, 33, 34) | §5 | +| S3 | Superseded by S5/§7–§8: the rebuild is its own module, not the transfer `Stage`; no transfer-intent sidecar (the rebuild artifacts of §7/§9 are separate) | §7, §8 | | S4 | No object age; collection depends only on reachability | §6 | | S5 | The unit that frees bytes is the pack. A rebuild copies only retained rows into a fresh Store; a published `pack` row is never updated or deleted in place | §7, §8 | | S6 | A SQLite Store compacts on the machine where it lives (`place::plan`, `control/crates/layerfs-store/src/place.rs:40-49`) | §7 | +| S7 | Report the three byte definitions, peak temporary space and residue; estimates carry `estimate: true`; a capped report names its cap | §11 | +| S8 | One fence: `(dev, ino)` per transaction on SQLite, the incarnation join on PostgreSQL; both `StaleStore` | §10 | +| S9 | Install is binary; `live_heads_digest` matches before and after | §7, §8 | | S10 | Logical removal never rewrites history or changes an ID | §4 | -| S11 | Compaction is exclusive over the whole Store; reads are unavailable during it | §5 | +| S11 | Compaction is exclusive against mounts and long-lived users; on PostgreSQL one-shot reads/writes may run until the swap, and a write that spans it makes the swap abandon; SQLite excludes all readers | §5 | +| 6 | Marker and position tables are added to 2.0 Stores at open by an additive step; 1.0 Stores are converted offline | §4.1 | | 7 | Removal markers live in marker tables; `branch` and `layer_stack` stay append-only | §4 | -| 14 | Compaction collects history rows no retained root reaches; Commits of a removed Branch that nothing retains become `NotFound` | §6.1 | +| 12a | PostgreSQL advisory key is `(kind, id)` over the Store, project and Branch scopes | §5.2 | +| 14 | Compaction collects history rows no retained root reaches; Commits of a removed Branch that nothing retains become `NoSuchCommit` | §6.1 | | 15 | A name held by a removed Branch or deleted project returns `NameTaken` until compaction removes the row; then it is free. `NameRetired` is not added | §4.4 | -| 16 | `remove_file` hides a path across the project's history at once and lets compaction reclaim what only that path reached; reads through it return `Removed` (details: item 35) | §4.3, §6.2 | +| 16 | `remove_file` hides a path across the project's history at once; 2.0 is visibility-only and frees no bytes for it (details: item 35) | §4.3, §6.2 | | 17 | `store.compact` has two paths, `none` and `rebuild`; there is no light path. C3 has no caller in 2.0 | §3 | | 18 | A leftover is judged by the Store generation; no `OrphanArtifact`, no leftover cap | §9 | | 19 | API codes follow #41 (`MountsActive`, `Busy`); one `StaleStore` for both backends | §10 | @@ -60,6 +76,7 @@ | 21 | PostgreSQL compaction builds in batches, then swaps two tables in one short transaction | §8 | | 22 | SQLite compaction is its own module: the walk is fused with the copy, the visited set is a temp-file table, verification is cheap by default | §6.3, §7 | | 23 | Removed: the `pinned` set, the per-transaction SQLite generation check, the capacity pre-check, the extra report fields | §6, §7, §11 | +| 26 | The durability profile is outside this contract | header | | 27 | One visit level: anything reached by a logical or base edge is kept with all its references | §6.2 | | 28 | `merged_from_id` and `displaced_id` are history edges | §6.1 | | 29 | A retired Branch is collected as a unit; the history closure is a fixpoint | §6.1 | @@ -68,13 +85,14 @@ | 32 | `project.remove` is retired; compaction reuses its removal statements | §4, §7, §8 | | 33 | Admission at project and Branch scope (project op, intent record before bind, PostgreSQL keys at three scopes) | §5 | | 34 | PostgreSQL presence locks only on long-lived sessions; SDK calls keep working through transaction poolers | §5.2 | -| 35 | `remove_file` marker with a frontier; whiteout at mount; object-ID reads not path-aware; purge best effort | §4.3 | +| 35 | `remove_file` marker with a Store history-serial frontier; every tree-building operation materializes the whiteout, not only mounts; a republished Layer keeps its source Commit's serial; object-ID reads not path-aware; 2.0 frees no bytes (visibility only) | §4.3 | | 36 | No format change for the PostgreSQL mark until #52 measures it | §6.2 | | 37 | All `inode_value_block` rows are kept in 2.0 | §6.4 | | 38 | The rebuild clears `binding_hint_block` | §6.4 | | 39 | All four calls are admin-profile and refused under a folder scope | §10 | | 40 | Compaction writes its phase into the op; `store.status` shows it | §11 | | 41 | A started rebuild completes | §3 | +| 42 | GC is developed and measured under the Disposable profile | header | Out of this release: object age (Q3), repacking partly dead packs (reported, not performed), in-place deletion of packs on either backend, a read-available @@ -87,11 +105,17 @@ compaction window (A'), pruning (#46). | `none` | Bytes in wholly dead packs are below **10%** of the Store's bytes | Mark only; nothing is written; the report gives the reclaimable bytes | unchanged | | `rebuild` | 10% or more | SQLite §7, PostgreSQL §8 | `G → G+1` | -The 10% value is a starting point, set after the first measurement (#52). +The numerator is `COALESCE(SUM(pack.length), 0)` over wholly dead packs and +the denominator `COALESCE(SUM(pack.length), 0)` over all packs, on both +backends; the test is `rebuild iff total > 0 AND dead * 10 >= total` (no +truncating integer division). The 10% value is frozen at 10%; a change needs a +#42 entry. #52 measures it. A Store with no packs, or packs summing to 0, is +`none` with `deadBytesBound = 0` and `zeroReason: "empty-store"`. Below it a rebuild would copy at least nine live bytes for each byte freed. The choice is made on the bound known after the metadata walk; a rebuild that has started completes even if the refined share falls below 10%, and the -report gives both numbers (#42 item 41). +report gives both numbers as `deadBytesBound` and `deadBytesRefined` (§11; +#42 item 41). There is no path that deletes rows in place: it would free no payload, touch most index pages of the hash-keyed tables and need its own deletion contract. @@ -99,39 +123,120 @@ most index pages of the hash-keyed tables and need its own deletion contract. All three removals write one marker row in one short write transaction. No pack, object, Commit or Layer row changes, and no ID changes. They do not -bump the Store generation. +bump the Store generation, but they do bump the project's `epoch` in +`project_epoch` (§5), which a concurrent writer checks before it commits. | Call | Marker table | Effect | |---|---|---| -| `branch.remove(name)` | `branch_retired(branch_id, removed_ms)` | Hidden from listings and name resolution; fork, merge, publish and mount refused; `main` → `ReservedName` | -| `project.delete(name)` | `layer_stack_retired(layer_stack_id, deleted_ms)` | Project hidden; its home entry is removed; its data stays until compaction; the Store stays addressable | -| `project.remove_file(project, path)` | `path_removed(layer_stack_id, path, frontier, removed_ms)` | §4.3 | +| `branch.remove(project, branch)` | `branch_retired(branch_id BLOB NOT NULL PRIMARY KEY REFERENCES branch(branch_id) ON DELETE CASCADE, removed_ms INTEGER NOT NULL) STRICT` | Hidden from listings and name resolution; fork, merge, publish and mount refused; `main` → `ReservedName` | +| `project.delete(project)` | `layer_stack_retired(layer_stack_id, deleted_ms)` | Project hidden; its home entry is removed; its data stays until compaction; the Store stays addressable | +| `project.remove_file(project, path)` | `path_removed(layer_stack_id BLOB NOT NULL, path_key BLOB/bytea NOT NULL, path BLOB/bytea NOT NULL, frontier_serial INTEGER NOT NULL, removed_ms INTEGER NOT NULL) STRICT`, `PRIMARY KEY(layer_stack_id, path_key)`, `REFERENCES layer_stack ON DELETE CASCADE`; `path_key = BLAKE3(normalized path)` (a 4096-byte `bytea` key cannot fit a PG btree), the stored `path` is compared on collision; `frontier_serial` is the marker frontier (§4.3) | §4.3 | `project.delete` is the only project removal: the hard-deleting -`project.remove` is retired, and compaction reuses its `removal_*` statements -(`engine/crates/layerfs-persistence/src/history/removal.rs`) to drop a deleted -project's history (#42 item 32). +`project.remove` is removed from the call table (an old client that sends it +gets `InvalidInput` "no call named `project.remove`", never a silent hard +delete), and its module is deleted; compaction reuses its `removal_*` +statements (`engine/crates/layerfs-persistence/src/history/removal.rs`) to +drop a deleted project's history (#42 item 32). Tests that call +`project.remove` migrate to `project.delete`. Retirement also covers the +worker op/route for `project.remove`, the remote-SQLite route for +`project.delete`, the legacy own-project identity save (project name == Store +name) before the home entry is removed, the call-count and MCP-profile +generators, and the PostgreSQL path. The worker (the Store's home) is named +`project.delete`; the frame is `{store, stack_id, deleted_ms?}` (the caller +writes `deleted_ms` to the sidecar before the call and resends it on +retries). The worker saves the legacy own-project identity, writes the +marker, removes its own entry and replies +`{kind: "Removed", project, stack_id, deleted_ms}`; the caller removes only +its own entry and echoes `home_entry_removed`. A lost reply is `Unknown`, +keeps the sidecar, and the retry resolves retired/live/absent; the old +`project.remove` worker arm is deleted. + +`project.delete` commits the Store marker first and removes the caller's home +entry after it. The marker is the commit point. If the home removal fails the +call returns success with `home_entry_removed: false` and the stored +`deleted_ms`; a retry from the same home is idempotent: it may read the +retired stack allow-listed, reuses `deleted_ms`, finishes the entry removal +and returns `home_entry_removed: true`. The durable delete intent +`{stack_id, deleted_ms, attempt_ms}` lives outside the removed entry (or the +entry is **not** renamed; one sidecar file at +`/store//delete/.json` with +`{store, project, stack_id, deleted_ms, attempt_ms, state, op_id}` is written +(temp + fsync + rename + dir fsync) after the identity save and before the +marker, with `pending|marked|done` updated atomically and unlinked after the +entry removal. `op_id` is additive (an older sidecar without it is still +valid): it records the project op the admit/mark attempt ran under, so the +retry can settle a lost admit/mark reply instead of leaving it uncertain +(§5.1, §10). The retry +re-reads the Store by the recorded stack id and compares it with the home +record, discarding a mismatch without touching a re-created project's entry; +a retired row reuses `deleted_ms` and finishes the entry; a live row with no +marker redoes the marker with the same `deleted_ms` and does **not** remove +the entry; an absent stack row finishes the entry. It never resolves a name. If the marker fails nothing is +removed. The legacy own-project identity save (project name == Store name) +runs before the marker transaction, is idempotent, and a failure refuses with +nothing removed. A different home's stale entry is not rewritten; the +`project.list`/`project.get` intersection in §4.2 hides it. ### 4.1 Representation -The marker tables are added at open by an additive step under the current -schema identity (#42 item 6). On SQLite this is one more `add_*` step, as -`add_file_digests` was; the existing steps, the table list and +The marker and intent tables are added at open by an additive step under +the current schema identity (#42 item 6). On SQLite this is one more `add_*` +step, as `add_file_digests` was; the existing steps, the table list and `tools/store_blocks.py` are updated with it. PostgreSQL has no such step today (its open check requires the exact table set and recorded definition, `backend/postgresql/schema.rs:158-252`), so new Stores get the tables in `schema.sql` and an additive step at open creates them and rewrites the recorded definition for older Stores (#42 item 31). 1.0 Stores are converted -offline. `branch` and `layer_stack` keep their full unique name indexes. +offline. The same step adds the position state: `history_meta.next_history_serial` +(the next serial to assign; never lowered), a `history_serial` column on +`commit` and `layer` (a Layer that republishes a Commit carries that +Commit's serial; every other Commit and Layer takes the next value in its +creation transaction), `project_epoch(layer_stack_id PRIMARY KEY, epoch)` +(one row created with the project, bumped in the same transaction as every +marker write, copied by a rebuild, collected with the project), and two +admission tables: `gc_intent(...)` (§5.1) and `gc_op(...)`. The same step +adds `store_policy.trace_salt` last, written as 32 random bytes by the +Store-creation INSERT (`randomblob(32)`/OS RNG) and backfilled for existing +rows; `store_policy` copies use an explicit column list. `gc_intent` is +the shared Store-side admission table (created empty, never copied); `gc_op` +is PostgreSQL's single compaction row (created by PG's additive step, +untouched by the swap, cleared on settle) with columns `generation`, +`phase`, `scratch_schema`, `mark_serial`, `mark_pack_id`, `mark_digest`, +`mark_totals`, `mark_stamp` (`MAX(content_signature.stamp)`), `started_ms`, +`dead_canonical`, `dead_stored`, `dead_metadata`, +`dead_logical`, `totals_applied`, `artifact`, `pid`, `backend_start`, +`usename`, `incarnation`. The `mark_*` columns are the first-statement tuple; the raw +head rows are hashed by the client. A GC-only `gc_dead(kind, id)` table (same additive step, never +copied, truncated on settle) carries the full dead set; a single `gc_op` row +cannot. SQLite keeps its phase in the +home/sidecar op and never writes the sealed DB, relying on the deterministic +artifact names for cross-machine recovery. The backfill runs on **every** +Store the step upgrades, including an existing 2.0 Store: Commits first by +`(created_ms, stack, id)`; then per Stack the genesis Layer first, a +republishing Layer takes its source Commit's serial, the rest by +`(source Commit created_ms, stack, id)`; `project_epoch(layer_stack_id, 0)` +for every existing stack; and +`next_history_serial = MAX(existing next_history_serial, +COALESCE(MAX(history_serial), 0) + 1)`; a Store with no stack/history keeps +its existing value. `branch` and `layer_stack` keep +their full unique name indexes. ### 4.2 Visibility filter No views: views count as schema on both backends. Every statement that lists or resolves a Branch or project carries a `NOT EXISTS` filter against the marker tables, and a guard test fails on any statement that reads `branch` or -`layer_stack` without it unless the statement is on an allow-list (the name -check and the fork/merge identity checks read retired rows on purpose). A -statement that bypasses the filter would resurrect a removed Branch. The +`layer_stack` without it unless the statement is on an allow-list: the +name-collision check (it must read the retired holder to return `NameTaken` +with its state), the fork/merge identity checks, compaction's mark/rebuild +statements, the `project.delete` retry, and two named by-id statements: +`branch_branch_by_id_any` (render/identity for `layer.list`/`layer.get`/ +`saved`/operator inspect) and `layerstack_stack_by_id_retired` (the retry's +live/absent read by the caller's recorded stack id). The ordinary +`branch_branch_by_id`/`layerstack_stack_by_id` stay filtered. Every +other statement that reads `branch` or `layer_stack` carries the filter; a new +allow-list entry needs a comment and a test. A statement that bypasses the filter would resurrect a removed Branch. The minimum is the Branch and project listings and name lookups (`branch_snapshot`, `branch_snapshot_named`, `layerstack_stack_by_name`), fork, merge, publish and mount resolution, and the project listing @@ -139,36 +244,137 @@ fork, merge, publish and mount resolution, and the project listing `identity::list_projects` and, since #678, the record rebuild in `backup.restore` (`control/crates/layerfs-store/src/backup/restore.rs`), so an unfiltered listing would write records for deleted projects back into a -home. +home. `project.list` and `project.get` intersect the home entries with this +filtered Store listing before paging: a stale entry (a different home, or a +failed home-entry removal) is absent from `project.list` and answers +`NoSuchProject` from `project.get`. The join is on the stack id recorded in +the home record: `manifest.stack` for a local SQLite record, +`record.stack` for PG/worker records; a missing stack is filled from the +filtered listing by name. The all-Stores listing omits an unreadable Store; +`project.list(store)` propagates `NoSuchStore`/`Busy`/`Unknown`. a Store that cannot be listed is omitted by `project.list` +and returns its own `NoSuchStore`/`Busy` from `project.get`, never the +unfiltered record. A hidden project is `NoSuchProject` for +the four calls, except `project.delete`'s same-home retry, which resolves the +caller's record by stack id and allow-lists its retired stack. ### 4.3 `remove_file` -- The marker names a path in one project and a **frontier**: the stack's - history serial when the marker was written. It applies to the Commits and - Layers at or below the frontier, the same way before and after any - compaction (#42 item 35): - - a read that resolves through the path returns `Removed`; - - a listing omits the entry and says that entries were removed (shape owned - by #47/#51); - - a mount of a Branch whose head is at or below the frontier applies a - whiteout for the path, so the next Commit records a real deletion. -- Commits after the frontier never inherit the path, and creating a file at - the same path later is an ordinary write that stays visible. -- Reads by object ID are not path-aware: they return the bytes until - compaction collects them, then `NotFound`; never different bytes. -- History rows and IDs are unchanged. Because the answer is `Removed` or - `NotFound`, not different bytes, an old ID never silently resolves to - changed contents. -- The call reports no freed bytes; compaction reports what it reclaimed (§6.2). -- The path is scoped to one project. The same bytes reached from another - project, another path, or as a delta base of a live object stay. -- Physical removal is best effort, and the documentation says so: a pack - shared with live objects is not repacked, and below the threshold - compaction writes nothing. A guaranteed purge (a targeted repack) is a - follow-up, not part of 2.0.0. -- Traces record a hash of the path, not the path. -- If #47 cannot deliver the path-aware walk in 2.0.0, the call ships as - visibility only and its documentation says plainly that it frees nothing. +- The marker names a path in one project and a **frontier**: the current + Store high-water, `next_history_serial - 1`, read under the Store write + lane in the same transaction as the marker; a node created concurrently is + ordered by its serial against that value, never by a later read. The first project's genesis Layer takes serial 1, so its first frontier + is 1; a Store with no Stack has none and `remove_file` is `NoSuchProject`. Every + Commit gets the next Store serial; a Layer that republishes a Commit + carries that Commit's serial, so `branch.publish` does not move a tree's + position, and every other Layer gets the next serial. A Commit or Layer is + *at or below* the frontier when its serial is at most the frontier; the + serial also covers Commits on unmerged Branches (#42 item 35). It applies + to the Commits and Layers at or below the frontier, before and after any + compaction: + - a read whose resolved tree actually contains the path (or a hidden + directory ancestor for an existing descendant) returns `Removed`; an + at-or-below node without the entry is `NotFound`/absent, and a + never-existing path hides nothing; + - a listing omits the entry and reports one top-level `removed_count` over + the queried subtree (present at 0, filtered before paging, no page slot or + admission cost); + - a mount of a Branch whose effective tree (its head Commit, else its base + Layer) is at or below the frontier applies a whiteout for the path, so + the next Commit records a real deletion. +- **Every operation that builds a new tree from a node at or below the + frontier materializes the whiteout**: a workspace Commit, a + non-fast-forward `branch.merge`, every one-shot tree creator (`file.write`, + `edit`, `apply`, `rm`, `mkdir`, `mv`, `cp`), and any server-side + construction. This tree/whiteout walk is mandatory in 2.0 and + distinct from the byte-freeing GC walk (§6.2). A fast-forward merge creates + no tree and is covered by the node it points at. `branch.publish` of a + Commit at or below the frontier republishes that tree as a Layer at the + same position: the marker hides the path and a mount of the Branch that + carries it whiteouts, so publish needs no whiteout of its own. A merge that + cannot materialize the whiteout is refused `Removed` with + `detail {paths: [{path, frontier_serial}]}`, listing every unmaterializable + path as a full element, deduplicated and sorted by normalized path bytes. +- A path explicitly re-created after the frontier is not a whiteout: the + marker hides only content inherited from nodes at or below the frontier. + In a merge of a head at or below the frontier with a head whose path was + re-created after it, the re-creation wins; the whiteout removes the + inherited side and suppresses any conflict from that side. An ordinary edit + conflict is reported only when both sides are post-frontier (the marker does + not apply) or on other paths. +- One marker per project and path: a repeat `remove_file` writes the current + Store high-water (`next_history_serial - 1`) as the new frontier, so + everything at or below is hidden again. It is `UpToDate` iff no project + node has a serial greater than **this path's** marker frontier (a missing + marker is -1); a commit in another project changes + `next_history_serial - 1` but neither rewrites the marker nor advances its + frontier. A path that never existed is accepted and + hides nothing. The newest frontier subsumes the older ones. +- Every marker write that advances the frontier bumps the project's `epoch` + in the same transaction; an `UpToDate` reply does not. +- Commits after the frontier never inherit the path; creating a file at the + same path later is an ordinary visible write. +- A path is **hidden at node N** only when the entry exists at N and the + marker's frontier (the maximum over the path and its `/`-boundary + ancestors) is at least N's `history_serial`; a marked-but-absent entry is + absent/`NotFound`, and a marker on a never-existing path hides nothing. +- Reads by object ID are not path-aware: bytes while retained, then + `NotFound` once compaction collects it, never different bytes. +- The result is `{kind: "Removed", project, path, frontier_serial, + removed_ms}` or `{kind: "UpToDate", project, path, frontier_serial, + removed_ms}` (the stored values). A `Removed` refusal always carries the one + detail shape `{paths: [{path, frontier_serial}]}`: one element for + read/stat (the request path with its governing maximum frontier); a merge + lists every unmaterializable path, sorted by normalized path bytes. + `file.read`/`file.stat` + refuse `Removed` with it. `file.list`/`file.glob` omit hidden entries and + report one top-level `removed_count` over the queried subtree (a hidden + target path is `Removed`; a marked-but-absent path is not counted). + `file.diff` has three states per side (visible/hidden/absent); hidden + sides never refuse: left visible + right hidden → `changeKind` `Removed`; + left hidden + right visible → `Added`; both hidden → `Removed` with both + side objects; a hidden side object is + `{removed: true, path, frontier_serial}`. A hidden side beats + `allow_missing`; only a genuinely absent side is `NoSuchPath` (with + `allow_missing: false`). `branch.diff`/`commit.diff` apply the same + per-side rule to their historical trees, so a removed path is absent, not a + spurious change. `file.revision` refuses `Removed` + when the anchor is hidden; otherwise it walks and **stops** at the first + hidden at-or-below version (never skips past it), returning only visible + versions. `file.blame` stops at the hidden version and attributes the + remaining lines at the tip. `file.grep`/`file.blame` omit hidden + hits. `project.export` omits it; `file.cp` from a hidden source and + `file.edit` are `Removed`; `file.mv`/`file.rm` from a hidden path return the + `NotFound`/`NoSuchPath` wire code, not `Removed`, and `file.mv` to a hidden + path is a visible re-creation; `mkdir`/`apply` follow the same + construction rule; a post-frontier write is the visible re-creation. +- The call accepts an absolute POSIX path and converts it to the Store's + normalized relative components (strip one leading `/`; `/a` and `a` are the + same). It refuses `InvalidInput` for empty, `/`, `//a`, `a//b`, `a/`, `./a`, + `a/./b`, `.`/`..` components, `\`, NUL, >4096 bytes or >256 components. A + directory argument hides its subtree only at a `/` boundary + (`p = m OR p begins m ++ b'/'`, computed as bytes in Rust, never `||` or + `LIKE` on a BLOB). A child of a removed **file** is `NotFound`; a read of + an existing descendant under a hidden directory is `Removed` with the + governing maximum frontier over the path and its ancestors (using + `history_serial`); an absent descendant is `NotFound`. An intermediate symlink component is `InvalidInput` (not followed); + a symlink leaf is hidden as an entry. Other hardlink names stay visible and + nothing is freed. +- History rows and IDs are unchanged. The trace key is BLAKE3(per-Store salt, + layer_stack_id, normalized relative path); the salt is a 32-byte + `store_policy.trace_salt` (random per Store, created by the additive step, + backfilled for converted Stores, copied by a rebuild). Every path argument + (`path`, `left_path`, `right_path`, `from_path`, `to_path`) is redacted + per call: the log records the normalized length as ``, never the + text; the daemon (native/worker) or the PG server-side call writes the keyed + hash, and the path argument names (`path`, `left_path`, `right_path`, + `from_path`, `to_path`, `path_prefix`, `pattern`) are in the per-call + redaction set. + Refusal details/messages are not traced; the `Removed` detail echoes the + request path, and raw paths never enter traces. +- The call frees no bytes in 2.0 (visibility only, §6.2); the path is scoped + to one project, so bytes reached elsewhere or as a live delta base stay. +- Physical removal, a path-aware GC walk and a guaranteed purge are follow-ups + that amend this contract before they ship. ### 4.4 Names @@ -177,12 +383,47 @@ home. name is never reused while its old rows exist. So: - A create or fork whose name a live row holds returns `NameTaken` (existing: - `engine/crates/layerfs-store-service/src/history/branch.rs:232,397`). + `engine/crates/layerfs-store-service/src/history/branch.rs:232,397`) with + `detail {holder: {kind: "branch"|"project", name, state: "live"}, + source: "store"}`. The detail rides + `HistoryError::NameTaken(Box)` (Holder/Source defined in + `layerfs-history`, boxed like `HeadMoved`); `lookup.rs` has an explicit arm + that projects `{holder, source}`. `source` is `store` only; a home-record + collision is a service `refuse("NameTaken", ..., {holder, source:"home"})`. + The `branch.rs:230-234,395-399` Null pre-checks are deleted, so every site + reaches the typed error. The branch query joins `branch_retired`; the + project query joins `layer_stack_retired`. - A name held by a removed Branch or deleted project also returns - `NameTaken`, with the holder's state in the detail. + `NameTaken`, with `detail {holder: {kind: "branch"|"project", name, + state: "live"|"retired"|"deleted"}, source: "store"}`; `source: "home"` is + used only for a project's home record. The `BranchId::named` identity check + and the name-collision statements both return this detail; the + `_ => "Failed"` arm is not allowed to swallow them. +- `branch_retired(branch_id BLOB NOT NULL PRIMARY KEY REFERENCES + branch(branch_id) ON DELETE CASCADE, removed_ms INTEGER NOT NULL) STRICT` + (same for `layer_stack_retired`), so a second remove cannot add a second + marker and a + collected base row takes its marker with it, on both backends. The write is + `INSERT ... ON CONFLICT(branch_id) DO NOTHING` with an affected-row check; + only an insert bumps `epoch`. A concurrent remove is `Busy` (phase + `"retire"`, no op), a repeat is `NoSuchBranch`; `project.delete`'s repeat is + the idempotent success in §4. +- `branch.fork` disambiguates by syntax: `main`, a valid HistoryName (a + Branch or `NoSuchBranch`, checked before `args::node`), or 66-hex (a Commit + or a Layer; a missing Layer is `NotFound`, a collected Commit + `NoSuchCommit`). A valid name is never retried as a node id; a Commit fork + keeps the retired row/name through `forked_from_id` and `commit.branch_id`, + and a Layer fork through `forked_from_id` and `layer.source_branch_id`. + A mount of a retired Branch is `NoSuchBranch`. For `merge`, a retired + **target** name is `NameTaken` while a retired source is `NoSuchBranch`; for + `publish`, a retired Branch is `NoSuchBranch` and a collected node is + `NoSuchCommit`. - Compaction removes a retired `branch` or `layer_stack` row once no retained row references it (`layer.source_branch_id`, `commit.branch_id` and the other history edges, `engine/crates/layerfs-persistence/sql/sqlite/history.sql:62-65`). + A Branch published by a retained Layer is pinned by that foreign key, and a + Branch named by a retained `commit.branch_id` is kept by the history + closure; only a Branch with neither reference is freed. The name is then free, and no retained row carries the old ID. The comment on `BranchId::named` ("never reused") is updated by #44 to say "never reused while its rows exist". @@ -193,54 +434,105 @@ name is never reused while its old rows exist. So: | Operation | Refused while | Code | |---|---|---| -| `branch.remove` | a mount or Sandbox of that Branch exists | `MountsActive` | -| `project.delete`, `project.remove_file` | any mount of the project (any Branch), or another user of the project | `MountsActive`, `Busy` | -| `store.compact` | any mount, client or operation on the Store, or unfinished Init/merge rows (#155 D-6) | `MountsActive`, `Busy` | - -Mounts take a Branch; there is no mount of a historical Commit. A Sandbox on a -machine that cannot be reached is `Busy`: its inactivity cannot be proven. - -The check and the exclusion are one atomic step: a new conflicting user is -refused from the check until the operation completes. +| `branch.remove` | a mount or Sandbox of that Branch, an unfinished Init/merge row names it, or another GC op at Branch scope | `MountsActive`, `Busy` | +| `project.delete`, `project.remove_file` | any mount of the project, another user of the project, an unfinished Init/merge row names it, or another GC op at project scope | `MountsActive`, `Busy` | +| `store.compact` | any mount, long-lived client or operation on the Store, or unfinished Init/merge rows | `MountsActive`, `Busy` | + +Mounts take a Branch; there is no mount of a historical Commit. All four +calls resolve their resource through the filtered statements (§4.2); a hidden +Branch is `NoSuchBranch`, a hidden project `NoSuchProject`, and a collected +Commit `NoSuchCommit` (the latter only on merge/publish), never a second +marker. The one exception is `project.delete`'s same-home retry, which +resolves the caller's recorded stack id under §4.2. + +`branch.merge` and `branch.publish` take no mount and are not in the table. A +non-fast-forward merge materializes the `remove_file` whiteout in its result +(§4.3) or is refused `Removed`; a publish of a Commit at or below the frontier +yields a Layer at the same position, which the marker hides. + +Every operation that creates a Commit or Layer, or writes under a project, +reads `project_epoch.epoch` at start and re-checks it before commit: +- SQLite: inside the one `BEGIN IMMEDIATE` transaction that also writes the + Commit/Layer, so a removal cannot interleave. +- PostgreSQL: the writer's last statement before commit is + `SELECT epoch FROM project_epoch WHERE layer_stack_id = $1 FOR SHARE` + (it blocks the marker's non-key `UPDATE`); a plain unlocked read is not + enough under READ COMMITTED. The marker transaction itself runs + `UPDATE project_epoch SET epoch = epoch + 1`, then reads the frontier + `next_history_serial - 1`, then inserts the marker. A missing epoch row + (post-cleanup project delete) is `Conflict`, never "unchanged". ### 5.1 SQLite -- **Store scope:** the existing Store lock, lease and op record - (`control/crates/layerfs-store/src/lease.rs`, `record.rs`, - `control/crates/layerfs-home/src/op.rs`). A live lease, reported by the - lease code as `InUse`, is returned as `Busy` at the API. -- **Project scope:** a project-level `op` on the project record, with the - same begin/settle pattern as the Store op - (`control/crates/layerfs-store/src/sqlite/family.rs:161-200`); Sandbox - create and mount check it (#42 item 33). -- **Branch scope:** a mount writes its Workspace intent record under the home - lock *before* bind, and removes it if bind fails. A removal checks the - records and writes its marker under the same lock, so a mount and a removal - can never both succeed; a bind that starts after the marker is refused by - the filtered statements (§4.2). +Admission is one Store-DB table and two `BEGIN IMMEDIATE` transactions +(SQLite 3.53.2 `lang_transaction`; a locked writer is `Busy`). + +`gc_intent(op_id PRIMARY KEY, kind, scope_kind, scope_id, workspace, sandbox, +machine, project, branch, owner_runtime, owner_boot, state, uncertain, phase, +generation, artifact, high_water, evidence, updated_ms)`, `STRICT`, with +`UNIQUE(scope_kind, scope_id, owner_boot)`; `kind` is `mount`, `init`, +`merge`, `removal` or `compaction`, `state` is `live`, `uncertain` or `done`, +`scope_kind` is `store`/`project`/`branch`, and the ids are typed per kind +(17-byte project/Branch, 33-byte commit/layer, 32-byte catalog id). The +migration step that adds it is the same additive step as §4.1. + +- A **mount** transaction checks that no operation op is running at every + scope it names (Store, project, Branch), inserts its intent and commits. A + **removal/compaction** transaction scans the intents in its scope, writes + its marker or op row, and commits. A live mount → `MountsActive`; a live + operation → `Busy`; a provably dead, uncertain op → `Unresolved`; a + provably dead, certain op is adopted or ignored per its `kind`. +- Compaction writes its `gc_intent` operation row **before** its first + checkpoint; the row lives in `.compact` during build/verify, moves + to the live Store after install, and is cleared at settle. `none` writes + and clears the same row (its only write); "nothing is written" in §3 means + no pack/object/history/generation change. +- Intent lifetime: the row is deleted in the `workspace.unmount` + transaction, on `sandbox.close`, daemon exit, machine stop, and in the + mount's error path if bind fails after the intent commit. A failed delete + is reported; a provably dead owner's row is ignored, never trusted. +- `machine_stopped` is provider evidence written into the intent/op; a live + but unreachable Sandbox is `Busy`; a removed machine record alone is not + proof. +- **Project scope:** `project.delete`/`remove_file` take a project op and + scan the intents naming the project. A mount is excluded by its own + intent, so several mounts of one project proceed. `project.delete` holds + its op through the marker transaction only; the retired-row entry-removal + retry needs no op, the live-row retry takes one and re-scans. +- **Branch scope:** the intent carries the Branch; a removal checks the + intents and writes its marker in the same transaction, so a mount and a + removal can never both succeed; a bind after the marker is refused by the + filtered statements (§4.2). +- `Unresolved` carries `{entity: {kind, name}, phase, op}`; a non-owning call + observes it, the owning call adopts/clears it. A `kind`-by-owner-state + matrix governs {mount, removal, compaction} × {live, unreachable, + dead-certain, dead-uncertain}. ### 5.2 PostgreSQL Leases are files in one home and cannot see another machine. So (#42 items 33, 34): -- **Presence.** Advisory keys at three scopes, `key(scope) = - blake3("layerfs/advisory/v1\0" ‖ catalog_id ‖ scope)[..8]` with scope the - Store, a project or a Branch (#42 item 12a, extended). Long-lived sessions - hold them shared on their own connection: the daemon for each mount (Store, - project and Branch keys), and compaction's own connection. A removal tries - the exclusive project or Branch key; compaction tries the exclusive Store - key. Failure is `Busy` or `MountsActive`, naming the holders (`pid`, - `client_addr`, `backend_start`). This makes an idle remote daemon with a - mount visible. -- **One-shot SDK calls** hold no presence lock. They rely on the fence below, - and on the swap's `ACCESS EXCLUSIVE NOWAIT` (§8): a transaction still open - at swap time makes the swap abandon. +- **Presence.** Advisory keys at three scopes, `key(kind, id) = + blake3("layerfs/advisory/v1\0" ‖ catalog_id ‖ kind ‖ id)[..8]` with kind 1 + the Store (32-byte `catalog_id`), 2 a project (17) and 3 a Branch (17); the + 8-byte truncation can cause a false `Busy` or a misclassified holder, never + a missed exclusion. A mount holds shared kind 1/2/3 on one dedicated + session for the daemon's life, refcounted per `(session, key)` and acquired + all-or-none with `pg_try_advisory_lock[_shared]`; a failed acquisition + unlocks what it took. Compaction holds only the exclusive kind 1 key, taken + before Phase M and held through Phase C/settle on that same pinned session. +- **Removals** take transaction-scoped locks in the marker transaction: + `branch.remove` = shared kind 1 + shared kind 2 + exclusive kind 3; + `project.delete`/`remove_file` = shared kind 1 + exclusive kind 2; order + Store → project → Branch. A failed shared attempt is `MountsActive`, a + failed exclusive attempt `Busy`; `pg_locks.mode` names the holder. +- **One-shot SDK calls** hold no presence lock. They rely on the + `project_epoch` `FOR SHARE` check (§5), the fence below, and the swap's + `ACCESS EXCLUSIVE NOWAIT` (§8). The four GC calls are not one-shot. - **Fence.** The generation check rides in the statements a client already sends: in the `BEGIN` batch of a transaction, and as a joined column of - `history_meta.catalog_incarnation` in the reads that run without a - transaction (`Mode::Immutable`/`Statement` skip `BEGIN`: - `engine/crates/layerfs-persistence/src/backend/postgresql/session/transaction.rs:263-268`). + `history_meta.catalog_incarnation` in reads without a transaction. No extra round trip. A mismatch is `StaleStore`. - **Connections.** Mounts and compaction need a direct or session-pooled connection; transaction pooling cannot hold a session lock and is @@ -248,7 +540,9 @@ Leases are files in one home and cannot see another machine. So (#42 items poolers. - **Dead clients.** A client whose TCP connection died holds its lock until the server notices. The guide documents `tcp_keepalives_idle`, - `client_connection_check_interval` and `pg_terminate_backend`. + `client_connection_check_interval` and `pg_terminate_backend`; a GC call's + lost reply is resolved on a second connection before the exclusive key is + taken. ## 6. Mark @@ -259,21 +553,32 @@ operations; a missing locator or corrupt dependency aborts with no writes. A recursive query from the retained roots over the history edges: -- Branch (not retired) → `head_commit_id`, `base_layer_id`, `forked_from_id` +- Branch → `head_commit_id`, `base_layer_id`, `forked_from_id` (followed for + every retained Branch; the **roots** are every non-retired Stack and every + Branch with no own or stack marker) - Stack (not retired) → `head_layer_id`, published Layers - Commit → `parent_commit_id`, `second_parent_id`, `base_layer_id`, - `merged_from_id`, `displaced_id` -- Layer → `parent_layer_id`, `source_commit_id` + `merged_from_id`, `displaced_id`, `branch_id` +- Layer → `parent_layer_id`, `source_commit_id`, `source_branch_id` `merged_from_id` and `displaced_id` are followed because doctor requires their targets (`diagnostic/history.rs:40,146`; #42 item 28). A retired Branch is collected as a unit: if a retained row references it (`commit.branch_id`, -`layer.source_branch_id`), its row stays and so does its head chain, because -`branch.head_commit_id` is a foreign key; the closure is the fixpoint of this -rule (#42 item 29). Every history edge is stack-local, so a live stack keeps -all its Layers and only Commits and retired Branch rows can go; a deleted -project goes whole. A fork keeps its source's history up to the fork point. -History rows outside the closure are collected by the rebuild (§7, §8); this +`layer.source_branch_id`), its row stays and so do `head_commit_id`, +`base_layer_id` and `forked_from_id`, and the head commit enters the Commit +edge set above; the closure is the fixpoint of these rules (#42 item 29). A +Layer's `source_branch_id` is a foreign key, so a published Branch and its +head chain stay retained while the Layer lives; that Branch keeps its name +(`NameTaken`) and compaction does not free it. "Free after compaction" (§4.4) +applies only to a Branch that nothing retains: no retained +`layer.source_branch_id` and no retained `commit.branch_id` (a fork's +`forked_from_id` is such a Commit). Every history edge is +stack-local, so a live stack keeps all its Layers and only Commits and +retired Branch rows can go; a deleted project goes whole. A fork keeps its source's history up to the fork point. +`store.history.branches` validates every retained `commit.branch_id`: it must +name a Branch in the same stack (SQLite cannot add the FK, so this is a doctor +edge). History rows outside the closure are collected by the rebuild (§7, §8); +this is required because the full doctor qualifies every Commit and Layer root it finds (`engine/crates/layerfs-persistence/src/diagnostic/history.rs:155-198`). @@ -285,31 +590,53 @@ finds (`engine/crates/layerfs-persistence/src/diagnostic/history.rs:155-198`). with `ChainBases::base_of` (`core/crates/layerfs-storage/src/encoding/delta/read.rs`). Do not reuse `qualify`: it skips file mappings, symlink targets and attribute trees and ignores delta bases. -- One visit level (#42 item 27): an object reached by a logical edge or a - base edge is kept with all of its references, because the full doctor - checks the references of every stored object - (`engine/crates/layerfs-persistence/src/diagnostic/scan.rs:129-224`). - Objects kept only because they are bases are reported in `keptWaste`. -- `remove_file`: when descending a root at or below a marker's frontier, the - walk does not enter the removed path. An object stays live if any other - path, project or delta chain reaches it. -- On PostgreSQL the base edges live inside pack groups, so a remote server - sends about the live payload to the client during the mark. No format - change is made for this until #52 measures it; the fallback is a nullable - `object_location.base_id` filled at publish (#42 item 36). +- Transitive closure (#42 item 27): each object is admitted once; admitting + it enqueues its logical references (`references()`) and its delta base + (`base_of`), and the queue runs to empty. An object reached only as a base + still keeps all of its references, because the full doctor checks the + references of every stored object (`diagnostic/scan.rs:129-224`). Objects + kept only because they are bases are reported in `keptWaste`. +- `remove_file` is **visibility-only in 2.0.0**: the marker hides the path in + reads, listings, mounts, merges and publishes, and compaction reclaims + nothing that only the removed path reached. A retained root's inode page + must stay (qualification refuses a missing inode, + `filesystem/qualify/walk.rs:183`), and rewriting the tree would change the + root and the Commit/Layer id (S10). A path-aware walk that frees bytes, and + per-entry page pruning, are a follow-up; `keptWaste` has no page component + in 2.0. +- On PostgreSQL the base edges live inside pack groups, so the mark (§8 + Phase M) reads that payload. A remote caller transfers it; `markBytes` is + the distinct live-pack body bytes read once, and #52 measures them. The + table copy moves no pack bytes. 2.0 keeps the format unchanged; adopting a + nullable `object_location.base_id` is a separate #52 decision with a schema + version and a defined NULL/backfilled distinction, not a runtime switch + (#42 item 36). - Window by window, sort lookups by object ID before locating them. - Whole files and chunks have no logical references; only their delta base is needed. Reading it still loads and authenticates the whole group - (`delta/read.rs:561-571`), so the payload part of the walk runs inside the - copy (§7 step 4), not as a separate pass. + (`delta/read.rs:561-571`); on SQLite the payload part of the walk runs + inside the copy (§7 step 4), and the PostgreSQL mark reads it in Phase M. ### 6.3 Visited set -A scratch table `visited(object_id PRIMARY KEY, pack_id) WITHOUT ROWID` -in a temporary file owned by the compaction connection (`temp_store=FILE`): -bounded memory, no second persistent database. Session connections keep -`temp_store=2` (`engine/crates/layerfs-persistence/src/backend/sqlite/session/profile.rs:88`). -On PostgreSQL, a temporary table. +A scratch table `visited(object_id PRIMARY KEY, pack_id) WITHOUT ROWID` in a +named scratch database beside the Store (`.compact-visited`), attached +to the compaction connection: it is in the op/artifact set and in +`peakTempBytes`. Its own journal (`.compact-visited-journal`) and any +multi-database super-journal (`-mj*`) are in the artifact set too; or the +visited DB runs `journal_mode=OFF` and the copy is not atomic with it. Session +connections keep `temp_store=2` +(`engine/crates/layerfs-persistence/src/backend/sqlite/session/profile.rs:88`); +both paths spill the closure to `.compact-visited` and choose the +path from the refined live set; the `none` path deletes the scratch before +replying, so it leaves no residue and never answers `Capacity` for a cap. On PostgreSQL it is a temporary table. + +`kept_node(kind, id)` is the history side of the same walk: `kind` is +`commit`, `layer`, `branch` or `stack`, and it holds the §6.1 closure. A +rebuild copies `layer_lineage.layer_id ∈ K_layer`, `commit_lineage.commit_id +∈ K_commit`, `absorbed.run ∈ R`, `reach.key ∈ K_stack ∪ R` (R := runs of kept +`commit_lineage` rows), and the history/catalog rows by `kept_node`; it +deletes the complement, and a deleted project goes whole. ### 6.4 Decision @@ -317,69 +644,153 @@ On PostgreSQL, a temporary table. - `none` or `rebuild` from §3, using the bytes of packs that hold no live object after the metadata walk (an upper bound that §7 step 4 refines). - Dead rows: `object_location`, `content_signature`, `file_digest` (keep a - row only if its root is retained, #155 R-4), history rows outside §6.1, and - retired `branch`/`layer_stack` rows (§4.4). + row only if its root is in `visited`; a digest or signature root is not a + mark root, so an uncommitted saved file's row is dead), history rows + outside §6.1, retired `branch`/`layer_stack` rows (§4.4), a `branch_retired` row whose + branch row is collected, a `layer_stack_retired` row whose stack is + collected, and `path_removed`/`project_epoch` rows of a deleted project (a + project goes whole). A live project's markers stay: `path_removed` is one + per path, and a serial allocated later never falls below a frontier. - Kept in 2.0: every `inode_value_block` row; the ordinals of pooled leaves are private to core, and the blocks are small. The report gives their bytes (#42 item 37). - Cleared: `binding_hint_block`. The hints are advisory and not per project, and they hold the file names of deleted projects and removed paths (#42 - item 38). + item 38). Clearing all of them costs only advisory lookup speed, never + correctness; a later Save repopulates hints for live paths. A per-project + clear is a follow-up, not 2.0.0. + +`live_heads_digest` (both backends) is BLAKE3 over +`"layerfs/live-heads/v1\0"`, then the non-retired stacks in id order as +`(stack_id, head_layer_id)`, then the Branches with no own or stack marker in +id order as +`(branch_id, head_commit_id or 33 zero bytes, base_layer_id)`, each +fixed-width. Commit ids are 33 bytes (tag `0x12` + 32), Layer ids 33 (tag +`0x32`), Branch and stack ids 17; a golden vector pins the bytes. A retired +row is absent, not zeroed; timestamps are not hashed, so SQLite and +PostgreSQL agree. ## 7. SQLite rebuild Runs as one operation on the Store's machine (S6). -1. Checkpoint the WAL and confirm no `-wal` remains (an immutable attach - ignores the WAL). -2. Create `.compact` beside the Store with a raw connection: +1. Take the persistence writer guard and hold it through step 7's rename. + Checkpoint the source with `PRAGMA wal_checkpoint(TRUNCATE)` and require + `busy == 0` (never unlink a WAL file); checked-close the last source + session and check for `-wal`/`-shm` while the guard is held; pass the + guard into the seal (no second acquire); use + `seal_holding() -> (size, mtime, db-header change counter, Writer)` + captured after the sidecar check and before release. The current + `Session::seal` releases the lane, so a returned Writer is required; there + is no re-acquire alternative. A busy checkpoint is + `Busy`. Record the sealed `(size, mtime, db-header change counter)`. +1.5 After the seal, `ATTACH` the old file `immutable=1` (it stays + byte-identical), create `.compact-visited`, run the complete + §6.1+§6.2 closure into it, and choose `none`/`rebuild` from the refined + live set. On `none`, delete the scratch and stop: no `.compact`, no + `.compact-visited`, no residue. On `rebuild`, keep the scratch and reuse + `visited` in step 4; step 2 creates the new file only on this path. +2. If the path is `rebuild`, create `.compact` beside the Store with a + raw connection: `page_size=4096`, the source's `auto_vacuum`, `schema::scripts`, - `application_id`, `user_version`. Give this connection a large - `cache_size`, and the attached old file a large `mmap_size`; the session - defaults are a 2 MiB cache and no mmap (`session/profile.rs:86-87`). -3. `ATTACH` the old file `immutable=1`; it stays byte-identical. -4. One rollback-journal transaction, foreign keys on, in this order: + `application_id`, `user_version`. The new file uses the source's + `(layout, acquisition)` derived from its `user_version`: `Monolithic` has + `pack.body` and no `pack_unit`; `GroupRows` has `pack_unit`; + `GroupRowsIndexed` also has its index. `schema_source`/`schema_definition` + must be those of that pair, or step 6's `validate` refuses. Give this connection a + large `cache_size`, and the attached old file a large `mmap_size`; the + session defaults are a 2 MiB cache and no mmap (`session/profile.rs:86-87`). +3. The old file is already attached `immutable=1` in step 1.5; it stays + byte-identical. +4. `PRAGMA foreign_keys=ON` outside the transaction (inside it the pragma + is a no-op), then one rollback-journal transaction, in this order: - Metadata walk (§6.1–§6.2 logical part) into `visited`. - - Payload sweep: live packs in descending `pack_id`. Copy each live pack - once, add the delta bases of its live records to `visited`. A base found - in a pack already passed goes on a late list and is copied at the end. - A base is not guaranteed to sit in a lower `pack_id` (first-wins - locators can move forward, - `core/crates/layerfs-storage/src/store/source.rs:9-13`), so the late - list is an indexed table, not an exception path. + - Payload sweep: a worklist of packs to copy, run to empty. Start with the + packs the mark marked live; copy each pack once. For every object + inserted into `visited` (a base, its references and their bases), run the + same `admit` fixpoint, insert each newly discovered object if absent and + enqueue **every** newly visited object's locating pack (passed or not); + do not follow records whose `object_id` is not in `visited`. A pack + reached only by a base is copied whole; `pack_id` is preserved and new `unit_id`s are + assigned; the dead set and `deadBytesRefined` are recomputed from the + final copied set. A base is not guaranteed to sit in a lower `pack_id` + (first-wins locators can move forward, + `core/crates/layerfs-storage/src/store/source.rs:9-13`), so the worklist + is an indexed table, not an exception path. - `pack_unit` for the copied packs, as a complete unit set (`engine/crates/layerfs-persistence/src/backend/sqlite/objects/units_read.rs:55-75`). + A `Monolithic` Store copies `pack` with its body and skips `pack_unit` + (the Monolithic decoder is used); `GroupRows` copies both; + `GroupRowsIndexed` copies both and the schema creates its unit index + (the index is not "copied"). `sqlite_sequence` is copied only when the + source has it; `store_totals` is UPDATEd as a whole row (keeps `init_*`) + and `store_policy` is `INSERT ... SELECT * FROM old.store_policy` + (allocators and salt verbatim); transient `init_*`/acquisition working + rows + are **not** copied, and a live Init op is admitted as `Busy`. - `object_location` by an ordered join with `visited`. - - `content_signature` entries that name a copied object; `file_digest`, - `inode_value_block`, history and catalog tables per §6.4, with a deleted - project's rows left out by the `removal_*` statements' selection; - `sqlite_sequence`, `store_policy` and `scope_allocator` copied; - `binding_hint_block` left empty; `history_meta` with - `catalog_incarnation = G + 1`. - - `store_totals`: `logical` is rebuilt by the history triggers and must - equal the old value minus the collected history rows' `logical`; - `canonical`, `stored` and `metadata` are summed. -5. Switch the new file to WAL and run the sidecar checks - (`engine/crates/layerfs-persistence/src/backend/sqlite/snapshot.rs:101-140`). -6. Verify: a real Session open (`validate`), `live_heads_digest` before and - after (a new function beside `heads_digest`, - `engine/crates/layerfs-persistence/src/backend/sqlite/heads.rs:83`, over - non-retired Branches and stacks only; #42 item 30), row counts against the mark, - `foreign_key_check`, the catalog allocator and totals checks. No sha256 of - either file. `quick_check` and the full doctor stay separate commands. -7. Install: re-read `G`; check `(catalog_id, incarnation, dev, ino)` and that - no sidecars exist; `sync_all` the new file; `rename` it over the Store; - fsync the directory. The old inode is freed at once. -8. A definite failure of compaction's own write (disk full, write refused) - aborts the transaction and deletes `.compact` in the same call, - returning `Capacity` or the failure (#155 D-22). + - `content_signature` entries that name a copied object; `file_digest` + rows whose root is in `visited`; all `inode_value_block` rows; history, + lineage (`layer_lineage`, `commit_lineage`) and catalog tables copied by + `kept_node`; `absorbed` by `run`; `reach` by its kind-mapped key; with a + deleted project's rows left out by the `kept_node`/retired predicate + (`removal_*` runs only on the writable new Store in Phase C); + `sqlite_sequence`, `store_policy`, `scope_allocator`, the marker tables + (`branch_retired`, `layer_stack_retired`, `path_removed`) and + `project_epoch` copied for rows the closure keeps; + `commit.history_serial`/`layer.history_serial` copied with their rows; + `history_meta.next_history_serial` copied unchanged; `binding_hint_block` + left empty; `history_meta` with `catalog_incarnation = G + 1`. + - `store_totals`: after **all** history copies, one UPDATE sets `logical` + to the triggers' value (or `old - dead_logical`), `canonical`/`stored`/ + `metadata` to the new sums, and `init_*` to the old row; assert + `old.logical == SUM(all history.logical)` before the copy. A copy before + the history insert would make the AFTER INSERT triggers add the + collected rows again (`old + collected`). +5. Switch the new file to WAL with a raw connection (`temp_store=MEMORY`, + `busy_timeout=0`, the source's `synchronous`); on macOS call + `disable_persistent_wal` before the checkpoint + (`snapshot.rs:116`, `seal.rs:31-32`); checkpoint with + `wal_checkpoint(TRUNCATE) == 0`; close it. No Session is opened. +6. Verify with an `immutable=1` open (`READ_ONLY|URI`, + `file:...?immutable=1`, percent-encoded path bytes so `?`/`#`/`%` do not + misdirect the URI, no profile apply/check, no lane) and run `validate` + there before the rename: + `schema::check`, + `foreign_key_check`, row counts against the mark, both `live_heads_digest` + values and the catalog allocator/totals checks. No sha256 of either file. + Close the reader; `quick_check` and the full doctor stay separate + commands. +7. Install: stat both paths for `-wal`/`-shm`/`-journal` and the + super-journal (`-mj*`); any sidecar is `Conflict` with no writes. Re-read + `G` through a fresh immutable handle and re-stat last; check + `(catalog_id, incarnation, dev, ino)` and the sealed `(size, mtime, + db-header change counter)`; a change is `Conflict`. `chmod 0600`; + `sync_all`; `rename`; fsync the directory; release the guard. A + transaction that began before install is caught at its next transaction + by the `(dev, ino)` fence, not at commit (documented limit). +8. A definite failure before the rename (disk full, write refused, sidecar, + checkpoint, validate, digest/count/FK, chmod/sync) aborts or rolls back and + deletes the artifact set `.compact{,-journal,-wal,-shm,-visited, + -visited-journal,-mj*}`; the old Store is unchanged apart from step 1's checkpoint. A + failure of the rename/fsync itself is installed-but-uncertain: keep the new + Store, settle the op `unknown` and report it; never delete the artifact as + if nothing happened. `SQLITE_FULL`/`BackendError::Capacity` is + `HistoryError::Capacity`, or the real `Refused { status: "Capacity" }` + path; `ENOSPC`/`EDQUOT`/`EFBIG` (`StorageFull`/`QuotaExceeded`/ + `FileTooLarge`) from chmod/sync/rename also map to `Capacity`, and + `SQLITE_FULL`/`SQLITE_TOOBIG`/`SQLITE_NOMEM` are Capacity on SQLite; no + `_` arm may turn it into another `Refused` status. `CapacityExceeded` is a + codec/canonical bound and is documented as `InvalidInput`/`ProviderFailure`, + not disk exhaustion. The existing transfer pipeline is not reused for this: its `Install` refuses an existing Store file and its `Retire` deletes one (`control/crates/layerfs-store/src/sqlite/transfer/steps.rs:262-288`). Cost: read about the live bytes plus the metadata, write about the live -bytes; peak disk = old Store + live bytes + the visited table. +bytes; peak disk = old Store + the new Store + the rollback journal/WAL + the +visited scratch file. ## 8. PostgreSQL rebuild @@ -387,66 +798,163 @@ Only `object_location.pack_id` references `pack`, so the payload lives in two tables. `content_signature` (at most 8192 rows, no foreign key: `sql/postgresql/schema.sql:45-50`) is cleaned in place. -**Phase A — build (exclusive advisory lock held, no table lock).** +**Phase M — mark (before Phase A).** Take the session-level exclusive Store +key before this phase and hold it through Phase C. The mark's **first +statement** reads `(catalog_incarnation, live_heads_digest, +history_meta.next_history_serial, next_pack_id, next_ordinal, +store_totals canonical/stored/metadata/logical)` and records that tuple; +any later publication makes Phase B `Conflict`, so a commit that lands during +the walk cannot be recorded while its objects are absent from `visited`. (Or +run the whole mark in one REPEATABLE READ transaction and record the tuple +inside it; state the vacuum cost.) One session, kept through Phase B, builds +`visited(object_id PRIMARY KEY, pack_id)` as a temporary table: start from the +retained roots, read pack groups in batches, follow +`FinalizedObject::admit(..).references()` and `ChainBases::base_of` as a +worklist to a fixpoint (each object once, bases of late objects included), and +record `live_heads_digest` and the live pack/object sets. After the walk, +write `gc_op` and `gc_dead` in batches (phase `mark`); a crash leaves both, +and the next `store.compact` adopts the op, truncates `gc_dead` and re-marks. +A `none` decision writes `gc_op` phase `mark`, truncates `gc_dead`, removes +the named artifact and clears `gc_op` before replying. +`gc_dead` carries `mark_stamp` for signature slots. The payload read is +reported as `markBytes`; the Phase A table copy itself moves no pack bytes. + +**Phase A — build (session-level exclusive Store advisory key, no table lock).** 1. Load the live object and pack IDs into temporary tables; `ANALYZE` them. -2. Create `pack` and `object_location` in a scratch schema with the Store's - column definitions and `STORAGE EXTERNAL` on `pack.body`, without the - trigger and the foreign key. -3. Copy live rows with `INSERT … SELECT` and a semi-join (`object_location` - has no unique key, `schema.sql:29-38`, so a plain join can duplicate rows), - in batches of about 1 GB by `pack_id`, each batch its own transaction. No - pack bytes cross the network. Batches may pause for standby lag. +2. Create `pack` and `object_location` in a scratch schema with + `CREATE TABLE ... (LIKE store.pack INCLUDING STORAGE, COMPRESSION, + CONSTRAINTS)` and the same for `object_location` (PK explicit; do not copy + `object_location_prefix`), plus the old `TABLESPACE` and `WITH + (reloptions)` read from `pg_class`. `pack.body` stays STORAGE EXTERNAL and + `object_location.object_id` stays STORAGE PLAIN; the trigger and foreign + key are added later. +3. Copy live rows with `INSERT … SELECT` and an `EXISTS` semi-join + (`object_location` has no unique key, `schema.sql:29-38`, so a plain join + can duplicate rows): `pack` rows with at least one visited object and + `object_location` rows whose `object_id` is visited, in batches of about + 1 GB by `pack_id`, each batch its own transaction. A retried batch first + deletes its own `pack_id` range from the scratch tables (idempotent), then + inserts; assert `count(*) = count(DISTINCT object_id) = |visited|`. No pack + bytes cross the network. Batches may pause for standby lag. 4. Build `object_location_prefix` and the foreign key, then `ANALYZE`. **Phase B — swap (one short transaction).** -5. `LOCK TABLE` the Store's tables `ACCESS EXCLUSIVE NOWAIT`. -6. Re-check `catalog_incarnation = G`, `live_heads_digest` (PostgreSQL gains - one; it has no heads digest today), and that `store_policy.next_pack_id` - and the ordinal allocator have not moved. Any change abandons the round - with no writes (`Conflict`). -7. Delete dead rows in place: `content_signature`, `file_digest`, history - rows (a deleted project's through the `removal_*` statements, which already - run on PostgreSQL) and retired name rows; clear `binding_hint_block`; - `inode_value_block` is kept (§6.4). `logical` in `store_totals` is reduced - by the collected history rows, as `removal_totals` does today - (`engine/crates/layerfs-persistence/src/history/removal.rs`); `canonical`, - `stored` and `metadata` are recomputed. -8. Copy the old tables' owner and ACL onto the new ones. -9. `DROP TABLE` the old `object_location` and `pack`; `ALTER TABLE … SET SCHEMA` +5. `LOCK TABLE` every base table of the Store schema (from `pg_class`, + including `store_lane`, `store_totals`, `history_meta`, + `content_signature`, the history tables and `gc_intent`/`gc_op`) in one + `ACCESS EXCLUSIVE NOWAIT`, with `store.*`/`scratch.*` qualified names. A + `55P03` abort is `Busy` with holder detail (not `Conflict`); `ROLLBACK` + first, then read holders and drop the scratch schema in a new + transaction. +6. Re-check `catalog_incarnation = G`, `live_heads_digest`, + `store_policy.next_pack_id`/the ordinal allocator, + `history_meta.next_history_serial` and `store_totals` + (`canonical`/`stored`/`metadata`/`logical`) against the values the mark + recorded. A + publication that reused a pre-reserved pack/ordinal may move none of the + first three but always bumps `store_totals`; any change abandons the round + with no writes (`Conflict`). No delta copy is attempted, so the new pack + stays in the old Store. +7. Copy the old tables' owner and ACL onto the new ones. +8. `DROP TABLE` the old `object_location` and `pack`; `ALTER TABLE … SET SCHEMA` the new ones into the Store's schema; create the `pack_immutable` trigger there, bound to the Store schema's `pack_immutable()` so doctor sees `EXECUTE FUNCTION pack_immutable()` (`diagnostic/postgresql_contract_expected.rs:213`). -10. Verify inside the transaction: row counts against the mark, - `live_heads_digest` unchanged, and the doctor contract query (tables, - constraints, indexes, trigger) clean. A failure rolls back. -11. `catalog_incarnation = G + 1`; `SET LOCAL synchronous_commit` to the - Store's setting or `local`, whichever is stronger; `COMMIT`. Then drop - the empty scratch schema. - -- **Crash:** a crash in phase A leaves only the scratch schema, which the op - record names and the next attempt removes. Phase B is atomic. -- **Lost `COMMIT` reply:** first prove the old backend has ended (the - exclusive advisory lock is free, or its recorded `pg_backend_pid()` is - gone), then read the incarnation. A read, not a replay. -- **Lock time:** `ACCESS EXCLUSIVE` is held for phase B only, seconds rather - than the length of the copy. No long transaction holds back vacuum for - other Stores in the same database. +9. Verify inside the transaction: row counts against the mark; + `SUM(new) = mark_totals - dead_*` with `logical` unchanged; the + `pg_attribute`/`attstorage`/`reloptions`/`tablespace` fingerprint recorded + in `gc_op` at mark equals the scratch tables' fingerprint; persist the + `dead_*` totals **before** the swap COMMIT. The settle transaction then + subtracts once and asserts the four `store_totals` sums. + `live_heads_digest` unchanged, and the bounded checks on the moved tables + (the `pack_immutable` trigger/function and `pg_attribute`/storage). Run only + the C/I contract entries for `pack`/`object_location` on the scratch tables + in Phase A (the trigger/function entries need the Store-schema function and + stay in the swap's bounded check), with `search_path=scratch`. A failure + rolls back. +10. `catalog_incarnation = G + 1`; the effective `synchronous_commit` is the + stronger of the Store's and the server's in the order + `off < local < remote_write < on < remote_apply`, set with `SET LOCAL` + around the swap and never lowered. It waits iff the level is at least + `remote_write` **and** `current_setting('synchronous_standby_names')` is + non-empty; then require the named FIRST/ANY standbys to appear in + `pg_stat_replication` with `state='streaming'` and the matching + `sync_state` (`sync`/`quorum`). Check before Phase M and again inside the + swap before COMMIT; a missing standby abandons with no writes (`Busy`, + standby list). A standby that dies after the check blocks the COMMIT; + `SET LOCAL` cannot bound that wait. + `DROP` the empty scratch schema before `COMMIT` (it is transactional). + +**Phase C — cleanup (batched, after the swap).** + +11. Delete only ids in the mark's **persisted dead set** in `gc_op` + (membership, not a predicate: exact `content_signature` slots, + `file_digest` roots, history/lineage ids, a deleted project's + `path_removed`/`project_epoch` rows, and marker/base row pairs). Per-table + watermarks (`commit`/`layer` serial, signature stamp) are only guards; a + row created after the mark is never a member, so a Commit/Layer/save + created during cleanup survives. Assert each batch's own `pack_id` range + and, after the last batch, `count(*) = count(DISTINCT object_id) = + |visited|`. Delete child-first (a project's closure + in one transaction; a marker with its base row) so the deferred FKs hold. + Clear `binding_hint_block` wholesale (it is not id-addressable, §6.4). + The swap already dropped dead packs and locations, so persist + `dead_canonical` (dropped `object_location.canonical_length`), + `dead_stored`/`dead_metadata` (dropped pack `length`; `stored` is all + domains, `metadata` only domain 0) and `dead_logical` in `gc_op` + **before** the swap COMMIT; `content_signature` deletes are by + `(slot, stamp)` with `stamp <= mark_stamp`; reduce + `store_totals` by those totals in the **same transaction that settles the + op**, or gate on `totals_applied`; never re-sum. Assert the new tables' + sums equal old totals minus dead totals. The op phase is `cleanup`; a crash resumes the + persisted set — there is no "re-derive from the current Store" path. The + Store is usable at `G + 1` throughout; the full doctor runs after cleanup. + +- **Scratch schema:** one deterministic, length-safe name per Store derived + from `catalog_id` (`lfs_gc_`, truncated to 63 bytes), recorded in the + Store-side `gc_op` row (§4.1) before `CREATE SCHEMA`; a crash names it from + the Store, not only from the caller's home. +- **Crash:** a crash in Phase M/A leaves only the scratch schema, which the + Store's op names and the next attempt removes. Phase B is atomic; a crash + after COMMIT resumes Phase C. +- **Lost `COMMIT` reply:** record `pid`, `backend_start`, `usename` and the + incarnation in `gc_op` in a transaction **before** the swap. Recovery on a + second connection (before taking the exclusive key) is one statement: + `SELECT pg_terminate_backend(a.pid, ) FROM pg_stat_activity a WHERE + a.pid = $1 AND a.backend_start = $2 AND a.usename = $3 AND + a.datname = current_database() AND a.pid <> pg_backend_pid()`, checking the + boolean and polling until the pair is gone, then reading the incarnation. + Terminating another role's backend needs `pg_signal_backend` or membership; + the precheck reports `Unsupported` when neither is available. +- **Lock time:** `ACCESS EXCLUSIVE` is held for the swap only, seconds rather + than the length of the copy or the cleanup. No long transaction holds back + vacuum for other Stores in the same database. - **Space:** old tables + new heap/TOAST + indexes + up to the live bytes of WAL. The guide states the WAL headroom requirement; a full `pg_wal` stops the whole server. -- **Privileges:** ownership of the Store's tables and `CREATE` on the schema, - otherwise `Unsupported`. +- **Privileges:** `CREATE` on the database (for the scratch schema), `TEMP` + (the visited tables), `USAGE` and `CREATE` on the Store schema, ownership + of the Store's tables, and `pg_read_all_stats` for `client_addr`/ + `backend_start` (which may be NULL); check all before Phase M, otherwise + `Unsupported`. ## 9. Failure and leftovers -- The op record names `G` and the staged artifact (`.compact` or the - scratch schema). +- The op record names `G` and the staged artifact. The SQLite artifact is + the set `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`; all of it is removed for the + reserved name, and the op is settled only after removal. The PostgreSQL + artifact is the scratch schema, whose deterministic name is recorded in the + Store's op row before it is created, so a crash on another machine can still + name and remove it. - The next `store.compact` judges it: the Store at `G` means not installed, so the named artifact is removed; `G+1` means installed, so the outcome is - recorded. A machine that cannot be reached reports `unknown`, never clean. + recorded. An op left uncertain by a dead owner is adopted by that + `store.compact` (its artifact and high-water are in `gc_op`); only a live + owner blocks it. A machine that cannot be reached reports `unknown`, never + clean. - A file or schema at the staged name that no record names is refused with the existing `Exists` and is not deleted. - Install is the only irreversible step: the Store is wholly old or wholly new. @@ -458,46 +966,133 @@ tables. `content_signature` (at most 8192 rows, no foreign key: - **SQLite:** at the start of every transaction, compare the Store path's `(dev, ino)` with the one recorded at open; a mismatch is `StaleStore` before anything is read or written. This covers both a reader and a writer - still holding the old file (formerly C8 and C8b). + still holding the old file (formerly C8 and C8b). Compaction holds + `lane::writer_admission` from the seal through the rename, so an admitted + writer cannot be in flight at install; a connection that bypassed admission + is caught at its next transaction. Install also requires the sealed + `(size, mtime, db-header change counter)` unchanged; a change is `Conflict` + with no writes. - **PostgreSQL:** the generation check of §5.2. - **`lfq1` tokens** of an older generation already fail, because their authenticator is keyed by the incarnation. | Code | Status | |---|---| -| `MountsActive`, `Busy`, `NotFound`, `NoSuchStore`, `Unsupported`, `ReservedName`, `Conflict`, `NameTaken`, `Capacity`, `Exists` | existing | +| `MountsActive`, `Busy`, `Unresolved`, `NotFound`, `NoSuchBranch`, `NoSuchCommit`, `NoSuchProject`, `NoSuchStore`, `Unsupported`, `ReservedName`, `Conflict`, `NameTaken`, `Capacity`, `Exists`, `InvalidInput` | existing (`Unresolved` now used by the four calls) | +| `Unknown` | service/control-plane outcome, not a `HistoryError` code (§4, §4.2): a lost reply or an undeterminable Store listing; detail `{entity: {kind, name}, phase, op}`, with `phase`/`op` `null` when no durable op is known | | `StaleStore` | new; one `HistoryError` variant with an explicit mapping arm, because the `_ => "Failed"` wildcard (`engine/crates/layerfs-store-service/src/history/lookup.rs:54,64`) would hide it | -| `Removed` | new; reading a path removed by `remove_file` | +| `Removed` | new; reading a path removed by `remove_file`; an explicit `HistoryError::Removed` arm in `lookup.rs` before the `_ => "Failed"` wildcard; detail always `{paths: [{path, frontier_serial}]}` — a merge lists every unmaterializable path, sorted by path bytes; `file.mv`/`file.rm` from a hidden path are the `NotFound`/`NoSuchPath` wire code, while `file.cp`/`file.edit` return `Removed` | -- A project create whose name is held returns `NameTaken` (today it returns - `Exists`), the same as a Branch create or fork. -- New `HistoryCatalog` methods get default `Unsupported` bodies so the eight - implementations need not change at once (C9). + +- `project.init` whose name is held returns `NameTaken` (today it returns + `Exists`), the same as a Branch create or fork; both the home record and the + Store name collision map to it. +- The new `HistoryCatalog` methods are enumerated in the #42 list + (`mark_*`, `retained_roots`, `get_retained_roots`, `remove_unreachable`); + both production providers implement them; the default body is `Unsupported`, + and `lookup.rs` maps `HistoryError::Unsupported` explicitly (C9). - All four calls belong to the MCP admin profile and are refused under a - folder scope (`api/crates/layerfs-api/src/calls/scope.rs`; #42 item 39). + folder scope (`api/crates/layerfs-api/src/calls/scope.rs:33`, `out of + scope: `; #42 item 39). A folder scope guards one folder and one + Branch; none of the four is a folder operation (`branch.remove` retires the + whole Branch, `project.*` the project, `store.compact` the Store), so they + are refused rather than reinterpreted at a wider scope. +- The four calls take `branch.remove(project, branch)`, + `project.delete(project)`, `project.remove_file(project, path)` and + `store.compact(name)`; no options. +- MCP: the admin classifier checks its admin list before the work families; + the four calls join it and `project.remove` leaves both the call table and + that list. `whyOf`, the profile prose and `--profile admin` usage name + the four calls; an old MCP `project_remove` is `InvalidParams "unknown + tool"`, a CLI usage error exits 2, and the library reports `InvalidInput`; + the precedence test covers `branch.remove` under `work`. The table becomes + 76 calls (38 work/38 admin); regenerate `gen-profiles`/`gen-coverage` and + the hard-coded 73/38/35 counts, and give `whyOf` one line per call. +- Results: `branch.remove` → `{kind: "Removed", project, branch, removed_ms}`; + `project.delete` → `{kind: "Removed", project, deleted_ms, + home_entry_removed}`; `project.remove_file` → §4.3's `Removed`/`UpToDate`; + `store.compact` → the §11 report. Success results and refusal details are + snake_case; refusal `detail` is snaked in the dispatcher (or built snake at + the refusal site), and a camelCase detail is a bug; the CLI prints the + rendered map; §11 names are logical. +- `MountsActive` carries `detail.holders` (mounts/Sandboxes); `Busy` carries + `{entity, phase, op}` plus the PostgreSQL holders (`pid`, `client_addr`, + `backend_start`). `InUse` stays for non-GC calls only. +- `Unresolved` carries `{entity: {kind, name}, phase, op}` and is observed by + a non-owning call and settled by the owning one: `store.compact` adopts a + dead compaction op; `project.delete`'s settlement reads the Store by the + recorded stack id (retired/absent finishes the entry, live redoes the + marker under the project op); `sandbox.close`/`machine.remove`/ + `store.remove` clear their own ops. `logs.reset` only truncates `calls.jsonl`; it cannot clear an op. + A live owner stays `Busy`; a provably dead, certain op is ignored. +- Capacity is the real `PersistenceError::Refused { status: "Capacity" }` + path (`StorageError::is_capacity_refusal`); add `StorageError::CapacityExceeded` + to that predicate, keep PG 53100/53200/53400/54000 (53300 + `too_many_connections` is transient and maps to `Busy`; 54001 is out), and + name the SQLite codes (`SQLITE_FULL`, `SQLITE_TOOBIG`, `SQLITE_NOMEM`). + `CapacityExceeded` (a codec/canonical bound) is documented as + `InvalidInput`/`ProviderFailure`, not disk exhaustion. The `_ => Refused` + arm gets an explicit Capacity arm. ## 11. Report -While compaction runs, it writes its phase (`mark`, `build`, `verify`, -`install`) into the op, and `store.status` shows it with the op's other fields +While compaction runs, it writes its phase into the op (`mark`, `build`, +`verify`, `install` on SQLite; `mark`, `build`, `swap`, `cleanup` on +PostgreSQL), and `store.status` shows it with the op's other fields (`control/crates/layerfs-home/src/op.rs:189-201`); there is no `PROGRESS` -option (#42 item 40). `store.compact` returns: +option (#42 item 40). On PostgreSQL `store.status` reads the Store-side +`gc_op`; on SQLite it reads the home op. The `op` projection is +`{id: op_id, name, phase, started: started_ms, uncertain}` from +`gc_op`/`gc_intent`, and `state` is `busy`/`unresolved` from it; a remote +SQLite Store's op is read from its home/sidecar via `step_on`. `store.compact` +returns: | Field | Meaning | |---|---| | `path` | `none` or `rebuild` | | `generation` | `{ before, after }` | -| `logicalDiscarded` | canonical bytes of collected objects | -| `backendReusable` | SQLite: the old file's free pages; PostgreSQL: 0 for rebuilt tables | +| `deadBytesBound` | bytes in wholly dead packs after the metadata walk; the value that chose the path | +| `deadBytesRefined` | the same bytes after the payload sweep (§7 step 4) | +| `logicalDiscarded` | the collected history rows' `logical` bytes (the `store_totals.logical` delta) | +| `backendReusable` | SQLite: rebuild = the new artifact's `freelist_count * page_size` before the rename (normally 0), none = the live Store's; PostgreSQL: 0 (no in-place reclaim) | | `physicalShrink` | SQLite: old file size minus new; PostgreSQL: `pg_total_relation_size` delta | -| `keptWaste` | bytes of dead objects in retained packs, bytes kept only as delta bases (with their references), and the kept `inode_value_block` bytes | - -A zero is always explained. Estimates are marked. +| `keptWaste` | object: `{deadInRetainedPacksBytes, deltaBases: {bytes, references: [id]}, inodeBlocksBytes}` | +| `peakTempBytes` | SQLite: the new Store + rollback journal/WAL + the `visited` scratch file and its journals/super-journal; PostgreSQL: the scratch schema + WAL | +| `residue` | object `{bytes, artifacts}`; a nonzero residue is explained | + +The result is `{kind: "Compacted", ...}`. `keptWaste` is +`{deadInRetainedPacksBytes, deltaBases: {bytes, references: [id]}, +inodeBlocksBytes}`; `residue` is `{bytes, artifacts: [string], reason?}`; +top-level `estimate: bool`; a capped field is `{value, cap}`; `zeroReason` +is per zero field with the closed vocabulary `empty-store`, `none-path`, +`no-history`, `no-waste`, `postgresql-in-place`; `markBytes` is a #52 metric, +not a result field. The names in this section (e.g. `deadBytesBound`, +`keptWaste.deadInRetainedPacksBytes`) are logical Rust names only; the wire, +SDK and CLI keys are snake_case (`dead_bytes_bound`, +`kept_waste.dead_in_retained_packs_bytes`), per §10. On the `none` path `deadBytesRefined` equals `deadBytesBound` (no +payload sweep runs below the threshold), and the report says so. `physicalShrink` +reads the old size before the rename; `backendReusable` reads the SQLite +free-page count × page size before it; `logicalDiscarded` is the summed +`logical` of the collected history rows; PostgreSQL reports 0 for rebuilt tables and does +not count in-place free space. `physicalShrink` samples `pg_total_relation_size` +before and after the swap; on PostgreSQL `deadBytesRefined` equals +`deadBytesBound` (there is no payload sweep to refine it). A zero is always +explained; a capped field carries its cap (S7). ## 12. Acceptance (#52) +Each bullet is one case; its label is its case ID and must be unique. + - **Crash injection** (`kill -9`, per backend) at mark, build, verify, before and after install: wholly old or wholly new; the leftover is judged by §9. +- **Backend matrix:** every removal, admission, report and name item runs on + SQLite and PostgreSQL; a converted 1.0 Store opens with the additive step on + both. +- **Crash matrix:** named failpoints at every phase (SQLite: mark, build, + verify, install, WAL switch, artifact removal, op settle; PostgreSQL: mark, + build, swap, cleanup, scratch drop), plus lost COMMIT, power-loss + (fsync/rename) and unresolved op/lease takeover; assert §9 state, + generation, digest and closure. - **No live object lost:** property tests over random fork / commit / merge / publish / `branch.remove` / `project.delete` / `remove_file` histories; closure sets compared before and after. @@ -512,18 +1107,178 @@ A zero is always explained. Estimates are marked. transaction open at swap time makes the swap abandon. - **Admission races:** a mount and a removal of the same Branch started together never both succeed. -- **Names:** `NameTaken` after removal (Branch and project), a free name after - compaction collects the row, `ReservedName` for `main`. +- **Names:** `NameTaken` after removal (Branch and project) and on create + collision (Branch and project; project create was `Exists`), a free name + after a rebuild collects the row, `ReservedName` for `main`. - **`remove_file`:** `Removed` for Commits at or below the frontier, before and after compaction; the next Commit of a mounted older head records the - deletion; a file created later at the path is visible; bytes reclaimed only - when no other path, project or delta chain uses them. -- **Speed and space** (one sample per arm, declared caches, generated - fixtures): downtime per GB of live data and per GB freed, bytes written, - peak disk, `ACCESS EXCLUSIVE` duration on PostgreSQL. The rebuild's build - phase is compared with plain `VACUUM INTO` of the same Store; the mark is - reported separately. A storage option that costs about 50% speed for about - 5% storage is rejected. + deletion; a file created later at the path is visible; 2.0 frees no bytes + for the removed path (visibility only). +- **`remove_file` and derived nodes:** a non-fast-forward `branch.merge` of + two heads at or below the frontier keeps the path hidden (the whiteout is + materialized), and a file created after the frontier is visible; a + fast-forward merge is the control (no new tree); a `branch.publish` of a + Commit at or below the frontier yields a hidden Layer, a mount of it + whiteouts, and its next Commit records the deletion; a merge that cannot + apply the whiteout is refused `Removed`. +- **Removed path in a merge:** a non-fast-forward merge of two heads at or + below the frontier reports no conflict for the removed path and omits it; a + merge of an at-or-below head with a post-frontier re-creation keeps the + re-created file, and only an ordinary edit conflict on it is reported. +- **Unmerged Branches:** `remove_file` hides the path in a Commit on an + unmerged Branch created before the frontier; a Commit on that Branch after + the frontier does not inherit it. +- **Layer-headed mount:** a Branch whose head is empty and whose base Layer is + at or below the frontier whiteouts the path at mount. +- **Visibility only:** `remove_file` frees no bytes; an object reachable only + through the removed path is retained; the marker hides reads/listings and a + mount/merge/publish whiteouts the path. +- **Published Branch:** a Branch published by a retained Layer, or named by + a retained `commit.branch_id`, keeps its name after `branch.remove`; only an + unreferenced Branch's name is freed by a rebuild (not by a `none` pass). +- **Late base:** a delta base in an already-passed pack and a depth-2 chain + are copied by the worklist; `pack_id` is preserved. +- **Digest roots:** an uncommitted saved file's `file_digest` row is collected + unless another retained root reaches its content. +- **Path grammar:** `/a` and `a` are accepted; empty, `/`, `//a`, `a/`, + `a//b`, `./a`, `a/./b`, `.`/`..` components, `\`, NUL, >4096 bytes and >256 + components are refused `InvalidInput`; a directory hides its subtree; a + child of a removed non-directory is `NotFound`; an intermediate symlink is + `InvalidInput` and a leaf is hidden; a hardlink survives. +- **Repeated removal:** a second `remove_file` after a re-creation hides the + re-created file; a repeat with no newer project node is `UpToDate`, while a + commit in another project neither rewrites the marker nor advances it; a + never-existing path is accepted. +- **Marker epoch:** a one-shot write racing `branch.remove` or + `project.delete` gets `Conflict` and leaves no Commit; a merge racing + `remove_file` gets `Conflict`, and the retry applies the whiteout. +- **Concurrent merge and removal (property):** a merge and a `remove_file` + started together never leave the path visible in a derived tree: one side + wins, the other either sees the marker or gets `Conflict` and retries with + the whiteout. +- **Marker cleanup:** a rebuild of a Store with a deleted project leaves no + `path_removed` row for it and keeps a live project's markers; a `none` pass + writes nothing and retains them. +- **Position state:** a converted Store backfills serials; + `next_history_serial` never falls after compaction; `project_epoch` copies + and bumps only on a marker write. +- **Marker survival:** a retained `branch_retired`/`layer_stack_retired`/ + `path_removed` survives a rebuild; a collected row takes its marker with it. +- **project.delete retry:** the marker commits, the home removal fails → + hidden, entry present, `home_entry_removed: false`; a same-home retry + finishes and returns the stored `deleted_ms`, with no second marker; the + own-Init identity is saved before the marker and a save failure removes + nothing. +- **Home listing:** a second home's stale entry is absent from `project.list` + and `project.get` answers `NoSuchProject`; Store calls agree. +- **PG cleanup:** a Commit/save during Phase C survives the high-water bound; + a crash resumes from `gc_op`; a marker and its base row are deleted in one + batch (no resurrection/orphan), with a failpoint at the boundary. +- **Admission:** a mount from another home/machine is visible in the Store-side + intent; `machine_stopped` is ignored; a second mount of one project + proceeds; an uncertain dead op is `Unresolved` and the owning call clears it. +- **NameTaken:** `detail {holder: {kind, name, state: live|retired|deleted}, + source}`; a forced two-reference fixture (Layer FK and `commit.branch_id`) + keeps the name; one reference and neither are the controls. The error + matrix covers `MountsActive`, `Busy`, `NoSuchBranch`/`NoSuchCommit`/ + `NoSuchProject`, `NameTaken`, `ReservedName`, `Removed`, `InvalidInput`. +- **Trace salt:** the call log stores `` for the path; the trace key + is the keyed hash; `Removed` echoes the path; a rebuild copies the salt. +- **Admission (liveness):** a live-but-unreachable Sandbox is `Busy`; + `machine_stopped` is ignored; a `gc_intent` from another home is visible; + `Unresolved` is observed by a non-owning call and settled by the owner. +- **Checkpoint/install:** a live reader makes `wal_checkpoint(TRUNCATE)` + return `busy>0` → `Busy`, no artifact, no op; a sidecar or `-mj*` at install + is `Conflict` with no writes. +- **Bind failure:** a committed intent whose bind fails is deleted in the + error path; a failed delete is reported; no `MountsActive` remains. +- **PG refcount:** two mounts keep the Store/project keys after one unmount; + a failed all-or-none acquire unlocks the taken subset. +- **Worker/lost reply:** an unreachable worker op is `unknown, never clean`; + a lost reply keeps the sidecar and the retry resolves retired/live/absent. +- **Trace:** the six path names are redacted; refusal details are not traced; + the salt is backfilled for an upgraded Store. +- **Artifacts (cross-backend):** SQLite leaves/removes + `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`; + PostgreSQL's `lfs_gc_` is recorded before CREATE, removable from + another machine, and a stray schema is `Exists`. +- **Position state (2.0 backfill):** every upgraded Store (2.0 included) + gets one `project_epoch` row per stack; `gc_op` is cleared on settle and + not copied; `next_history_serial` never lowered. +- **Digest agreement:** SQLite and PostgreSQL report the same + `live_heads_digest` for the same fixture; a retired head changes it. +- **PostgreSQL mark:** the mark transfers only `markBytes`; the table copy + moves no bytes; a base object that only a dead pack holds is kept. +- **Reserved pack:** a Save that reserves a pack/ordinal before the mark and + publishes during Phase A (or Phase C) moves `store_totals`; the swap + `Conflict`s, the pack stays in the old Store, and the cleanup failpoint + keeps it; no dangling location. +- **PG cleanup (resume):** after the swap the Store is usable at `G + 1`; + Phase C resumes after a crash; totals/ACL/trigger/hints are asserted (no + `inode` on PG; that assertion belongs to the SQLite install). +- **PG privileges and reply:** missing `CREATE`/`TEMP`/`pg_read_all_stats` is + `Unsupported`; a lost `COMMIT` reply is resolved by proving the backend + ended, then reading the incarnation. +- **SQLite layouts:** schema 36 (`Monolithic`), 37 (`GroupRows`), 38 + (`GroupRowsIndexed`) and their 42/43/44 acquisition variants rebuild; + `Monolithic` copies `pack` (body) and no `pack_unit`; `GroupRows` copies + both; `GroupRowsIndexed` copies `pack_unit` and the schema creates its + index (not "copied"); `sqlite_sequence` is kept when present and + `init_*`/acquisition tables are empty. +- **Install fence:** a connection that bypassed the writer lane and opens a + transaction after install gets `StaleStore`; an in-flight transaction is + excluded by the lane (a documented limit); a sealed-state or sidecar change + makes install `Conflict` with no writes. +- **Artifacts (SQLite exact):** a crash leaves + `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`; the next + compact removes all of it; `none` leaves no `.compact`; a stray name with + no op is `Exists`. +- **Threshold and failures:** 9% wholly dead → `none`; 10% and 30% → + `rebuild`; an empty Store (0/0, COALESCEd sums) → `none` with a + `zeroReason`; a started rebuild completes when the refined share drops + below 10%; `Capacity` and a verify failure abort, delete the artifact set + and leave the old Store unchanged apart from step 1's checkpoint. +- **Mount/compact race:** a mount during compact is `Busy` with the compact + op; compaction returns `MountsActive` when a mount wins; a Commit during the + rebuild is not lost (PG: a write during Phase A makes the swap `Conflict`; + during Phase C it survives the high-water bound). +- **Profile and scope:** all four calls are refused under a folder scope + (`out of scope`) and allowed only in the MCP admin profile. +- **Progress:** while `store.compact` runs, `store.status` shows the op phase + (`mark`, `build`, `verify`, `install` on SQLite; `mark`, `build`, `swap`, + `cleanup` on PostgreSQL). +- **Report:** both paths; `kind:"Compacted"`, snake_case keys, every §11 + field with its unit and sampling point (`freelist_count * page_size`, old + size before rename, history `logical` delta, peak temp = new file + + journal/WAL + visited, `physicalShrink`, `keptWaste` components, + `residue {bytes,artifacts}`, `estimate`, capped `cap`, a `zeroReason`); + `markBytes` is a #52 metric (PG-only, not a result field); + `keptWaste` is `{deadInRetainedPacksBytes, deltaBases:{bytes,references}, + inodeBlocksBytes}`; bound≥refined; PG `backendReusable = 0` and PG/none + `deadBytesRefined == deadBytesBound`. +- **Read surface:** `file.read`/`stat`/`list`/`glob`/`diff`/`revision`/ + `export`/cp-from before and after compaction, with the §4.3 shapes; add + `edit`/`grep`/`blame`/`rm`/`mv`/`mkdir`/`cp`/`apply`, the + visible/hidden/absent diff table, `removed_count` (0 and >0), + `branch.diff`/`commit.diff`, and one whiteout case per one-shot tree + creator (`write`/`edit`/`apply`/`rm`/`mkdir`/`mv`/`cp`). +- **Restore and listing:** `backup.restore` before and after a removal; a + second home's stale entry; the §4.2 guard test and allow-list. +- **Error matrix:** exact code and message per case, including `StaleStore`, + `Removed`, `InvalidInput` for `project.remove`, `Exists`, `Unsupported` and + `Capacity`. +- **Digest golden vector:** a fixed-id fixture (out-of-order ids, a retired + Branch and stack, differing timestamps) hashes to one literal vector on both + backends; an absent head is 33 zero bytes, not 32, and widths are fixed at + 17/33. +- **Speed and space** (at least three runs per arm, median and range, + declared caches, generated fixtures): downtime per GB of live data and per + GB freed, bytes written, peak disk, `ACCESS EXCLUSIVE` duration on + PostgreSQL. Downtime per GB freed is absolute bytes when nothing is freed + (the `none` path and removal-only runs). The rebuild's build phase is + compared with plain `VACUUM INTO` of the same Store; the mark is reported + separately. A storage option that costs about 50% more time for about 5% + less space is rejected. ## 13. Estimates, not measurements @@ -532,3 +1287,18 @@ the review of 2026-11-14 estimated about 2–3 minutes of downtime for §7, and hours if the full doctor ran before and after. For PostgreSQL with the same Store, about 9 minutes in total with `ACCESS EXCLUSIVE` held for about two seconds. Nothing has been measured; #52 owns the numbers. + +#52 measures, per backend, these arms: `none` at 9% wholly dead; `rebuild` at +10% and 30%; a 50 GB total / 35 GB live (30% dead) Store, plus a 50 GB +live-store arm; and each removal type (branch, project, remove_file) as a +marker-only arm, plus removal-then-compact at a declared share. A +`remove_file`/`remove_file`-then-compact arm is 0-freed and reports absolute +bytes. At least three runs per arm, median and range; declare the hardware, +SQLite 3.53.2 with `page_size`, `journal_mode`, caches, `synchronous_commit` +and PostgreSQL version. Record the +§11 fields, `markBytes`, downtime per GB of live data and absolute bytes when +nothing is freed (0/0 or removal-only), bytes written, peak disk, +`ACCESS EXCLUSIVE` duration, WAL bytes and the `VACUUM INTO` baseline; use +`store.status` for the phase. A storage option that costs about 50% more time +for about 5% less space is rejected, naming the option and the measured +numbers. diff --git a/core/docs/issues/project-41/gc-acceptance-matrix.md b/core/docs/issues/project-41/gc-acceptance-matrix.md new file mode 100644 index 0000000000..e462bf967e --- /dev/null +++ b/core/docs/issues/project-41/gc-acceptance-matrix.md @@ -0,0 +1,187 @@ +# GC acceptance matrix: #52 evidence plan for the §12 cases + +> Draft matrix for the frozen `LayerFS-GC-spec.md` §12 (the spec wins; this +> page adds no contract). The plan was written at main layer `32d78561a`; +> statuses below are re-checked on main `32ae51ca` (T-G75) and reconciled +> against the reports published on main: T12.3c at `3282f9f6865` regenerated +> [`gc-t12.3a-sqlite-matrix-report.md`](gc-t12.3a-sqlite-matrix-report.md) +> (executed 8 / covered 29 / partial 16 / deferred 7 / SQLite gaps 0), beside +> T12.3a/T12.3b/T9/T10/T-G6a; T-G28 added the real-process SIGKILL arms and +> moved AC-01 to `partial`; T-G60 extended them to the mark, copy, verify and +> rename points; T-G38 and T-G54 supplied the real PostgreSQL +> reply-loss and restricted-role privilege arms and moved AC-44 to `covered`; +> T-G65 killed the real `layerfs store compact` process itself at the mark, +> build, verify and install points and moved AC-01 back to `covered`. +> The final counts are executed 8 / covered 30 / partial 16 / deferred 6; +> T-G75 re-ran the SQLite suites from `32ae51ca` and re-checked all 60 rows. +> AC-01..AC-57 are the §12 bullets one-to-one, in +> spec order; AC-58..AC-60 pin sub-steps of §7/§8 that §12 folds into broader +> cases. Each row's expected result restates spec text only; a mismatch is a +> spec bug, not a matrix change. +> +> Status vocabulary: `executed` (a T12.3c runner arm really executes the +> case), `covered` (a named existing test or fixture covers it), `partial` +> (some named arms proven; the evidence cell says what remains), `deferred` (a +> PostgreSQL-only row the SQLite runner leaves to T12.3b by name), `pass` (the +> named arm passed in the recorded run), `pending` (no §12-conforming evidence +> recorded yet; none remain). The dispositions +> are the SQLite half; the PostgreSQL half is T12.3b and its evidence stays +> named below. T-G66 measured the 50 GB `none` and `rebuild` arms (one run each); +> §13's measurement caveat now applies to the 30% dead and 50 GB-live arms, and +> an E3 row records the three-run or property evidence that exists and stays +> `partial` where it does not. +> Tiers are this page's evidence scale, not contract. + +## Evidence tiers (E0-E3) + +| Tier | Meaning | +|---|---| +| E0 | Spec reasoning only; no executable evidence. Does not accept a case. | +| E1 | One deterministic test on the named backend, fixed fixture, exit asserted. | +| E2 | Deterministic CI test on both backends (or the named backend's full named-phase/failpoint matrix), fixed fixture, state, refusal and digest asserted. | +| E3 | Measured or statistical: at least 3 runs with median and range (hardware, caches and versions declared), a property test over random histories, or a 50 GB scale arm. | + +## Matrix + +| Case ID | Contract (spec §) | Backend | Fixture / command | Expected result | Tier | Status | Evidence | +|---|---|---|---|---|---|---|---| +| AC-01 | §12 Crash injection; §9 | both | Store with one wholly dead pack; `kill -9` the daemon at mark, build, verify, before and after install; next `store.compact` | Store is wholly old or wholly new; the leftover is judged by §9; generation and digest asserted | E2 | covered | T12.3a `sqlite_compact_crash.rs#crash_before_seal`..`#crash_after_install` (in-process failpoints); T-G28/T-G60 `sqlite_compact_crash.rs::real_process` `#sigkill_before_seal`, `#sigkill_after_seal` (mark), `#sigkill_during_copy` (copy; the gate is immediately before `VACUUM INTO`, because SQLite's copy cannot be interrupted mid-call), `#sigkill_during_verify` (verify), `#sigkill_during_rename`, `#sigkill_before_install` and `#sigkill_after_install` (install), `#sigkill_after_build` (build) and `#sigkill_during_settle` (settle) - 9 re-executed-test-child SIGKILL arms; T-G65 `api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs` `#sigkill_before_seal`, `#sigkill_after_seal` (mark), `#sigkill_before_vacuum`, `#sigkill_after_build` (build), `#sigkill_during_verify`, `#sigkill_before_install` (verify), `#sigkill_after_install`, `#sigkill_during_settle` (install) - 8 SIGKILL arms that start the built `layerfs store compact` command, wait through the engine's socket gate and kill that process (`status.signal() == 9`) at a Store with one wholly dead pack, then reopen through the CLI and assert `G`/`G + 1`, the artifact set and killed-session sidecars, the `store.status` phase/`uncertain`/`unresolved`, the next compact settling with empty residue, the retained layer readable and `doctor` clean; T12.3b `postgresql_compact.rs#every_postgresql_failpoint_leaves_a_resumable_leftover` (in-process, no `kill -9`) - `covered` for SQLite because the killed process is the production process that performs the compaction (no daemon serves Store calls, #352 F-020); the residual is that the long-lived `layerfs worker` serving a machine's Store is still not exercised, and the PostgreSQL half remains T12.3b's | +| AC-02 | §12 Backend matrix; §4.1 | both | Run every removal, admission, report and name case on SQLite and PostgreSQL; open a converted 1.0 Store on both | Each case's §12 result holds on both backends; the additive step adds the §4.1 tables on both | E2 | partial | T12.3a `sqlite_compact.rs#a_wholly_dead_pack_is_rebuilt_away`; T12.3b `postgresql_position_columns` 4/4 (converted 1.0 Store arm is SQLite-only) | +| AC-03 | §12 Crash matrix; §9 | both | Named failpoints: SQLite mark, build, verify, install, WAL switch, artifact removal, op settle; PG mark, build, swap, cleanup, scratch drop; plus lost COMMIT, power loss (fsync/rename) and unresolved op/lease takeover | §9 state, generation, digest and closure hold after resume; only a live owner blocks; an unreachable machine reports unknown, never clean | E2 | covered | T12.3a `sqlite_compact_crash.rs#crash_after_wal_switch` + mark/build/verify/install failpoints; T12.3b `postgresql_compact.rs#every_postgresql_failpoint_leaves_a_resumable_leftover`; lost COMMIT/power loss deferred | +| AC-04 | §12 No live object lost; §6.1-§6.2 | both | Property test over random fork, commit, merge, publish, `branch.remove`, `project.delete` and `remove_file` histories; compare closure sets before and after | No live object reaches a collected row; the retained closure is unchanged | E3 | partial | T12.1 `sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript`; T12.3a `sqlite_compact_matrix.rs#arm_random_store_shapes` (seeded; full random generator deferred) | +| AC-05 | §12 Independent walk; §9 | both | After compaction, walk the new Store with `diagnostic/scan.rs` and run the full doctor on the fixtures (#155 D-23) | Walk and doctor pass on the compacted Store; no dangling reference | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact_fixtures.rs#the_rebuild_report_and_markers_hold_on_postgresql`; `postgresql_diagnostic` 5/5 | +| AC-06 | §12 Regression; §6.4 | both | After compaction, Save bytes whose `file_digest` row named a collected root | The Save succeeds; no stale digest row blocks it | E2 | executed | T12.3c `sqlite_compact_matrix.rs#arm_digest_row_after_collection` - a Save whose `file_digest` row named a root the rebuild collected; the row goes with its root, recording the same content again succeeds and points at the new root; PostgreSQL half T12.3b | +| AC-07 | §12 Fences; §10 | both | A connection that bypassed admission; a second compaction; a remote PG daemon holding a mount; a one-shot SDK transaction open at swap time | Bypass gets `StaleStore`; second compaction gets `Busy`; the mount blocks compaction and the matching removal, naming itself; the open transaction makes the swap abandon | E2 | executed | T12.3c `sqlite_compact_matrix.rs#arm_mount_and_compaction_exclude_each_other`; `sqlite_compact.rs#a_store_replaced_under_an_open_handle_is_stale_at_the_next_transaction` - bypass gives `StaleStore`; a live mount makes compaction `MountsActive` naming it; a live compaction refuses a mount and a second compaction `BusyOp`, leaving no op; the open one-shot SDK transaction arm is PostgreSQL (T12.3b) | +| AC-08 | §12 Admission races; §5.1 | both | Start a mount and a removal of the same Branch together | Never both succeed; the loser gets `MountsActive` or `Busy` | E2 | covered | T12.3a `admission.rs#a_concurrent_mount_and_branch_remove_have_one_winner` (SQLite half; PG arm not recorded) | +| AC-09 | §12 Names; §4.4 | both | `NameTaken` after removal (Branch and project); create collision (Branch and project; project create was `Exists`); free name after a rebuild collects the row; `ReservedName` for `main` | Exact codes per §4.4; only a rebuild frees an unreferenced name | E2 | covered | T12.3a `branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names`; `gc_calls.rs#branch_remove_refuses_reserved_and_absent_branches` (SQLite half) | +| AC-10 | §12 remove_file; §4.3 | both | `Removed` for Commits at or below the frontier, before and after compaction; the next Commit of a mounted older head records the deletion; a file created later at the path is visible | Codes and visibility per §4.3; 2.0 frees no bytes for the removed path | E2 | covered | T12.3a `path_removal.rs#marker_frontier_and_up_to_date_follow_the_store_position` (SQLite half) | +| AC-11 | §12 remove_file and derived nodes; §4.3 | both | Non-FF `branch.merge` of two heads at or below the frontier; a post-frontier re-creation; a FF merge control; `branch.publish` of an at-or-below Commit; a merge that cannot apply the whiteout | Path stays hidden, whiteout materialized; post-frontier file visible; FF merge creates no tree; published Layer hidden, its mount whiteouts, next Commit records the deletion; inapplicable whiteout refused `Removed` | E2 | partial | T12.3c `sdk_path_whiteouts.rs#a_merge_of_two_hidden_sides_keeps_the_path_absent`; `sdk_path_whiteouts.rs#a_merge_keeps_a_post_frontier_re_creation`; `sdk_path_merge_removal.rs#a_fast_forward_merge_creates_no_tree_and_the_path_stays_hidden`; `sdk_path_merge_removal.rs#publishing_an_at_or_below_commit_yields_a_hidden_layer_and_a_layer_headed_mount` - non-FF whiteouts, the FF control, a post-frontier re-creation and publish-at-or-below with a layer-headed mount whiteout execute; partial because a merge that cannot materialize the whiteout has no implementation branch to refuse (`removal::derive_root` always derives), so that clause is deferred by name, not claimed | +| AC-12 | §12 Removed path in a merge; §4.3 | both | Non-FF merge of two at-or-below heads; merge of an at-or-below head with a post-frontier re-creation | No conflict for the removed path, it is omitted; the re-created file is kept and only an ordinary edit conflict on it is reported | E2 | covered | T12.3c `sdk_path_whiteouts.rs#a_merge_of_two_hidden_sides_keeps_the_path_absent`; `sdk_path_whiteouts.rs#a_merge_keeps_a_post_frontier_re_creation`; `sdk_path_merge_removal.rs#a_recreated_removed_path_still_conflicts_as_an_ordinary_edit` - a removed path in a merge is omitted with no conflict; a post-frontier re-creation is kept and only an ordinary edit conflict on it is reported | +| AC-13 | §12 Unmerged Branches; §4.3 | both | `remove_file` then a Commit on an unmerged Branch created before the frontier; another Commit after the frontier | The earlier Commit's path is hidden, the later one does not inherit it | E2 | covered | T12.3c `sdk_path_merge_removal.rs#an_unmerged_branch_created_before_the_frontier_hides_but_does_not_inherit` - the earlier Commit on an unmerged Branch created before the frontier is hidden by the marker; a Commit after the frontier does not inherit the path | +| AC-14 | §12 Layer-headed mount; §4.3 | both | Branch whose head is empty and whose base Layer is at or below the frontier; mount it | The path is whiteouted at mount | E2 | covered | T12.3c `sdk_path_merge_removal.rs#publishing_an_at_or_below_commit_yields_a_hidden_layer_and_a_layer_headed_mount`; `sdk_path_whiteouts.rs#a_marker_under_a_live_mount_is_refused_and_materializes_after_it_closes` - a Branch whose head is empty and whose base Layer is at or below the frontier whiteouts the path at mount, and its next Commit records the deletion | +| AC-15 | §12 Visibility only; §6.2 | both | Object reachable only through the removed path; marker hiding reads/listings; mount, merge and publish whiteouts | No bytes freed; the object is retained; reads/listings hide the path; derived trees whiteout it | E2 | partial | T12.3a `kept_objects.rs#a_retained_tree_and_inode_are_kept_with_their_packs`; T12.1 fixture (read/listing hiding and derived whiteouts not one test) | +| AC-16 | §12 Published Branch; §4.4 | both | Branch published by a retained Layer; Branch named by a retained `commit.branch_id`; `branch.remove` then rebuild | Name stays taken; only an unreferenced Branch's name is freed by a rebuild (not by a `none` pass) | E2 | covered | T12.3a `branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names`; T12.1 fixture (SQLite half) | +| AC-17 | §12 Late base; §7 step 4 | both | Delta base in an already-passed pack; a depth-2 chain | Worklist copies both; `pack_id` preserved | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact_fixtures.rs#the_rebuild_report_and_markers_hold_on_postgresql` (depth-2 chain, `pack_id` kept) | +| AC-18 | §12 Digest roots; §6.4 | both | Uncommitted saved file's `file_digest` row; another retained root reaching its content | Row collected unless the retained root reaches the content | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact_fixtures.rs#the_rebuild_report_and_markers_hold_on_postgresql` | +| AC-19 | §12 Path grammar; §4.3 | both | `/a` and `a`; empty, `/`, `//a`, `a/`, `a//b`, `./a`, `a/./b`, dot and dot-dot components, backslash, NUL, >4096 bytes, >256 components; directory subtree; child of a removed non-directory; symlink leaf and intermediate component; hardlink | Accepted paths hide correctly; bad forms are `InvalidInput`; directory hides its subtree; child of removed non-directory `NotFound`; intermediate symlink `InvalidInput`, leaf hidden; hardlink survives | E2 | partial | T12.3a `gc_calls.rs#project_remove_file_checks_its_path_grammar_then_reports_markers`; `path_removal.rs#marker_frontier_and_up_to_date_follow_the_store_position` (full form table missing) | +| AC-20 | §12 Repeated removal; §4.3 | both | Second `remove_file` after a re-creation; repeat with no newer project node; a commit in another project; never-existing path | Re-creation hidden; repeat `UpToDate`; other project neither rewrites nor advances the marker; never-existing path accepted, hides nothing | E2 | partial | T12.3a `path_removal.rs#a_raw_marker_frontier_also_yields_up_to_date`; `#an_unknown_project_is_missing` (re-creation/other-project arms partial) | +| AC-21 | §12 Marker epoch; §5 | both | One-shot write racing `branch.remove` or `project.delete`; merge racing `remove_file` | `Conflict`, no Commit left; retry applies the whiteout | E2 | partial | T12.3a `epoch_fence.rs#an_epoch_change_during_a_commit_is_detected_and_rolled_back`; T12.3b `postgresql_compact_fixtures.rs#a_marker_write_bumps_the_epoch_and_the_fence_refuses_a_racing_write` (true concurrent PG trigger arm missing) | +| AC-22 | §12 Concurrent merge and removal (property); §4.3 | both | Property test: a merge and a `remove_file` started together | The path is never left visible in a derived tree; one side wins, the other sees the marker or gets `Conflict` and retries with the whiteout | E3 | covered | T12.3c `sdk_path_merge_removal.rs#a_merge_and_a_removal_started_together_never_leave_the_path_visible`; `epoch_fence.rs#an_epoch_change_during_a_merge_is_detected_and_rolled_back` - a deterministic barrier starts a merge and a `remove_file` together for three rounds; the loser sees the marker or gets `Conflict` and retries with the whiteout, and a derived tree never shows the path; PostgreSQL half T12.3b | +| AC-23 | §12 Marker cleanup; §6.4 | both | Rebuild of a Store with a deleted project and a live project with markers; a `none` pass | No `path_removed` row for the deleted project; live markers kept; `none` writes nothing and retains them | E2 | partial | T12.3a `project_delete.rs#deleting_a_project_hides_it_and_marks_once`; T12.1 fixture (dedicated marker-cleanup arm missing) | +| AC-24 | §12 Position state; §4.1 | both | Converted Store; `store.compact`; a marker write | Serials backfilled; `next_history_serial` never falls; `project_epoch` copied and bumped only on a marker write | E2 | covered | T12.3a `gc_backfill.rs#commits_layers_and_epochs_are_backfilled_in_deterministic_order`; T12.3b `postgresql_position_columns` + fixture | +| AC-25 | §12 Marker survival; §4.4 | both | Retained `branch_retired`, `layer_stack_retired` and `path_removed`; a collected base row | Retained markers survive a rebuild; a collected row takes its marker with it | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact_fixtures.rs#the_rebuild_report_and_markers_hold_on_postgresql` | +| AC-26 | §12 project.delete retry; §4 | both | Marker commits and home removal fails; same-home retry; own-Init identity save failure | Hidden, entry present, `home_entry_removed: false`; retry finishes and returns the stored `deleted_ms`, no second marker; the identity save precedes the marker, a save failure removes nothing | E2 | covered | T12.3a `project_delete.rs#retry_classifies_retired_live_and_absent`; `#deleting_a_project_hides_it_and_marks_once` (SQLite half) | +| AC-27 | §12 Home listing; §4.2 | both | Second home's stale entry; `project.list` and `project.get`; Store calls | Stale entry absent from `project.list`, `project.get` answers `NoSuchProject`; Store calls agree | E2 | covered | T12.3a `project_delete.rs#paging_skips_a_hidden_project`; `#every_layer_stack_lookup_carries_the_marker_filter` (SQLite half) | +| AC-28 | §12 PG cleanup; §8 Phase C | PG | Commit/save during Phase C; crash mid-cleanup; failpoint at the marker/base-row batch boundary | The late write survives the high-water bound; cleanup resumes from `gc_op`; marker and base row deleted in one batch, no resurrection or orphan | E2 | deferred | T12.3b `postgresql_compact_fixtures.rs#a_save_after_the_swap_survives_the_resumed_cleanup`; `#every_postgresql_failpoint_leaves_a_resumable_leftover` (marker/base-row batch failpoint still missing) | +| AC-29 | §12 Admission; §5.1 | both | Mount from another home or machine; `machine_stopped` evidence; a second mount of one project; an uncertain dead op | The mount is visible in the Store-side intent; `machine_stopped` ignored; the second mount proceeds; `Unresolved` observed and settled by the owning call | E2 | covered | T12.3a `admission.rs#a_mount_blocks_all_three_removals_until_released`; T12.3b `postgresql_compact.rs` owner-adoption tests (mount-work admission deferred) | +| AC-30 | §12 NameTaken; §4.4 | both | `NameTaken` detail for live, retired and deleted holders; forced two-reference fixture (Layer FK and `commit.branch_id`); one-reference and no-reference controls; error matrix | Detail carries holder kind, name and state; two references keep the name, the controls do not; matrix covers `MountsActive`, `Busy`, `NoSuchBranch`, `NoSuchCommit`, `NoSuchProject`, `NameTaken`, `ReservedName`, `Removed`, `InvalidInput` | E2 | partial | T12.3a `branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names`; `gc_calls.rs#wrong_kinds_and_unknown_options_are_refused_before_any_effect` (PG detail matrix deferred) | +| AC-31 | §12 Trace salt; §4.3 | both | Call log with path arguments; `Removed` refusal; rebuild | Log stores ``, trace key is the keyed hash; `Removed` echoes the path; the salt is copied by the rebuild | E2 | covered | T12.3a `gc_trace.rs#path_arguments_are_byte_counts_in_the_call_log`; `#the_trace_key_is_salted_by_the_store_policy_salt` (PG salt backfill deferred) | +| AC-32 | §12 Admission (liveness); §5.1 | both | Live-but-unreachable Sandbox; `machine_stopped`; `gc_intent` from another home; non-owning call | Live-unreachable is `Busy`; `machine_stopped` ignored; the other home's intent visible; `Unresolved` observed by the non-owner and settled by the owner | E2 | partial | T12.3a `admission.rs#a_live_operation_is_busy_and_an_uncertain_owner_is_unresolved`; T12.3b owner-adoption tests (other-home intent deferred) | +| AC-33 | §12 Checkpoint/install; §7 steps 1, 7 | SQLite | Live reader during `wal_checkpoint(TRUNCATE)`; a sidecar or `-mj*` present at install | `busy>0` makes the checkpoint `Busy` with no artifact and no op; a sidecar at install is `Conflict` with no writes | E2 | executed | T12.3a `sqlite_compact_matrix.rs#arm_checkpoint_busy`; `#arm_sidecar_at_install` | +| AC-34 | §12 Bind failure; §5.1 | both | Committed intent whose bind fails; failed intent delete | Intent deleted in the error path; the failed delete is reported; no `MountsActive` remains | E2 | partial | T12.3c `sdk_mount_bind_failure.rs#a_bind_failure_cleans_its_intent_and_leaves_no_mounts_active` - a committed mount intent whose bind fails at the root check is deleted in the error path and no `MountsActive` remains; partial because the failed-delete sub-arm is not inducible on SQLite (the schema guard rejects a trigger on `gc_intent`, and a lock held across the bind refuses the register) and the explicit `Cleanup` report is covered by the seam code path, not executed; PostgreSQL half T12.3b | +| AC-35 | §12 PG refcount; §5.2 | PG | Two mounts, one unmount; failed all-or-none acquire | Store and project advisory keys stay after one unmount; the failed acquire unlocks the taken subset | E2 | deferred | T12.3b deferred: PG advisory-key refcount is the mount/admission layer; no compaction fixture | +| AC-36 | §12 Worker/lost reply; §4, §9 | both | Unreachable worker op; lost reply; retry | Op is `unknown`, never clean; the sidecar is kept; the retry resolves retired, live or absent | E2 | covered | T12.3c `project_delete_worker.rs#a_lost_worker_reply_is_unknown_and_keeps_the_sidecar_for_the_retry`; `project_delete.rs#a_retired_retry_reuses_the_intent_deleted_ms_and_finishes_the_entry`; `project_delete.rs#an_absent_stack_finishes_a_stale_entry` - a lost marker reply is `Unknown` with the sidecar kept; the retry resolves retired, live or absent; PostgreSQL half T12.3b | +| AC-37 | §12 Trace; §4.3 | both | Six path names; refusal details; upgraded Store | The six path names are redacted; refusal details are not traced; the salt is backfilled | E2 | partial | T12.3a `gc_trace.rs#the_redacted_set_covers_every_path_bearing_call`; `#the_trace_key_is_salted_by_the_store_policy_salt` (PG salt backfill deferred) | +| AC-38 | §12 Artifacts (cross-backend); §9 | both | SQLite artifact set `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`; PG `lfs_gc_` schema; a stray schema | SQLite leaves and removes the full set; PG records the name before CREATE, a remote machine can remove it, a stray schema is `Exists` | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact.rs#every_postgresql_failpoint_leaves_a_resumable_leftover` (remote/stray-schema arms deferred) | +| AC-39 | §12 Position state (2.0 backfill); §4.1 | both | Every upgraded Store (2.0 included); `gc_op` settle; serial allocation | One `project_epoch` row per stack; `gc_op` cleared on settle and not copied; `next_history_serial` never lowered | E2 | covered | T12.3a `gc_backfill.rs#commits_layers_and_epochs_are_backfilled_in_deterministic_order`; T12.3b `postgresql_position_columns` 4/4 + fixture | +| AC-40 | §12 Digest agreement; §6.4 | both | Same fixture on SQLite and PostgreSQL; retired head | Same `live_heads_digest`; a retired head changes it | E2 | covered | T12.1 fixture; T12.3b `postgresql_compact_fixtures.rs#the_live_heads_digest_vector_is_the_sqlite_literal` + rebuild fixture | +| AC-41 | §12 PostgreSQL mark; §8 Phase M | PG | Mark transfer; table copy; a base object held only by a dead pack | Only `markBytes` crosses the wire; the copy moves no pack bytes; the base is kept | E2 | deferred | T12.3b `postgresql_compact_fixtures.rs#the_rebuild_report_and_markers_hold_on_postgresql` (depth-2 `pack_id` kept; `markBytes` is a #52 metric, not a result field) | +| AC-42 | §12 Reserved pack; §8 Phase B | PG | Save reserves a pack/ordinal before the mark and publishes during Phase A (or C); cleanup failpoint | `store_totals` moves; the swap `Conflict`s; the pack stays in the old Store; the failpoint keeps it; no dangling location | E2 | deferred | T12.3b deferred: the PG round has no pause point between build and swap; the reserved-pack race is not deterministically injectable | +| AC-43 | §12 PG cleanup (resume); §8 Phase C | PG | After the swap at `G+1`; crash mid-cleanup; totals, ACL, trigger, hints | Store usable at `G+1`; cleanup resumes; totals/ACL/trigger/hints asserted; no `inode` on PG | E2 | deferred | T12.3b `#the_rebuild_report_and_markers_hold_on_postgresql`; `#a_save_after_the_swap_survives_the_resumed_cleanup` | +| AC-44 | §12 PG privileges and reply; §8 | PG | Missing `CREATE`, `TEMP` or `pg_read_all_stats`; lost `COMMIT` reply | `Unsupported`; the lost reply is resolved by proving the backend ended, then reading the incarnation | E2 | covered | T-G38 `postgresql_compact.rs#a_killed_backend_before_the_swap_commit_leaves_the_store_at_g` (a real `pg_terminate_backend(pid, backend_start)` parks Phase B's `gc_op` update before COMMIT: the Store is wholly at `G`, the owner is proved ended and the next `store.compact` adopts the `G` leftover); `#a_killed_backend_during_phase_c_resumes_at_g_plus_1` (a real kill in Phase C after the swap COMMIT: wholly at `G + 1`, the next call reads the incarnation and finishes Phase C); `#a_lost_swap_reply_from_an_ended_owner_resumes_at_g_plus_1` (`PostgresAfterSwap` simulated lost reply, owner then really killed, fresh connection resolves). The privilege half is T-G54 `postgresql_compact.rs#a_role_without_create_on_the_database_is_refused_as_unsupported`, `#a_role_without_create_on_the_store_schema_is_refused_as_unsupported`, `#a_role_without_temp_is_refused_as_unsupported` and `#a_role_without_pg_read_all_stats_is_refused_as_unsupported` (each restricted role is `Unsupported` naming its missing privilege, asserted before the intent, the mark and any scratch schema) plus `#a_fully_privileged_role_compacts` (the owner role with all five grants rebuilds at `G + 1`); `access.rs` now also checks both `CREATE`s and `pg_read_all_stats` | +| AC-45 | §12 SQLite layouts; §7 step 2 | SQLite | Schema 36 (`Monolithic`), 37 (`GroupRows`), 38 (`GroupRowsIndexed`) and their 42/43/44 acquisition variants rebuild | `Monolithic` copies `pack` body and no `pack_unit`; `GroupRows` copies both; `GroupRowsIndexed` copies `pack_unit` and the schema creates its index; `sqlite_sequence` kept when present; `init_*`/acquisition tables empty | E1 | covered | T12.3a `sqlite_compact.rs#group_rows_layout_opens_compacts_and_takes_none`; `#group_rows_indexed_layout_opens_compacts_and_takes_none`; `#acquisition_layout_opens_compacts_and_clears_working_rows` | +| AC-46 | §12 Install fence; §10 | SQLite | Connection that bypassed the writer lane opening a transaction after install; in-flight transaction; sealed-state or sidecar change at install | `StaleStore`; the in-flight transaction is excluded by the lane (documented limit); a sealed-state or sidecar change is `Conflict` with no writes | E2 | executed | T12.3a `sqlite_compact_matrix.rs#arm_sidecar_at_install`; `sqlite_compact.rs#a_store_replaced_between_seal_and_install_is_stale`; `#a_store_replaced_under_an_open_handle_is_stale_at_the_next_transaction` | +| AC-47 | §12 Artifacts (SQLite exact); §9 | SQLite | Crash mid-compact; next compact; `none` pass; stray name with no op | Crash leaves the full `.compact` set; the next compact removes all of it; `none` leaves no `.compact`; a stray name is `Exists` | E2 | covered | T12.3a `sqlite_compact_crash.rs#crash_during_copy`; `#crash_during_settle`; `sqlite_compact.rs#a_stray_staged_name_is_refused_and_not_deleted` | +| AC-48 | §12 Threshold and failures; §3 | both | 9%, 10% and 30% wholly dead; empty Store (0/0); started rebuild whose refined share falls below 10%; `Capacity`; verify failure | 9% is `none`, 10% and 30% are `rebuild`; empty Store is `none` with `zeroReason: empty-store`; the started rebuild completes; `Capacity` and verify failure abort, delete the artifact set and leave the old Store unchanged apart from step 1's checkpoint | E2 | covered | T12.3a `sqlite_compact.rs#nine_percent_wholly_dead_bytes_take_the_none_path`; `#ten_percent_wholly_dead_bytes_rebuild_at_the_threshold`; `#thirty_percent_wholly_dead_bytes_rebuild_above_the_threshold`; `#an_empty_store_takes_the_none_path`; `#a_capacity_failure_leaves_the_store_unchanged` (PG boundary arms not separately run) | +| AC-49 | §12 Mount/compact race; §5, §8 | both | Mount during compact; mount wins the race; Commit during the rebuild | `Busy` with the compact op; compaction returns `MountsActive` when the mount wins; the Commit is not lost (PG Phase A write makes the swap `Conflict`; Phase C survives the high-water bound) | E2 | executed | T12.3c `sqlite_compact_matrix.rs#arm_mount_during_compaction_is_busy`; `sqlite_compact_matrix.rs#arm_commit_during_rebuild`; `admission.rs#a_concurrent_mount_and_branch_remove_have_one_winner` - a mount during compaction is `BusyOp` with the compaction; compaction returns `MountsActive` when the mount wins; a Commit racing the rebuild is `StaleStore` or lands on `G + 1` and its retry is never lost; PG Phase A/C arms are T12.3b | +| AC-50 | §12 Profile and scope; §10 | both | All four calls under a folder scope; MCP admin profile | Refused `out of scope`; allowed only in the admin profile | E2 | covered | T12.3a `calls_scope.rs#a_scope_refuses_every_call_it_does_not_cover`; `gc_calls.rs#the_four_gc_calls_take_ids_only` (SQLite-side control test; PG not separate) | +| AC-51 | §12 Progress; §11 | both | `store.compact` running; `store.status` | `store.status` shows the op phase: SQLite `mark`, `build`, `verify`, `install`; PG `mark`, `build`, `swap`, `cleanup` | E2 | executed | T12.3a `sqlite_compact_matrix.rs#arm_status_phases`; T10 `compact_report_status.rs#status_projects_the_sidecar_phase_and_state`; T-G6a `postgresql_compact.rs#a_rebuild_records_bounded_metrics_with_pg_phases`; T10.5 `postgresql_status.rs#every_postgresql_failpoint_projects_its_phase` (PG `store.status` reads `gc_op`) | +| AC-52 | §12 Report; §11 | both | `none` and `rebuild` paths; every §11 field | `kind: Compacted`, snake_case keys, every §11 field with its unit and sampling point (`freelist_count * page_size`, old size before rename, history `logical` delta, peak temp = pre-truncate staged copy + new file + rollback-journal bound + visited, `physicalShrink`, `keptWaste`, `residue`, `estimate`, capped `cap`, `zeroReason`); `markBytes` is a #52 metric, not a result field; bound at least refined; PG `backendReusable` = 0 and PG/none `deadBytesRefined` equals `deadBytesBound` | E2 | covered | T12.1 golden `sqlite_compact_golden.json`; T10 `compact_report_status.rs#the_report_wire_is_the_snake_case_contract_shape`; T12.3b `#the_rebuild_report_and_markers_hold_on_postgresql` | +| AC-53 | §12 Read surface; §4.3 | both | `file.read`/`stat`/`list`/`glob`/`diff`/`revision`/`export`/cp-from before and after compaction; `edit`/`grep`/`blame`/`rm`/`mv`/`mkdir`/`cp`/`apply`; `branch.diff`/`commit.diff` | §4.3 shapes; visible/hidden/absent diff table; `removed_count` 0 and >0; one whiteout case per one-shot tree creator | E2 | partial | T12.3a `project_export.rs#export_omits_a_path_hidden_by_remove_file`; `gc_calls.rs#project_remove_file_checks_its_path_grammar_then_reports_markers` (full read-surface table not executed) | +| AC-54 | §12 Restore and listing; §4.2 | both | `backup.restore` before and after a removal; second home's stale entry | Restore succeeds; the stale entry stays out; the §4.2 guard test and allow-list hold | E2 | partial | T12.3a `restore_install.rs#a_folder_made_unprivate_during_the_download_is_refused_before_the_install`; `restored_records.rs#a_restored_project_reads_as_a_sandbox_reads_it` (restore-window arm `Unsupported` on this Sandbox) | +| AC-55 | §12 Error matrix; §10 | both | Exact code and message per case, including `StaleStore`, `Removed`, `InvalidInput` for `project.remove`, `Exists`, `Unsupported`, `Capacity` | Exact code and message; snake_case details | E2 | executed | T12.3a `sqlite_compact_matrix.rs#arm_error_codes`; `#arm_checkpoint_busy`; `sqlite_compact.rs#a_stray_staged_name_is_refused_and_not_deleted` (full engine/API message matrix partial) | +| AC-56 | §12 Digest golden vector; §6.4 | both | Fixed-id fixture (out-of-order ids, a retired Branch and stack, differing timestamps); absent head | One literal vector on both backends; absent head is 33 zero bytes, not 32; widths fixed at 17/33 | E3 | partial | T12.1 SQLite literal vector; T12.3b `postgresql_compact_fixtures.rs#the_live_heads_digest_vector_is_the_sqlite_literal` (3/3 identical runs) | +| AC-57 | §12 Speed and space; §13 | both | At least 3 runs per arm, median and range, declared caches, generated fixtures; §13 arms: `none` at 9%, `rebuild` at 10% and 30%, 50 GB total/35 GB live, 50 GB live, each removal type, removal-then-compact, `remove_file` 0-freed | Downtime per GB live and per GB freed, bytes written, peak disk, PG `ACCESS EXCLUSIVE` duration; absolute bytes when nothing is freed; build phase vs plain `VACUUM INTO`; mark reported separately; a 50% time/5% space option rejected | E3 | partial | T-G61 `sqlite_compact_capacity.rs#capacity_measure` + `sqlite_compact_capacity_measure.json`: a real 9.987 GB Store, `none` at 8.88% dead (3 runs, median 149.318 s) and `rebuild` at 10.00% dead (3 runs, median 246.371 s; mark 149.089 s, build 94.317 s, verify 0.312 s, install 1.916 s; dead 1.011 GB, shrink 1.017 GB, peak temp 9.144 GB) plus one WAL/FULL rebuild (284.078 s); T-G66 `sqlite_compact_capacity.rs#capacity_measure` + `sqlite_compact_capacity_measure_50gb.json`: a real 49.999 GB Store (384,850 packs; 347,490 live objects; 50.235 GB physical at `none`, 50.863 GB at `rebuild`), `none` at 8.876% dead (1 run, 1,633.585 s, 0 B freed) and `rebuild` at 10.000% dead (1 run, 5,131.835 s; mark 784.251 s, build 4,254.371 s, verify 85.557 s, install 7.311 s; dead 5.062 GB, shrink 5.100 GB, receipt peak temp 45.784 GB under the old `new + visited` formula, sampled real peak 143.1 GB = ~2.9x the Store, T-G72 corrected receipt bound 147.609 GB = 2.90x the old file and `sqlite_compact_capacity.rs#the_peak_temp_receipt_covers_the_staged_copy_and_the_rollback_journal` bounds the journal + unlinked rewrite temp on a moderate fixture); T12.3a `sqlite_compact_matrix.rs#arm_measurement` + `sqlite_compact_measure.json` (tiny fixture); T-G6a `postgresql_compact.rs#a_rebuild_records_bounded_metrics_with_pg_phases` (PG phase durations); §13's 30% dead / 50 GB-live arms, each removal type, removal-then-compact, the plain `VACUUM INTO` comparison and PG `ACCESS EXCLUSIVE` remain deferred/[E]; model source: [`gc-capacity-model.md`](gc-capacity-model.md) (10 GB three-run [M], 50 GB one-run [M] for `none`/`rebuild`; receipt `peakTempBytes` bounds the staged copy + journal + unlinked rewrite temp (T-G72)) | +| AC-58 | §7 step 1.5 (refined decision) | SQLite | After the seal: `ATTACH` the old file `immutable=1`, create `.compact-visited`, run the complete §6.1+§6.2 closure, choose `none`/`rebuild` from the refined live set | `none` deletes the scratch and stops with no `.compact` and no residue; `rebuild` keeps the scratch, reuses `visited` in step 4; step 2 creates the new file only on `rebuild` | E2 | covered | T12.1 fixture; T12.3a `sqlite_compact_crash.rs#crash_before_copy`; `#crash_during_copy` | +| AC-59 | §7 step 1 (seal) | SQLite | `PRAGMA wal_checkpoint(TRUNCATE)`; checked-close the last session; sidecar check under the writer guard; `seal_holding()` | `busy == 0` required; WAL never unlinked; sealed `(size, mtime, db-header change counter)` recorded before release; the guard passes into the seal | E2 | executed | T12.3a `sqlite_compact_matrix.rs#arm_checkpoint_busy`; `#arm_seal`; `sqlite_compact.rs#a_store_replaced_between_seal_and_install_is_stale` | +| AC-60 | §8 Phase B step 10 (standby) | PG | Effective `synchronous_commit` at least `remote_write` with `synchronous_standby_names` set; standby missing before Phase M; standby missing inside the swap; standby dies after the check | Wait only when required; `FIRST`/`ANY` standbys must be `state=streaming` with matching `sync_state`; a missing standby abandons before COMMIT with no writes (`Busy`, standby list); a standby dying after the check blocks COMMIT | E2 | deferred | T12.3b deferred: a real standby needs a second cluster/GUCs; `compact.rs` predicate unit tests pin the E1 decision | +## Evidence index + +| Source | Report | Tests / fixtures | AC ranges | +|---|---|---|---| +| T12.1 golden fixture | [gc-t12-sqlite-compaction-fixtures.md](gc-t12-sqlite-compaction-fixtures.md) | `tests/sqlite_compact_fixtures.rs`, `tests/fixtures/sqlite_compact_golden.json` | AC-04, 05, 17, 18, 25, 38, 40, 47, 48, 52, 56, 58 | +| T12.3c SQLite gap closure | [gc-t12.3a-sqlite-matrix-report.md](gc-t12.3a-sqlite-matrix-report.md) (regenerated by T12.3c; "SQLite gaps: none") | `engine/crates/layerfs-persistence/tests/sqlite_compact_matrix.rs` (8 executed rows); `engine/crates/layerfs-store-service/tests/sdk_path_whiteouts.rs`, `sdk_path_merge_removal.rs`, `sdk_mount_bind_failure.rs`; `engine/crates/layerfs-persistence/tests/epoch_fence.rs`; `control/crates/layerfs-control/tests/project_delete_worker.rs` | AC-06, 07, 11, 12, 13, 14, 22, 34, 36, 49 | +| T12.3a SQLite matrix | [gc-t12.3a-sqlite-matrix-report.md](gc-t12.3a-sqlite-matrix-report.md) | `tests/sqlite_compact_matrix.rs` (executed arms), `sqlite_compact.rs`, `sqlite_compact_crash.rs`, `sqlite_compact_fixtures.rs`, `admission.rs`, `path_removal.rs`, `branch_removal.rs`, `project_delete.rs`, `epoch_fence.rs`, `gc_backfill.rs`, `kept_objects.rs`, `gc_trace.rs`, `gc_calls.rs`, `calls_scope.rs`, `project_export.rs`, `restore_install.rs`, `restored_records.rs` | SQLite half of AC-01..AC-60; executed AC-33/46/51/55/59 | +| T12.3b PostgreSQL acceptance | [gc-t12.3b-postgresql-acceptance.md](gc-t12.3b-postgresql-acceptance.md) | `tests/postgresql_compact_fixtures.rs`, `postgresql_compact.rs`, `postgresql_position_columns.rs`, `postgresql_open_check.rs`, `postgresql_diagnostic.rs` | PG half of AC-02, 28-32, 34-44, 56, 60; also AC-01, 03, 05, 17, 18, 21, 24, 25, 49, 51, 52 | +| T9 PostgreSQL rebuild | [gc-t9-postgresql-rebuild.md](gc-t9-postgresql-rebuild.md) | `tests/postgresql_compact.rs` | AC-28, 41, 43, 44, 49, 60; Phases M/A/B/C | +| T10 report and status | [gc-t10-report-status.md](gc-t10-report-status.md) | `control/crates/layerfs-store/tests/compact_report_status.rs`; `sqlite_compact.rs#the_report_projects_every_section_11_field` | AC-51, 52 | +| T-G6a PG metrics | `engine/crates/layerfs-persistence/src/compact_metrics.rs` (`CompactPhase::{PostgresMark,PostgresBuild,PostgresSwap,PostgresCleanup}`) | `postgresql_compact.rs#a_rebuild_records_bounded_metrics_with_pg_phases`, `#a_none_path_records_only_the_pg_mark_phase` | AC-51, 57 | +| T8 SQLite rebuild | [gc-t8-sqlite-rebuild.md](gc-t8-sqlite-rebuild.md) | `tests/sqlite_compact.rs`, `sqlite_compact_crash.rs` | AC-33, 46, 47, 48, 58, 59 | +| T-G28/T-G60 real-process SIGKILL | - (T-G28 on main layer `32a7d0cf`; T-G60 on `task-g60`) | `sqlite_compact_crash.rs::real_process` (9 SIGKILL arms: mark x2, copy, verify, rename, build, before/after install, settle; child re-execution) | AC-01 | +| T-G65 real-process `store.compact` kill | - (T-G65 on `task-g65`) | `api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs` (8 SIGKILL arms on the built `layerfs store compact` process: mark x2, build x2, verify x2, install x2); gated failpoint in `control/crates/layerfs-store/src/compact.rs` | AC-01 | +| T-G38/T-G54 PG reply loss and privileges | - (main layers `32dc46a2`, `32a2621d`) | `postgresql_compact.rs` (real `pg_terminate_backend` kills, restricted-role fixtures); `backend/postgresql/access.rs` privilege check | AC-44 | +| T-G61/T-G66 SQLite capacity | [gc-capacity-model.md](gc-capacity-model.md) §1 (10 GB three-run [M], 50 GB one-run [M]) | `engine/crates/layerfs-persistence/tests/sqlite_compact_capacity.rs` (`#capacity_measure`, opt-in/ignored); `tests/fixtures/sqlite_compact_capacity_measure.json`, `tests/fixtures/sqlite_compact_capacity_measure_50gb.json` | AC-57 | +| Gap record | T12.3a/T12.3b/T12.3c `## Gaps` / `SQLite gaps` | none | SQLite gaps 0 after T12.3c (AC-06, 11, 12, 13, 14, 22, 34, 36 closed); AC-44 covered at T-G38/T-G54; AC-35, 42, 60 deferred | + +T12.3c's report is on main as the regenerated +`gc-t12.3a-sqlite-matrix-report.md` linked above; its eight SQLite-gap rows +now stand `executed` / `covered` / `partial` and its SQLite-gap list is empty. +`deferred` rows name the layer that owns them; none is silently waived. + +## Status summary + +At the plan layer all 60 rows were `pending`; the dispositions after T12.3c, +T-G28, T-G38/T-G54 and T-G65 are: + +| Status | Rows | Count | +|---|---|---| +| `executed` | AC-06, 07, 33, 46, 49, 51, 55, 59 | 8 | +| `covered` | AC-01, 03, 05, 08, 09, 10, 12, 13, 14, 16, 17, 18, 22, 24, 25, 26, 27, 29, 31, 36, 38, 39, 40, 44, 45, 47, 48, 50, 52, 58 | 30 | +| `partial` | AC-02, 04, 11, 15, 19, 20, 21, 23, 30, 32, 34, 37, 53, 54, 56, 57 | 16 | +| `deferred` | AC-28, 35, 41, 42, 43, 60 | 6 | +| `pass` | none | 0 | +| `pending` | none | 0 | + +AC-01 moved from `covered` to `partial` at T-G28 because its real-process +SIGKILL arms re-executed the test binary, not the production process. T-G60 +extended those arms to every phase. T-G65 closed the gap: +`api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs` starts the built +`layerfs` command with `store compact`, waits through the engine's socket gate +and `SIGKILL`s that process at the mark, build, verify and install points, so +the killed process is the one that performs the compaction (no daemon serves +Store calls, #352 F-020). AC-01 is `covered` again; the residual note is that +the long-lived `layerfs worker` that serves a machine's Store is still not the +killed process. The six `deferred` rows are +PostgreSQL-only: T12.3b executes the PG halves +of AC-28, 41 and 43, while AC-35 (advisory-key refcount), AC-42 +(reserved-pack race) and AC-60 (a real standby) need server control the +harness does not have. AC-44 moved to `covered` at T-G54: T-G38's real +`pg_terminate_backend` kills cover the lost `COMMIT` reply, and T-G54's +restricted-role fixtures prove each missing `CREATE`, `TEMP` or +`pg_read_all_stats` is `Unsupported` before any scratch schema is created. No row is `pending` +and no SQLite evidence gap remains (T12.3c). + +## Coverage map (required area -> cases) + +- Removals: branch AC-09, AC-16; project AC-26, AC-27; file AC-10..AC-21, AC-23..AC-25, AC-54. +- Admission: AC-07, AC-08, AC-29, AC-32, AC-34, AC-35, AC-49; epoch AC-21, AC-24, AC-39. +- Mark and closure: AC-04, AC-05, AC-15, AC-17, AC-18, AC-25, AC-40, AC-41. +- SQLite compaction (step 1.5, seal, sidecars, install, artifacts): AC-33, AC-46, AC-47, AC-58, AC-59; crash coverage AC-01, AC-03, AC-48. +- PG compaction (mark, swap, cleanup, scratch, standby, lost reply): AC-28, AC-41, AC-42, AC-43, AC-44, AC-49, AC-60; scratch in AC-38. +- Report and `store.status`: AC-51, AC-52. +- API and error shapes: AC-09, AC-26, AC-30, AC-34, AC-36, AC-50, AC-55. +- Read surface: AC-53, AC-54. +- Crash failpoints: AC-01, AC-03, AC-28, AC-36, AC-46, AC-47. +- 9/10/30% threshold: AC-48; measured arms in AC-57. +- Golden digest: AC-40, AC-56. +- 50 GB capacity: AC-57 (§13 arms). +- Names: AC-09, AC-16, AC-30. +- Trace: AC-31, AC-37. + +## Notes + +- Statuses record evidence, not #52 acceptance; T12.3c, T12.3b, T-G28, T-G60, T-G65 and T-G75 keep acceptance at #52. +- Evidence cells name the test/file in the report, not a new expected result. +- `markBytes` is measured in AC-41 and AC-57, never reported as a `store.compact` field (§11). +- A case is accepted at E2 only when the named backend's failpoints are exercised; E3 rows additionally need three runs or the property test, per §12 Speed and space. +- Evidence recording (run id, fixture hash, spec layer, artifact paths) is the next #52 step; the cells above name tests, not run ids. diff --git a/core/docs/issues/project-41/gc-api-contract.md b/core/docs/issues/project-41/gc-api-contract.md new file mode 100644 index 0000000000..1655c951ec --- /dev/null +++ b/core/docs/issues/project-41/gc-api-contract.md @@ -0,0 +1,120 @@ +# GC API contract (T11): four calls, results, refusals + +> Draft for T11 of layerfs-project#41, derived **only** from the frozen `LayerFS-GC-spec.md` (the spec wins; `§N` cites it). No behavior beyond the spec is asserted; unknowns are listed in §6. + +## 1. Calls and signatures + +| Call | Arguments | Scope | +|---|---|---| +| `branch.remove(project, branch)` | project, Branch | one Branch | +| `project.delete(project)` | project | one project | +| `project.remove_file(project, path)` | project, absolute POSIX path | one project + path | +| `store.compact(name)` | Store | one Store | + +Each takes only the resource identifier: no confirm, force, dry-run, stop-Sandboxes, Store, URL or volume option (§1). The +three removals are logical and reclaim nothing; `store.compact` is the only byte-reclaiming call (§1, §4). `project.remove` is +retired — an old client gets `InvalidInput` ("no call named `project.remove`"), never a silent hard delete (§4). +`branch.remove` of `main` is `ReservedName` (§4). `store.compact` picks `none`/`rebuild` by the 10% wholly-dead-pack rule; a +started rebuild completes even below 10% (§3, #42 item 41). + +## 2. Success shapes + +snake_case on every surface (§10); these fields are required: + +- `branch.remove` → `{kind: "Removed", project, branch, removed_ms}` (§10). +- `project.delete` → `{kind: "Removed", project, deleted_ms, home_entry_removed}`; the worker frame is `{store, stack_id, + deleted_ms?}`, its reply `{kind: "Removed", project, stack_id, deleted_ms}`, and the caller echoes `home_entry_removed` (§4, + §10). +- `project.remove_file` → `{kind: "Removed"|"UpToDate", project, path, frontier_serial, removed_ms}` — the stored marker + values. `UpToDate` iff no project node is above **this path's** marker frontier (missing = -1); a commit in another project + does not make it `UpToDate` (§4.3). +- `store.compact` → `{kind: "Compacted", ...}` with §11's report: `path` (`none`|`rebuild`), `generation {before, after}`, + `deadBytesBound`, `deadBytesRefined`, `logicalDiscarded`, `backendReusable`, `physicalShrink`, `keptWaste + {deadInRetainedPacksBytes, deltaBases {bytes, references}, inodeBlocksBytes}`, `peakTempBytes`, `residue {bytes, artifacts[, + reason]}` (§11). + +Binding rules: `none` leaves the generation unchanged, `rebuild` is `G → G+1` (§3, §11). `estimate: bool` is top-level; a +capped field is `{value, cap}`; every zero field names a `zeroReason` from `empty-store`, `none-path`, `no-history`, +`no-waste`, `postgresql-in-place` (§11, S7). On `none`, `deadBytesRefined == deadBytesBound`; on PostgreSQL they are always +equal (no payload sweep) (§11). `home_entry_removed: false` is still success — the marker is the commit point and a same-home +retry is idempotent (§4). A repeat `branch.remove` is `NoSuchBranch` (a concurrent one is `Busy`, phase `"retire"`); a repeat +`project.delete` is §4's idempotent success (§4.4). + +## 3. Refusals and detail shapes + +| Code | GC trigger | `detail` | +|---|---|---| +| `MountsActive` | a mount/Sandbox of the Branch or project is in scope (§5) | `holders` (mounts/Sandboxes) | +| `Busy` | another user of the project/Store, a live op, a busy lane, a concurrent remove (§5, §4.4) | `{entity, phase, op}` (+ PG `pid`, `client_addr`, `backend_start`) | +| `Unresolved` | a dead owner left an uncertain op; observed by a non-owning call (§5.1, §10) | `{entity: {kind, name}, phase, op}` | +| `Removed` | a read/stat/merge hits a `remove_file` marker (§4.3, §10) | `{paths: [{path, frontier_serial}]}` | +| `NameTaken` | a create/fork/merge target name still held; `project.init` (§4.4, §10) | `{holder: {kind: branch\|project, name, state: live\|retired\|deleted}, source: store\|home}` | +| `StaleStore` | SQLite `(dev, ino)` differs from open; PG generation/fence mismatch (§10, §5.2) | unspecified | +| `Capacity` | a real `PersistenceError::Refused {status: "Capacity"}` (§10) | unspecified | +| `Unsupported` | default catalog body; PG transaction pooling for mounts/compaction (§10, §5.2) | unspecified | +| `ReservedName` | `branch.remove` of `main` (§4) | — | +| `Conflict` | sealed tuple changed at install; missing `project_epoch` row after cleanup (§10, §5) | unspecified | +| `NotFound`, `NoSuchBranch`, `NoSuchCommit`, `NoSuchProject`, `NoSuchStore` | a hidden/collected resource, resolved through filtered statements (§4.2, §5) | — | +| `InvalidInput` | bad `remove_file` path, retired `project.remove`, symlink component (§4.3, §4) | — | +| `Exists` | a stray artifact at the staged compact name with no record (§9) | — | + +`InUse` stays for non-GC calls only (§10). **snake_case rule:** success results and refusal details are snake_case; the +dispatcher snakes the detail (or the site builds it snake); a camelCase detail is a bug; the CLI prints the rendered map; §11 +names are logical, not rendered (§10, §11). A busy checkpoint, a live owner and a reachable-but-unresponsive Sandbox stay +`Busy`; only a provably dead, uncertain op is `Unresolved` (§5.1, §7). + +## 4. MCP, folder scope, CLI/SDK, `store.status` + +- All four are **admin-profile** calls, refused under a folder scope with `out of scope: ` + (`api/crates/layerfs-api/src/calls/scope.rs:33`; #42 item 39): a folder scope guards one folder and one Branch, and none of + the four is a folder operation, so it is refused, never widened (§10). +- The admin classifier checks its admin list before the work families; the four join it and `project.remove` leaves both the + call table and that list. MCP names follow the existing `project_remove` mapping (`project.delete` → `project_delete`); an + old `project_remove` is `InvalidParams "unknown tool"`, a CLI usage error exits 2, the library reports `InvalidInput` (§10). +- The table becomes 76 (38 work / 38 admin): regenerate `gen-profiles`/`gen-coverage` and the hard-coded 73/38/35 counts; + `whyOf`, the profile prose and `--profile admin` usage name the four calls, one `whyOf` line each; a precedence test covers + `branch.remove` under `work` (§10). +- CLI/SDK surface: one command/one SDK method per call, ids only — `layerfs branch remove `, `layerfs + project delete `, `layerfs project remove-file `, `layerfs store compact ` (the runbook + already uses the last); results are the rendered snake_case map (§1, §10). +- `store.status` while compacting (§11): `op = {id, name, phase, started, uncertain}` from `gc_op` (PostgreSQL, Store-side) or + the home op (SQLite; a remote home via `step_on`); `state` is `busy`/`unresolved`; phases `mark`/`build`/`verify`/`install` + (SQLite) and `mark`/`build`/`swap`/`cleanup` (PostgreSQL); there is no `PROGRESS` option (#42 item 40). + +## 5. Implementation checklist (T11) + +1. Call table: add the four, delete `project.remove`; ids-only arguments (§1, §10). +2. `HistoryError`: add `Removed` and `StaleStore` with explicit arms in `lookup.rs` before `_ => "Failed"`; `NameTaken` rides + the boxed `NameTakenState` and `lookup.rs` projects `{holder, source}`; map `HistoryError::Unsupported` explicitly (§4.4, + §10). +3. `HistoryCatalog`: `mark_*`, `retained_roots`, `get_retained_roots`, `remove_unreachable`; both providers implement them, + default `Unsupported` (§10). +4. Dispatcher snakes every detail and result; builders carry §2's fields and §11's report with `estimate`, `{value, cap}`, + `zeroReason` (§10, §11). +5. `remove_file`: normalize the absolute POSIX path (strip one leading `/`); reject empty, `/`, `//a`, `a//b`, `a/`, `./a`, + `a/./b`, `.`/`..`, `\`, NUL, >4096 bytes, >256 components; subtree match only at a `/` boundary over bytes; frontier + `next_history_serial - 1` read under the Store write lane in the marker transaction; `epoch` bump only on advance; per-call + trace redaction with `trace_salt` (§4.3). +6. `project.delete`: worker frame, legacy identity save, sidecar `pending|marked|done`, retry order, `home_entry_removed` echo + (§4); a `project.init` name collision is `NameTaken` (§10). +7. Capacity: add `StorageError::CapacityExceeded` to the predicate, keep PG 53100/53200/53400/54000, map 53300 to `Busy`, drop + 54001, name `SQLITE_FULL`/`SQLITE_TOOBIG`/`SQLITE_NOMEM`, explicit arm before `_ => Refused` (§10). +8. MCP/profile generators, `whyOf`, counts, precedence test, folder-scope refusal (§4). +9. `store.status` op projection and phases; `gc_op` (PG) / home op (SQLite) (§11). + +## 6. Spec gaps and questions + +1. Only `Removed`, `MountsActive`, `Busy`, `Unresolved` and `NameTaken` have a stated `detail`; `StaleStore`, `Capacity`, + `Unsupported`, `Conflict` and `ReservedName` have none, and §10's "one detail shape" sentence covers only `Removed`. +2. `Unknown` is prose ("a lost reply is `Unknown`", §4; `project.list(store)` propagates `Busy`/`Unknown`, §4.2) but absent + from §10's code table and has no detail shape. +3. §11 names fields camelCase (`deadBytesBound`) while §10 requires snake_case rendering; the mapping is implicit. +4. §4.3 refuses a merge `Removed` with `detail {paths: [...]}`, while the canonical detail is `{paths: [{path, + frontier_serial}]}`; whether the merge echoes full elements is unstated. +5. Only `project.delete` has an idempotent retry contract (§4). For `branch.remove`/`remove_file` a lost reply "stays + uncertain" (§1) with no re-answer specified. +6. `project.delete` returns `Removed` with `home_entry_removed: false`, where another home's stale entry may persist (hidden + only by the §4.2 intersection); the result does not name that residue. + +Note: the brief's main ref `4e65ebba…` (40 hex) is not a LayerFS ref; `branch get main` reports Layer `3216923362f73a85…`, +root `27872fc7…`; T11 forked `main` as resolved. diff --git a/core/docs/issues/project-41/gc-capacity-model.md b/core/docs/issues/project-41/gc-capacity-model.md new file mode 100644 index 0000000000..f9a9dd2bd2 --- /dev/null +++ b/core/docs/issues/project-41/gc-capacity-model.md @@ -0,0 +1,122 @@ +# GC capacity model: a 50 GB Store (spec section 13) + +> Deferred 50 GB / §13 capacity model for `layerfs-project#41`. Adds no contract; [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) wins, `§N` cites it. +> **[M]** = measured on the cited artifact; **[E]** = extrapolated from the stated assumptions. Nothing marked [E] is a measurement. +> **T-G61** measured a real **10.0 GB** Store (`sqlite_compact_capacity_measure.json`): three `none` runs at 8.88% dead, three `rebuild` runs at 10.00% dead and one WAL/FULL rebuild. **T-G66** then measured the **50 GB** arm on the same host (`sqlite_compact_capacity_measure_50gb.json`): a **49.999 GB** pack-byte Store (384,850 packs, 347,490 live whole-file objects, 33,850 dead = 8.876%, built in 761.2 s), **one** `none` run and **one** `rebuild` run at 10.000% dead. One run per arm is what §13 asks of the 50 GB arm, not a three-run median; the 10 GB three-run medians stay the repeated-run basis. **The 50 GB numbers do not scale linearly from the 10 GB ones**: the 10 GB Store and its rebuild artifacts fitted the host's page cache, the 50 GB one does not, so its `rebuild` is **85.5 min** and its real temp peak on disk is **143.1 GB above the pre-rebuild baseline** (**~2.9×** the Store) — not the [E] ~20 min and 1.9×. **T-G72** replaced the receipt's `new + visited` peak with a documented bound over the run's temp artifacts (pre-truncate staged copy + new file + rollback journal + visited): **147.609 GB** for the same 50 GB `rebuild`, 3.2% above the sampled peak and no longer under-reporting the journal. The 30% dead, 50 GB-live/35 GB-live, each-removal-type and PostgreSQL `ACCESS EXCLUSIVE` arms remain [E]. + +## 1. Measured basis + +| Quantity | Tiny fixture (T12.3a) [M] | Capacity fixture (T-G61), 10 GB [M] | 50 GB arm (T-G66) [M] | +|---|---|---|---| +| Store size | 20 live roots, 20 dead packs | **9.987 GB pack bytes** (76,870 packs; 69,399 live 131,071-byte whole-file objects, 6,770 dead); 10.035 GB physical | **49.999 GB pack bytes** (384,850 packs; 347,490 live 131,071-byte whole-file objects, 33,850 dead); **50.235 GB physical** at the `none` seal, 50.863 GB at the `rebuild` seal | +| Profile | `Disposable` (WAL/OFF) | `Disposable` (WAL/OFF); one `Durable` (WAL/FULL) control | `Disposable` (WAL/OFF); no `Durable` arm (owner profile disabled) | +| `none` wall | n/a | 148.519 / 149.704 / **149.318 s** median; range 148.519–149.704 | **1,633.585 s** (one run) | +| `rebuild` wall | 26.738 / 28.201 / 28.681 ms; median 28.201 ms | 246.371 / 255.548 / 243.306 s; median **246.371 s**; range 243.306–255.548 | **5,131.835 s** (one run) | +| `Durable` rebuild | n/a | **284.078 s** (one run) | not run (owner profile) | +| `deadBytesBound` | 1,100 B | **887,601,160 B** at 8.88% (`none`); **1,011,104,896 B** at 10.00% (`rebuild`) | **4,438,005,800 B** at 8.876% (`none`); **5,062,342,096 B** at 10.000% (`rebuild`) | +| `physicalShrink` | 20,480 B | **1,016.5–1,019.0 MB** (mean 1.017 GB); `none` 0 | **5,099,651,072 B** (5.100 GB); `none` 0 | +| `peakTempBytes` (receipt) | **758,240 B** (T-G72 bound; old formula 258,048 B) | **29,481,103,648 B** (29.481 GB bound; old formula 9.144 GB) | **147,608,626,376 B** (147.609 GB bound; old formula 45.784 GB) | +| Peak on disk, sampled | n/a | not sampled | **143.1 GB above the pre-rebuild baseline** (§3) | +| New file | n/a | 9,139,773,440 B (9.140 GB) | 45,763,203,072 B (45.763 GB) | +| Fixture build | n/a | 150 s | **761.2 s** (65.7 MB/s over 49.999 GB) | +| Host | linux-x86_64, rustc 1.85.1 | 88 vCPU, 135 GB RAM, ext4, 4.0 TB free | 88 vCPU, 125 GB visible RAM, ext4 (`/dev/sda2`), 4.0 TB free; same rustc 1.85.1 | + +Phase durations, 50 GB `rebuild` (one run, WAL/OFF): **mark 784.251 s**, **build 4,254.371 s**, **verify 85.557 s**, **install 7.311 s** (sum 5,131.490 s of the 5,131.835 s wall). `none`: mark 1,633.579 s and nothing else. +Sources: [`sqlite_compact_capacity_measure.json`](../../../../engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_capacity_measure.json) (10 GB) and [`sqlite_compact_capacity_measure_50gb.json`](../../../../engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_capacity_measure_50gb.json) (50 GB). + +Caches [M]: the 10 GB Store fitted in the host's page cache and no cache drop ran between its runs; the 50 GB arm did not fit. Its `none` mark ran immediately after the fixture build (50 GB of fresh writes still in the page cache) at **35.9 s per live GB**; the `rebuild` mark, after that read pass, ran at **17.2 s per live GB** — the 16.4 s/GB of the 10 GB arm. The mark is still single-threaded payload/identity hashing (~62 MB/s effective); the 2.1× spread is cache state, not the object count. No cache drop ran between the two 50 GB arms either. + +Per-GB rates measured on this host (GB = 10^9 B): + +| Step | 10 GB [M] | 50 GB [M] | Basis | +|---|---|---|---| +| Mark (`none`) | 14.9 s per stored GB / 16.4 per live GB | **35.9 s per live GB** (32.7 per stored GB) | 1,633.579 s over 45.561 GB live; cold page cache, right after the fixture build | +| Mark (`rebuild`) | 16.4 s per live GB | **17.2 s per live GB** | 784.251 s over 45.561 GB live; warm after the `none` read pass | +| Build (`VACUUM INTO` + prune + `VACUUM`) | 10.3 s per new GB | **93.0 s per new GB** | 4,254.371 s over 45.763 GB new; the phase moves ~141 GB (staged copy 50.85 GB, 44.6 GB rollback journal, target rewrite 45.76 GB) at ~33 MB/s | +| Verify | 0.034 s per new GB (0.31 s total) | **1.87 s per new GB** (85.557 s) | at 50 GB it reads the payload back; the 10 GB read was cache-only | +| Install | ~1.9 s fixed | **7.311 s** | rename, fsync, settle | + +The mark dominates at 10 GB; at 50 GB the build phase dominates by 5.4× — the opposite. Do not extrapolate either phase linearly from the 10 GB arm: the 10 GB run was cache-optimistic, and the 50 GB build rate depends on free page cache and device write throughput rather than on CPU. Use the 50 GB [M] rates above for a 50 GB Store and re-measure with §7's harness on the target host. + +## 2. The 50 GB / 9% Store and the rule + +`rebuild iff total > 0 AND dead * 10 >= total` (§3); `dead` = bytes in packs with no live object after the metadata walk (§6.4). GB = 10^9 B. + +| Dead share | Old | Dead | Live | `dead*10 >= total` | Path | Measured? | +|---|---|---|---|---|---|---| +| 9% | 50.0 GB | 4.5 GB | 45.5 GB | 45 >= 50: **no** | `none` | **50 GB [M]**: 49.999 GB pack bytes, 8.876% dead → `none`, 0 B freed | +| 10% | 50.0 GB | 5.0 GB | 45.0 GB | 50 >= 50: **yes** | `rebuild` | **50 GB [M]**: 50.623 GB pack bytes, 10.000% dead → `rebuild`, 5.100 GB freed | +| 30% | 50.0 GB | 15.0 GB | 35.0 GB | 150 >= 50: **yes** | `rebuild` | [E] only; §13's 50 GB total/35 GB live and 50 GB-live arms remain deferred | + +At **9% the measured path is `none`**: mark only, no file, generation unchanged (7 → 7), **0 bytes freed**; the report still gives the dead bound (4.438 GB measured at 50 GB; 0.888 GB at 10 GB). +The measured 50 GB rebuild copied a 45.763 GB new file to free 5.100 GB — **8.97 B copied per B freed** [M], against 9.04 at 10 GB [M] and the frozen 10% floor's ~9.0 [E]. At 30% it is ~2.3 [E]. + +## 3. Temp-space model + +**SQLite (measured).** 50 GB arm: old physical file 50.863 GB; new `.compact` 45.763 GB; `.compact-visited` 20,365,312 B. The rebuild's temp artifacts are the *whole* staged copy, a rollback journal and SQLite's rewrite temp database — not the new file plus visited. `VACUUM INTO` first writes the whole sealed Store to `.compact` (the old page count, 50.863 GB); the prune's `DELETE ... WHERE NOT IN visited` grows `.compact-journal` to **44.6 GB** (44,630,503,928 B observed); the closing `VACUUM` then writes the vacuumed Store to SQLite's unlinked temp database (≈45.763 GB, in the process temp directory) while the staged file is rewritten in place and the rollback journal records the pages it overwrites. A 20 s disk sampler saw the run's real temp peak at **143.1 GB above the pre-rebuild baseline** (sample max 315.9 GB used against 172.8 GB before the rebuild) = staged 50.85 + rewrite temp 45.76 + journal 44.6–45.8 GB; **~2.9×** the 50 GB pack-byte Store [M]. +The old receipt computed `target_bytes + visited_bytes` (`Built::peak_temp_bytes` in `engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs`) *after* the staged file was truncated: 45.784 GB = new + visited, under-reporting the rollback journal and the staged/temp copies (the T-G66 finding). +**T-G72 bounds the whole run instead.** `Built::peak_temp_bytes` is `staged_bytes + journal_bound + target_bytes + visited_bytes`: the staged extent measured right after `VACUUM INTO`, the rollback-journal upper bound (one record per staged page, `page_size + 8` B, plus an 8192 B header allowance), the new file (which also bounds the rewrite's temp database) and the visited scratch. The 50 GB arm is 50,862,854,144 + 50,962,203,848 + 45,763,203,072 + 20,365,312 = **147,608,626,376 B (147.609 GB) = 2.90× the old file**, 4.5 GB (3.2%) above the sampled peak: the bound charges the journal the whole staged page count instead of the pages the transactions actually touch. The total footprint is old + peak = **~198 GB (3.9×)** at 50 GB; the measured sample was old + 143.1 ≈ 194 GB (3.8×) [M]. Upstream issue: [Ephemeral-AI-Lab/layerfs#695](https://github.com/Ephemeral-AI-Lab/layerfs/issues/695). +Visited is metadata-scale: 20,365,312 B for 347,490 live objects = **58.6 B per visited object** [M] (10 GB: 57 B). +`physicalShrink` (5.100 GB) exceeds `deadBytesBound` (5.062 GB) by ~0.7%, as at 10 GB (0.6%): shrink is file-level and includes free pages; do not equate the two. + +**PostgreSQL.** Peak = old tables (50 GB, dead included) + scratch schema `lfs_gc_` (LIKE copy of live `pack`/`object_location`) + index/PK + `ANALYZE` + WAL "up to the live bytes" (§8 "Space"); mark temp tables are session-temp and small. +Extrapolated [E; SQLite measured: the T-G72 receipt bound is 2.90× the old file and old + peak ~3.9×, so the SQLite rows below are receipt-bound estimates and every [E] row stays a projection]: + +| Backend | Case | Old | New file / scratch | Visited / index | Journal / WAL | Peak temp | Total footprint | +|---|---|---|---|---|---|---|---| +| SQLite | 9% `none` | 50.0 | 0 | <=0.1 GB | 0 | **<=0.2 GB** | ~50.2 GB | +| SQLite | 10% `rebuild` | 50.0 | ~45.8 new + ~50.9 staged | ~0.02 GB | ~44.6 GB prune / ~45.8 GB rewrite | **~147.6 GB bound** (sampled 143.1) | **~198 GB (3.9× bound; 3.8× sampled)** | +| SQLite | 30% `rebuild` | 50.0 | ~35.2 new + ~50.9 staged | ~0.02–0.1 GB | ~35 GB prune/rewrite [E] | ~137 GB bound [E] (actual ~120 [E]) | **~187 GB [E] (3.7×)** | +| PG | 9% `none` | 50.0 | 0 | 0 | mark only | **~50 GB** | ~50 GB | +| PG | 10% `rebuild` | 50.0 | ~45.0 | ~4–6 GB | <=45 GB | **~99–101 GB, <=146 GB** | same | +| PG | 30% `rebuild` | 50.0 | ~35.0 | ~3–5 GB | <=35 GB | **~88–90 GB, <=125 GB** | same | + +**Headroom [M].** Keep **>=150 GB free** for a 50 GB `rebuild` at ~10% dead (measured 143.1 GB sampled peak, ~2.9× the Store), >=115 GB at <=30% dead [E]; `none` needs a few GB. The T-G61 [E] guidance of 95–110 GB came from the receipt field and is **too low**. +Size `pg_wal` separately: a full `pg_wal` stops the server (§8). + +## 4. Time model + +Measured 50 GB [M] on this host, beside the 10 GB medians. Linearity is **not** assumed: the 50 GB column is measured, not scaled. + +| Dead | Path | Measured old | 10 GB wall (median) [M] | 50 GB wall [M] | s/GB live at 50 GB [M] | Freed at 50 GB | +|---|---|---|---|---|---|---| +| 9% | `none` | 49.999 GB | 149.318 s | **1,633.585 s (~27.2 min)** | 35.9 | 0 | +| 10% | `rebuild` | 50.623 GB | 246.371 s | **5,131.835 s (~85.5 min)** | 112.6 | 5.100 GB | +| 10% | `rebuild`, Durable | - | 284.078 s | not run | - | - | +| 30% | `rebuild` | - | - | **~65–70 min [E]** (mark 17.2 s/GB + build 93 s/GB over ~35.8 GB new) | ~110 [E] | ~15.0 GB | + +The oldest [E] table said 1.8–2.0 min for a 50 GB rebuild; the linear T-G61 [E] said ~20.3 min; the measured 50 GB rebuild is **85.5 min**, 4.2× the linear projection. Two measured causes: (a) the build phase is **9× slower per new GB** than at 10 GB (93.0 against 10.3 s/GB) because the rebuild's ~146 GB working set (old + staged + journal) no longer fits the 125 GB page cache, so the copy is real device I/O; (b) the mark has a 2.1× cold/warm spread (35.9 against 17.2 s/GB live). Plan **~27 min** for a 50 GB `none` and **~85 min** for a 50 GB `rebuild` on a host like this one [M]; re-measure with §7's harness on the target host. +PostgreSQL is not measured by AC-57; its server-side `INSERT ... SELECT` copy, index build and `ANALYZE` extrapolate to **4–10 min**, `ACCESS EXCLUSIVE` only at the swap, **~2 s** [E]. + +## 5. Operation window, mounts and commits + +- **SQLite.** `writer_admission` is held checkpoint→rename, so the exclusive lane is the whole §7 run: **27.2 min for a 50 GB `none`** and **85.5 min for a 50 GB `rebuild`** [M]; the 10 GB values are 2.5 min each [M]. A live mount = `MountsActive`; a mount during compaction = `BusyOp` (AC-07/AC-49); a Commit racing install = `StaleStore` or lands on `G+1`, retry never lost. `none` is mark-only but still holds the lane for its mark. +- **PostgreSQL.** The session advisory key spans M–C; mounts get `BusyOp`, a post-mark commit makes the swap `Conflict` with no writes (§8). `ACCESS EXCLUSIVE` is the swap only (~2 s) [E]; the `G+1` Store is usable during C. Plan 25 minutes quiet for SQLite at 50 GB [M for the phases, E for the quiet-window policy], mostly online for PG [E]. +- **Monitoring.** `store.status` gives `op {id,name,phase,started,uncertain}`, `state` busy/unresolved and phases — SQLite `mark/build/verify/install`, PG `mark/build/swap/cleanup` (§11). The capacity runs' T10.3 phase sums are in the fixtures (`none` = all mark; `rebuild` = mark/build/verify/install). + `compact_metrics` has runs, operations, refusals, settles, retries, status, slo, phase durations and last §11 gauges: process-local, no CLI/SDK renderer, no PG metrics. + Don't loop a direct reader: it makes the checkpoint `Busy` (§7; [`gc-runbook.md`](gc-runbook.md) §1). + +## 6. Risks + +- **Disk full (both).** SQLite `SQLITE_FULL`/`ENOSPC`/`EDQUOT`/`EFBIG` → `Capacity`, artifact deleted, old Store unchanged apart from checkpoint (§7 step 8; AC-55). The measured 50 GB run needed **143.1 GB** of sampled temp peak (~2.9× the 50 GB Store); the T-G72 receipt bound is **147.609 GB** (2.90× the old file), so keep **>=155 GB free** and re-check before a 30% run (>=140 GB there [E]). +- **Peak temp.** `peakTempBytes` now bounds the run's temp artifacts (T-G72): pre-truncate staged copy + new file + rollback-journal bound + visited. The 50 GB receipt is 147.609 GB (2.90× the old file; sampled 143.1 GB); total footprint = old + peak ≈ 198 GB (3.9×). The journal term is conservative: the bound charges one record per staged page while the run journaled 44.6 GB [M]. +- **WAL.** SQLite needs `wal_checkpoint(TRUNCATE) busy == 0` and never unlinks `-wal`/`-shm` (a live reader is `Busy`); PG WAL ≤ live bytes + standby lag. +- **PG standby.** `synchronous_commit ≥ remote_write` with `synchronous_standby_names` needs a streaming sync/quorum standby; missing → `Busy` no writes; one dying after the check blocks COMMIT and `SET LOCAL` cannot bound it (§8; AC-60 deferred). +- **Installed-but-uncertain / races.** Rename/fsync failure or lost COMMIT keeps the new Store at `G+1`, settles `unknown`; never delete the artifact; PG: prove the backend ended (`pid`, `backend_start`, `usename`), then read the incarnation. + `MountsActive`/`BusyOp`/`StaleStore` are expected: quiesce, retry, never kill an owner. The 20,480 B vs 1,100 B ratio and 28.2 ms are tiny-fixture effects; the 10 GB and 50 GB numbers above are the capacity evidence. + +## 7. Runbook thresholds (50 GB Store) + +1. **Eligibility:** only `dead*10 >= total` (>=10% dead, §3); below it `none`, no file, 0 freed — but still a full mark (**27 min at 50 GB** [M]). Record the dead bound and re-check later. +2. **Economics/space [M]:** at 10% dead the measured rebuild copies **8.97 B per B freed** [M] (10 GB: 9.04 [M]) and needs **~148 GB free** (147.609 GB receipt bound, 2.90×) [M]; prefer **>=20–30% dead** (30% ~2.3 B per B [E], ~137 GB bound [E]). +3. **Window/quiesce [M]:** SQLite **~27 min** quiet for a 50 GB `none` and **~85 min** for a 50 GB `rebuild`; the 10 GB values are 2.5 min each. No full doctor; expect `BusyOp`. A `Busy` owner: wait, do not terminate (runbook §2). +4. **Recovery gate:** if `store.status.state` is `unresolved`, rerun `store.compact` to adopt the op; never hand-delete artifacts or `gc_intent`/`gc_dead` (runbook §2–§3). +5. **Backup/alerts/failures:** `backup.create` before the first run ([`gc-rollout.md`](gc-rollout.md) §3; §9); alert on `Capacity`, `unresolved`, `retries`, nonzero `residue`, PG WAL/standby lag. `Capacity` → free space and rerun; uncertain → keep the new Store, settle `unknown`. +6. **Re-measure per host.** `CAPACITY_MEASURE=1 UPDATE_CAPACITY=1 cargo test -p layerfs-persistence --release --test sqlite_compact_capacity -- --ignored --nocapture` with a TMPDIR of **>=3× the target** (the receipt bound is 2.90×; the measured temp peak was 143.1 GB). The 50 GB arm used `CAPACITY_GROUPS=3510 CAPACITY_DEAD_OBJECTS=33850 CAPACITY_RUNS=1 CAPACITY_KEEP=1 CAPACITY_OUT=<...>_50gb.json`; the mark is CPU-bound and the copy I/O-bound, so a host with faster SHA-256 and more page cache can be several times quicker. + +## Sources + +- [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md): §3 threshold, §6.4 dead set, §7 SQLite rebuild/cost/Capacity, §8 PG phases/space/standby, §11 report and `peakTempBytes`, §13 deferred 50 GB arms and estimates. +- [`gc-t12.3a-sqlite-matrix-report.md`](gc-t12.3a-sqlite-matrix-report.md) (AC-57) and `sqlite_compact_measure.json` (the tiny [M] numbers; its `peakTempBytes` is the T-G72 bound, 758,240 B); `sqlite_compact_capacity_measure.json` and `sqlite_compact_capacity.rs#capacity_measure` (the 10 GB [M] numbers); `sqlite_compact_capacity_measure_50gb.json` (the 50 GB [M] numbers, one run per arm). The two capacity JSONs still record the T-G66 old-formula `peakTempBytes` (45.784 GB at 50 GB); the T-G72 bounds in this page are arithmetic over their measured page counts and sizes, not a re-measurement. +- [`gc-t9-postgresql-rebuild.md`](gc-t9-postgresql-rebuild.md) (M/A/B/C, scratch schema, WAL/standby gaps) and [`gc-implementation-report.md`](gc-implementation-report.md) (status/metrics projection). +- [`gc-runbook.md`](gc-runbook.md) and [`gc-rollout.md`](gc-rollout.md) (safe cleanup, rehearsal). diff --git a/core/docs/issues/project-41/gc-implementation-report.md b/core/docs/issues/project-41/gc-implementation-report.md new file mode 100644 index 0000000000..82456cefb3 --- /dev/null +++ b/core/docs/issues/project-41/gc-implementation-report.md @@ -0,0 +1,485 @@ +# GC implementation report: soft removal and Store compaction + +> Final report for `layerfs-project#41`. The frozen +> [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) (2.0.0) wins; `§N` and `AC-nn` +> cite it. This page certifies main layer `32ae51ca` (audited by T-G75 on +> 2026-11-15) in §8; it adds no contract and leaves acceptance sign-off to +> #52. + +## 1. Scope and what shipped +Four ids-only, admin-profile calls on SQLite and PostgreSQL: +`branch.remove`, `project.delete`, `project.remove_file` and `store.compact`. +The first three change visibility and retention only; `store.compact` +reclaims bytes. +**Schema and removals.** The additive open step adds `branch_retired`, +`layer_stack_retired`, `path_removed`, `project_epoch`, `gc_intent`, `gc_op`, +`gc_dead` and `kept_node`, plus `history_meta.next_history_serial` (never +lowered), `commit.history_serial`, `layer.history_serial` and +`store_policy.trace_salt`; it backfills serials deterministically, creates one +zero epoch per stack and raises the next serial above the maximum. `branch` and +`layer_stack` stay append-only; 1.0 Stores convert offline; there is no +down-migration (§4.1). `branch.remove` writes `branch_retired`; +`project.delete` writes `layer_stack_retired` plus a retry sidecar and returns +`home_entry_removed: false` on a home-removal failure; `project.remove_file` +writes `path_removed` at frontier `next_history_serial - 1`. Visibility is +filtered statements plus an allow-list guard, not views, and the three removal +markers are never rewritten (§4.2-§4.4). + +**Admission and mark.** `gc_intent` is one Store-scoped row per operation +(kind, scope, state, owner pid/start/boot, phase, generation, artifact, high +water). SQLite uses two `BEGIN IMMEDIATE` transactions and reports +`MountsActive`, `Busy` or `Unresolved`; PostgreSQL holds `(kind, id)` advisory +keys at Store, project and Branch scope, records the owner in `gc_op`, and ends +a dead idle owner with `pg_terminate_backend(pid, backend_start)`. The epoch +fence re-checks `project_epoch.epoch` before commit (same transaction on +SQLite, a final `FOR SHARE` on PostgreSQL); a changed or missing epoch is +`Conflict` with no Commit (§5). `HistoryProvider::mark_gc` reads the tuple +(`catalog_incarnation`, `next_history_serial`, `next_pack_id`, `next_ordinal`, +`store_totals`, `MAX(stamp)`, history rows), runs the §6.1 history closure and +the §6.2 object closure (`FinalizedObject::admit` plus +`ChainBases::base_of`, one visit level, delta bases), and writes `kept_node`, +the object/pack set, `deadBytesBound`/`deadBytesRefined`, `gc_dead` and the +§6.4 `live_heads_digest` (absent head is 33 zero bytes). `keptWaste` covers +retained-pack waste, delta bases and all `inode_value_block` rows. + +**SQLite rebuild.** `SqliteHandles::compact` holds `writer_admission` from +checkpoint through rename, runs `wal_checkpoint(TRUNCATE)` (busy is `Busy`; the +WAL is never unlinked), seals `(size, mtime, db-header change counter)`, +attaches the old file `immutable=1`, builds `.compact-visited`, runs +`VACUUM INTO .compact`, and in one transaction keeps retained rows, deletes the +complement, sets `G + 1`, recomputes `store_totals` and clears +`binding_hint_block`. Verification checks schema, foreign keys, counts, both +digests, allocator and totals; install rechecks sidecars and `-mj*`, applies +`chmod 0600` and `sync_all`, renames and fsyncs; settle removes the artifact +set and op record. Failpoints `AfterSeal`, `AfterBuild`, `AfterWalSwitch`, +`AfterVerify`, `BeforeInstall`, `AfterInstall` and `CapacityAtBuild` cover the +crash states; the artifact set is +`.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`; a stray name is +`Exists`, a `(dev, ino)` change is `StaleStore`, and a sealed-tuple change at +install is `Conflict`. The path is `none` below 10 percent, `rebuild` at or +above it; an empty Store is `none` with `zeroReason: empty-store`; a started +rebuild completes (§7). + +**PostgreSQL rebuild.** `PostgresHandles::compact` runs four phases. M writes +`kept_node`, `gc_op` (phase `mark`, scratch `lfs_gc_`), `gc_dead` and the +dead totals. A creates the scratch schema with LIKE copies of `pack` and +`object_location`, copies retained rows in idempotent batches of 512 packs, +then adds the prefix index, foreign key and `ANALYZE`. B is one short +transaction: `ACCESS EXCLUSIVE NOWAIT` (`55P03` is `Busy`), re-read the mark +tuple and digest (`Conflict` on change), copy owner and ACL, swap the tables, +recreate `pack_immutable`, settle the totals, set `G + 1`, re-check +`synchronous_commit` and the standby predicate, drop the scratch, `COMMIT`. C +deletes only `gc_dead` members, clears `binding_hint_block` and the acquisition +rows, reduces `store_totals` once against the row sums, clears `gc_dead` and +`gc_op`, and releases the intent. The next call adopts a dead idle owner, is +`Busy` on a live owner, and resumes Phase C at `G + 1`; a lost `COMMIT` reply +is resolved by proving the backend ended, then reading the incarnation. +PostgreSQL reports `backendReusable = 0` and `postgresql-in-place`, and has no +`inode` table (§8, §9). + +**Report, status, metrics.** `CompactReport`/`CompactStatus` in +`engine/crates/layerfs-persistence/src/report.rs` and the single serializer in +`control/crates/layerfs-store/src/report.rs` render every §11 field in +snake_case (`dead_bytes_bound`, `kept_waste`, `residue`, `estimate`, and one +`zero_reason` per zero field from +`empty-store|none-path|no-history|no-waste|postgresql-in-place`). `store.status` +adds `op {id, name, phase, started, uncertain}`, `state` (`busy` or +`unresolved`; `uncertain` is true for every remaining record) and the backend +`phases` (SQLite `mark/build/verify/install`; PostgreSQL +`mark/build/swap/cleanup`). `compact_metrics.rs` publishes counters (`runs`, +`operations{outcome}`, `refusals{code}`, `settles{kind}`, `retries{reason}`, +`status{state}`, `slo{objective,result}`), phase durations and last-run §11 +gauges, with labels only from closed enums. + +**API, MCP, CLI, SDK.** The call table is 76 entries (38 work / 38 admin); the +four calls are admin-only and refused under a folder scope with `out of +scope: `. `project.remove` is retired: old clients get `InvalidInput`, +MCP reports an unknown tool, and the CLI exits 2; `project.init` on a held name +is `NameTaken`. MCP names are `branch_remove`, `project_delete`, +`project_remove_file` and `store_compact`; the CLI has `layerfs branch remove`, +`project delete`, `project remove-file` and `store compact`; JS and Python +expose the same four methods. The call log redacts path-bearing arguments +(``) and hashes keys with `trace_salt`. + +| Expected-base CAS upstream | `CommitRequest` carries `expected_head`, `expected_base` and `expected_root`; a moved Branch is `HeadMoved` and nothing is written, so a stale daemon commit cannot clobber a removal | +| Whiteouts | `remove_file` hides at the frontier; merge, publish and mount materialize the whiteout; a merge that cannot is `Removed` with full path elements | +| `gc_intent` / `gc_op` / `gc_dead` | intent is admission and liveness; `gc_op` is the one compaction row with phase, scratch and owner; `gc_dead` is persisted membership, not a predicate | +| Generation | `catalog_incarnation` is `G`; a rebuild installs `G + 1`; leftovers, fences and resume judge by the recorded generation | +| Reclaim unit | the pack; a rebuild copies retained rows into a fresh Store; no in-place pack delete; `rebuild iff total > 0 AND dead * 10 >= total`; a started rebuild completes | +| Visibility-only `remove_file` | 2.0 hides the path and keeps objects reached only through it; a path-aware walk is a follow-up | +| Thresholds | `deadBytesBound` from the metadata walk, `deadBytesRefined` from the payload sweep; PostgreSQL always reports them equal | + +## 3. Test evidence + +T-G75 re-ran the suites from main `32ae51ca` on 2026-11-15 in a Sandbox +Workspace (Branch `task-g75`); the counts below are those runs unless the row +names an earlier run. Earlier lanes were recorded on main `32df79da` or the +Branch the row names. The final lanes are: + +| Suite | Result | Recorded by | +|---|---|---| +| `layerfs-persistence` (full lane) | 271 passed, 0 failed, 3 ignored | T-G75 (T-G24: 264/0/2) | +| `layerfs-store-service` | 214 passed, 0 failed, 15 ignored | T-G75 (T-G24: same) | +| `layerfs-store` | 59 passed, 0 failed, 0 ignored | T-G75 (T-G24: same) | +| `postgresql_compact` | 20 passed (real `pg_terminate_backend` reply-loss arms and the restricted-role privilege arms) | T-G38/T-G54 | +| `postgresql_status` | 3 passed (persistence) + 1 passed (control) | T10.5/T-G53 | +| `postgresql_compact_fixtures` | 5 passed | T12.3b | +| `sqlite_compact` | 20 passed | T-G52; re-run T-G75 | +| `sqlite_compact_crash` | 23 passed (13 in-process + 9 real-process SIGKILL + the re-executed child placeholder) | T-G28/T-G60, re-run T-G52 and T-G75 | +| `sqlite_compact_fixtures` | 1 passed | T-G52; re-run T-G75 | +| `sqlite_compact_matrix` | 1 runner, 8 executed arms | T-G52; re-run T-G75 | +| `sqlite_compact_capacity` | 1 passed, 1 ignored (the opt-in 50 GB arm is not run by default) | re-run T-G75 | +| PostgreSQL doctor (physical) | 16 passed | T-G55 | + +**SQLite lane (T12.3-era baseline; the final counts are the table above).** + +| Binary | Tests | Pins | +|---|---|---| +| `sqlite_compact` | 20 | `none`/`rebuild`, 9/10/30 percent, empty Store, capacity abort, layouts, stray name, report fields, leftover op | +| `sqlite_compact_crash` | 23 | in-process failpoints at seal/build/WAL switch/verify/install/settle and the artifact set, plus 9 real-process SIGKILL arms (mark: BeforeSeal/AfterSeal; copy: BeforeVacuum; verify: DuringVerify; rename: DuringRename; build: AfterBuild; install: BeforeInstall/AfterInstall; settle: DuringSettle) and the re-executed child placeholder | +| `sqlite_compact_fixtures` | 1 | golden receipt with every §11 field, digest vector, three outcomes | +| `sqlite_compact_matrix` | 1 runner, 8 arms | checkpoint busy, sidecar at install, status phases, error codes, seal, random shapes, measurement, digest row after collection | +| `compact_metrics`, `admission`, `path_removal`, `branch_removal`, `project_delete` | 4, 5, 3, 3, 5 | metrics, admission races, frontier, markers | +| `epoch_fence`, `gc_backfill`, `kept_objects`, `kept_node`, layouts, upgrade | 7, 4, 5, 7, 7+9, 2+2 | epoch rollback, backfill, retention, layouts | +| `gc_trace`, `gc_calls`, `calls_scope` (API) | 5, 8, 4 | redaction, four-call shapes, scope refusal | +| `compact_report_status`, `project_delete` (control) | 3, 15+6+2 | wire shape, status, sidecar and frames | +| `branch_remove`, `admission`, `epoch_fence`, `project_delete`, `kernel_guard` (store-service) | 3, 1, 1, 1, 7 | service removals and guard | + +**PostgreSQL lane (T12.3b baseline; the final counts are the table above).** +PostgreSQL 17.12, `cargo test -p layerfs-persistence +--features postgresql`, `--test-threads=1`: 15 test binaries, 73 tests passed +at T12.3b. The run covers `postgresql_compact` (8 at that layer; 20 on +`32df79da`), `postgresql_compact_fixtures` (5, +three consecutive runs), `postgresql_position_columns` (4), +`postgresql_open_check` (3), `postgresql_diagnostic` (5), +`postgresql_acquisition` (4), `postgresql_acquisition_compaction` (4), +`postgresql_identical_ids` (3), `layerstack_removal` (2), +`postgresql_commit_round_trips` (1) and the SQLite controls. The new fixture +proves the §6.4 digest is byte-identical to the SQLite golden and the rebuild +report and markers hold on PG. + +**Harness and CI.** `tools/ci/test_store_ext4.sh` requires +`LAYERFS_TEST_TMPDIR` on ext4, xfs or btrfs (apfs or hfs on macOS), refuses +tmpfs, overlay, FUSE and network mounts before cargo, and points `TMPDIR`, +`CARGO_TARGET_DIR` and `CARGO_HOME` there. `--quick` runs a cross-suite +subset; `--full` runs every Store suite and adds `--features postgresql` when +`LAYERFS_TEST_POSTGRES_URL` is set. `.github/workflows/store-ext4.yml` is the +CI lane: `quick` on push and pull request, `full-postgresql` (a `postgres:17` +service) on schedule and manual dispatch; it is report-only. + +## 4. Acceptance matrix status + +The matrix has 60 cases (47 both, 6 SQLite-only, 7 PostgreSQL-only). Only +#52 records acceptance; these notes record evidence and tier. + +| Runner | Executed | Covered/pass | Partial | Deferred | Gaps | +|---|---|---|---|---|---| +| T12.3a SQLite half (pre-T12.3c) | 5 | 24 | 16 | 7 (PG-only) | 8 | +| T12.3b PostgreSQL half | 0 | 11 | 11 | 8 | 0 | +| T12.3c SQLite gap closure | 8 | 29 | 16 | 7 (PG-only) | 0 | +| T-G28 real-process SIGKILL (AC-01) | 8 | 28 | 17 | 7 (PG-only) | 0 | +| T-G38/T-G54 PG reply loss and privileges (AC-44) | 8 | 29 | 17 | 6 (PG-only) | 0 | +| T-G60 remaining SIGKILL points (AC-01) | 8 | 29 | 17 | 6 (PG-only) | 0 | +| T-G65 real-process `store.compact` kill (AC-01) | 8 | 30 | 16 | 6 (PG-only) | 0 | + +T12.3c closed the eight SQLite gaps: AC-06 (post-compaction Save of a +collected digest), AC-11 (non-FF merge whiteouts and publish at the +frontier), AC-12 (removed path in a merge), AC-13 (unmerged Branch marker +inheritance), AC-14 (layer-headed mount whiteout), AC-22 (concurrent +merge/removal property), AC-34 (bind failure and failed intent delete) and +AC-36 (worker lost reply); its report records "SQLite gaps: none". The +PostgreSQL half's partial and deferred rows are AC-02, AC-29, AC-30, AC-31, +AC-32, AC-34, AC-35, AC-36, AC-37, AC-38, AC-41, AC-42 and AC-60. T-G28 +added the real-process SIGKILL arms of `sqlite_compact_crash.rs`; AC-01 moved +from `covered` to `partial` because the kill targeted a test child, not the +production process. T-G60 extended the real arms to the mark (`BeforeSeal`/ +`AfterSeal`), copy (`BeforeVacuum`), verify and rename points. T-G65 then +started the built `layerfs store compact` command, killed that process at the +mark, build, verify and install points, and asserted `G`/`G + 1`, the +artifact set, the `store.status` projection and the settling run, so AC-01 is +`covered` again (the long-lived `layerfs worker` is still not the killed +process). T-G38's real `pg_terminate_backend` kills and T-G54's +restricted-role fixtures moved AC-44 from `deferred` to `covered`, so the +final dispositions are 8 executed, 30 covered, 16 partial and 6 deferred. +T-G75 re-checked all 60 matrix rows against `32ae51ca` and kept those +dispositions (AC-01 and AC-44 `covered`, AC-57 `partial`). + +## 5. Known gaps and limitations + +These are the gaps that remain on `32ae51ca`; tasks that closed an earlier gap +are recorded in §7 instead. + +- **Clippy clean (fixed by G58/G63/G71).** The gap is closed: G58/G63 fixed + the former 11 pre-existing warnings and G71 fixed the last two; T-G75 + re-ran + `cargo clippy -p layerfs-persistence -p layerfs-store-service --all-targets --features postgresql --no-deps -- -D warnings` + and it exits 0 with zero warnings on the lib and test targets. +- **Branch-delete CLI deployed (fixed 2026-11-15).** The gap is closed: the + 2.0.0 build `4e65ebbae` is live with host CLI `1dc15838…`, bundle `layerfs` + `c4737445…`, `layerfs-daemon` `b8dd0766…` and + `layerfs-sandbox-helper` `3d033ec0…`; `layerfs help branch` ends with + `branch remove `, and a probe against a missing name + returns `NoSuchBranch`. Operators use `layerfs branch remove` directly; MCP + `branch_remove` and the SDK method stay equivalent. The cutover opened the + Store with the one-way GC schema migration: the sqlite file grew + 1,111,203,840 -> 1,111,310,336 B (live hash `d5d65e3b…`) on first open. +- **PG `physicalShrink` is a keyword proxy.** PostgreSQL computes + `physical_shrink` from the `pg_total_relation_size` delta of `pack` and + `object_location` around the swap (an in-place rewrite), not from file-level + bytes; `backendReusable = 0` with `postgresql-in-place` names that absence. + SQLite keeps the file-level measure. +- **Real `kill -9` of the production compaction process (T-G28/T-G60/ + T-G65; AC-01 `covered`).** `sqlite_compact_crash.rs::real_process` spawns a + separate process on the fixture Store and the parent sends `SIGKILL` while + it is stopped at the failpoint; T-G60 extended those arms to the mark + (`BeforeSeal`/`AfterSeal`; the `BeforeSeal` kill keeps the writer + session's WAL sidecars, which the next open replays), copy + (`BeforeVacuum`, immediately before `VACUUM INTO` because SQLite runs that + copy as one uninterruptible call), verify (`DuringVerify`) and rename + (`DuringRename`). Those arms kill a re-executed test child, so T-G65 adds + the production process: + `api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs` starts the + built `layerfs store compact` command, the engine's gate stops it at the + named failpoint, and the test `SIGKILL`s it there, then reopens through the + CLI and asserts `G`/`G + 1`, the artifact set and sidecars, the + `store.status` phase/`uncertain`/`unresolved`, the settling next run, the + retained layer and `doctor`. No daemon serves Store calls (#352 F-020), so + this is the process that performs the native compaction; the long-lived + `layerfs worker` that serves a machine's Store is still not the killed + process. +- **Capacity model: 10 GB and 50 GB measured (T-G61, T-G66).** + [`gc-capacity-model.md`](gc-capacity-model.md) rests on a real 9.987 GB + Store measurement (`sqlite_compact_capacity.rs#capacity_measure`): `none` at + 8.88% dead (3 runs, median 149.318 s) and `rebuild` at 10.00% dead (3 runs, + median 246.371 s; mark 149.089 s, build 94.317 s, verify 0.312 s, install + 1.916 s; dead 1.011 GB, shrink 1.017 GB, peak temp 9.144 GB, 1.90x total + footprint), plus one WAL/FULL rebuild (284.078 s). T-G66 then measured the + **50 GB** arm (one run per arm, `sqlite_compact_capacity_measure_50gb.json`): + 49.999 GB pack bytes / 50.863 GB physical, `none` at 8.876% dead + (1,633.585 s) and `rebuild` at 10.000% dead (5,131.835 s; mark 784.251 s, + build 4,254.371 s, verify 85.557 s, install 7.311 s; dead 5.062 GB, shrink + 5.100 GB, old-formula receipt peak temp 45.784 GB). The 50 GB numbers are + **not** linear from 10 GB: the build phase is 93.0 s/GB new instead of 10.3, + so the rebuild is 85.5 min instead of the [E] ~20 min, and the sampled real + peak is 143.1 GB (~2.9x the Store). T-G72 replaced the old `new + visited` + receipt with a bound over the staged copy, the new file, the rollback + journal and the visited scratch: **147.609 GB (2.90x the old file)** for the + same 50 GB `rebuild`, 3.2% above the sampled peak, tracked as + [layerfs#695](https://github.com/Ephemeral-AI-Lab/layerfs/issues/695). + The 30% dead / 50 GB-live arms and the `ACCESS EXCLUSIVE` duration remain + [E]. +- **PostgreSQL `--test-threads`.** T-G14 gave each `postgresql_compact` test + its own catalog binding (`postgresql-compact-`), so its 20 tests pass + with the default test threads (three consecutive runs); the Store-scoped + advisory key is no longer shared. Other PG suites that still share one + schema or session state keep `--test-threads=1` until they get the same + per-test binding. +- **`.git/index` merge rule.** `/.lww` lists `/.git/index` after + `%include .gitignore`, so merging a Branch forked from an older layer keeps + the newer index whole instead of conflicting on the binary file. Only this + generated file is added; no source file is listed. +- **Branch cleanup is soft and bounded (updated 2026-11-15).** `branch.remove` + is live, but removal is a marker write: the name stays taken (a re-fork is + `NameTaken` with holder `state: "retired"`, reads are `NoSuchBranch`) until + `store.compact` collects the rows, and `main` is `ReservedName`. A Branch + with a live mount is `MountsActive`, and a Branch pinned by a retained Layer + or `commit.branch_id` also keeps `NameTaken`; a rebuild needs an idle Store. + The 2026-11-15 cleanup retired 145 Branches (20 empty + 125 superseded) and + deliberately left 162 (unknown or non-empty); T-G75 re-probed the live CLI + on `32ae51ca` (a missing name is `NoSuchBranch`) and counted 174 live + Branches, the 162 that cleanup left plus later gap-fix task Branches. The + remaining work is data judgment, not a missing capability. +- **`project.remove` retired.** Old clients get `InvalidInput`, MCP reports an + unknown tool, and the CLI exits 2; there is no compatibility alias. +- `remove_file` reclaims no bytes in 2.0; a path-aware walk is a follow-up. + PostgreSQL ACL replay is best-effort, and `markBytes` is a #52 metric, not a + report field. Compaction metrics are process-local with no SDK or CLI + renderer, and PostgreSQL compactions have no metrics yet. +- AC-60's real standby arms and the reserved-pack race of AC-42 are deferred; + AC-28/41/43 have T12.3b evidence and AC-35's advisory-key refcount does not. + +## 6. How to run + +``` +# SQLite compaction lane, on a filesystem that carries SQLite locks +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --quick +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --full +cargo test -p layerfs-persistence --test sqlite_compact +cargo test -p layerfs-persistence --test sqlite_compact_crash +cargo test -p layerfs-persistence --test sqlite_compact_fixtures +cargo test -p layerfs-persistence --test sqlite_compact_matrix +UPDATE_GOLDEN=1 cargo test -p layerfs-persistence --test sqlite_compact_fixtures + +# PostgreSQL, one thread +LAYERFS_TEST_POSTGRES_URL="host=127.0.0.1 port=55432 user=postgres dbname=postgres sslmode=disable" \ + cargo test -p layerfs-persistence --features postgresql --test postgresql_compact -- --test-threads=1 +``` + +The ext4/xfs/btrfs requirement is the kernel guard +(`engine/crates/layerfs-store-service/src/kernel_guard.rs`): tmpfs, overlay, +FUSE and network mounts are refused `Unsupported` because they cannot carry +the WAL locks and the directory flock. Inside a Docker Sandbox the run +directory (`$HOME`, `/layerfs/data/machine/native/run/`) is ext4; +`/tmp` is tmpfs there. The PG value is a libpq keyword string; +`postgresql_diagnostic` needs the URI form. + +## 7. Commit and branch index + +Main layers are publications; heads are the saved Branch tips. `T12.3b` was in +flight at the baseline and is now published on main (`32223b46`, tidy `32927884`). + +| Epic | Branch | Head commit | Main layer | Result | +|---|---|---|---|---| +| T1 schema and position | task-t1.2d-merged, task-t1.7-merged3 | 12eee0da5b, 12fb3019bd | 32b602714d, 32860cbe46 | markers, intents, serials, epoch, trace salt, backfill | +| T2 history contract | task-t2.4-ctors-test-merged3 | 12ebeb2dfb | 32c5500017 | typed `NameTaken`/`Removed`, catalog stubs | +| T3 `branch.remove` | task-t3-final5 | 12dabb4673 | 3256c829a6 | `branch_retired`, `ReservedName`, name lifetime | +| T4 `project.delete` | task-t4.6-merged | 12e8a214b4 | 32aca049c3 | `layer_stack_retired`, sidecar, retry | +| T5 `project.remove_file` | task-t5.8 | 12f58625e0 | 3299d92d08 | `path_removed`, frontier, whiteouts, grammar | +| T6 admission and epoch | task-t6.5-merged4 | 12ebc5d982 | 32e895c4eb | `gc_intent`, codes, epoch fence, PG advisory keys | +| T7 mark and closure | task-t7.2 | 12a41bf33f | 3240699d11 | mark tuple, closures, `kept_node`, digest | +| T8 SQLite rebuild | task-t8.1-merged | 122151d179 | 323465c8b3 | seal, visited, verify, rename install, failpoints | +| T9 PostgreSQL rebuild | task-t9e | 1225694fd7 | 32c9181e3d | phases M/A/B/C, `gc_op` resume, standby | +| T10 report, status, metrics | task-t10.1b, task-t10.3-final | 121262d292, 1236755412 | 32515e1b2a, 3271a46892 | §11 report, status op, `compact_metrics` | +| T11 API, MCP, CLI, SDK | task-t11.3-final | 1271019370 | 3218fea5bc | 76 calls, admin profile, `project.remove` retired | +| T12.1 SQLite fixtures | task-t12.1-merged2 | 12db7c4ea4 | 32444eb25c | golden receipt, §11 fields, digest vector | +| T12.2 SQLite crash matrix | task-t12.2-merged2 | 12433023b7 | 32502588ab | failpoints, artifact set, `StaleStore` | +| T12.3a SQLite matrix | merged3-t12.3a | 1277362ac5 | 327d6a42bd | 5 executed / 24 covered / 16 partial / 8 gaps | +| T12.3b PostgreSQL acceptance | task-t12.3b-final | 1210405949 | 32223b46 | PG-half matrix, 15 binaries / 73 passed (published) | +| T13 spec gaps and runbook | task-t13b, task-g17-publish | 12c0efe9dd, 12dcce8e15 | 32ab564277, 3284fb82 | G1-G6 decisions, operator runbook, testing docs | +| T-G13 default-feature build | task-g13-pub2 | 1299885ee9 | 32971532c5 | PG imports gated behind the feature | +| T-G28 real-process SIGKILL | task-g28-merged | 12106c4dd7 | 32a7d0cf07 | 4 SIGKILL arms; AC-01 `partial` | +| T-G52 SQLite crash re-run | task-g52 | 12c002e409 | 32bf908cf5 | 20/18/1/1, matrix 8 arms | +| T10.5 PG `store.status` | merged-t10.5c | 12f80d29df | 328a16a4c9 | persistence `postgresql_status` 3, control 1 | +| T-G38 PG reply loss | task-g38b-merged | 128162224e | 32dc46a25a | real backend kills and lost `COMMIT` | +| T-G53 PG status control | g53-merged | 12876c4f1f | 322a2c59a1 | control `postgresql_status` +1 | +| T-G54 PG privileges | g54-merged | 12f5197908 | 32a2621dbb | AC-44 `covered`; `postgresql_compact` 20 | +| T-G55 doctor physical | g55-integ | 122880b8b6 | 3285f0d588 | 16 checks | +| T-G57 closeout base | g57-merged | 12babcbaea | 32df79da | T-G57 publication | + +The docs-only review rounds A-M are on `gc-phase-a` ... `gc-phase-m` and the +`gc-schema`/`gc-contract` branches; they changed no product contract. The +post-closeout gap fixes are published as `task-g58-merged2` (G58/G63 clippy), +`task-g63`, `task-g64`, `g61-integ` (capacity harness), `task-g65-merged` and +`task-g65-merged2` (real-process kill), `task-g67` (physical doctor proxy), +`task-g69` (runbook and cleanup), `g70-merged` (report), `task-g71` (final +clippy), `task-g66b` (50 GB measurement), `task-g72` (peak-temp bound) and +`task-g74` (report generator); T-G75 audits those layers. + +## 8. Closeout + +- **Final main layer.** `32ae51ca` (root `d0b744cb`), the layer this audit + certifies; it is the T-G74 publication (commit `128899cd74`). The chain from + the previous closeout is T-G57 `32df79da` -> T12.8 `3255cfb1fa` -> T-G60 + `32284e2d4c` -> T-G59 `327b250e45` -> T-G58 `329abfa4b4` -> T-G63 + `32e51aa657` -> T-G64 `32feb7df87` -> G61 `32977da52f` -> T-G67 + `327892e625` -> T-G69 `32cfd1e67a` -> T-G65 `3299d19429` -> `32957696ef` + -> G70 `32bb6d7557` -> G71 `32f89ff7b8` -> T-G66b `32c363ad8a` -> T-G72 + `327aa16ab0` -> T-G74 `32ae51ca`. This closeout publishes as main's next + layer. +- **Shipped.** Four admin-only, ids-only calls on SQLite and PostgreSQL: + `branch.remove`, `project.delete`, `project.remove_file` and + `store.compact`; the §4.1 additive schema and deterministic backfill; the + `gc_intent`/`gc_op` admission intent, the epoch fence and the §6.1/§6.2 + mark with the §6.4 digest; the SQLite seal/visited/verify/rename rebuild + with the 10% `none`/`rebuild` threshold and named failpoints; the + PostgreSQL Phase M/A/B/C rebuild with `gc_op` resume, ACL and the standby + predicate; the §11 `CompactReport`/`CompactStatus`, `store.status` and + `compact_metrics` (SQLite phases plus `pg_mark`/`pg_build`/`pg_swap`/ + `pg_cleanup`); the 76-call API/MCP/CLI/SDK table with `project.remove` + retired; and the ext4 harness plus report-only CI lane. +- **Final test evidence on `32ae51ca` (T-G75 re-run).** 271 passed / 0 failed + / 3 ignored (`layerfs-persistence`; T-G24 recorded 264/0/2), 214/0/15 + (`layerfs-store-service`) and 59/0/0 (`layerfs-store`), 544 passed / 0 + failed / 18 ignored in all. The five SQLite compaction targets re-ran to + `sqlite_compact` 20, `sqlite_compact_crash` 23, `sqlite_compact_fixtures` + 1, `sqlite_compact_matrix` 1 runner (8 arms) and `sqlite_compact_capacity` + 1 passed + 1 ignored (the opt-in 50 GB arm). The PostgreSQL lanes were not + re-run here (this Sandbox has no server): 20 `postgresql_compact` (T-G54), + 3+1 `postgresql_status` (T10.5/T-G53), 5 `postgresql_compact_fixtures` + (T12.3b) and 16 doctor-physical checks (T-G55) stay as recorded. The full + table is in §3. +- **Clippy clean (G58/G63/G71).** G58/G63 fixed the former 11 pre-existing + warnings and G71 fixed the last two; T-G75 re-ran + `cargo clippy -p layerfs-persistence -p layerfs-store-service --all-targets --features postgresql --no-deps -- -D warnings` + to exit 0 with zero warnings on the lib and test targets. +- **Matrix after T12.3c, T-G28/T-G60, T-G38/T-G54 and T-G65.** 60 cases: 8 + `executed`, 30 `covered`, 16 `partial`, 6 `deferred` (all + PostgreSQL-only), 0 SQLite evidence gaps, 0 `pending`; T-G75 re-checked all + 60 rows on `32ae51ca` (AC-01 and AC-44 `covered`, AC-57 `partial`). +- **Remaining partial (16).** AC-02, 04, 11, 15, 19, 20, 21, 23, 30, 32, + 34, 37, 53, 54, 56, 57. Why: the SQLite half is proven but the PostgreSQL + half is T12.3b's or not named (AC-02/30/32/34), the full form/read-surface + table is not one test (AC-19/53), the named arm is not inducible or does not + exist (AC-11's inapplicable-whiteout branch, AC-34's failed intent delete), + or the E3 scale/three-run arms remain (AC-04, 56, 57). +- **Remaining deferred (6, PostgreSQL-only).** AC-28, 35, 41, 42, 43, 60. + T12.3b executes the PG halves of AC-28/41/43; AC-35 (advisory-key refcount) + and AC-42 (reserved-pack race) have no deterministic pause point, while + AC-60 (a real standby) needs server control the harness does not have. +- **Capacity model.** [`gc-capacity-model.md`](gc-capacity-model.md) records a + real 9.987 GB measurement ([M]: `none` 149.318 s, `rebuild` 246.371 s median, + phase sums and the T-G72 peak bound in + `sqlite_compact_capacity_measure.json`) and the real 49.999 GB measurement + ([M], one run per arm, phase sums and 5.100 GB shrink in + `sqlite_compact_capacity_measure_50gb.json`; 85.5 min rebuild, sampled peak + 143.1 GB). T-G72 replaced the old `new + visited` receipt with a documented + bound over the staged copy, the new file, the rollback journal and the + visited scratch: **147.609 GB (2.90x the old file)** for the 50 GB + `rebuild`, 3.2% above the sampled peak, tracked as + [layerfs#695](https://github.com/Ephemeral-AI-Lab/layerfs/issues/695). + AC-57 stays `partial` for the section 13 30% dead / 50 GB-live arms and the + PostgreSQL arms. +- **Branch-removal cutover and cleanup (2026-11-15, main `327892e6`).** + `branch.remove` is live end to end. Build identity: version `2.0.0`, + commit `4e65ebbae`; host CLI `1dc15838…`, bundle `layerfs` `c4737445…`, + `layerfs-daemon` `b8dd0766…`, `layerfs-sandbox-helper` `3d033ec0…`. The + Store was opened once by the new build (one-way GC schema migration, + 1,111,203,840 -> 1,111,310,336 B, live hash `d5d65e3b…`). Probe: + `layerfs branch remove … __deploy_probe_missing__` is `NoSuchBranch`; + `help branch` lists `remove`. Semantics are unchanged (§4.2): the marker + hides the Branch, `branch remove … main` is `ReservedName`, and the name + stays taken until `store.compact` rebuilds. Retirement: 307 -> 287 (20 + empty) -> 162 (125 superseded), 145 total, 0 refusals; 162 remained by + choice (unknown or non-empty, deliberately untouched). T-G75 re-probed the + live CLI from `32ae51ca`: `help branch` lists `remove`, a missing name is + `NoSuchBranch`, and the Store holds 174 live Branches (the 162 that cleanup + left plus later gap-fix task Branches). Backup: + `/home/dell/lfs-work/backup-20261115-180517` (earlier + `/home/dell/lfs-work/backup-20261115-180149`); rollback was not needed. + `layerfs doctor` is `{"ok":true,"findings":[]}`, and no Sandbox/Workspace of + the cutover or cleanup remains. +- **Validation checklist (T12.8, re-verified T-G75).** Every artifact below + exists on `32ae51ca`; rows 12-13 record the 2026-11-15 cutover and are + re-verified on main `32ae51ca`: + + | # | Artifact | Path | Check | + |---|---|---|---| + | 1 | implementation report | `core/docs/issues/project-41/gc-implementation-report.md` | present; updated by T-G75 | + | 2 | acceptance matrix | `core/docs/issues/project-41/gc-acceptance-matrix.md` | present; 60 rows, 8/30/16/6 | + | 3 | capacity model | `core/docs/issues/project-41/gc-capacity-model.md` | present; 10 GB (3 runs) and 50 GB (1 run) measured [M]; T-G72 peak bound 147.609 GB (2.90x); 30% dead / 50 GB-live and PG arms [E] | + | 4 | 76-call coverage | `docs/architecture/api/calls/coverage.md` | generated block: 76 calls, 10 families, no front-end problems | + | 5 | ext4 harness | `tools/ci/test_store_ext4.sh` | present, executable | + | 6 | CI lane | `.github/workflows/store-ext4.yml` | present; `quick` and `full-postgresql` | + | 7 | PG phase metric | `engine/crates/layerfs-persistence/src/compact_metrics.rs` | `PostgresMark => "pg_mark"` | + | 8 | real SIGKILL arms | `engine/crates/layerfs-persistence/tests/sqlite_compact_crash.rs` | `sigkill_before_seal`, `sigkill_after_seal`, `sigkill_during_copy`, `sigkill_during_verify`, `sigkill_during_rename`, `sigkill_after_build`, `sigkill_before_install`, `sigkill_after_install`, `sigkill_during_settle` | + | 9 | privilege check | `engine/crates/layerfs-persistence/src/backend/postgresql/access.rs` | `compaction_missing` checks both `CREATE`s and `pg_read_all_stats` | + | 10 | PG conninfo helper | `engine/crates/layerfs-persistence/tests/pg_doctor/conninfo.rs` | present | + | 11 | PG status control | `control/crates/layerfs-store/tests/postgresql_status.rs` | present; 1 test | + | 12 | `branch.remove` live | host CLI `layerfs branch remove` | live on 2.0.0/`4e65ebbae`, re-probed T-G75; `help branch` lists `remove`; probe on a missing name returns `NoSuchBranch` | + | 13 | doctor clean after cutover | `layerfs doctor` | `{"ok":true,"findings":[]}`; 145 Branches retired (20 empty + 125 superseded), 162 remained then and 174 are live on `32ae51ca`; removal is soft, so a name returns only after `store compact` | + | 14 | clippy clean | `cargo clippy -p layerfs-persistence -p layerfs-store-service --all-targets --features postgresql --no-deps -- -D warnings` | T-G75: exit 0, zero warnings | + | 15 | final suite re-run | `cargo test -p layerfs-persistence -p layerfs-store-service -p layerfs-store --no-fail-fast` | T-G75: 544 passed / 0 failed / 18 ignored; the five SQLite compaction targets keep 20/23/1(+1 ignored)/1/1 | + + `git diff --check` is clean on the closeout Branch. +- **How to run.** + `LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --quick` + (or `--full`, adding `--features postgresql` when `LAYERFS_TEST_POSTGRES_URL` + is set) needs ext4/xfs/btrfs. `cargo test -p layerfs-persistence --test + sqlite_compact_matrix` runs the T12.3c arms; `UPDATE_REPORT=1 cargo test -p + layerfs-persistence --test sqlite_compact_matrix` regenerates the report. + The opt-in capacity arm is + `CAPACITY_MEASURE=1 UPDATE_CAPACITY=1 cargo test -p layerfs-persistence + --release --test sqlite_compact_capacity -- --ignored --nocapture` with a + TMPDIR of >=2.2x the target; it writes + `tests/fixtures/sqlite_compact_capacity_measure.json`. + `.github/workflows/store-ext4.yml` is the report-only CI lane. diff --git a/core/docs/issues/project-41/gc-rollout.md b/core/docs/issues/project-41/gc-rollout.md new file mode 100644 index 0000000000..5765c7f3c9 --- /dev/null +++ b/core/docs/issues/project-41/gc-rollout.md @@ -0,0 +1,119 @@ +# GC rollout, rollback and dry run (T1.6) + +> Plan for the frozen `LayerFS-GC-spec.md` (2.0.0; the spec wins, `§N` cites it). This page adds no contract and no option: the four calls take only a resource +> identifier, with no confirm, force or dry run (§1), and are admin-profile only, refused under a folder scope (§10). + +## 1. Rollout order + +| Step | Content | Contract | +|---|---|---| +| T1.x | Additive schema: marker/intent tables, position state, `gc_op`/`gc_dead`, `trace_salt` | §4.1 | +| T3/T4/T5 | Removals `branch.remove`, `project.delete`, `project.remove_file`: marker rows only, no bytes freed | §4 | +| T6 | Admission: `gc_intent`, `MountsActive`/`Busy`/`Unresolved`, epoch fence | §5 | +| T7 | Mark: reachability closure at `G`, `none`/`rebuild` from wholly dead packs | §3, §6 | +| T8 | SQLite rebuild: seal, `visited` scratch, verify, rename install | §7 | +| T9 | PostgreSQL rebuild: Phase M mark, Phase A build, Phase B swap, Phase C cleanup | §8 | +| T10/T11 | Report (§11 fields) and API surface | §9–§11 | +| T12 | Acceptance (§12 cases) and measurement (§13) | §12 | + +Order is forced: a rebuild copies T1.x's tables and cleans T3–T5's marker rows. T8/T9 are independent per backend; no step enables `store.compact` by itself. + +## 2. Expand and contract + +- **Expand (T1.x, T3–T5).** The schema step only adds tables and columns and one idempotent backfill under the current schema identity; no column changes type or meaning, + none is dropped, and `history_meta.next_history_serial` is never lowered (§4.1). Removals add marker rows and bump `project_epoch.epoch` (§4, §5). Both are additive: a + Store that never removed anything and never compacts is a plain 2.0 Store. +- **Old readers.** SQLite takes the step as one more `add_*`; PostgreSQL's open check requires the exact table set and recorded definition, so the step rewrites that + definition for older Stores (§4.1). An older PG binary that predates the step refuses the upgraded Store, and the spec defines no down-migration: **downgrade is not + supported**. Roll forward, or restore a pre-upgrade backup. +- **Contract.** Two API contractions are version cuts, not toggles: `project.remove` leaves the call table (an old client gets `InvalidInput`, never a silent hard delete) + and `project.init` returns `NameTaken` instead of `Exists` (§4, §10). Both land with T1.x and are asserted in the error matrix. +- **Flags.** None are added. `store.compact` is opt-in by the caller invoking it: no automatic collection, no online sweep (§1), and the spec defines no global + enable/disable switch. Do not invent one; the only "enable" is the release cut plus §7, and an owner may simply not call it. + +## 3. Dry run + +`store.compact` has no dry-run option (§1). Two non-mutating paths exist and neither is a new call: + +1. **Copy rehearsal.** `backup.create`, `backup.restore` into a scratch Store/home, run `store.compact` against the *scratch* name, compare. §9 names `backup.create` + before compaction as the recovery path for a mark bug; a copy is the closest honest rehearsal. +2. **`none` outcome.** Below 10% wholly dead packs the path is `none`: mark only, nothing written, generation unchanged, `deadBytesRefined == deadBytesBound` (§3, §11). + It cannot be requested, but on a Store expected to be `none` it is a real non-mutating run. + +Compare, before → after (both backends; §11): + +| Observation | `none` | `rebuild` | +|---|---|---| +| `store.status` | no op before/after; phase visible during | same; phases `mark`/`build`/`verify`/`install` (SQLite) or `mark`/`build`/`swap`/`cleanup` (PG) | +| `generation {before, after}` | equal, `G` | `G → G + 1` | +| `deadBytesBound` ≥ `deadBytesRefined` | equal | refined ≤ bound, from the payload sweep | +| `logicalDiscarded` | 0 with a `zeroReason` | collected history `logical` bytes | +| `keptWaste` | measured, unchanged by the rehearsal | `{deadInRetainedPacksBytes, deltaBases, inodeBlocksBytes}` | +| `store_totals` | unchanged | `logical` unchanged; `canonical`/`stored`/`metadata` = old − `dead_*` (§7 step 4, §8 step 9) | +| `residue` | empty | empty after settle; nonzero is explained | + +Also compare `physicalShrink` and `backendReusable` (§11). A rehearsal that disagrees with the live Store is a fixture difference, not a different path: both obey the +same §3 rule. + +## 4. Rollback + +- **Schema is additive.** The T1.x step is the only schema change and re-running it is a no-op; there is no down-migration. Do not un-create the tables by hand: without + `gc_intent`/`gc_op` the Store cannot admit or recover an operation, and PostgreSQL's open check (exact table set, recorded definition) refuses it (§4.1). +- **Markers are not undone by dropping tables.** Dropping `branch_retired`, `layer_stack_retired` or `path_removed` would resurrect names and paths whose history a + rebuild may already have collected (a deleted project's rows are dropped by the rebuild, §7/§8), and §1 promises no undo. The only supported re-creation is a Commit + **after** the frontier that writes the path again: a post-frontier re-creation is visible, and the marker hides only inherited content (§4.3). A Branch or project name + is re-created after a rebuild frees it; the history is gone (§4.2, §12 "Names"). +- **A failed compaction keeps `G`.** A definite failure before the rename aborts and deletes the artifact set + `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}` (SQLite) or the recorded `lfs_gc_` scratch schema (PostgreSQL); the old Store is unchanged + apart from step 1's checkpoint (§7 step 8, §8, §9). Keep `G` and re-run later. +- **Installed-but-uncertain.** A failure of the rename/fsync itself, or a lost `COMMIT` reply, is not pre-install: keep the new Store at `G + 1`, settle the op `unknown` + and report it; never delete the artifact as if nothing happened (§7 step 8, §8). On PostgreSQL resolve a lost reply by proving the backend ended (`pid`, + `backend_start`, `usename`), then read the incarnation (§8). +- **Artifacts belong to the next `store.compact`.** Only a compaction that names them from its op removes them; a staged name no record names is `Exists` and is not + deleted (§9). Leave crash leftovers alone by hand. + +## 5. Verification gates + +| Phase | Tests | `store.status` / report | Doctor | +|---|---|---|---| +| T1.x | converted 1.0/2.0 Stores open; backfill (`history_serial`, `project_epoch`, `trace_salt`, never-lowered serial); `tools/store_blocks.py` | unchanged, no op row | full, before and after | +| T3–T5 | marker transaction, §4.2 visibility guard, admission races, whiteout on merge/mount/publish | no op left; `Removed`/`NoSuch*` shapes | full | +| T6 | intent lifetime, `machine_stopped`, `Unresolved` ownership, `holders` | `busy`/`unresolved` only while owned | full | +| T7 | closure vs reference walk, `live_heads_digest`, "no live object lost" (§12) | phase `mark`; path chosen | full on fixtures | +| T8 | §7 failpoints (mark/build/verify/install/WAL switch/artifact removal/op settle), exact artifact set, `StaleStore` | both paths' §11 fields; `physicalShrink`, `backendReusable` | `validate` before rename; full after | +| T9 | §8 failpoints (mark/build/swap/cleanup/scratch drop), `ACCESS EXCLUSIVE` duration, standby, reply loss, privileges | PG zeros (`backendReusable = 0`); resume from `gc_op` | full after cleanup | +| T10/T11 | §11 snake_case keys, `zeroReason` vocabulary, capped `cap`, scope refusals (§10) | phase and `op` projection | full | +| T12 | whole §12 matrix; independent `diagnostic/scan.rs` walk; 3 runs per arm (§13) | every field with unit and sampling point | full on fixtures | + +`quick_check` and the full doctor stay separate commands, not part of install (§7 step 6). A gate is green only on both backends, or on the rows §12 assigns. + +## 6. Failure handling + +- **Crash.** The Store is wholly old or wholly new (§9). The next `store.compact` judges the recorded `G`: at `G` the artifact is removed (not installed); at `G + 1` the + outcome is recorded and Phase C resumes. A PG crash in Phase M/A leaves only the scratch schema, which the op names; Phase B is atomic. +- **`Busy`.** A live mount, long-lived client or operation holds the scope. The call does not wait, retry or replay; prepare inactivity and call once later (§1, §5). +- **`Unresolved`.** A dead, uncertain owner's op. A non-owning call observes it; only the owning call (the next `store.compact`) adopts or clears it (§5, §10). An + unreachable machine reports `unknown`, never clean (§9). +- **Lost reply.** The outcome stays uncertain: read `store.status`, the op and the generation before deciding; never replay blind, and never delete a sidecar or an + artifact the op names. +- **Standby.** PostgreSQL waits only when `synchronous_commit` is at least `remote_write` and `synchronous_standby_names` is non-empty; the check runs before Phase M and + again inside the swap. A missing standby abandons with `Busy` (standby list); a standby dying after the check blocks the `COMMIT` unbounded (§8). SQLite has no such + gate. +- **`Capacity` / disk full.** Aborts, deletes the artifact, leaves the old Store unchanged apart from the checkpoint; `Capacity` is the real refusal path, not a codec + bound (§7). +- **`StaleStore`.** A connection that bypassed admission is caught at its next transaction; an in-flight transaction at install is a documented limit (§7, §10). + +## 7. Go/no-go: enabling `store.compact` on a shared Store + +1. `backup.create` succeeds and a `backup.restore` drill of this Store was done (§9). +2. `store.status` is clean: no `holders`, `state` not `busy`/`unresolved`, no live `gc_intent` row, no existing `.compact*` set or `lfs_gc_` schema. +3. All mounts, daemons and long-lived clients of the Store are gone, and no Init/merge row names it (§5); one owner knows nobody may start one during the window. +4. The backend's T8 or T9 gate and the §12 rows touching it are green; the full doctor is clean on a fixture of the same schema layout (§7 step 6, §12). +5. Disk headroom covers peak temp: old Store + new Store + journal/WAL + `visited` (SQLite); old tables + new heap/TOAST + indexes + live-bytes WAL and `pg_wal` headroom + (PG) (§7 cost, §8). +6. PostgreSQL only: `CREATE` on the database, `TEMP`, `USAGE`/`CREATE` on the Store schema, table ownership, `pg_read_all_stats`, else `Unsupported`; a direct or + session-pooled connection (transaction pooling is `Unsupported`); standby replication at the intended level (§5.2, §8). +7. The expected path is known: wholly dead bytes below 10% means `none` and no shrink — decide in advance whether the run is still wanted (§3). +8. The call is made under the MCP admin profile, not a folder scope (§10). +9. Rollback is understood: keep `G`, let only the next `store.compact` remove named artifacts, restore from backup if a mark bug is suspected (§9). +10. One attempt, no replay: a refusal from §6 is inspected before any second call (§1, §9). diff --git a/core/docs/issues/project-41/gc-runbook.md b/core/docs/issues/project-41/gc-runbook.md new file mode 100644 index 0000000000..2a238425c6 --- /dev/null +++ b/core/docs/issues/project-41/gc-runbook.md @@ -0,0 +1,181 @@ +# GC operator runbook: `store.compact` and the three removals + +> Operational page for the frozen `LayerFS-GC-spec.md` (the spec wins). Baseline +> `a6d84131b`; calls land in T3–T11. Admin-profile only, refused under a folder +> scope (§10). No confirm/force/dry-run; a lost reply stays uncertain, nothing retries itself (§1, §9). + +## 1. Triage: stuck compact or a phase in `store.status` + +`layerfs store status ` shows `holders`, `state` (`busy`/`unresolved`) and +`op = {id, name, phase, started, uncertain}` (§11). Phases — SQLite `mark`, `build`, +`verify`, `install`; PG `mark`, `build`, `swap`, `cleanup`. + +- **SQLite.** The op/phase is the *home op* (`store//record.json`, field `op`; + a remote home is read via `step_on`); the Store DB has the admission row: + `sqlite3 -readonly .sqlite "SELECT kind, scope_kind, state, uncertain, phase, generation, artifact FROM gc_intent WHERE state <> 'done';"` + Artifacts sit beside the Store file: `.compact{,-journal,-wal,-shm,-visited,-visited-journal,-mj*}`. + A direct reader may see `busy`/`locked` in the exclusive window; don't loop. Never unlink `-wal`/`-shm` (§7 step 1). +- **PostgreSQL.** `store.status` reads the Store-side `gc_op` (§11). On a direct or session-pooled `psql`: + + ```sql + SELECT generation, phase, scratch_schema, artifact, pid, backend_start, incarnation FROM gc_op; + SELECT (SELECT count(*) FROM gc_dead), (SELECT catalog_incarnation FROM history_meta); + SELECT kind, scope_kind, scope_id, state, uncertain, phase, artifact FROM gc_intent WHERE state <> 'done'; + SELECT nspname FROM pg_namespace WHERE nspname LIKE 'lfs_gc_%'; + ``` + + `gc_op` is the one compaction row; `gc_dead` is its persisted dead set (membership, + not a predicate); `gc_intent` is admission. `lfs_gc_` is recorded in `gc_op` + **before** `CREATE SCHEMA` (§8). Never INSERT/UPDATE/DELETE `gc_intent`, `gc_dead`, + marker tables or `project_epoch` by hand. + +## 2. `Unresolved`, live vs dead owner, lost reply + +`Unresolved` = a provably dead owner left an **uncertain** op; a non-owning call observes +it, the owning/next call settles it (§5.1, §10). A live owner is `Busy` — wait, don't kill it. + +1. Liveness comes from the recorded owner, not the clock: SQLite home op + `owner.pid`/`pid_start`/`pid_boot`; PG `gc_op.pid` + `backend_start` against `pg_stat_activity`. +2. Dead owner, uncertain op: run `layerfs store compact ` again; it adopts the dead + op with the artifact/high-water in the record (§9). `sandbox.close`/`machine.remove`/ + `store.remove` clear their own ops; `logs.reset` cannot (§10). A removed machine record alone is no proof (§5.1). +3. **PG lost `COMMIT` reply** — resolve on a *second* connection **before** the exclusive key + (§8). The swap recorded `pid`, `backend_start`, `usename` and the incarnation in + `gc_op` before the swap (`usename` is a `gc_op` column, §4.1). Prove the backend + ended, then read the generation: + + ```sql + SELECT pg_terminate_backend(a.pid, 30000) + FROM pg_stat_activity a + WHERE a.pid = AND a.backend_start = '' + AND a.usename = '' AND a.datname = current_database() + AND a.pid <> pg_backend_pid(); + ``` + + Check the boolean, poll until the `(pid, backend_start)` pair is gone, then read + `history_meta.catalog_incarnation`: `G` = not committed, `G+1` = installed. Needs PG 14+ + and `pg_signal_backend`/membership, else `Unsupported` (§8). Never terminate a live owner to clear `Busy`. + +## 3. Safe cleanup + +Default: **let the next `store.compact` judge it** (§9). The op names `G` and the artifact. +Store at `G` = not installed → next compact removes the named artifact set; `G+1` = +installed → it records the outcome. A dead owner's op is adopted; only a live owner blocks. + +- Delete by hand only when **no record names it**: no compaction `op`/`gc_op` row (PG: no + `gc_op.scratch_schema`/`artifact`), no live owner, no exclusive key. A stray at the staged + name with no record is refused `Exists` and not deleted by the code (§9); after the checks it is safe, otherwise leave it. +- Never remove `.compact-visited*` during a compact: it is the live visited set and part of `peakTempBytes` (§6.3, §11). +- **Never** delete a live Store's `gc_intent`/`gc_dead` by hand: admission and the Phase C + dead set are cleared only by the owning call on settle (§5.1, §8 Phase C). +- PG: drop `lfs_gc_` only when `gc_op` names no schema and no session holds the exclusive key; a named schema is the next compact's to remove. +- A definite pre-rename SQLite failure deletes its own artifact set; a rename/fsync failure is + **installed-but-uncertain** — keep the new Store, settle `unknown`, report it, never delete it (§7 step 8). + +## 4. Rollback and reversal (limits) + +- **Schema rollback is additive.** Marker/position/admission tables and the + `history_serial`/`trace_salt` columns are added at open; a downgrade leaves them (§4.1, + decision 6). No down migration; dropping them is not a rollback. The PG open check records + an exact table set (§4.1), so a pre-GC PG binary may refuse the added tables — forward-fix or restore instead. +- **Markers cannot be undone by dropping marker tables.** Dropping `branch_retired`/ + `layer_stack_retired`/`path_removed` resurrects retired rows without home entries, breaks + the "name never reused while rows exist" `BranchId::named` rule (§4.4), and cannot restore rows a rebuild already collected. +- **Supported reversal is re-creation after the frontier, never deleting markers** (§4.3): + a file is written/created at serial > `frontier_serial`; a Branch is created/forked once a + rebuild frees the name (new id/history); a project is `project.init`-ed once its retired stack row is collected (new empty project). +- **Limits.** Old ids/history/bytes never return; a Branch pinned by a retained Layer or + `commit.branch_id` keeps `NameTaken` (§4.4); `remove_file` reversal does not unhide + at-or-below versions; `rebuild` install is irreversible (§9). Content recovery is + `backup.create`/`backup.restore` from before compaction (SQLite; the server's backup for PG); + no undo copy is kept (§9, #155 D-24). The 2026-11-15 branch cutover keeps its + pre-change home and Store in `/home/dell/lfs-work/backup-20261115-180517` + (earlier `backup-20261115-180149`); restore that backup rather than editing + markers (see §7). +- `project.remove` is gone; an old client gets `InvalidInput` (§4, §10). + +## 5. Known gaps at this baseline + +- **PG existing-Store additive (T1.3b):** new PG Stores get the GC tables from `schema.sql`; + an existing 2.0 PG Store needs the additive step at open. Until then open/compact refuses; don't hand-create tables (§4.1). +- **Old-Store column ALTER (T1.2b):** new SQLite Stores get `commit.history_serial`, + `layer.history_serial`, `store_policy.trace_salt`; older Stores lack them until T1.2b's + ALTER + definition gate. GC refuses; don't hand-ALTER (§4.1). +- **`remove_file` is visibility-only in 2.0:** it hides reads/listings/mounts/merges/publishes + and frees no bytes; objects reachable only via the path are retained (§6.2, decisions 16/35). +- **No path-level physical reclaim:** path-aware walk and per-entry page pruning are follow-ups; `keptWaste` has no page component (§6.2). +- 1.0 Stores convert offline (§4.1); no online migration. + +## 6. First 10 minutes + +1. `layerfs store status `: read `state`, `holders`, `op.phase`, `op.uncertain`. Don't kill a live owner; `Busy` is expected. +2. `Unresolved`: prove the owner dead (home pid/start, or PG `pid`+`backend_start`), then + re-run `layerfs store compact ` to adopt. For a lost PG swap reply, use §2 on a second connection. +3. Before manual steps, back up (`backup.create` on SQLite; server backup on PG) and record generation `G`, op id, artifact name. +4. Compare artifact/schema with the op; leave anything a record names to the next compact (`G` removes, `G+1` records). +5. Never hand-edit `gc_intent`, `gc_dead`, markers or `project_epoch`; never unlink `-wal`/`-shm`; never drop a schema `gc_op` names. +6. To re-use a name after a removal, re-create after the frontier (or after a rebuild frees it); don't delete markers. Escalate if old content must be restored. + +## 7. Branch retirement (`branch.remove`, live since 2026-11-15) + +`branch.remove` is live on the 2.0.0 build `4e65ebbae` (host CLI `1dc15838…`, +bundle `layerfs` `c4737445…`, daemon `b8dd0766…`, helper `3d033ec0…`); +`layerfs help branch` lists it, and a probe on a missing name returns +`NoSuchBranch` (exit 125). The call is a marker write, not a delete: it hides +the Branch, keeps its rows and its name until a later `store.compact` rebuild +collects the marker, and never touches `main` (`ReservedName`). + +**Preflight.** + +1. `layerfs sandbox list ` is empty, or every listed Sandbox belongs + to a task you have agreed to exclude; a mounted Branch is `MountsActive`. +2. `layerfs doctor` is `{"ok":true,"findings":[]}`; `machine status docker` is + `running`. +3. Take a backup; the cutover used + `/home/dell/lfs-work/backup-20261115-180517` (bundle, host, daemon, helper, + `bundle.json`, `worker.json` and the Store volume; the earlier one is + `backup-20261115-180149`). Keep it until the retired names are no longer + needed. +4. Page the inventory: `layerfs branch list --page-size 100 + --page-pos `; the last page has `has_more: false`. Record the + names and the count before and after. +5. Build the retire list: an empty Branch (`head: null`), or an explicitly + reviewed superseded Branch (typically a `-merged`/`-integ`/`-final`/ + `-publish` variant) whose content is already on `main` or no longer needed; + `layerfs branch diff main --paths-only` shows the paths. + Never include `main`, a running task's Branch, or a Branch with a live + mount. + +**Procedure.** + +- For each name: `layerfs branch remove `. One call per + Branch; there is no batch, force or dry-run form. `Busy` is another + operation holding the Store scope (wait, call once more); `MountsActive` is + a live mount; `NoSuchBranch` means already gone; `ReservedName` is `main`. + Record every refusal. +- Verify: the retired name reads `NoSuchBranch`, a re-fork is `NameTaken` with + the holder's `state: "retired"`, `branch list` no longer shows it, and the + `main` head is unchanged. +- **Soft name retention.** The name is not reusable until a rebuild collects + the `branch_retired` rows; plan around that and never hand-delete markers + (§4). `store.compact` below is the only supported reclaim. + +**Reclaim (optional, later).** `layerfs store compact ` only when the +Store is idle (no mounts, daemon or other op). A rebuild copies retained rows +into a fresh Store and installs `G + 1`; only then are retired names and their +rows collected. A `none` outcome (<10 % wholly dead) keeps everything, and the +retired names stay taken. Follow the compaction procedure in §6 and the +rollback limits in §4. + +**Rollback.** Restore the whole home and Store from the pre-cutover backup +above (or `backup.restore` from a `backup.create` taken during the window); +markers cannot be undone by dropping tables (§4). The 2026-11-15 cutover was +not rolled back: no call failed, and `main` and `Cargo.toml` were byte-identical +before and after. + +**2026-11-15 result.** 145 Branches retired (20 empty at cutover + 125 +superseded), 0 refusals; 162 remained by choice (unknown or non-empty, +deliberately untouched). `main` stayed `32977da5…` (root `56dbe645…`), +`layerfs doctor` stayed clean, and no Sandbox/Workspace of the cleanup was +left running. The new build's one-way GC schema migration grew the sqlite +Store 1,111,203,840 -> 1,111,310,336 B on first open. diff --git a/core/docs/issues/project-41/gc-spec-gaps.md b/core/docs/issues/project-41/gc-spec-gaps.md new file mode 100644 index 0000000000..b4117e2ace --- /dev/null +++ b/core/docs/issues/project-41/gc-spec-gaps.md @@ -0,0 +1,96 @@ +# GC spec gaps: implementation decisions (T13b) + +> **Status:** implementation note for layerfs-project#41. `LayerFS-GC-spec.md` is **frozen** (2.0.0, +> owner-approved on #42): nothing here changes contract text. Where the spec is silent these are +> implementation decisions — the least-surprising option consistent with it. A "correction" entry is a +> proposed #42 amendment, not a change made here. + +**Baseline:** `main` at T13b; companion docs `gc-api-contract.md` (T11), `gc-acceptance-matrix.md` (T12), `gc-runbook.md`. + +## G1. Detail shapes missing for five codes (§10) +**Spec.** §10's table lists `StaleStore`, `Capacity`, `Unsupported`, `Conflict`, `ReservedName`, but states a +`detail` only for `MountsActive`, `Busy`, `Unresolved` (§10), `Removed` (§4.3, §10) and `NameTaken` (§4.4); +otherwise §10 requires only snake_case details. +**Decision.** All five carry an **empty detail** (`{}`). No field is invented: the spec names none, so no client may +depend on one, and `code` plus message are the surface. `ReservedName` (today only `branch.remove` of `main`, §4) +does not echo the Branch; `Conflict` (sealed tuple, §7/§10; missing `project_epoch`, §5) does not echo the failed +check; `Capacity`/`Unsupported` (§10) do not echo backend or catalog method; `StaleStore` (§10) does not echo +`(dev, ino)` or the generation. +**Impact.** T11: one empty-detail helper, explicit `HistoryError` arms before `_ => "Failed"`, never a `Failed` +mapping. T3/T4/T5: propagate `{}` unchanged, no `branch`/`project` field added at the site. T12: error-matrix rows +assert code, message and `detail == {}`, never an unnamed field. +**Correction.** None; additive fields later would need a #42 amendment. + +## G2. `Unknown` absent from §10's code table (§4, §4.2, §10) +**Spec.** §4: "a lost reply is `Unknown`, keeps the sidecar"; §4.2: `project.list(store)` propagates +`NoSuchStore`/`Busy`/`Unknown`. §10's table omits `Unknown`. +**Decision.** `Unknown` is a **service/control-plane outcome**, not a `HistoryError`/`lookup.rs` code: it exists for +the caller of a lost reply and for a Store listing that cannot be determined. It reuses the `Unresolved` detail +shape `{entity: {kind, name}, phase, op}` — same uncertainty, different observer (owning caller vs non-owning +call) — with `phase` and `op` `null` when no durable op is known. It joins neither `HistoryError` nor §10's table. +**Impact.** T4/T11: the `project.delete`/`store.compact` worker path keeps the sidecar and returns `Unknown`; T12 +"Worker/lost reply" asserts it and no cleanup; `project.list(store)` propagates it untouched. T3/T5 have no worker path. +**Correction.** Yes: a §10 row (or one §4 sentence) calling `Unknown` a service code with the `Unresolved` shape. + +## G3. §11 camelCase names vs §10 snake_case rendering (§10, §11) +**Spec.** §11 names `deadBytesBound`, `deadBytesRefined`, `logicalDiscarded`, `backendReusable`, `physicalShrink`, +`keptWaste.deadInRetainedPacksBytes`, `keptWaste.deltaBases`, `inodeBlocksBytes`, `peakTempBytes`, `zeroReason`; +§10 requires snake_case results/details and says "§11 names are logical, not rendered". +**Decision.** §11 names are Rust/logical only; every wire, CLI and SDK key is snake_case, mechanically: +`dead_bytes_bound`, `dead_bytes_refined`, `logical_discarded`, `backend_reusable`, `physical_shrink`, +`peak_temp_bytes`, `zero_reason`, `kept_waste {dead_in_retained_packs_bytes, delta_bases {bytes, references}, +inode_blocks_bytes}`. `kind`, `path`, `generation`, `before`, `after`, `residue`, `bytes`, `artifacts`, `reason`, +`value`, `cap`, `estimate`, `references` are single words. One serializer does it; no per-call map. +**Impact.** T10 owns the report struct (serde `rename_all = "snake_case"`); T11 renders verbatim; T12 asserts the +snake keys on both paths. T3/T4/T5 results are already snake_case (`removed_ms`, `deleted_ms`, `home_entry_removed`, +`frontier_serial`). +**Correction.** None needed; §11 already defers to §10. A one-line "rendered snake_case" note would remove the ambiguity. + +## G4. Merge `Removed` detail vs the canonical shape (§4.3, §10) +**Spec.** §4.3: "A merge that cannot materialize the whiteout is refused `Removed` with `detail {paths: [...]}`"; +the same section: "Every refusal carries one detail shape: `{paths: [{path, frontier_serial}]}`"; §10 repeats it. +**Decision.** One shape everywhere: `{paths: [{path, frontier_serial}]}`. The merge refusal lists every path it +cannot materialize as a full element (not a bare string), each with the governing maximum frontier over the path and +its `/`-boundary ancestors (§4.3); elements are sorted by normalized path bytes and deduplicated. read/stat emit one +element: the request path with its governing frontier. A directory element names the directory; descendants are +covered by the same frontier rule. +**Impact.** T5: the whiteout walk produces this list; T11: one detail serializer shared by read/stat/merge; T12: +"`remove_file` and derived nodes" and "Removed path in a merge" assert full elements and deterministic order. T3/T4 +never emit `Removed`. +**Correction.** No behavior change; §4.3's `[...]` is shorthand for §10's shape. A clarification amendment could say +"full §10 elements"; not made here. + +## G5. Idempotent retry only for `project.delete` (§1, §4, §4.4) +**Spec.** §4 gives `project.delete` a durable sidecar, marker-as-commit-point and an idempotent retry reusing +`deleted_ms`; §4.4 makes a repeat `branch.remove` `NoSuchBranch`; §1 says a lost reply stays uncertain and nothing +retries itself. +**Decision.** Keep the asymmetry. Only `project.delete` is retry-idempotent (sidecar `.../delete/.json`, +states `pending|marked|done`; the retry resolves retired/live/absent). `branch.remove` has no sidecar in 2.0: a lost +reply is `Unknown` (G2) and a repeat after success is `NoSuchBranch`; the API never turns that into `Removed`. +`remove_file` is re-callable but not replayable: a repeat is a new call that writes the current high-water as the +new frontier (§4.3), so it may hide newer content; it is `UpToDate` only when no project node is above this path's +marker frontier. No client, CLI, SDK or server auto-retries any of the three. +**Impact.** T3: repeat `NoSuchBranch`, no `deleted_ms` echo; T4: sole sidecar/retry path, plus `deleted_ms` reuse; +T5: repeat = new frontier/`UpToDate`, no stored reply; T11: no retry option/parameter, `Unknown` documented; T12: +retry case only for `project.delete`, the other repeats as above. +**Correction.** None; the asymmetry is intended (§4 is the single exception). + +## G6. `project.delete` `home_entry_removed:false` residue (§4, §4.2) +**Spec.** §4: the marker is the commit point; a home-removal failure returns success with `home_entry_removed:false` +and the stored `deleted_ms`; a different home's stale entry is not rewritten and is hidden by the §4.2 intersection. +**Decision.** Return exactly the §10 shape and add **no** residue field (that would be a contract change): +`{kind: "Removed", project, deleted_ms, home_entry_removed}`. The residue is another home's entry; it is named +nowhere in the result. The sidecar stays `marked` (durable evidence for a same-home retry); `project.list` omits the +entry and `project.get` answers `NoSuchProject`. A same-home retry finishes the entry removal and returns `true` with +the reused `deleted_ms`. Operator visibility is the sidecar and the call log, not the result. +**Impact.** T4: sidecar state machine and same-home retry; T11: no residue field; T12: "project.delete retry" and +"Home listing" cases (hidden, entry present, retry true). T3/T5 unaffected. +**Correction.** None; §4 already states this. A residue field in the result would be a #42 amendment. + +## Cross-cutting + +- Every refusal keeps one code and one stable message (§12 error matrix); these decisions add no code and no field. +- Details are built snake_case at the site or snaked once in the dispatcher (§10); an empty detail stays `{}` and is + never dropped or synthesized. +- These decisions bind T3, T4, T5, T11, T12 and the T10 report; the frozen spec remains the authority and wins on + disagreement. diff --git a/core/docs/issues/project-41/gc-t10-report-status.md b/core/docs/issues/project-41/gc-t10-report-status.md new file mode 100644 index 0000000000..e8646ff64d --- /dev/null +++ b/core/docs/issues/project-41/gc-t10-report-status.md @@ -0,0 +1,180 @@ +# T10: the §11 report and `store.status` + +> Implementation note for the frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) +> §10/§11. The spec wins; `§N` cites it. No contract is added here. + +## Placement + +- `engine/crates/layerfs-persistence/src/report.rs` — the backend-neutral + `CompactReport` (with `CompactGeneration`, `CompactKeptWaste`, + `CompactResidue`, `CompactZeroReason`), the `CompactReportSource` trait that + projects a backend receipt into it, and `CompactStatus`, the rendered + `store.status` projection of a run. The sidecar reader itself is T12.2's + `compact_op_status`/`CompactOpStatus`; T10 extends that projection with the + run's `started_ms` and owner (`pid`, kernel start, boot). +- `control/crates/layerfs-store/src/report.rs` — the one serializer: + `compact_report` and `compact_status`. Every key is snake_case (§10; §11 + names are logical) and `CompactZeroReason::wire_field` names each zero field + by its rendered key. +- `CompactReceipt` is unchanged: `From<&CompactReceipt>`/`From` + and the trait project it. The control renderer no longer builds a map itself. +- `layerfs_store::sqlite::transfer::step::StoreStep::CompactOp` reads only + `.compact-op`; it travels the same `store.file` frame to a worker, so + a remote SQLite Store answers it without opening the database, scanning the + directory or touching an artifact. + +## Report keys + +| §11 name | rendered key | +|---|---| +| `path` | `path` (`none`/`rebuild`) | +| `generation` | `generation {before, after}` | +| `deadBytesBound` / `deadBytesRefined` | `dead_bytes_bound` / `dead_bytes_refined` | +| `logicalDiscarded` | `logical_discarded` | +| `backendReusable` | `backend_reusable` | +| `physicalShrink` | `physical_shrink` | +| `keptWaste` | `kept_waste {dead_in_retained_packs_bytes, delta_bases {bytes, references}, inode_blocks_bytes}` | +| `peakTempBytes` | `peak_temp_bytes` | +| `residue` | `residue {bytes, artifacts, reason?}` | +| `estimate` | `estimate` | +| `zeroReason` per zero field | `zero_reasons [{field, reason}]` | + +`kind` is `Compacted`. `residue.bytes` is what is **left**, not what was +removed; `clear_artifacts` now adds a size only when a removal left a file, so +a successful settle reports an empty residue of 0 bytes (T10 fixes the T8 +accounting). + +## `store.status` + +While a compaction runs, or after a dead owner left one, the call adds: + +- `op` — `{id, name, phase, started, uncertain}` from `.compact-op` + (SQLite) / the Store's `gc_op` (PostgreSQL, T9); +- `state` — `busy` while the owner lives, `unresolved` once it is gone + (otherwise the existing `idle`/`in_use`/`busy`/`down` state). `uncertain` + is the engine projection's own fact and is true for **every** record that + remains, live or leftover; `state` is what separates the two. Equating + `uncertain == true` with `unresolved` is wrong. +- `phases` — the backend's ordered phases: `mark`, `build`, `verify`, + `install` on SQLite (T9 adds `mark`, `build`, `swap`, `cleanup`). + +No compaction record means `op: null` and `phases: null`, and a transfer +`op` still renders exactly as before. The sidecar now records the owner +`pid`, kernel start time and boot id; the status step compares them with +`layerfs_home::process::alive_as`, as leases do, so a reused pid cannot pass +as a live owner. The run writes `mark`, then `build`, `verify` and `install` +as it enters each phase, so the phase is visible while it runs (AC-51). + +## PostgreSQL hook (T9) + +`CompactReportSource` is the hook: SQLite's `CompactReceipt` implements it, +and T9 implements it for its PostgreSQL receipt. The report struct names no +backend-only field, so PostgreSQL reports its zeros through the same keys +(`backend_reusable = 0`, `dead_bytes_refined == dead_bytes_bound`) without a +wire change. `store.status` reads the Store-side `gc_op` at the same point in +`status.rs`; nothing is read from a file there. + +## Metrics and SLO signals (T10.3, PostgreSQL T10.4) + +`engine/crates/layerfs-persistence/src/compact_metrics.rs` publishes the +compaction observations from the real `store.compact` and `store.status` +paths: + +- counters: `compact.runs`, `compact.operations{outcome}`, + `compact.refusals{code}`, `compact.settles{kind}`, + `compact.retries{reason}`, `compact.status{state}` and + `compact.slo{objective,result}` (`residue_free`, `generation`); +- duration aggregates: `compact.phase.duration_ns{phase,statistic}` for + `mark`/`build`/`verify`/`install` on SQLite and + `pg_mark`/`pg_build`/`pg_swap`/`pg_cleanup` on PostgreSQL, and + `compact.duration_ns{statistic}`, each with `count`, `sum` and `max`; +- the last successful run's §11 gauges: `compact.dead_bytes{kind}`, + `compact.kept_waste{part}`, `compact.kept_waste_bytes`, + `compact.residue_bytes` and `compact.generation{which}`. + +Labels come only from closed enums: outcome, phase, refusal code, settle kind, +retry reason, status state, SLO objective/result, statistic and report key. A +Store name, path, operation id or artifact name is never a label, so metric +cardinality is fixed. A SQLite `none` run times only `mark` and a PostgreSQL +`none` run only `pg_mark`; a rebuild times all four phases its backend names; +a failure or unknown run records its outcome and total but publishes no report +gauge; a run that settles an earlier leftover adds `leftover` to +`compact.settles` and `compact.retries`. A `Busy`/`Unresolved` refusal that +stops a SQLite call before a run is counted once by the control path, and a +refusal a measured run itself produces (either backend) is counted by that +run. + +PostgreSQL §8 emits the same observation from +`backend/postgresql/compact.rs`: its `RunMetrics` times Phase M/A/B/C as +`pg_mark`/`pg_build`/`pg_swap`/`pg_cleanup`. Those are distinct closed values, +not aliases of the SQLite phases, so a process total never blends a SQLite +phase with a PostgreSQL phase of another meaning. It records the same §11 +gauges from the PostgreSQL receipt (where `dead_bytes_refined == +dead_bytes_bound`, `backend_reusable = 0` and `residue` is empty) and maps +`Busy`/`BusyOp` to `compact.refusals{code="busy"}` and `Unresolved` to +`code="unresolved"`. A resumed `G + 1` leftover records Phase C, the receipt's +original `generation {before, after}` and the `leftover` settle/retry; a `G` +leftover is settled before the new round. + +The registry follows the telemetry crate's rules (fixed low-cardinality +labels, recording never changes a result). `store.compact` has no new public +metrics call: `snapshot()` reads the process totals and +`CompactMetricsCapture` captures one thread, which the tests use. + +## Tests + +- `engine/crates/layerfs-persistence/tests/compact_metrics.rs`: a successful + SQLite rebuild (all four phase durations, outcome, + dead/kept-waste/residue/generation gauges and both SLO checks), the `none` + path (only `mark` timed, generation kept), a stopped `AfterBuild` run + followed by the leftover settle (`uncertain` outcome, then `rebuild` + + `retries{leftover}` + `settles{leftover}`), and a definite failure with no + report gauge. +- `engine/crates/layerfs-persistence/tests/postgresql_compact.rs`: the same + capture on a real PostgreSQL Store: a successful rebuild (the four `pg_*` + phases, outcome and the same report gauges and SLO checks), the `none` path + (only `pg_mark`), a Busy swap refusal (`failed` + + `refusals{code="busy"}`, phases M/A/B, no report gauge) and an uncertain + leftover intent refusal (`failed` + `refusals{code="unresolved"}`, no phase, + no report gauge). +- `engine/crates/layerfs-persistence/tests/support/metrics.rs`: the one + closed label-key/value assertion both capture tests use. +- `engine/crates/layerfs-persistence/tests/sqlite_compact.rs`: + `the_report_projects_every_section_11_field`, + `the_empty_store_report_explains_its_zeros`, + `a_leftover_op_reports_its_phase_and_state` (a real `AfterBuild` failpoint: + phase `build`; `status(true)` is `busy`, `status(false)` is `unresolved`, + both uncertain; ordered phases, then the next run settles the artifact and + the record). +- `control/crates/layerfs-store/tests/compact_report_status.rs`: the report + wire is the snake_case contract shape (including `zero_reasons` and the + `delta_bases.references` hex), and `store.status` projects an idle Store, + a live owner's record and a leftover one (`op`, `state`, `phases`), and the + `compact.status{state}` metric of each read. +- `engine/crates/layerfs-persistence/tests/postgresql_status.rs` (T10.5): on a + real PostgreSQL Store, an idle Store projects null; a live non-idle owner + projects `busy` with `uncertain`; a gone owner projects `unresolved`; each + `mark`/`build`/`swap` failpoint projects its recorded phase from the scratch + name after `gc_intent` is released; and a completed run leaves no row. +- `control/crates/layerfs-store/tests/postgresql_status.rs` (T10.5): the same + projection through the control `store.status` call on a real PostgreSQL + Store: no row projects `idle` with `op`/`phases` null; a live + `pg_stat_activity` owner projects `busy`; the gone owner projects + `unresolved`; each of `mark`/`build`/`swap`/`cleanup` is projected from the + row; the bounded `compact.status{state}` samples are emitted once each; and + a Store whose row was removed is idle again. + +## Gaps + +- The compaction metrics are emitted into the process registry only; no SDK + call or CLI command renders `snapshot()` yet. +- PostgreSQL compaction metrics cover the run and its admission/refusal paths. + T10.5 supplies the PostgreSQL `store.status` source: `status.rs` reads the + Store-side `gc_op` with its `gc_intent` on one status query (no Store open) + and projects `busy`/`unresolved` and the `mark`/`build`/`swap`/`cleanup` + phases, so `compact.status{state}` now has both sources. +- No control-level test joins `store.compact` and `store.status` in one run: + the control case writes the rows a compaction leaves and checks the + projection, while the persistence suites run the compactions themselves. +- The `{value, cap}` capped-field shape is not produced: the SQLite receipt + has no cap today. diff --git a/core/docs/issues/project-41/gc-t12-sqlite-compaction-fixtures.md b/core/docs/issues/project-41/gc-t12-sqlite-compaction-fixtures.md new file mode 100644 index 0000000000..c96960b7a7 --- /dev/null +++ b/core/docs/issues/project-41/gc-t12-sqlite-compaction-fixtures.md @@ -0,0 +1,88 @@ +# T12.1: SQLite compaction fixtures and the golden receipt + +> Acceptance fixture for the frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) +> §11 (report), §12 (acceptance) and §6.4 (live-heads digest). It adds no +> contract: the spec and the matrix win; `§N` and `AC-nn` cite them. + +## What the fixture is + +`engine/crates/layerfs-persistence/tests/sqlite_compact_fixtures.rs` builds one +Store through the public APIs only (`Fixture::put`/`record`/`inode`, the +`HistoryCatalog` methods, `SqliteHandles::compact`). It is the first fixture +that exercises the §7 rebuild with every §11 report component non-trivial: + +| Fixture part | What it pins | +|---|---| +| Two Stacks (one live, one `mark_stack_deleted`) | retained history and a project collected whole | +| A published Branch retired but still named by its retained Layers | `branch_retired` marker survives; name stays taken | +| An unmerged Branch retired and named by nothing | retired Branch row and marker collected | +| Commits with known `statistics.logical` (120/240/360/70/40) | `logicalDiscarded` is the exact history `logical` delta (160) | +| 12 unreferenced whole files, one per pack | wholly dead packs and `deadBytesBound` | +| A depth-2 PREFIX chain `base2 <- base1 <- target` with only `target` a retained root | `keptWaste.deltaBases` references both bases; pack ids survive (AC-17) | +| One retained pack with a reached group and an unreached group | `keptWaste.deadInRetainedPacksBytes`; a 2.0 rebuild keeps the group | +| A pooled inode leaf inside every tree | `keptWaste.inodeBlocksBytes` (all `inode_value_block` rows are kept) | +| Two `file_digest` rows, one root retained and one collected | AC-18 | +| A retired Branch with no head and a fixed-id digest Store | §6.4 golden vector (AC-56, SQLite half) | + +The transcript covers three outcomes: + +- `emptyNone`: an empty Store is `none` with `zeroReason: empty-store`, no + generation change, no artifact. +- `noDeadNone`: a Store whose every pack holds a live object is `none` with + `zeroReason: no-waste`; `deadBytesRefined == deadBytesBound` and the digest + and generation are unchanged. +- `rebuild`: `G -> G+1`; live objects (including the delta target through its + chain) read, dead objects and packs disappear, the retained pack keeps its + unreached group, collected history rows and their markers disappear, a + retained `branch_retired` marker stays, the full doctor passes and the + `live_heads_digest` is unchanged. + +## Defect found by the fixture + +The rebuild report's `residue.bytes` counted the bytes of every artifact the +settle *removed*, not only the ones that remain, so a fully successful rebuild +reported a nonzero residue with `artifacts: []` and no `reason` — contrary to +§11 ("a nonzero residue is explained") and the T8 note ("residue reports +anything that could not be removed"). `clear_artifacts` now adds a file's size +only when its removal failed; the fixture asserts `residue.bytes == 0` and the +golden pins it. `sqlite_compact` still passes. + +## Golden transcript + +`engine/crates/layerfs-persistence/tests/fixtures/sqlite_compact_golden.json` +is the byte-for-byte golden (`Json::render`, every object sorted by key). It +contains the three receipts, the mark tuple (digest, object count, packs), the +history markers and the fixture identities. A change to any value fails the +test; update it deliberately: + +``` +UPDATE_GOLDEN=1 cargo test -p layerfs-persistence --test sqlite_compact_fixtures +cargo test -p layerfs-persistence --test sqlite_compact_fixtures +``` + +The second run recompiles the embedded golden and checks it. + +## Matrix rows covered (SQLite half) + +| Case | Evidence | +|---|---| +| AC-04 | deterministic fixture: no live object reaches a collected row; closure compared before/after | +| AC-05 | full doctor (includes `diagnostic/scan.rs`) on the compacted Store | +| AC-17 | depth-2 chain copied; `pack_id` preserved on the bases and the target | +| AC-18 | collected digest row gone, retained one kept | +| AC-25 | retained `branch_retired` survives; collected `branch_retired`/`layer_stack_retired` go | +| AC-38 | the successful artifact set is removed and no stray name remains | +| AC-40 | SQLite `live_heads_digest` is identical before and after; a retired head moves it | +| AC-47 | `none` leaves no `.compact`; a successful settle leaves no artifact | +| AC-48 | empty Store (0/0) is `none` with `zeroReason`; the fixture is a `rebuild` arm | +| AC-52 | every §11 field on both paths, with units and sampling point, pinned by the golden | +| AC-56 | fixed-id digest vector with out-of-order ids, a retired Branch and stack, and an absent head (SQLite half) | +| AC-58 | `none` leaves no `.compact`/`.compact-visited`; `rebuild` settles to no artifact | + +Not covered here, by design (T12.2/T12.3): crash failpoints and `kill -9` +(AC-01, AC-03, AC-33, AC-46, AC-47 crash arm, AC-58 mid-run arm, AC-59), the +9%/10%/30% boundary arms and property tests (AC-04 at E3, AC-48 boundary, +AC-57), the PostgreSQL halves (AC-02, AC-28..AC-44, AC-60), admission races +(AC-07, AC-08, AC-49), and the report/`store.status` op projection (AC-51). +The PostgreSQL digest agreement (AC-40) and the shared literal vector (AC-56) +are proven on SQLite only here. diff --git a/core/docs/issues/project-41/gc-t12.3a-sqlite-matrix-report.md b/core/docs/issues/project-41/gc-t12.3a-sqlite-matrix-report.md new file mode 100644 index 0000000000..f3b4ce8c9a --- /dev/null +++ b/core/docs/issues/project-41/gc-t12.3a-sqlite-matrix-report.md @@ -0,0 +1,203 @@ +# T12.3a: SQLite acceptance-matrix runner report + +> Generated by `cargo test -p layerfs-persistence --test sqlite_compact_matrix`. +> The frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) section 12 and +> [`gc-acceptance-matrix.md`](gc-acceptance-matrix.md) AC-01..AC-60 win; this +> page records evidence and adds no contract. Regenerate with +> `UPDATE_REPORT=1 cargo test -p layerfs-persistence --test sqlite_compact_matrix`. + +## Scope and counts + +- Rows: 60 (AC-01..AC-60); backend split: both 47, SQLite-only 6, PG-only 7. +- Executed here: 8; covered by a named existing test/fixture: 29; partial: 16; deferred to T12.3b: 7; SQLite gaps: 0. +- **T-G28/T-G60 follow-up.** T-G28 later added the real-process SIGKILL arms + and T-G60 extended them to mark, copy, verify and rename, so + `sqlite_compact_crash` now has 23 tests (9 real-process SIGKILL arms and the + child placeholder), not the 13 recorded below. Those arms still kill a + re-executed test child, so T-G65 added + `api/crates/layerfs-cli/tests/sqlite_compact_process_kill.rs`: 8 SIGKILL + arms on the built `layerfs store compact` process at mark, build, verify and + install, so AC-01 is `covered` (the matrix now reads covered 30 / partial + 16). This page keeps the T12.3c run's original counts. +- A `covered`/`partial` row names a file and test function that this runner + asserts exists; an `executed` row names an arm this binary really runs. +- A cross-backend row records its SQLite half only; every PostgreSQL half + and the PostgreSQL-only rows are deferred to T12.3b by name. +- **T-G61 capacity follow-up.** A separate opt-in test, + `sqlite_compact_capacity.rs#capacity_measure` (ignored by default), measured a + real **9.987 GB** Store: `none` at 8.88% dead (three runs, median 149.318 s) + and `rebuild` at 10.00% dead (three runs, median 246.371 s; mark 149.089 s, + build 94.317 s, verify 0.312 s, install 1.916 s; dead 1.011 GB, shrink + 1.017 GB, peak temp 9.144 GB), plus one WAL/FULL rebuild (284.078 s). The + numbers are in `tests/fixtures/sqlite_compact_capacity_measure.json`; the + 50 GB arms and the 30% arm remain [E]. + +## Matrix (SQLite half) + +| Case | Backend | Matrix tier | Disposition | Evidence | Note | +|---|---|---|---|---|---| +| AC-01 | both | E2 | covered | sqlite_compact_crash.rs#crash_before_seal; sqlite_compact_crash.rs#crash_during_copy; sqlite_compact_crash.rs#crash_after_verify; sqlite_compact_crash.rs#crash_after_install; sqlite_compact_crash.rs#crash_during_settle | The SQLite section 9 crash matrix through named failpoints; a real kill -9 of a separate daemon process is T12.2's in-process stop points, not run here. | +| AC-02 | both | E2 | partial | sqlite_compact.rs#a_wholly_dead_pack_is_rebuilt_away; sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | The SQLite arm runs through the suite; the converted 1.0 Store arm and the PostgreSQL backend matrix are deferred to T12.3b. | +| AC-03 | both | E2 | covered | sqlite_compact_crash.rs#crash_before_seal; sqlite_compact_crash.rs#crash_after_wal_switch; sqlite_compact_crash.rs#crash_before_install; sqlite_compact_crash.rs#crash_after_install | SQLite mark/build/verify/install and WAL-switch stop points; lost COMMIT and power-loss arms belong to the PostgreSQL/fsync halves. | +| AC-04 | both | E3 | partial | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; this runner #arm_random_store_shapes | Deterministic closure fixture plus a seeded six-history reachability property arm; the full random fork/commit/merge/publish/removal generator is not built here. | +| AC-05 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; this runner #arm_random_store_shapes | Full doctor (including the diagnostic scan) on the compacted Store, also in the property arm. | +| AC-06 | both | E2 | executed | this runner #arm_digest_row_after_collection | A Save's `file_digest` row named a root the rebuild collected; the row goes with its root and recording the same content again succeeds. The PostgreSQL half is T12.3b. | +| AC-07 | both | E2 | executed | this runner #arm_mount_and_compaction_exclude_each_other; sqlite_compact.rs#a_store_replaced_under_an_open_handle_is_stale_at_the_next_transaction | SQLite half executed: bypass gives `StaleStore`, a mount blocks compaction (`MountsActive`, naming the holder) and a live compaction refuses a mount and a second compaction (`BusyOp`). The open one-shot SDK transaction arm is PostgreSQL, T12.3b. | +| AC-08 | both | E2 | covered | admission.rs#a_concurrent_mount_and_branch_remove_have_one_winner | One winner; the loser sees MountsActive, and a removed Branch is Missing. | +| AC-09 | both | E2 | covered | branch_removal.rs#a_removed_branch_is_hidden_and_the_epoch_bumps_once; branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names; gc_calls.rs#branch_remove_refuses_reserved_and_absent_branches | Reserved main, absent Branch and holder details are asserted; project-side name collisions are in AC-30. | +| AC-10 | both | E2 | covered | path_removal.rs#marker_frontier_and_up_to_date_follow_the_store_position | Removed/UpToDate codes and the frontier; 2.0 frees no bytes for the removed path. | +| AC-11 | both | E2 | partial | sdk_path_whiteouts.rs#a_merge_of_two_hidden_sides_keeps_the_path_absent; sdk_path_whiteouts.rs#a_merge_keeps_a_post_frontier_re_creation; sdk_path_merge_removal.rs#a_fast_forward_merge_creates_no_tree_and_the_path_stays_hidden; sdk_path_merge_removal.rs#publishing_an_at_or_below_commit_yields_a_hidden_layer_and_a_layer_headed_mount | Non-FF whiteouts, the fast-forward control, a post-frontier re-creation and publish-at-or-below with a layer-headed mount whiteout execute. A merge that cannot materialize the whiteout has no implementation branch to refuse (`removal::derive_root` always derives), so that clause is deferred by name, not claimed. | +| AC-12 | both | E2 | covered | sdk_path_whiteouts.rs#a_merge_of_two_hidden_sides_keeps_the_path_absent; sdk_path_whiteouts.rs#a_merge_keeps_a_post_frontier_re_creation; sdk_path_merge_removal.rs#a_recreated_removed_path_still_conflicts_as_an_ordinary_edit | A removed path in a merge is omitted with no conflict; a post-frontier re-creation is kept, and only an ordinary edit conflict on it is reported. | +| AC-13 | both | E2 | covered | sdk_path_merge_removal.rs#an_unmerged_branch_created_before_the_frontier_hides_but_does_not_inherit | The earlier Commit on an unmerged Branch is hidden by the marker; a Commit after the frontier does not inherit the path. | +| AC-14 | both | E2 | covered | sdk_path_merge_removal.rs#publishing_an_at_or_below_commit_yields_a_hidden_layer_and_a_layer_headed_mount; sdk_path_whiteouts.rs#a_marker_under_a_live_mount_is_refused_and_materializes_after_it_closes | A Branch whose head is empty and whose base Layer is at or below the frontier whiteouts the path at mount; its next Commit records the deletion. | +| AC-15 | both | E2 | partial | kept_objects.rs#a_retained_tree_and_inode_are_kept_with_their_packs; sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | Retention of the only-reaching-path object is proven; marker hiding in reads/listings and derived whiteouts are not in one named test. | +| AC-16 | both | E2 | covered | branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names; sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | T12.1 pins a retained retired Branch name and a collected unreferenced one; the branch.remove-then-rebuild arm is exercised through those markers. | +| AC-17 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; kept_objects.rs#a_delta_base_is_enqueued_and_reported | Depth-2 chain copied, pack ids preserved. | +| AC-18 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | Collected digest row gone, retained one kept. | +| AC-19 | both | E2 | partial | gc_calls.rs#project_remove_file_checks_its_path_grammar_then_reports_markers; path_removal.rs#marker_frontier_and_up_to_date_follow_the_store_position | Path-grammar refusals and the marker frontier are named; the full form table (symlink/hardlink, >4096 bytes, >256 components) is not one test. | +| AC-20 | both | E2 | partial | path_removal.rs#a_raw_marker_frontier_also_yields_up_to_date; path_removal.rs#an_unknown_project_is_missing | UpToDate and never-existing paths are named; the re-creation and other-project arms are partial. | +| AC-21 | both | E2 | partial | epoch_fence.rs#an_epoch_change_during_a_commit_is_detected_and_rolled_back; epoch_fence.rs#a_concurrent_commit_and_removal_have_one_winner | One-shot writes racing removals roll back as Conflict; the merge-racing-remove_file arm is not named. | +| AC-22 | both | E3 | covered | sdk_path_merge_removal.rs#a_merge_and_a_removal_started_together_never_leave_the_path_visible; epoch_fence.rs#an_epoch_change_during_a_merge_is_detected_and_rolled_back | A deterministic barrier starts a merge and a `remove_file` together for three rounds: the loser sees the marker or gets `Conflict` and retries with the whiteout, and a tree derived afterwards never shows the path. The PostgreSQL half is T12.3b. | +| AC-23 | both | E2 | partial | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; project_delete.rs#deleting_a_project_hides_it_and_marks_once | Deleted-project rows and markers are collected by the rebuild; a dedicated path_removed cleanup arm is not named. | +| AC-24 | both | E2 | covered | gc_backfill.rs#commits_layers_and_epochs_are_backfilled_in_deterministic_order; gc_backfill.rs#existing_serials_are_kept_and_new_ones_start_above_the_maximum | Serials backfilled, next_history_serial never falls. | +| AC-25 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | Retained branch_retired/layer_stack_retired markers survive; collected rows take their markers. | +| AC-26 | both | E2 | covered | project_delete.rs#retry_classifies_retired_live_and_absent; project_delete.rs#deleting_a_project_hides_it_and_marks_once | Hidden, entry present, retry returns the stored deleted_ms. | +| AC-27 | both | E2 | covered | project_delete.rs#paging_skips_a_hidden_project; project_delete.rs#every_layer_stack_lookup_carries_the_marker_filter | Stale home entries stay out of list/lookup. | +| AC-28 | PG | E2 | deferred (T12.3b) | - | PostgreSQL Phase C cleanup and its failpoints: T12.3b. | +| AC-29 | both | E2 | covered | admission.rs#a_live_operation_is_busy_and_an_uncertain_owner_is_unresolved; admission.rs#a_mount_blocks_all_three_removals_until_released | Owner liveness and Unresolved settlement; machine_stopped and the other-home intent are partial. | +| AC-30 | both | E2 | partial | branch_removal.rs#a_live_holder_is_reported_for_branch_and_project_names; gc_calls.rs#wrong_kinds_and_unknown_options_are_refused_before_any_effect | Holder detail and refusal codes are named; the full exact-message matrix (AC-55) is partial. | +| AC-31 | both | E2 | covered | gc_trace.rs#path_arguments_are_byte_counts_in_the_call_log; gc_trace.rs#the_trace_key_is_salted_by_the_store_policy_salt | Byte-count path arguments and the keyed trace hash are asserted. | +| AC-32 | both | E2 | partial | admission.rs#a_live_operation_is_busy_and_an_uncertain_owner_is_unresolved | Live/uncertain ownership is named; live-but-unreachable, machine_stopped and another home's intent are partial. | +| AC-33 | SQLite | E2 | executed | this runner #arm_checkpoint_busy; this runner #arm_sidecar_at_install | A live reader makes wal_checkpoint(TRUNCATE) Busy with no artifact and no op; a -mj* super-journal at install is Conflict with no writes. | +| AC-34 | both | E2 | partial | sdk_mount_bind_failure.rs#a_bind_failure_cleans_its_intent_and_leaves_no_mounts_active | A committed mount intent whose bind fails at the root check is deleted in the error path and no `MountsActive` remains. The failed-delete sub-arm is not inducible on SQLite: the storage schema guard rejects a trigger on `gc_intent`, and a lock held across the bind refuses the register too; the explicit `Cleanup` report is covered by the seam's code path, not executed here. The PostgreSQL half is T12.3b. | +| AC-35 | PG | E2 | deferred (T12.3b) | - | PostgreSQL advisory-key refcount: T12.3b. | +| AC-36 | both | E2 | covered | project_delete_worker.rs#a_lost_worker_reply_is_unknown_and_keeps_the_sidecar_for_the_retry; project_delete.rs#a_retired_retry_reuses_the_intent_deleted_ms_and_finishes_the_entry; project_delete.rs#an_absent_stack_finishes_a_stale_entry | A lost marker reply is `Unknown` with the sidecar kept; the retry resolves retired, live or absent. The PostgreSQL half is T12.3b. | +| AC-37 | both | E2 | partial | gc_trace.rs#the_redacted_set_covers_every_path_bearing_call; gc_trace.rs#the_trace_key_is_salted_by_the_store_policy_salt | Redaction and the keyed hash are named; salt backfill on an upgraded Store is partial. | +| AC-38 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; sqlite_compact_crash.rs#crash_during_settle | The SQLite artifact set is removed exactly; the PostgreSQL schema/name arms are T12.3b. | +| AC-39 | both | E2 | covered | gc_backfill.rs#commits_layers_and_epochs_are_backfilled_in_deterministic_order | One project_epoch row per stack, gc_op not copied, next_history_serial never lowered. | +| AC-40 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; kept_objects.rs#the_digest_is_stable_and_moves_with_a_head | SQLite live_heads_digest is identical before/after and moves with a head; PostgreSQL agreement is deferred. | +| AC-41 | PG | E2 | deferred (T12.3b) | - | PostgreSQL Phase M mark transfer: T12.3b. | +| AC-42 | PG | E2 | deferred (T12.3b) | - | PostgreSQL reserved pack/Phase B: T12.3b. | +| AC-43 | PG | E2 | deferred (T12.3b) | - | PostgreSQL Phase C cleanup resume: T12.3b. | +| AC-44 | PG | E2 | deferred (T12.3b) | - | PostgreSQL privileges and lost COMMIT reply: T12.3b. | +| AC-45 | SQLite | E1 | covered | sqlite_compact.rs#group_rows_layout_opens_compacts_and_takes_none; sqlite_compact.rs#group_rows_indexed_layout_opens_compacts_and_takes_none; sqlite_compact.rs#acquisition_layout_opens_compacts_and_clears_working_rows; sqlite_group_rows.rs#explicit_creation_reopens_declared_units_and_keeps_sparse_canonical_order | Monolithic/GroupRows/GroupRowsIndexed and the acquisition variants compact; working rows are cleared. | +| AC-46 | SQLite | E2 | executed | this runner #arm_sidecar_at_install; sqlite_compact.rs#a_store_replaced_between_seal_and_install_is_stale; sqlite_compact.rs#a_store_replaced_under_an_open_handle_is_stale_at_the_next_transaction | Sealed-state/sidecar change at install gives Conflict with no writes; a replaced Store gives StaleStore. The in-flight-transaction exclusion is a documented lane limit, not probed. | +| AC-47 | SQLite | E2 | covered | sqlite_compact_crash.rs#crash_during_copy; sqlite_compact_crash.rs#crash_during_settle; sqlite_compact.rs#a_stray_staged_name_is_refused_and_not_deleted; sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript | Crash leaves the full set, the next compact removes it, none leaves no artifact, a stray name is Exists. | +| AC-48 | both | E2 | covered | sqlite_compact.rs#nine_percent_wholly_dead_bytes_take_the_none_path; sqlite_compact.rs#ten_percent_wholly_dead_bytes_rebuild_at_the_threshold; sqlite_compact.rs#thirty_percent_wholly_dead_bytes_rebuild_above_the_threshold; sqlite_compact.rs#an_empty_store_takes_the_none_path; sqlite_compact.rs#a_capacity_failure_leaves_the_store_unchanged | 9/10/30 percent, empty-store zeroReason, capacity abort; verify-failure and re-refine arms are partial. | +| AC-49 | both | E2 | executed | this runner #arm_mount_during_compaction_is_busy; this runner #arm_commit_during_rebuild; admission.rs#a_concurrent_mount_and_branch_remove_have_one_winner | SQLite half executed: a mount during compact is `BusyOp` with the compaction; compaction returns `MountsActive` when the mount wins; a Commit racing the rebuild gets `StaleStore` or lands, and its retry is never lost. The PG Phase A/Phase C arms are T12.3b. | +| AC-50 | both | E2 | covered | calls_scope.rs#a_scope_refuses_every_call_it_does_not_cover; gc_calls.rs#the_four_gc_calls_take_ids_only | Folder scope refuses the four calls; the admin profile is the only allowance. | +| AC-51 | both | E2 | executed | this runner #arm_status_phases; compact_report_status.rs#status_projects_the_sidecar_phase_and_state; sqlite_compact_crash.rs#crash_before_seal | The op sidecar records mark/build/verify/install (runner); T10 projects it through store.status, and the named control test asserts the phase, state and phases list. | +| AC-52 | both | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; sqlite_compact_golden.json; compact_report_status.rs#the_report_wire_is_the_snake_case_contract_shape | Every section 11 field pinned with units and sampling point (golden) and rendered by the T10 wire-shape test; markBytes is a metric, not a result field. | +| AC-53 | both | E2 | partial | project_export.rs#export_omits_a_path_hidden_by_remove_file; gc_calls.rs#project_remove_file_checks_its_path_grammar_then_reports_markers | One hidden-path export case is named; the full read-surface table (read/stat/list/glob/diff/revision/edit/grep/blame/cp/apply) is not executed. | +| AC-54 | both | E2 | partial | restore_install.rs#a_folder_made_unprivate_during_the_download_is_refused_before_the_install; restored_records.rs#a_restored_project_reads_as_a_sandbox_reads_it | Restore install guards and restored records are named; restore before/after a removal and the stale-entry listing arm are partial. The restore-window arm needs a lock-capable filesystem (ext4/xfs/btrfs), so on this Sandbox it reports Unsupported while the other two cases pass. | +| AC-55 | both | E2 | executed | this runner #arm_error_codes; this runner #arm_checkpoint_busy; sqlite_compact.rs#a_stray_staged_name_is_refused_and_not_deleted | Exact SQLite texts asserted: Busy, Conflict("Store sidecar at install"), Exists("unrecorded compaction artifact"), Capacity("disk space"); the full engine/API message matrix stays partial. | +| AC-56 | both | E3 | partial | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; sqlite_compact_golden.json | The literal SQLite vector is pinned (absent head 33 zero bytes); the shared PostgreSQL literal and the three-run E3 shape are deferred. | +| AC-57 | both | E3 | partial | this runner #arm_measurement; sqlite_compact_measure.json; T-G61 sqlite_compact_capacity.rs#capacity_measure; sqlite_compact_capacity_measure.json | The tiny three-run arm is median 28.2 ms. T-G61 measured a real 9.987 GB Store with 3 runs per arm: `none` at 8.88% dead (median 149.318 s) and `rebuild` at 10.00% dead (median 246.371 s, mark 149.089 s / build 94.317 s / verify 0.312 s / install 1.916 s), plus one WAL/FULL rebuild at 284.078 s; profile, host and toolchain are declared in the fixture, and the warm page cache is declared below. The section 13 50 GB arms, the 30% arm, each removal type, the plain `VACUUM INTO` comparison and PostgreSQL timings remain deferred/[E]. | +| AC-58 | SQLite | E2 | covered | sqlite_compact_fixtures.rs#the_sqlite_compaction_receipts_match_the_golden_transcript; sqlite_compact_crash.rs#crash_before_copy; sqlite_compact_crash.rs#crash_during_copy | none deletes the scratch and leaves no .compact; rebuild keeps the visited scratch through the build; step 2 writes only on rebuild. | +| AC-59 | SQLite | E2 | executed | this runner #arm_checkpoint_busy; this runner #arm_seal; sqlite_compact.rs#a_store_replaced_between_seal_and_install_is_stale | busy != 0 refuses Busy and the WAL is never unlinked; a successful seal records (size, mtime, counter) as fenced by the StaleStore arm. | +| AC-60 | PG | E2 | deferred (T12.3b) | - | PostgreSQL synchronous standby handling: T12.3b. | + +## Executed in this runner + +- AC-33 / AC-59: `arm_checkpoint_busy` - a live reader makes + `wal_checkpoint(TRUNCATE)` report busy, the compaction refuses `Busy`, + leaves no `.compact`, `.compact-visited` or `.compact-op`, and the WAL is + never unlinked; the next run rebuilds at `G -> G+1`. +- AC-33 / AC-46: `arm_sidecar_at_install` - a `-mj*` super-journal placed + at install is `Conflict("Store sidecar at install")` with no artifact, + no op and an unchanged generation. +- AC-51: `arm_status_phases` - stop points at mark, build, verify and install + record the same phase in `.compact-op`; every phase is observed. +- AC-55: `arm_error_codes` - exact `Exists("unrecorded compaction artifact")` and + `Capacity("disk space")` texts, with no artifact after the capacity abort. +- AC-59: `arm_seal` - a successful seal leaves no sidecar, reports the main-file + bytes and a SQLite version, and the file reopens. +- AC-04 / AC-05: `arm_random_store_shapes` - a seeded property arm over six + reachability shapes: every live object stays readable, every wholly dead one + is collected, the retained-closure digest is unchanged and the doctor is clean. +- AC-06: `arm_digest_row_after_collection` - a `file_digest` row named a + root the rebuild collected, so the row goes; recording the same content + again succeeds and points at the new root. +- AC-07 / AC-49: `arm_mount_and_compaction_exclude_each_other` - a live mount + makes compaction `MountsActive` naming it, and a live compaction makes a + mount and a second compaction `BusyOp`; the refused runs leave no op. +- AC-49: `arm_mount_during_compaction_is_busy` - the stopped run's live + compaction intent refuses a mount with `BusyOp`, and the next run adopts + the leftover and rebuilds. +- AC-49: `arm_commit_during_rebuild` - a Commit started inside the install + fence is `StaleStore` or lands on `G + 1`; a retry is never lost. +- AC-57: `arm_measurement` - three runs of the same rebuild with median and + range in `engine/crates/layerfs-persistence/tests/fixtures/ + sqlite_compact_measure.json` (refresh with `UPDATE_MEASURE=1`). The separate + T-G61 `sqlite_compact_capacity.rs#capacity_measure` measures a real 9.987 GB + Store (three `none` + three `rebuild` runs, one WAL/FULL control) into + `sqlite_compact_capacity_measure.json`; it is opt-in because the fixture is + ~10 GB and the ignored test is not part of a normal suite. + +## Deferred to T12.3b (PostgreSQL) + +- AC-28 - PostgreSQL Phase C cleanup and its failpoints: T12.3b. +- AC-35 - PostgreSQL advisory-key refcount: T12.3b. +- AC-41 - PostgreSQL Phase M mark transfer: T12.3b. +- AC-42 - PostgreSQL reserved pack/Phase B: T12.3b. +- AC-43 - PostgreSQL Phase C cleanup resume: T12.3b. +- AC-44 - PostgreSQL privileges and lost COMMIT reply: T12.3b. +- AC-60 - PostgreSQL synchronous standby handling: T12.3b. +- The PostgreSQL half of every `both` row (digest agreement, artifact + names, Phase M/B/C, standby, lost reply, 50 GB arms). + +## SQLite gaps (not claimed by this runner) + +- none; every SQLite gap this runner can execute is executed or covered. + +## E3 arms + +- AC-04: the T12.1 closure fixture (deterministic) plus the seeded + reachability property arm; the full random history generator is deferred. +- AC-22: a deterministic barrier starts a merge and a `remove_file` together + for three rounds; the loser retries and a derived tree never shows the path. +- AC-56: the SQLite literal vector is pinned by the T12.1 golden; the shared + PostgreSQL literal is deferred. +- AC-57: three-run measurement arm executed on this Sandbox (small fixture), + plus T-G61's real 9.987 GB capacity fixture with three runs per arm + (`none` 149.318 s median, `rebuild` 246.371 s median, phase sums recorded). + Its 50 GB projection, the 30% arm, PG `ACCESS EXCLUSIVE` duration and the + plain `VACUUM INTO` comparison are deferred/[E]. + +## Status and report projection + +T10 (merged from main after this branch forked) projects `.compact-op` +through `store.status`: `op {id, name, phase, started, uncertain}`, the +busy/unresolved `state` and the backend `phases`. The named control tests +in AC-51 and AC-52 assert that projection and the snake_case section 11 +render; the runner still asserts the recorded SQLite phases directly, so +AC-51 does not depend on the projection alone. + +## Run environment + +- T-G61 capacity run (separate opt-in test): Docker Sandbox `g61sbx` + (Linux x86_64, 88 vCPU, 135 GB RAM, ext4 overlay, 4.0 TB free), rustc + 1.85.1, `SqlitePersistenceProfile::Disposable` (WAL/OFF) plus one + `Durable` control, `CARGO_TARGET_DIR=/var/tmp/target-g61`, fixture under + `/var/tmp/g61big`; the test ran 1678 s. Caches: the ~10 GB Store fits in the + 135 GB page cache and no cache drop ran between the three runs of an arm; + the mark is CPU-bound at ~62 MB/s, not cache-bound. +- Docker Sandbox `t123csbx` (Linux x86_64, tmpfs `/tmp`, overlayfs + `/var/tmp`), rustc 1.85.1, `SqlitePersistenceProfile::Disposable` + (WAL/OFF), `CARGO_TARGET_DIR=/tmp/target-t123c`. +- Verified here: `sqlite_compact_matrix` (1 test); the persistence suites + `sqlite_compact` (20), `sqlite_compact_crash` (13), + `sqlite_compact_fixtures` (1), `admission` (5), `path_removal` (3), + `branch_removal` (3), `project_delete` (5), `epoch_fence` (7), + `gc_backfill` (4), `kept_objects` (5); the Store-service path suites + `sdk_path_merge_removal` (5), `sdk_mount_bind_failure` (1), + `sdk_path_whiteouts` (7), `sdk_path_hidden_semantics` (2), + `sdk_path_removal` (2); and `layerfs-control --features postgresql + project_delete_worker` (5), `layerfs-store --features postgresql + project_delete` (15) and `compact_report_status` (3). + All of those pass on the merged branch. +- The control `restore_install` arm that opens a Store needs ext4/xfs/btrfs; + this Sandbox has no such direct filesystem, so that one case reports + `Unsupported` while its other two cases pass. It is an environment limit, + not a matrix result; the cited API tests are validated by source name only + in this run. diff --git a/core/docs/issues/project-41/gc-t12.3b-postgresql-acceptance.md b/core/docs/issues/project-41/gc-t12.3b-postgresql-acceptance.md new file mode 100644 index 0000000000..ddefe61a52 --- /dev/null +++ b/core/docs/issues/project-41/gc-t12.3b-postgresql-acceptance.md @@ -0,0 +1,150 @@ +# T12.3b: the PostgreSQL half of the GC acceptance matrix + +> Acceptance note for the frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) +> §8/§9/§11/§12, the companion of +> [`gc-t12-sqlite-compaction-fixtures.md`](gc-t12-sqlite-compaction-fixtures.md) +> (SQLite half) and [`gc-t9-postgresql-rebuild.md`](gc-t9-postgresql-rebuild.md) +> (the PostgreSQL rebuild). It adds no contract: the spec and the +> [`gc-acceptance-matrix.md`](gc-acceptance-matrix.md) win; `§N` and `AC-nn` +> cite them. The matrix statuses stay `open` (only #52 records acceptance); +> this note records the PG-half evidence and its tier. +> +> **T-G28/T-G60 follow-up.** `sqlite_compact_crash` now has 23 tests (9 +> real-process SIGKILL arms at mark, copy, verify, rename, build, install and +> settle, plus the child placeholder), not the 13 passed recorded below, and +> the matrix statuses are no longer `open`: AC-01 is `partial` and the other +> rows are `executed`/`covered`/`partial`/`deferred`. This page keeps the +> T12.3b baseline counts. + +## Environment + +- PostgreSQL **17.12** (`postgresql-17_17.12-1.pgdg12+1`, Debian 12), server on + `127.0.0.1:55432`, one schema per test dropped at test end, `postgres` + superuser, `sslmode=disable`. +- `LAYERFS_TEST_POSTGRES_URL` was set for every run below. The suites that pass + the URL straight to the driver take the keyword form + (`host=127.0.0.1 port=55432 user=postgres dbname=postgres sslmode=disable`). + The suites that append startup options (`postgresql_diagnostic`) need the URI + form (`postgresql://postgres@127.0.0.1:55432/postgres?sslmode=disable`); + with the keyword form those three tests fail at connect, which is a harness + URL-shape issue, not a Store result. +- Toolchain: Rust 1.85.1, `cargo test -p layerfs-persistence --features + postgresql`, `-j 8`, `CARGO_TARGET_DIR=/tmp/target-merged`. +- Branch `task-t12.3b` forked main layer `32c9181e`; it was merged with main + before publishing, and every result below was re-run on the merged tree + (main `3284fb82` at the merge), so the commands and counts are the merged + branch's, not the fork base's. + +## The fixture + +`engine/crates/layerfs-persistence/tests/postgresql_compact_fixtures.rs` is +the T12.1 fixture rebuilt on PostgreSQL through the public APIs only. It is a +new test target (5 tests); it changes no production code. + +| Test | What it pins | Matrix rows | +|---|---|---| +| `the_live_heads_digest_vector_is_the_sqlite_literal` | The §6.4 vector on PG is **byte-identical to the T12.1 SQLite golden**: the Commit id, `absentHeadDigest` (33 zero bytes) and `retiredBranchDigest` are the literals embedded in `fixtures/sqlite_compact_golden.json`. | AC-40, AC-56 (PG half) | +| `the_rebuild_report_and_markers_hold_on_postgresql` | The full T12.1 rebuild fixture on PG: `live_heads_digest` equals the SQLite golden **rebuild** literal; `deadBytesBound == deadBytesRefined`; `backendReusable = 0` with `postgresql-in-place`; `physicalShrink`, `peakTempBytes`, `keptWaste.{deadInRetainedPacksBytes, inodeBlocksBytes, deltaBases}`; `logicalDiscarded == 160`; empty residue; `G -> G+1`; depth-2 chain kept with `pack_id` and pack length unchanged; retained pack keeps its unreached group; markers/digest rows follow the retained set; full doctor; epoch copied, serial never lowered. | AC-02, AC-05, AC-17, AC-18, AC-25, AC-40, AC-41, AC-43, AC-52 | +| `a_save_after_the_swap_survives_the_resumed_cleanup` | `PostgresAfterSwap` aborts the round at `G+1`; a Save lands after the swap; the resumed Phase C deletes only the persisted dead set, the late write (object, pack, totals) survives the high-water bound, and the Store is usable at `G+1`. | AC-28, AC-43, AC-49 (Phase C arm) | +| `every_postgresql_failpoint_leaves_a_resumable_leftover` | All four named §8 failpoints (`mark`, `build`, `swap`, `cleanup`) leave the documented state (generation, dead pack, scratch schema, op phase, owner pid) and the next call adopts/resumes it; the heads digest is unchanged and the doctor is clean. | AC-01 (in-process arm), AC-03 (PG failpoints), AC-28, AC-43 | +| `a_marker_write_bumps_the_epoch_and_the_fence_refuses_a_racing_write` | Commit/Layer leave `project_epoch` alone; a Branch removal and a `remove_path` marker bump it once each; a repeated marker is `UpToDate` and does not bump; compact copies the epoch and never lowers `next_history_serial`; a removal-first stale Commit and a missing epoch row are both `Conflict("project epoch")` and write nothing. | AC-21, AC-24, AC-39 | + +The digest equality is not a value comparison on "both backends ran" alone: the +fixture ids, roots and Commit records are content-addressed, so the PostgreSQL +mark hashing the SQLite literal proves the §6.4 vector agrees byte for byte. +Run three times, the five tests passed 3/3 with the same literals (the matrix +lists AC-56 at E3; the deterministic two-backend literal is E2, three +identical runs are recorded here for the E3 arm). + +## Matrix: requested PostgreSQL-half rows + +Counts: **19 rows — 5 passed, 6 partial, 8 deferred** (AC-33 is a SQLite-only +row and is not part of the PG half). + +| Case | Result | Tier | Evidence / leftover | +|---|---|---|---| +| AC-02 | partial | E1 | The additive step on PG (position columns + serial backfill) passes `postgresql_position_columns` 4/4; the report/removal parity is covered below. A converted **1.0** Store is SQLite-only: PostgreSQL is a 2.0 format with no 1.0 reader, so that arm is not runnable on this backend. | +| AC-28 | **pass** | E1 | `a_save_after_the_swap_survives_the_resumed_cleanup`: late Save survives the resumed Phase C; op/generation asserted. Deferred sub-arm: the marker/base-row batch boundary failpoint (no injected point inside `cleanup`; Postgres only has the four round failpoints). | +| AC-29 | partial | E1 | `postgresql_compact` 8/8: a live idle owner is terminated by `(pid, backend_start)` and adopted; the caller's own uncertain round is adopted without self-termination. Mount-work admission belongs to the Store/Workspace layer and is not in this harness (deferred). | +| AC-30 | deferred | E0 | The `NameTaken` detail/error matrix is backend-neutral history work; no PG-specific fixture was added here. | +| AC-31 | deferred | E0 | Call-log/trace-salt redaction is the control-layer path, not the persistence harness. | +| AC-32 | partial | E1 | Same T9 owner-adoption evidence as AC-29 (uncertain op settled by the owning call). "Another home's intent visible" is control-layer, deferred. | +| AC-34 | deferred | E0 | A failed intent bind/delete needs the admission registry around a mount/init call, not this harness. | +| AC-35 | deferred | E0 | The project/Store advisory-key refcount exercise is the mount layer (`pg_advisory` keys), outside the persistence fixture. | +| AC-36 | partial | E1 | Lost swap reply (`postgresql_compact`), lost cleanup reply and lost mark/build replies (`every_postgresql_failpoint_leaves_a_resumable_leftover`) all resolve as documented. An unreachable worker/remote Store is deferred (needs the worker transport). | +| AC-37 | deferred | E0 | Trace redaction is the control-layer call log. | +| AC-38 | partial | E1 | The scratch name `lfs_gc_` is recorded before CREATE and removed at the swap/settle: the four-failpoint test asserts `scratch_exists` per phase. Deferred: a remote machine removing the scratch schema and a stray schema refusing with `Exists`. | +| AC-39 | **pass** | E1 | `postgresql_position_columns` 4/4 (one `project_epoch` row per stack, serials backfilled once, never lowered) plus the new fixture: the rebuild copies the epoch, `gc_op`/`gc_dead` are cleared on settle and not copied. | +| AC-40 | **pass** | E2 | `the_live_heads_digest_vector_is_the_sqlite_literal` + `the_rebuild_report_and_markers_hold_on_postgresql` vs the T12.1 SQLite golden; the retired head moves the digest on both. | +| AC-41 | partial | E1 | The depth-2 chain is kept only as delta bases, both reported in identity order; every retained pack keeps its `pack_id` and its `length` after the swap. Deferred: `markBytes` as a wire metric — it is a #52 metric and is not a `store.compact` result field (§11 matrix note), so there is nothing to assert in the receipt. | +| AC-42 | deferred | E0 | A Save reserved before the mark and published during Phase A must make the swap `Conflict`. The PG round has no pause point between build and swap (`stop()` returns immediately), so a publication cannot be interleaved deterministically; a wall-clock race would not be a fixed fixture. | +| AC-43 | **pass** | E2 | After the swap and the resumed cleanup: the four `store_totals` equal their row sums, `pack`/`object_location` keep owner and the `pack_immutable` trigger bound to the schema function (and the trigger still refuses an update), `binding_hint_block` is cleared, there is no `inode` table on PG, the Store opens at `G+1` and passes the full doctor. | +| AC-44 | deferred | E0 | Missing `CREATE`/`TEMP`/`pg_read_all_stats` needs roles the suite may create and a server it may reconfigure; a truly lost `COMMIT` reply needs a killed backend. The `PostgresAfterSwap` failpoint is the deterministic substitute and proves resume, not reply loss. | +| AC-56 | **pass** | E2 (3/3 runs) | The PG digests are the T12.1 SQLite literals: absent head (`6864c4…`), retired branch (`dafcdd…`), and the rebuild vector (`d3a3ea…`); the frozen Commit id `121c28…` is identical on both backends. | +| AC-60 | deferred | E0 (predicate E1) | A real synchronous standby needs a second cluster and `synchronous_standby_names`/`synchronous_commit` changes on a dedicated server; a shared suite URL cannot own those GUCs. `compact.rs` unit tests pin the predicate (no names / below `remote_write` → no wait; names → a streaming sync/quorum standby with a matching `sync_state`). | + +## Matrix: additional PostgreSQL rows recorded by this note + +Counts: **11 rows — 6 passed, 5 partial, 0 deferred**. + +| Case | Result | Tier | Evidence / leftover | +|---|---|---|---| +| AC-01 | partial | E1 | The four in-process PG aborts leave a wholly old (`mark`, `build`) or wholly new (`swap`, `cleanup`) Store and the next call settles. A `kill -9` of a daemon at the same points is not injectable in this harness. | +| AC-03 | partial | E1 | Named PG failpoints `mark`, `build`, `swap`, `cleanup` are all exercised with state, generation, op phase, scratch and digest asserted. Lost `COMMIT`, power loss and lease takeover are deferred (AC-44 note). | +| AC-05 | **pass** | E2 | Full doctor on the compacted PG Store in both rebuild tests; `postgresql_diagnostic` 5/5 (transport, cancellation, denied signature). | +| AC-17 | **pass** | E1 | Depth-2 PREFIX chain copied; `pack_id` preserved for both bases and the target. | +| AC-18 | **pass** | E1 | The collected `file_digest` root is gone, the retained one survives. | +| AC-21 | partial | E1 | Removal-first refusal (`Missing`/`Conflict`, no Commit) and the missing-epoch-row `Conflict` are deterministic on PG; the true concurrent one-shot-write arm (a trigger injecting an epoch change mid-transaction, as the SQLite `epoch_fence` tests do) is not implemented for PG here. | +| AC-24 | **pass** | E1 | Marker write bumps `project_epoch` once; `UpToDate` does not; compact copies it; serial never falls. | +| AC-25 | **pass** | E1 | A retained `branch_retired` row survives a rebuild; a collected Branch takes its marker with it. | +| AC-49 | partial | E1 | Phase C survives the high-water bound (late Save); the mount-wins-the-race arm needs the mount/lease layer, deferred. | +| AC-51 | partial | E1 | The op row records the §8 phase (`swap` asserted after the failpoint, `mark`/`build` in the matrix test). Projecting it through `store.status` needs a Store-home fixture; the T10 serializer test is SQLite-side today. | +| AC-52 | **pass** | E2 | The PG report has every §11 component: `deadBytesBound == deadBytesRefined`, `backendReusable = 0` + `postgresql-in-place`, `physicalShrink > 0`, `peakTempBytes > 0`, `keptWaste` three parts, empty residue, `logicalDiscarded` = history delta, `estimate = true`, zero reasons named. | + +## Commands and results + +Server: PostgreSQL 17.12 on `127.0.0.1:55432`; `LAYERFS_TEST_POSTGRES_URL` set as +above; `-j 8`; `--test-threads=1`. + +| Command (`cargo test -p layerfs-persistence --features postgresql --test …`) | Result | +|---|---| +| `postgresql_compact_fixtures` (new) | **5 passed**; 3 consecutive runs, 5 passed each | +| `postgresql_compact` | 8 passed | +| `postgresql_position_columns` | 4 passed | +| `postgresql_open_check` | 3 passed | +| `postgresql_commit_round_trips` | On the fork base: 1 failed, `13 != 11`; current main already fixes the expectation (see below), the merged tree passes 1/1 | +| `postgresql_diagnostic` (URI URL) | 5 passed | +| `postgresql_acquisition_compaction` | 4 passed | +| `postgresql_acquisition` | 4 passed | +| `postgresql_identical_ids` | 3 passed | +| `layerstack_removal` | 2 passed (one is the PostgreSQL project-removal arm) | +| `sqlite_compact_fixtures` | 1 passed (the golden still matches) | +| `sqlite_compact_crash` | 13 passed | +| `sqlite_compact` | 20 passed | + +## Baseline note: the stale round-trip count is already fixed on main + +`postgresql_commit_round_trips.rs` expected 11 round trips for `lane + head + +commit_branch` on the fork base; the path takes 13. The two extra statements are +T6.5's writer fence (`gc_epoch_read` at the start of the write transaction and +`gc_epoch_share` … `FOR SHARE` as its last statement, `src/history/epoch.rs`). +Current main already carries the updated expectation (13), so this branch does +not change that file; it only records the finding. + +## Gaps (not contract changes) + +- **AC-42** (a Save reserved before the mark racing the swap) and **AC-60** + (real standby, missing standby before/inside the swap, dying after the check) + need a hook the deterministic round does not have or a dedicated server whose + GUCs the suite owns. +- **AC-44** privileges and a killed backend's lost `COMMIT` need server roles + and processes the suite cannot own; the swap failpoint is the recorded + substitute. +- **AC-28**'s marker/base-row batch boundary needs a failpoint inside Phase C; + only the four round failpoints exist. +- The mount/lease admission rows (**AC-29/32/35/49**) are Store-layer, not + compaction-layer; only their compaction-op liveness arm is here. +- **AC-30/31/34/37** (error detail, trace, intent bind, redaction) are + control-layer rows and are untouched. +- `markBytes` (AC-41) is not a `store.compact` field, so the PG half cannot + assert it from the receipt. diff --git a/core/docs/issues/project-41/gc-t8-sqlite-rebuild.md b/core/docs/issues/project-41/gc-t8-sqlite-rebuild.md new file mode 100644 index 0000000000..ca544b11a7 --- /dev/null +++ b/core/docs/issues/project-41/gc-t8-sqlite-rebuild.md @@ -0,0 +1,157 @@ +# T8: SQLite `store.compact` rebuild + +> Implementation note for the frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) +> §7 (SQLite rebuild), §9 (failure and leftovers) and §11 (report). It adds no +> contract: the spec wins and `§N` cites it. + +## Placement + +`SqliteHandles::compact` is the host-side primitive T10 wraps as +`store.compact`. It consumes the handles like `SqliteHandles::seal` +(`engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs`): a rebuild +replaces the Store file and the caller reopens it afterwards. The public +result is `CompactReceipt`, one value per §11 field, plus the small +`CompactPath`, `CompactKeptWaste`, `CompactResidue` and `CompactZeroReason` +types. The `GcIntent` admission row is registered through the T6 +`HistoryCatalog::gc_register` API; a mark is the T7.2 `HistoryProvider::mark`. + +## Run (SQLite) + +1. **Lane.** `Session::hold_lane()` takes the Store's FIFO turn and the + cross-process `writer_admission` lock, and keeps both. Every later + transaction of this thread is nested work of that lane, so no admitted + writer can interleave between the mark, the seal and the rename. +2. **Checkpoint.** `Session::checkpoint_holding()` runs + `PRAGMA wal_checkpoint(TRUNCATE)` under the held lane; a nonzero `busy` is + `Busy`, never retried. +3. **Admission.** The compacting call writes `.compact-op` (the SQLite + sidecar equivalent of `gc_op`) and registers one Store-scoped + `gc_intent(kind='compaction')` row with the tuple: generation, mark serial, + mark pack id, digest, totals, stamp, phase, owner tokens. +4. **Mark.** `mark()` runs in its write transaction under the same lane. The + §6.1 history closure is written to `kept_node`; the §6.2 closure follows + logical references and delta bases to its fixpoint, so the packs it keeps + are already the refined live set. `deadBytesBound` and + `deadBytesRefined` are therefore equal on both §3 paths. +5. **Path.** `rebuild iff SUM(pack.length) > 0 AND dead * 10 >= SUM(pack.length)`. + `none` clears its intent and op record and returns; it writes no Store + table and creates no artifact, so no scratch exists to delete. +6. **Seal.** `Session::seal_holding(writer)` checkpoints, checked-closes, + checks `-wal`/`-shm`/`-journal`, and captures `(size, mtime, change + counter)` while the lane is still held (§7 step 1). The sealed tuple and + the §6.4 `live_heads_digest` are then re-read through an `immutable=1` + handle and compared with the mark; a difference is `Conflict`. +7. **Build.** `.compact-visited` (`journal_mode=OFF`) holds the visited + object and live-pack sets. `VACUUM INTO .compact` copies the sealed + file compactly; inside one transaction the retained rows are kept and the + complement deleted (dead packs/pack units, unreferenced locations, + signatures and digests, history/lineage/catalog rows outside `kept_node`, + markers of collected rows, merge scratch, `gc_intent`/`gc_dead`/`gc_op`, + acquisition working rows), `binding_hint_block` is cleared, + `catalog_incarnation` becomes `G + 1`, and `store_totals` is recomputed + from the retained rows with its `init_*` columns untouched. `VACUUM`, a + recreated `sqlite_sequence`, and a WAL switch with a zero-`busy` TRUNCATE + checkpoint finish the artifact. Package immutability triggers are dropped + for the delete and recreated from their stored SQL. +8. **Verify.** An `immutable=1` reader runs `schema::check`, + `foreign_key_check`, row counts against the mark (`object_location`, + `pack`, `kept_node`), both live-heads digests, the allocator tuple, and the + recomputed totals against their row sums. +9. **Install.** Sidecars and `-mj*` on both files are rechecked, the sealed + `(size, mtime, change counter)` and the full tuple are re-read last, the + artifact gets `chmod 0600` and `sync_all`, then `rename` and a directory + fsync. A rename/fsync failure is installed-but-uncertain: the op record is + kept at phase `install` and `UnknownOutcome` is returned. +10. **Settle.** The artifact set is removed, then the op record. `residue` + reports anything that could not be removed. + +## Failure and leftovers (§9) + +The next `store.compact` reads `.compact-op` under the lane. Because +the lane was free, the recorded owner is gone: it releases that op's admission +intent (`gc_release`), removes the named artifact set, and removes the op +record, judging by the generation it read (`G` = not installed, `G + 1` or +later = installed/advanced). An artifact set that no op record names is +refused `Exists` and is never deleted. A definite pre-install failure deletes +the artifact set and the op record; the old Store is unchanged apart from the +checkpoint. Failpoints (`AfterSeal`, `AfterBuild`, `AfterWalSwitch`, +`AfterVerify`, `BeforeInstall`, `AfterInstall`) exercise the crash state +without killing the process. + +## Report (§11) + +`CompactReceipt` carries `path`, `generation {before, after}`, +`deadBytesBound`, `deadBytesRefined`, `logicalDiscarded`, +`backendReusable` (free pages × page size), `physicalShrink` (old size − new), +`keptWaste`, `peakTempBytes`, `residue`, `estimate` (`true`: §13) and one +`zeroReason` per zero field from the closed vocabulary. `logicalDiscarded` is +the collected history rows' `logical` bytes; `parallel` note: `estimate` is +always true until #52 measures the arms. + +`peakTempBytes` is the §11 peak temporary space as a documented upper bound +(T-G72): `staged_bytes + journal_bound + target_bytes + visited_bytes`. The +staged copy holds the sealed Store's whole extent until the rewrite truncates +it (`VACUUM INTO`); the rewrite holds SQLite's unlinked temp database (the new +file) beside it and journals the pages it overwrites; the journal bound is one +rollback-journal record per staged page (`page_size + 8` B) plus 8192 B of +header. The 50 GB arm's bound is 147.609 GB against a 143.1 GB sampled temp +peak; the old `new + visited` receipt (45.784 GB) dropped the 44.6 GB +rollback journal (T-G66 finding, T-G72 fix). Upstream issue: [Ephemeral-AI-Lab/layerfs#695](https://github.com/Ephemeral-AI-Lab/layerfs/issues/695). + +## Tests + +`engine/crates/layerfs-persistence/tests/sqlite_compact.rs`: + +- empty Store → `none`, `zeroReason: empty-store`, unchanged generation; +- no wholly dead pack → `none`, `deadBytesRefined == deadBytesBound`, no + artifact, unchanged generation; +- a wholly dead pack → `rebuild`, `G + 1`, dead object gone, retained object + readable, no artifact/sidecar, full doctor clean; +- retained Commit/Layer history and its objects survive a rebuild; the full + doctor passes on the installed Store; +- a stray `.compact` with no op record is `Exists` and not deleted; +- `AfterBuild` leaves the staged Store, visited scratch and op record; the + reopened Store is still at `G`, and the next call settles and rebuilds; +- `AfterInstall` leaves the installed Store at `G + 1` and the op record; the + next call judges it and settles; +- generation increases once per installed rebuild. + +T-G72 (`tests/sqlite_compact_capacity.rs`): a moderate fixture samples the +staged copy, the rollback journal and SQLite's unlinked rewrite temp database +from a second thread and asserts the receipt bounds the new file plus the +journal and the whole sampled footprint; `compact.rs`'s unit test pins the +50 GB arithmetic. + +Runs: `cargo test -p layerfs-persistence --offline` (all binaries pass), +`cargo check --workspace --offline` passes. `kernel_guard` in +`layerfs-store-service` fails in this container because `/tmp` is tmpfs and +the guard refuses direct Store access; it is unrelated to this change. + +## Gaps (for T10/T12) + +- ~~The `(dev, ino)` `StaleStore` fence (§10) is not implemented in the SQLite + session.~~ Implemented in T8.1: `Session` records `(dev, ino)` at open and + refuses the next explicit transaction, read-only snapshot or immutable read + with `StaleStore`; the install fence compares the same pair with + `SealedFacts` before the rename. +- ~~`Capacity` mapping is implemented but no capacity/failpoint test asserts + it.~~ T8.1 adds `CompactFailpoint::CapacityAtBuild` (ENOSPC after the staged + file exists) and unit tests for the `ENOSPC`/`EDQUOT`/`EFBIG` mapping. +- ~~The 9%/10%/30% boundary and the `GroupRows`/`GroupRowsIndexed` and + acquisition layouts are exercised only on the Monolithic layout.~~ T8.1 + exercises 9% (`none`), 10% (rebuild at the boundary) and 30% (rebuild), both + grouped layouts on the `none` and rebuild paths, and the acquisition layout + on open/`none`/rebuild with its working rows cleared. The `postgresql` + feature is not built here. +- A definite pre-install failure now releases its `gc_intent` while the Store + is still open (T8.1): the admission row cannot be cleared after the seal, + and a live intent that outlived its op record refused every later GC call + `BusyOp`. The op record is kept only when the release itself fails, as the + next run's recovery breadcrumb (§9). +- ~~Peak temp is the new file plus the visited scratch; journal/WAL sizes + after the checkpoint are zero and are not added.~~ T-G72: `peakTempBytes` + bounds the pre-truncate staged copy, the new file (the rewrite's temp + database), the prune/rewrite rollback journal and the visited scratch. It is + an estimate and over-reports the sampled peak by a few percent. +- The mark runs before the seal under the same lane (the spec's step 1.5 runs + it after the seal); the sealed tuple re-read makes the window explicit. diff --git a/core/docs/issues/project-41/gc-t9-postgresql-rebuild.md b/core/docs/issues/project-41/gc-t9-postgresql-rebuild.md new file mode 100644 index 0000000000..041dd5db97 --- /dev/null +++ b/core/docs/issues/project-41/gc-t9-postgresql-rebuild.md @@ -0,0 +1,121 @@ +# T9: PostgreSQL `store.compact` rebuild + +> Implementation note for the frozen [`LayerFS-GC-spec.md`](LayerFS-GC-spec.md) +> §8 (PostgreSQL rebuild), §9 (failure and leftovers) and §11 (report). It adds +> no contract: the spec wins and `§N` cites it. + +## Placement + +`PostgresHandles::compact` is the Store-side primitive +(`engine/crates/layerfs-persistence/src/backend/postgresql/compact.rs`); the +`store.compact` control call dials the Store's recorded URL, opens its schema, +and runs it (`control/crates/layerfs-store/src/compact.rs`). Unlike SQLite the +session is kept; the caller reopens when it needs the new generation pinned +(the diagnostic guard rejects a stale incarnation by design, §10). + +The mark reuses T7.2: `HistoryProvider::mark_gc` reads the §8 tuple as the +mark's first statement and then runs the shared §6.1/§6.2 closure in one write +transaction. The new SQLite-portable statement `gc_tuple_read` is registered +with the other history statements, so both engines share it. + +## Run (PostgreSQL) + +1. **Admission.** `settle_leftover` judges a recorded `gc_op` first (§9): `G` + with a live `idle` owner is terminated with the two-argument + `pg_terminate_backend(pid, backend_start)` and adopted; a live working owner + is `Busy`; `G + 1` resumes Phase C. Then one Store-scoped `gc_intent` + (`compaction`, exclusive) is registered: its session advisory key is held + through Phase C, and a failure releases it. +2. **Phase M — mark.** The first statement reads `(catalog_incarnation, + next_history_serial, next_pack_id, next_ordinal, store_totals.*, + MAX(stamp), history rows)`; the T7.2 closure writes `kept_node` and returns + the object/pack set and live-heads digest. The set is loaded into session + temporary tables (`gc_visited`, `gc_live_pack`). + `deadBytesBound` = stored bytes minus the retained packs' bytes. + `gc_op` (phase `mark`, deterministic scratch name `lfs_gc_`) and the + persisted `gc_dead` membership (dead Commit/Layer/Branch/Stack ids, + `content_signature` slots, `file_digest` roots) are written next; the + `dead_logical` sum of dead history rows is recorded. A `none` decision + truncates `gc_dead`, clears `gc_op`, releases the intent and returns. +3. **Phase A — build** (session advisory key, no table lock). `CREATE SCHEMA` + `lfs_gc_`; `CREATE TABLE ... (LIKE schema.pack INCLUDING STORAGE + INCLUDING COMPRESSION INCLUDING CONSTRAINTS)` plus the explicit primary key + (the copy does not carry it), the same for `object_location`; owner, + tablespace and reloptions are copied from `pg_class`. Retained rows are + copied in pack-id batches, each its own transaction and idempotent by + deleting its own range first; `object_location` uses an `EXISTS` semi-join. + The prefix index, foreign key and `ANALYZE` follow; counts are checked + against the mark. +4. **Phase B — swap** (one short transaction). Every Store base table is + locked `ACCESS EXCLUSIVE NOWAIT`; `55P03` rolls back, drops the scratch + schema in a new transaction and is `Busy`. The mark tuple and live-heads + digest are re-read under the lock; any change is `Conflict` with no writes. + Owner/ACL are applied, the two tables swapped, the `pack_immutable` trigger + recreated, counts and the four totals checked, `dead_canonical/stored/ + metadata` persisted, `catalog_incarnation = G + 1`, the effective + `synchronous_commit` (Store and server, never lowered) set, the standby + predicate re-checked against `synchronous_standby_names` and `pg_stat_replication`, + the scratch schema dropped, and `COMMIT`. +5. **Phase C — cleanup** (batched, after the swap). Only `gc_dead` members are + deleted, child first; `binding_hint_block` is cleared; the acquisition + working tables are emptied. `store_totals` is reduced once by the persisted + `dead_*` totals in the settle transaction and checked against the retained + row sums; `gc_dead`/`gc_op` are cleared and the intent released. A row + created after the mark is not a member, so it survives. + +Report (§11): `path`, `generation {before, after}`, `deadBytesBound` = +`deadBytesRefined`, `logicalDiscarded`, `backendReusable = 0` +(`postgresql-in-place`), `physicalShrink` from `pg_total_relation_size`, +`keptWaste`, `peakTempBytes` (scratch schema), empty `residue`, `estimate` and +the zero reasons; PostgreSQL reports 0 for rebuilt-table reusable space. + +## Tests + +`engine/crates/layerfs-persistence/tests/postgresql_compact.rs` (real +PostgreSQL; `LAYERFS_TEST_POSTGRES_URL`): + +| Test | Covers | +|---|---| +| `an_empty_store_takes_the_none_path` | empty Store → `none`, `empty-store`, no artifact, cleared `gc_op`/`gc_dead`/intent | +| `a_live_store_takes_the_none_path` | live Store → `none`, bound = refined, no shrink | +| `a_wholly_dead_pack_is_rebuilt_away_and_totals_settle` | rebuild, dead pack collected, retained object kept, `G → G+1`, totals invariant, scratch dropped | +| `retained_roots_survive_a_rebuild_that_collects_a_deleted_project` | retained roots survive; a deleted project's history, markers and objects are collected; `logicalDiscarded > 0` | +| `a_lost_swap_reply_is_resumed_by_the_next_compact` | failpoint after the swap: the op stays at phase `swap`, `G+1`; the next compact finishes Phase C and reports the installed outcome | +| `a_stale_owner_backend_is_terminated_before_the_next_round` | a failpoint before Phase A leaves an idle owner; the next session terminates it with `pg_terminate_backend(pid, backend_start)` and adopts the op | +| `the_same_session_resumes_an_uncertain_round` | a failpoint before Phase A leaves the caller's own idle session as the recorded owner; the retry adopts its own op instead of terminating itself | +| `an_exclusive_table_lock_makes_the_swap_busy` | a conflicting `ACCESS EXCLUSIVE` lock at the swap is `Busy` (55P03), and the scratch schema is dropped | + +Unit tests in `compact.rs` pin the standby predicate (`rank < remote_write` or +no names → no wait; names → a streaming sync/quorum standby is required) and +the `synchronous_commit` strength order. + +Result at T9: `cargo test -p layerfs-persistence --features postgresql --test +postgresql_compact` — 8 passed on PostgreSQL 17.12 (Debian, server on +`127.0.0.1:55432`); `--lib` 4 passed; the SQLite suite +(`--test sqlite_compact`) passed (17 when T9 branched, 20 on the rebased main with the T12 fixtures); `sqlite_compact_crash` passed 13. + +> **T-G28/T-G60 follow-up.** `sqlite_compact_crash` grew to 23 tests with the +> real-process SIGKILL arms (9 arms after T-G60), so the 13 passed here is the +> T9 baseline. The +> original `Gaps` bullet below still says those rows remain `open`; the current +> matrix has them `partial`/`deferred`. This page keeps the T9 counts. + +## Gaps (not contract changes) + +- **AC-41/AC-42/AC-43/AC-44/AC-60 remain `open`** in the acceptance matrix: + the tests are E1/E2 evidence, not the full #52 matrix. Not covered here: + a reserved-pack publish racing Phase A/C, a mid-cleanup crash failpoint, a + real synchronous standby, and a truly lost `COMMIT` reply from a killed + backend. The swap-phase failpoint proves the resume path, not the server's + reply loss. +- **ACL replay** is best-effort: the owner and a default table ACL are copied; + non-default column/function ACLs are outside this note. +- **Busy holder detail** is the code only (`{entity, phase, op}` and PG + `pid/client_addr/backend_start` are not populated yet); the runbook's lock + query is the manual path. +- The Phase A batch size is a fixed 512 packs, not a 1 GB byte budget; the + scratch copy is `INSERT ... SELECT`, so no pack bytes cross the client. +- `physicalShrink`/`peakTempBytes` are sampled, and a resumed cleanup reports + them as 0 (the op does not persist them). +- `store.status` reading the Store-side `gc_op` is T10/T11; this note only + writes the row/phases it needs. diff --git a/docs/architecture/api/README.md b/docs/architecture/api/README.md index 467bbcc365..c85436b1fc 100644 --- a/docs/architecture/api/README.md +++ b/docs/architecture/api/README.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The public surface: the `layerfs-api` call table with its one dispatcher, and the front ends (the `layerfs` command, Node, Python and a local MCP server) that expose its **73 calls in 10 families** with the same names and arguments. +The public surface: the `layerfs-api` call table with its one dispatcher, and the front ends (the `layerfs` command, Node, Python and a local MCP server) that expose its **76 calls in 10 families** with the same names and arguments. | | | | --- | --- | @@ -85,7 +85,7 @@ give each call's own arguments, answer and errors. | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | -| [`calls_table.rs`](../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 73 calls in ten families; one source file per call; refusals before any effect | +| [`calls_table.rs`](../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 76 calls in ten families; one source file per call; refusals before any effect | | [`coverage.mjs`](../../../api/node/test/coverage.mjs) | `node --test api/node/test/coverage.mjs` | macOS or Linux, with the built addon, Python module and CLI | every front end matches the table | | [`file-history.mjs`](../../../api/node/examples/file-history.mjs) | `node api/node/examples/file-history.mjs` | macOS or Linux, with the built addon | a Store, Init, file writes and history reads | diff --git a/docs/architecture/api/calls/README.md b/docs/architecture/api/calls/README.md index dc953392b0..2744390222 100644 --- a/docs/architecture/api/calls/README.md +++ b/docs/architecture/api/calls/README.md @@ -41,7 +41,7 @@ The call table and the one dispatcher every front end goes through: what a call | Behaviour | Detail | Source | | --- | --- | --- | -| Table | ten `Family { name, list }`; a `Call` is `{ family, call, args, options, help, run }`, an `Arg` `{ name, kind, optional }`; 73 calls, help order | [`table.rs`](../../../../api/crates/layerfs-api/src/calls/table.rs), [`lib.rs`](../../../../api/crates/layerfs-api/src/lib.rs) `families` | +| Table | ten `Family { name, list }`; a `Call` is `{ family, call, args, options, help, run }`, an `Arg` `{ name, kind, optional }`; 76 calls, help order | [`table.rs`](../../../../api/crates/layerfs-api/src/calls/table.rs), [`lib.rs`](../../../../api/crates/layerfs-api/src/lib.rs) `families` | | JSON form | `table_json()`: `[{ family, call, args: [{ name, kind, optional }], options, help }]`; Node's `table`, Python's `TABLE`; the CLI parser and help read the same `Call` values | `table.rs` `table_json` | | Shared options | `PAGE` (`page_size`, `page_pos`), `DIFF` (`paths_only`, `page_size`, `page_pos`, `cursor`), `MESSAGE` (`message`), `PROGRESS` (`on_progress`) | `table.rs` | | Kinds | below | `table.rs` `Kind` | @@ -118,8 +118,14 @@ with one line in `/trace/calls.jsonl`, except the `logs` calls and with | `tag` | a top-level `log_tag` argument (taken out before the check; no entry declares it), else `LAYERFS_LOGS_TAG`; at most 128 bytes | Values are cut to 200 characters. Content, JSON, and the `Text` arguments -`command`, `message`, `old`, `new`, `password` and `url` are logged only as -`` (`REDACTED`). The line is written after the outcome and never +`command`, `message`, `old`, `new`, `password`, `url` and every path argument +(`path`, `left_path`, `right_path`, `from_path`, `to_path`, `path_prefix`) +are logged only as `` (`REDACTED`), so a `project.remove_file` or +`file.*` path never enters the log (#41 §4.3). A path counts its normalized +form, one leading `/` stripped (`/a` and `a` are both `<1 bytes>`); a glob or +grep `pattern` is not a path and counts its own bytes. A refusal contributes +only its code: its message and `detail` (which may echo the path, as `Removed` +does) are never logged. The line is written after the outcome and never changes it. Reading and clearing it are the [`logs`](../sdk/logs.md) calls. ## Invariants @@ -154,7 +160,7 @@ changes it. Reading and clearing it are the [`logs`](../sdk/logs.md) calls. | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | -| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host, temporary folders | ten families and 73 calls; unknown calls and arguments refused before any effect; each family reached; JSON round trips; sizes and keys; a relative home refused; one source file per call | +| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host, temporary folders | ten families and 76 calls; unknown calls and arguments refused before any effect; each family reached; JSON round trips; sizes and keys; a relative home refused; one source file per call | | [`calls_scope.rs`](../../../../api/crates/layerfs-api/tests/calls_scope.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_scope` | any Unix host | a scope names its project, refuses every call it does not cover, needs a Sandbox of its project, and a scoped `branch.list` reads every page | | [`scope_references.rs`](../../../../api/crates/layerfs-api/tests/scope_references.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test scope_references` | any Unix host | fork and publish references outside the namespace refused before any effect; the JSON form refuses the same | | [`logs.rs`](../../../../api/crates/layerfs-api/tests/logs.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test logs` | any Unix host | one line per call, rendering and redaction, `logs.list` and `logs.reset` | diff --git a/docs/architecture/api/calls/coverage.md b/docs/architecture/api/calls/coverage.md index a6cfa5dd53..53f4a26fcb 100644 --- a/docs/architecture/api/calls/coverage.md +++ b/docs/architecture/api/calls/coverage.md @@ -42,7 +42,7 @@ check and proves a missing, renamed or extra call is reported. -61 calls in 9 families, counted from the Node table. Calls present: Node 61, Python 61, Python `aio` 61, CLI 61, MCP 61 (34 in `work`, 27 admin only). +76 calls in 10 families, counted from the Node table. Calls present: Node 76, Python 76, Python `aio` 76, CLI 76, MCP 76 (38 in `work`, 38 admin only). Argument names that are Python keywords: none. @@ -53,24 +53,30 @@ Front-end problems: none. | `project.init` | project, folder | timeout, on_progress() | yes | yes | yes | yes (--progress) | admin | | `project.list` | ?store | page_size, page_pos | yes | yes | yes | yes | yes | | `project.get` | project | - | yes | yes | yes | yes | yes | +| `project.stats` | project, ?branch, ?commit | - | yes | yes | yes | yes | yes | | `project.export` | project, destination | branch, on_progress() | yes | yes | yes | yes (--progress) | yes | -| `project.remove` | project | - | yes | yes | yes | yes | admin | -| `branch.list` | project | page_size, page_pos | yes | yes | yes | yes | yes | +| `project.delete` | project | - | yes | yes | yes | yes | admin | +| `project.remove_file` | project, path | - | yes | yes | yes | yes | admin | +| `branch.list` | project | page_size, page_pos, page | yes | yes | yes | yes | yes | | `branch.get` | project, branch | - | yes | yes | yes | yes | yes | +| `branch.commits` | project, branch | page, page_size, at_commit, include_storage | yes | yes | yes | yes | yes | +| `branch.get_commit` | project, branch, commit | - | yes | yes | yes | yes | yes | | `branch.fork` | project, name, from_branch, ?from_commit | - | yes | yes | yes | yes | yes | | `branch.merge` | project, name, a, b | message, units | yes | yes | yes | yes | yes | | `branch.publish` | project, branch, ?commit | - | yes | yes | yes | yes | yes | -| `branch.diff` | project, from_branch, to_branch | paths_only, page_size, page_pos, cursor | yes | yes | yes | yes | yes | +| `branch.diff` | project, from_branch, to_branch | paths_only, page_size, page_pos, cursor, page, from_commit, to_commit, path_prefix, include_attribution, continuation | yes | yes | yes | yes | yes | +| `branch.remove` | project, branch | - | yes | yes | yes | yes | admin | | `commit.list` | project, branch | page_size, page_pos | yes | yes | yes | yes | yes | | `commit.get` | project, branch, commit | - | yes | yes | yes | yes | yes | | `commit.diff` | project, from_commit, to_commit | paths_only, page_size, page_pos, cursor | yes | yes | yes | yes | yes | | `file.read` | project, branch, path, ?commit | start_line, end_line | yes | yes | yes | yes | yes | | `file.stat` | project, branch, path, ?commit | - | yes | yes | yes | yes | yes | -| `file.list` | project, branch, path, ?commit | page_size, page_pos | yes | yes | yes | yes | yes | -| `file.glob` | project, branch, path, pattern, ?commit | page_size, page_pos | yes | yes | yes | yes | yes | -| `file.grep` | project, branch, path, pattern, ?commit | page_size, page_pos | yes | yes | yes | yes | yes | -| `file.blame` | project, branch, path, ?commit | from_line | yes | yes | yes | yes | yes | -| `file.diff` | project, left_branch, left_path, right_branch, right_path | left_commit, right_commit | yes | yes | yes | yes | yes | +| `file.list` | project, branch, path, ?commit | page_size, page, page_pos | yes | yes | yes | yes | yes | +| `file.glob` | project, branch, path, pattern, ?commit | page_size, page, page_pos | yes | yes | yes | yes | yes | +| `file.grep` | project, branch, path, pattern, ?commit | page_size, page, page_pos | yes | yes | yes | yes | yes | +| `file.revision` | project, branch, path | at_commit, traversal, page, page_size, continuation | yes | yes | yes | yes | yes | +| `file.blame` | project, branch, path, ?commit | from_line, line_count | yes | yes | yes | yes | yes | +| `file.diff` | project, left_branch, left_path, right_branch, right_path | left_commit, right_commit, include_attribution, allow_missing, page, page_size | yes | yes | yes | yes | yes | | `file.write` | project, branch, path, content | message, mode | yes | yes | yes | yes (stdin/--from) | yes | | `file.edit` | project, branch, path | old, new, message | yes | yes | yes | yes | yes | | `file.rm` | project, branch, path | message | yes | yes | yes | yes | yes | @@ -78,7 +84,7 @@ Front-end problems: none. | `file.mv` | project, branch, from_path, to_path | message | yes | yes | yes | yes | yes | | `file.cp` | project, branch, from_path, to_path | message | yes | yes | yes | yes | yes | | `file.apply` | project, branch, changes | message | yes | yes | yes | yes (stdin/--from) | yes | -| `sandbox.create` | project, name, ?machine | image | yes | yes | yes | yes | admin | +| `sandbox.create` | project, name, ?machine | image, on_progress() | yes | yes | yes | yes (--progress) | admin | | `sandbox.list` | ?project | page_size, page_pos | yes | yes | yes | yes | yes | | `sandbox.get` | name | page_size, page_pos | yes | yes | yes | yes | yes | | `sandbox.close` | name | force | yes | yes | yes | yes | admin | @@ -91,15 +97,19 @@ Front-end problems: none. | `machine.list` | - | - | yes | yes | yes | yes | admin | | `machine.platforms` | - | - | yes | yes | yes | yes | admin | | `machine.get` | name | - | yes | yes | yes | yes | admin | +| `machine.images` | name | - | yes | yes | yes | yes | admin | +| `machine.load` | name, image | on_progress() | yes | yes | yes | yes (--progress) | admin | +| `machine.prune` | name, ?image | unused | yes | yes | yes | yes | admin | | `machine.status` | name | - | yes | yes | yes | yes | admin | -| `machine.start` | name | - | yes | yes | yes | yes | admin | -| `machine.stop` | name | - | yes | yes | yes | yes | admin | -| `machine.create` | name, platform | cpus, memory, disk, image | yes | yes | yes | yes | admin | +| `machine.start` | name | on_progress() | yes | yes | yes | yes (--progress) | admin | +| `machine.stop` | name | force | yes | yes | yes | yes | admin | +| `machine.create` | name, platform | cpus, memory, disk, image, os_image, on_progress() | yes | yes | yes | yes (--progress) | admin | | `machine.remove` | name | - | yes | yes | yes | yes | admin | | `machine.update` | name | cpus, memory, image, docker, wsl, daemon | yes | yes | yes | yes | admin | | `store.list` | - | - | yes | yes | yes | yes | admin | | `store.get` | name | - | yes | yes | yes | yes | admin | | `store.status` | name | - | yes | yes | yes | yes | admin | +| `store.stats` | name | - | yes | yes | yes | yes | admin | | `store.create` | name | - | yes | yes | yes | yes | admin | | `store.connect` | name, url | password, synchronous_commit | yes | yes | yes | yes | admin | | `store.attach` | name, machine | url, password | yes | yes | yes | yes | admin | @@ -107,12 +117,15 @@ Front-end problems: none. | `store.push` | name, machine | on_progress() | yes | yes | yes | yes (--progress) | admin | | `store.pull` | name | on_progress() | yes | yes | yes | yes (--progress) | admin | | `store.remove` | name | - | yes | yes | yes | yes | admin | +| `store.compact` | name | - | yes | yes | yes | yes | admin | | `store.disconnect` | name | - | yes | yes | yes | yes | admin | | `backup.connect` | name, url | key, region, part_size | yes | yes | yes | yes | admin | | `backup.disconnect` | name | - | yes | yes | yes | yes | admin | | `backup.list` | ?bucket | - | yes | yes | yes | yes | admin | | `backup.create` | store, bucket, ?file | on_progress() | yes | yes | yes | yes (--progress) | admin | | `backup.restore` | store, bucket, ?file | on_progress() | yes | yes | yes | yes (--progress) | admin | +| `logs.list` | - | op, project, client, tag, outcome, since, cursor, limit | yes | yes | yes | yes | admin | +| `logs.reset` | - | - | yes | yes | yes | yes | admin | diff --git a/docs/architecture/api/front-ends/mcp.md b/docs/architecture/api/front-ends/mcp.md index 4f4fd02c3e..1a91f60383 100644 --- a/docs/architecture/api/front-ends/mcp.md +++ b/docs/architecture/api/front-ends/mcp.md @@ -98,12 +98,12 @@ Each call belongs to exactly one bucket, `work` (listed by both profiles) or | Bucket | Calls | | --- | --- | | `work` | the `branch`, `commit`, `file` and `workspace` families; `project.list`, `project.get`, `project.export`, `sandbox.list`, `sandbox.get` | -| `admin` | `project.init`, `project.remove`, `sandbox.create`, `sandbox.close`; the `machine`, `store`, `backup` and `logs` families | +| `admin` | `project.init`, `project.delete`, `project.remove_file`, `branch.remove`, `store.compact`, `sandbox.create`, `sandbox.close`; the `machine`, `store`, `backup` and `logs` families | `work` lets an agent read a project, work on Branches and files (each write is one explicit Commit), run in a mounted Workspace and export a snapshot. `admin` adds the calls that start workers, move whole Stores, hold -credentials, delete records or change the shape of the home. A new call with +credentials, retire or compact records, or change the shape of the home. A new call with no bucket fails `tools()`, generation and the test rather than appearing silently. Regenerate the table below with `node api/mcp/scripts/gen-profiles.mjs` (`--check` compares; both need the @@ -111,16 +111,17 @@ built addon). -73 calls: 38 in `work`, 35 in `admin` only; `--profile admin` lists all 73. +76 calls: 38 in `work`, 38 in `admin` only; `--profile admin` lists all 76. | Call | Bucket | Profiles that list it | Why | | --- | --- | --- | --- | | `project.init` | admin | admin | import a host folder into a Store; administration | -| `project.list` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | -| `project.get` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | -| `project.stats` | work | work, admin | read a project's record or its entry counts, or export one (work); importing and removing a project are administration | +| `project.list` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | +| `project.get` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | +| `project.stats` | work | work, admin | read a project's record or its entry counts, or export one (work); importing, deleting or hiding a path in a project is administration | | `project.export` | work | work, admin | export a Branch snapshot to a local folder under a launch-time --export-root; a folder scope refuses it | -| `project.remove` | admin | admin | remove a project from its Store; administration | +| `project.delete` | admin | admin | retire a project in its Store and remove its home entry; administration; a folder scope refuses it | +| `project.remove_file` | admin | admin | hide one absolute path from every node at or below its marker frontier; administration; a folder scope refuses it | | `branch.list` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.get` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.commits` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | @@ -129,6 +130,7 @@ built addon). | `branch.merge` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.publish` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | | `branch.diff` | work | work, admin | work on Branches: list, read, fork, merge, publish and diff | +| `branch.remove` | admin | admin | retire one Branch in its Store; administration; a folder scope refuses it | | `commit.list` | work | work, admin | read a Branch's Commit history | | `commit.get` | work | work, admin | read a Branch's Commit history | | `commit.diff` | work | work, admin | read a Branch's Commit history | @@ -180,6 +182,7 @@ built addon). | `store.push` | admin | admin | create, connect, transfer and remove Stores; administration | | `store.pull` | admin | admin | create, connect, transfer and remove Stores; administration | | `store.remove` | admin | admin | create, connect, transfer and remove Stores; administration | +| `store.compact` | admin | admin | reclaim one sqlite Store's dead bytes; administration; a folder scope refuses it | | `store.disconnect` | admin | admin | create, connect, transfer and remove Stores; administration | | `backup.connect` | admin | admin | upload and restore a Store on a bucket; administration | | `backup.disconnect` | admin | admin | upload and restore a Store on a bucket; administration | diff --git a/docs/architecture/api/sdk/README.md b/docs/architecture/api/sdk/README.md index a1b2ff608b..c994cdfa8f 100644 --- a/docs/architecture/api/sdk/README.md +++ b/docs/architecture/api/sdk/README.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -Every call a program can make: **73 calls in 10 families**, the same names and arguments in JavaScript, Python and the `layerfs` command, one page per family. +Every call a program can make: **76 calls in 10 families**, the same names and arguments in JavaScript, Python and the `layerfs` command, one page per family. | | | | --- | --- | @@ -49,14 +49,14 @@ built table. | Family | Calls, in help order | Runs by default | Source | | --- | --- | --- | --- | -| [`project`](project.md) | [`init`](project.md#projectinit), [`list`](project.md#projectlist), [`get`](project.md#projectget), [`stats`](project.md#projectstats), [`export`](project.md#projectexport), [`remove`](project.md#projectremove) | `list`, `get`: home records; the rest where the Store's calls run | [`project/`](../../../../api/crates/layerfs-api/src/project) | -| [`branch`](branch.md) | [`list`](branch.md#branchlist), [`get`](branch.md#branchget), [`commits`](branch.md#branchcommits), [`get_commit`](branch.md#branchget_commit), [`fork`](branch.md#branchfork), [`merge`](branch.md#branchmerge), [`publish`](branch.md#branchpublish), [`diff`](branch.md#branchdiff) | where the Store's calls run | [`branch/`](../../../../api/crates/layerfs-api/src/branch) | +| [`project`](project.md) | [`init`](project.md#projectinit), [`list`](project.md#projectlist), [`get`](project.md#projectget), [`stats`](project.md#projectstats), [`export`](project.md#projectexport), [`delete`](project.md#projectdelete), [`remove_file`](project.md#projectremove_file) | `list`, `get`: home records; the rest where the Store's calls run | [`project/`](../../../../api/crates/layerfs-api/src/project) | +| [`branch`](branch.md) | [`list`](branch.md#branchlist), [`get`](branch.md#branchget), [`commits`](branch.md#branchcommits), [`get_commit`](branch.md#branchget_commit), [`fork`](branch.md#branchfork), [`merge`](branch.md#branchmerge), [`publish`](branch.md#branchpublish), [`diff`](branch.md#branchdiff), [`remove`](branch.md#branchremove) | where the Store's calls run | [`branch/`](../../../../api/crates/layerfs-api/src/branch) | | [`commit`](commit.md) | [`list`](commit.md#commitlist), [`get`](commit.md#commitget), [`diff`](commit.md#commitdiff) | where the Store's calls run | [`commit/`](../../../../api/crates/layerfs-api/src/commit) | | [`file`](file.md) | [`read`](file.md#fileread), [`stat`](file.md#filestat), [`list`](file.md#filelist), [`glob`](file.md#fileglob), [`grep`](file.md#filegrep), [`revision`](file.md#filerevision), [`blame`](file.md#fileblame), [`diff`](file.md#filediff), [`write`](file.md#filewrite), [`edit`](file.md#fileedit), [`rm`](file.md#filerm), [`mkdir`](file.md#filemkdir), [`mv`](file.md#filemv), [`cp`](file.md#filecp), [`apply`](file.md#fileapply) | where the Store's calls run | [`file/`](../../../../api/crates/layerfs-api/src/file) | | [`sandbox`](sandbox.md) | [`create`](sandbox.md#sandboxcreate), [`list`](sandbox.md#sandboxlist), [`get`](sandbox.md#sandboxget), [`close`](sandbox.md#sandboxclose) | records here; start and stop on the Sandbox's machine | [`sandbox/`](../../../../api/crates/layerfs-api/src/sandbox) | | [`workspace`](workspace.md) | [`mount`](workspace.md#workspacemount), [`exec`](workspace.md#workspaceexec), [`exec_cancel`](workspace.md#workspaceexec_cancel), [`commit`](workspace.md#workspacecommit), [`unmount`](workspace.md#workspaceunmount), [`status`](workspace.md#workspacestatus) | the Sandbox's daemon; `exec` and `exec_cancel` in the Sandbox's runtime | [`workspace/`](../../../../api/crates/layerfs-api/src/workspace) | | [`machine`](machine.md) | [`list`](machine.md#machinelist), [`platforms`](machine.md#machineplatforms), [`get`](machine.md#machineget), [`images`](machine.md#machineimages), [`load`](machine.md#machineload), [`prune`](machine.md#machineprune), [`status`](machine.md#machinestatus), [`start`](machine.md#machinestart), [`stop`](machine.md#machinestop), [`create`](machine.md#machinecreate), [`remove`](machine.md#machineremove), [`update`](machine.md#machineupdate) | the caller's process, through the platform adapter | [`machine/`](../../../../api/crates/layerfs-api/src/machine) | -| [`store`](store.md) | [`list`](store.md#storelist), [`get`](store.md#storeget), [`status`](store.md#storestatus), [`stats`](store.md#storestats), [`create`](store.md#storecreate), [`connect`](store.md#storeconnect), [`attach`](store.md#storeattach), [`detach`](store.md#storedetach), [`push`](store.md#storepush), [`pull`](store.md#storepull), [`remove`](store.md#storeremove), [`disconnect`](store.md#storedisconnect) | the caller's process; sqlite file steps in the Store machine's worker | [`store/`](../../../../api/crates/layerfs-api/src/store) | +| [`store`](store.md) | [`list`](store.md#storelist), [`get`](store.md#storeget), [`status`](store.md#storestatus), [`stats`](store.md#storestats), [`create`](store.md#storecreate), [`connect`](store.md#storeconnect), [`attach`](store.md#storeattach), [`detach`](store.md#storedetach), [`push`](store.md#storepush), [`pull`](store.md#storepull), [`remove`](store.md#storeremove), [`compact`](store.md#storecompact), [`disconnect`](store.md#storedisconnect) | the caller's process; sqlite file steps in the Store machine's worker | [`store/`](../../../../api/crates/layerfs-api/src/store) | | [`backup`](backup.md) | [`connect`](backup.md#backupconnect), [`disconnect`](backup.md#backupdisconnect), [`list`](backup.md#backuplist), [`create`](backup.md#backupcreate), [`restore`](backup.md#backuprestore) | the caller's process; `create` stages on the Store's machine | [`backup/`](../../../../api/crates/layerfs-api/src/backup) | | [`logs`](logs.md) | [`list`](logs.md#logslist), [`reset`](logs.md#logsreset) | the caller's process, home files only | [`logs/`](../../../../api/crates/layerfs-api/src/logs) | @@ -103,20 +103,20 @@ in the [API layer page](../README.md#calling-conventions). | Test or example | Command | Platform | Shows | | --- | --- | --- | --- | | [`inventory.mjs`](../../../../api/node/test/branch-file/inventory.mjs) | `perl -e 'alarm 120; exec @ARGV' node --test api/node/test/branch-file/inventory.mjs` | macOS or Linux, with the built addon (`npm --prefix api run build:native`) and `target/debug/layerfs` | the count line and one heading per call match the built table; branch and file CLI help exposes every option | -| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 73 calls in ten families; one source file per call; unknown calls and arguments refused before any effect | +| [`calls_table.rs`](../../../../api/crates/layerfs-api/tests/calls_table.rs) | `cargo +1.85.1 test --locked -p layerfs-api --test calls_table` | any Unix host | 76 calls in ten families; one source file per call; unknown calls and arguments refused before any effect | | [`file-history.mjs`](../../../../api/node/examples/file-history.mjs) | `node api/node/examples/file-history.mjs` | macOS or Linux, with the built addon | a Store, Init, file writes and history reads | ## Pages | Page | What it covers | | --- | --- | -| [project](project.md) | Init, project records, stats, export, remove | -| [branch](branch.md) | Branches, saved history, fork, merge, publish, diff; the saved-query rules | +| [project](project.md) | Init, project records, stats, export, delete, path removal | +| [branch](branch.md) | Branches, saved history, fork, merge, publish, diff, retire; the saved-query rules | | [commit](commit.md) | a Branch's Commits and saved comparisons | | [file](file.md) | reads at a saved version; one-Commit writes | | [sandbox](sandbox.md) | Sandboxes: create, list, get, close | | [workspace](workspace.md) | mount, exec, cancel, commit, status, unmount | | [machine](machine.md) | built-in and VM machines | -| [store](store.md) | sqlite and PostgreSQL Stores | +| [store](store.md) | sqlite and PostgreSQL Stores; compaction | | [backup](backup.md) | buckets and Store backups | | [logs](logs.md) | the home's call log | diff --git a/docs/architecture/api/sdk/branch.md b/docs/architecture/api/sdk/branch.md index e658f92160..85933cdfd9 100644 --- a/docs/architecture/api/sdk/branch.md +++ b/docs/architecture/api/sdk/branch.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `branch` calls: list and read a project's Branches and their saved history, fork, merge, publish to `main`, and compare two Branches, within the [SDK](README.md). +The `branch` calls: list and read a project's Branches and their saved history, fork, merge, publish to `main`, compare two Branches and retire one, within the [SDK](README.md). | | | | --- | --- | @@ -35,6 +35,7 @@ The `branch` calls: list and read a project's Branches and their saved history, | [`branch.merge`](#branchmerge) | `branch.merge` | write | | [`branch.publish`](#branchpublish) | `branch.publish` | write | | [`branch.diff`](#branchdiff) | `branch.diff_branches` | saved read | +| [`branch.remove`](#branchremove) | `branch.remove` | write | Each entry forwards a typed request to `layerfs_store::calls::branch`, which renames the table's snake_case fields to the Store method's @@ -219,33 +220,19 @@ before the lane; only the final `merge_branch` publish holds it. ### branch.publish -Makes a Branch's head, or one of its Commits, `main`'s next Layer. By -default it refuses to drop work: if `main` gained a Layer since the Branch -forked, the publish is refused `HeadMoved` and nothing is written (#691). -Merge the Branch with `main` into a new Branch and publish that, or pass -`force` to overwrite `main` deliberately. +Makes a Branch's head, or one of its Commits, `main`'s next Layer. It +overwrites: Layers added to `main` since the Branch's base are reported, not +merged. ```text -JS await layerfs.branch.publish(project, branch, commit?, { expected_base, expected_head, force }) -Python layerfs.branch.publish(project, branch, commit=None, *, expected_base=None, expected_head=None, force=None) -CLI layerfs branch publish [] [--expected-base ] [--expected-head ] [--force] +JS await layerfs.branch.publish(project, branch, commit?) +Python layerfs.branch.publish(project, branch, commit=None) +CLI layerfs branch publish [] ``` `branch` must be a side Branch (`main` is `NoSuchBranch`); `commit` is a 66-hex Commit id (a Layer id is `InvalidInput`), default the head. -| Option | Kind | Rule | -| --- | --- | --- | -| `expected_base` | Layer id | `main`'s head must still be this Layer | -| `expected_head` | Commit id | the Branch's head must still be this Commit | -| `force` | bool | publish over Layers `main` gained since the fork; they are reported in `overwrote` | - -Without `force`, a publish goes ahead when `main` is still at the Branch's -fork point, when `main`'s head is this Branch's own earlier publication and -the Commit contains it (publishing again at milestones), or when `main` -already holds the Commit's tree (`NoChanges`). A Branch made by merging with -`main` has `main`'s head as its base, so it publishes as a fast-forward. - ```text Added: { kind: "Added", source: { branch, commit }, published_layer: { ...Layer, overwrote_count }, based_on, @@ -255,12 +242,9 @@ NoChanges: { kind: "NoChanges", head_layer } (its tree equals main's head) ``` The add is a compare-and-set on `main`'s head and the Branch's base: -`HeadMoved` when either moved, or when a check above refuses, never retried. -Its `detail` has `expectedBase`/`actualBase` (or `expectedHead`/`actualHead`). -Other errors: `NoCommit` (no saved Commit), `NotInHistory` (the Commit is not -on the Branch). After `Unknown`, publishing the same Commit again answers -`UpToDate` if it landed, even when `main` has moved on since or -`expected_base` names the head read before the first attempt. +`HeadMoved` when either moved, never retried. Other errors: `NoCommit` (no +saved Commit), `NotInHistory` (the Commit is not on the Branch). After +`Unknown`, publishing the same Commit again answers `UpToDate` if it landed. ### branch.diff @@ -304,6 +288,31 @@ comparison and attribution are each bounded to 64 MiB per request ([`read/branch_compare.rs`](../../../../engine/crates/layerfs-store-service/src/read/branch_compare.rs), [`read/compare.rs`](../../../../engine/crates/layerfs-store-service/src/read/compare.rs)). +### branch.remove + +Retires one Branch in its Store (spec §4). Its row is hidden from listings and +name resolution; fork, merge, publish and mount of it are refused, its Commits +and objects stay until a later [`store.compact`](store.md#storecompact), and +`main` is `ReservedName`. + +```text +JS await layerfs.branch.remove(project, branch) +Python layerfs.branch.remove(project, branch) +CLI layerfs branch remove +``` + +Returns `{ kind: "Removed", project, branch, removed_ms }`. A repeat is +`NoSuchBranch` (only `project.delete` is retry-idempotent); a concurrent +remove is `Busy` with phase `"retire"`. + +| Error | When | Source | +| --- | --- | --- | +| `ReservedName` | the Branch is `main` | [`methods/branch/remove.rs`](../../../../engine/crates/layerfs-store-service/src/methods/branch/remove.rs) | +| `NoSuchStore`, `NoSuchBranch` | the Store or Branch is missing (or already retired) | same | +| `MountsActive` | a mount of the Branch is live | [`history/admission.rs`](../../../../engine/crates/layerfs-store-service/src/history/admission.rs) | +| `Busy`, `Unresolved` | another user or operation holds the Branch, or a dead owner left an uncertain one | spec §5.1 | +| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | + ## Saved queries Shared by `branch.commits`, `branch.get_commit`, `branch.diff` and the diff --git a/docs/architecture/api/sdk/project.md b/docs/architecture/api/sdk/project.md index e300021835..597349806f 100644 --- a/docs/architecture/api/sdk/project.md +++ b/docs/architecture/api/sdk/project.md @@ -2,12 +2,12 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `project` calls: import a host folder into a Store as `/`, read the home's project records, count or export a saved tree, and remove a project, within the [SDK](README.md). +The `project` calls: import a host folder into a Store as `/`, read the home's project records, count or export a saved tree, retire a project, and hide one path from every node at or below a frontier, within the [SDK](README.md). | | | | --- | --- | | Source | [`api/crates/layerfs-api/src/project`](../../../../api/crates/layerfs-api/src/project), [`layerfs-store/src/project`](../../../../control/crates/layerfs-store/src/project), [`layerfs-control/src/project.rs`](../../../../control/crates/layerfs-control/src/project.rs) | -| Runs by default | `list`, `get`: the caller's process, home records only. `init`, `stats`, `export`, `remove`: where the Store's calls run (the caller's process for PostgreSQL and a sqlite Store on a locally executing machine, else that machine's worker) | +| Runs by default | `list`, `get`: the caller's process, home records only. `init`, `stats`, `export`, `delete`, `remove_file`: where the Store's calls run (the caller's process for PostgreSQL and a sqlite Store on a locally executing machine, else that machine's worker) | | Design | [Stores and projects](../../control/stores-and-projects/README.md), [projects](../../control/stores-and-projects/projects.md), [Project Init](../../engine/project-init/README.md) | ## Calls @@ -22,7 +22,7 @@ The `project` calls: import a host folder into a Store as `/`, r +--> stats export (one pinned saved tree) +--> branch.*, commit.*, file.*, sandbox.create ... v - remove / (no Sandbox of it may be recorded) + delete / remove_file / ``` | Call | Returns | @@ -32,7 +32,8 @@ The `project` calls: import a host folder into a Store as `/`, r | [`project.get`](#projectget) | the project summary | | [`project.stats`](#projectstats) | entry counts of one pinned tree | | [`project.export`](#projectexport) | pinned identity and local output counts | -| [`project.remove`](#projectremove) | `{ stack, packs_kept: true, project }` | +| [`project.delete`](#projectdelete) | `{ kind: "Removed", project, deleted_ms, home_entry_removed }` | +| [`project.remove_file`](#projectremove_file) | `{ kind: "Removed" \| "UpToDate", project, path, frontier_serial, removed_ms }` | The **project summary** is `ProjectRecord::to_sdk` ([`project/record.rs`](../../../../control/crates/layerfs-store/src/project/record.rs)): @@ -231,36 +232,63 @@ per 200 ms besides the first and last Export only reads history: a lost reply creates no source mutation and no uncertain intent. -### project.remove +### project.delete -Drops one project's LayerStack (Layers, Branches, Commits) from its Store in -one write, then the project's home entry; other projects stay. +Retires one project in its Store and removes its home entry (spec §4). The +project's Layers, Branches, Commits, packs and objects stay until a later +[`store.compact`](store.md#storecompact) collects them: the project is hidden +from listings and name resolution, and the Store stays addressable. No mount +or operation of the project may be live. ```text -JS await layerfs.project.remove(project) -Python layerfs.project.remove(project) -CLI layerfs project remove +JS await layerfs.project.delete(project) +Python layerfs.project.delete(project) +CLI layerfs project delete ``` -Returns `{ stack, packs_kept: true, project }`: `stack` is the removed -LayerStack's id; `packs_kept` is always true because the project's packs and -objects stay in the Store -([`project/remove.rs`](../../../../control/crates/layerfs-store/src/project/remove.rs)). -It runs through `layerfs_control::project::remove` -([`project.rs`](../../../../control/crates/layerfs-control/src/project.rs)), -under the Store's lease, locally or as the worker operation `project.remove`. +Returns `{ kind: "Removed", project, deleted_ms, home_entry_removed }`. The +Store marker is the commit point: if the home entry cannot be removed the +call still succeeds with `home_entry_removed: false` and keeps its durable +intent `store//delete/.json`, so a repeat from the same home +reuses `deleted_ms` and finishes the entry. The call is idempotent only +through that intent; it never resolves the name again. A lost worker reply +is `Unknown` and keeps the intent. | Error | When | Source | | --- | --- | --- | -| `NoSuchProject` | also when the Store holds no LayerStack of that name | [`identity.rs`](../../../../control/crates/layerfs-store/src/identity.rs) | -| `InUse` | a Sandbox of the project is recorded; `detail.related` lists `{ kind: "sandbox", name }` | [`inventory.rs`](../../../../control/crates/layerfs-control/src/inventory.rs) | -| `Unsupported` | a PostgreSQL Store ("removing a project from a PostgreSQL Store is not built"); the kernel guard refuses the Store's directory when opened (non-private mode/owner/type — another user's directory or group/other access instead of `0700` — or unsupported filesystem) | [`project/family.rs`](../../../../control/crates/layerfs-store/src/project/family.rs) | -| `Failed` | the Store write failed, its outcome included | `identity.rs` `remove_project` | -| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | +| `NoSuchStore`, `NoSuchProject` | the Store or project is missing (or already retired) | [`project/delete.rs`](../../../../control/crates/layerfs-store/src/project/delete.rs) | +| `MountsActive` | a mount of the project is live; its holders are named | [`history/admission.rs`](../../../../engine/crates/layerfs-store-service/src/history/admission.rs) | +| `Busy`, `Unresolved` | another user or operation holds the project, or a dead owner left an uncertain one | spec §5.1 | +| `Unsupported` | the Store is on another machine and the project record names no LayerStack id | [`project/delete.rs`](../../../../control/crates/layerfs-store/src/project/delete.rs) | +| `Unknown` | worker route: the answer was lost; the intent stays | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | + +### project.remove_file + +Hides one absolute project path from every node at or below its marker +frontier (spec §4.3). It writes one `path_removed` marker and changes no +pack, object, Commit or Layer; reads and stats of the path afterwards are +refused `Removed`. + +```text +JS await layerfs.project.remove_file(project, path) +Python layerfs.project.remove_file(project, path) +CLI layerfs project remove-file +``` + +The path is normalized (one leading `/` stripped) and must be an absolute +POSIX path of at most 4096 bytes and 256 components, with no empty, `.` or +`..` component and no `\` or NUL +([`path.rs`](../../../../core/crates/layerfs-history/src/contract/path.rs)). +Returns `{ kind: "Removed" | "UpToDate", project, path, frontier_serial, +removed_ms }`: the marker's stored values, `UpToDate` when no project node is +above this path's marker frontier. -After `Failed` or `Unknown` the home entry is kept (it is removed only after -success). `branch.list` answering `NoSuchProject` from the Store means the -stack is gone. +| Error | When | Source | +| --- | --- | --- | +| `InvalidInput` | the path is not a normalized absolute POSIX path | [`path.rs`](../../../../core/crates/layerfs-history/src/contract/path.rs) | +| `NoSuchStore`, `NoSuchProject` | the Store or project is missing (or retired) | [`methods/project.rs`](../../../../engine/crates/layerfs-store-service/src/methods/project.rs) | +| `MountsActive`, `Busy`, `Unresolved` | project-scope admission, as `project.delete` | spec §5.1 | +| `Unknown` | worker route: the answer was lost | [`worker/client.rs`](../../../../control/crates/layerfs-machine/src/worker/client.rs) | ## Family errors diff --git a/docs/architecture/api/sdk/store.md b/docs/architecture/api/sdk/store.md index 9ecdbe155b..f29787e1cd 100644 --- a/docs/architecture/api/sdk/store.md +++ b/docs/architecture/api/sdk/store.md @@ -2,7 +2,7 @@ > **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. -The `store` calls: create, connect, inspect, move and remove the databases that hold every project's history, within the [SDK](README.md). +The `store` calls: create, connect, inspect, move, remove and compact the databases that hold every project's history, within the [SDK](README.md). | | | | --- | --- | @@ -24,6 +24,7 @@ The `store` calls: create, connect, inspect, move and remove the databases that | (back to native) detach v v remove (file + projects) disconnect (data stays) + compact (reclaim dead bytes) ``` | Call | Kind | Returns | @@ -39,6 +40,7 @@ The `store` calls: create, connect, inspect, move and remove the databases that | [`store.push`](#storepush) | sqlite | `{ store, from, to, bytes, heads }` | | [`store.pull`](#storepull) | sqlite | `{ store, from, to, bytes, heads }` | | [`store.remove`](#storeremove) | sqlite | `{ removed: name }` | +| [`store.compact`](#storecompact) | sqlite | `{ kind: "Compacted", ... }`, the §11 report | | [`store.disconnect`](#storedisconnect) | PostgreSQL | `{ disconnected: name }` | A sqlite Store is made with the Disposable profile (WAL, @@ -128,7 +130,14 @@ leases are ignored, not removed password reference is resolved here and the server dialed once; a PostgreSQL Store is never `down` (an unreachable server shows in `server`) ([`status.rs`](../../../../control/crates/layerfs-store/src/status.rs)). It is -the call an `Unresolved` refusal names. Errors: `NotFound`; `InvalidInput` (a +the call an `Unresolved` refusal names. When a compaction runs on a sqlite +Store, `op` is read from `.compact-op`; on a PostgreSQL Store it is +the Store-side `gc_op` row with its `gc_intent`, read by one status query +with no Store session and no artifact read. Either way `state` is `busy` +while the owner lives and `unresolved` once it is gone, `uncertain` stays +the record's own fact, and `phases` names the backend's order (`mark`, +`build`, `verify`, `install` on sqlite; `mark`, `build`, `swap`, `cleanup` +on PostgreSQL). Errors: `NotFound`; `InvalidInput` (a record of unknown kind); `Unavailable` (a 1.1.0 Store whose machine is not known; `layerfs import-env` fixes it). @@ -372,6 +381,39 @@ uncertain. Errors: `InvalidInput` (a sqlite Store; use `store.remove`); recorded, or a call in this process is running on it, [`open.rs`](../../../../control/crates/layerfs-store/src/open.rs)); `Failed`. +### store.compact + +Reclaims one sqlite Store's dead bytes by rebuilding it from its live history +(spec §3, §7): the only byte-reclaiming call, with no confirm, force or dry +run and no automatic collection. It writes its operation intent before the +first checkpoint, verifies the rebuilt Store, and installs it by rename; a +definite failure before the rename keeps the old Store and the generation `G`, +while an installed-but-uncertain reply stays at `G + 1` and is reported, never +deleted. A Store with less than 10% wholly dead packs takes the `none` path: +it marks only, writes nothing and reports `dead_bytes_refined == +dead_bytes_bound`. + +```text +JS await layerfs.store.compact(name) +Python layerfs.store.compact(name) +CLI layerfs store compact +``` + +Returns `{ kind: "Compacted", path, generation: {before, after}, ... }` +with the report's snake_case fields: `dead_bytes_bound`, +`dead_bytes_refined`, `logical_discarded`, `backend_reusable`, +`physical_shrink`, `kept_waste {dead_in_retained_packs_bytes, delta_bases +{bytes, references}, inode_blocks_bytes}`, `peak_temp_bytes`, `residue`, +`estimate` and `zero_reason`; a capped field is `{value, cap}`. + +| Error | When | Source | +| --- | --- | --- | +| `NoSuchStore`, `Unsupported` | a missing Store, a PostgreSQL Store, a non-private Store directory, or an unsupported filesystem | [`compact.rs`](../../../../control/crates/layerfs-store/src/compact.rs) | +| `MountsActive`, `Busy`, `Unresolved` | a mount, long-lived client or operation holds the Store, or a dead owner left an uncertain one | spec §5 | +| `StaleStore`, `Conflict` | a connection bypassed admission, or the sealed identity changed | spec §7, §10 | +| `Capacity` | a real allocation refusal during the rebuild; the old Store is kept | spec §7 | +| `Unknown` | the reply was lost around install; read `store.status` and the op before any second call | spec §9 | + ## Family errors | Error | When | Source | diff --git a/docs/architecture/control/home/README.md b/docs/architecture/control/home/README.md index 9ed4321e45..8c7ed8b17e 100644 --- a/docs/architecture/control/home/README.md +++ b/docs/architecture/control/home/README.md @@ -155,8 +155,12 @@ already holds as it is. | `tag` | per-call `log_tag`, else `LAYERFS_LOGS_TAG`; at most 128 bytes, no control characters, else dropped | Values are cut to 200 characters. Content and Json arguments and the Text -arguments `command`, `message`, `old`, `new`, `password` and `url` are -logged as ``. +arguments `command`, `message`, `old`, `new`, `password`, `url` and every +path argument (`path`, `left_path`, `right_path`, `from_path`, `to_path`, +`path_prefix`) are logged as `` of the normalized form, one leading +`/` stripped (`/a` and `a` are both `<1 bytes>`); a glob or grep `pattern` +counts its own bytes. A refusal contributes only its code: its message and +`detail` are never logged. No line is written for a running or killed call, worker requests, a call's internal parts, commands outside the call table (`help`, diff --git a/docs/architecture/core/history/README.md b/docs/architecture/core/history/README.md index 36e9b5680b..f6f589e55a 100644 --- a/docs/architecture/core/history/README.md +++ b/docs/architecture/core/history/README.md @@ -75,7 +75,7 @@ or any process, memory, socket or stdout/stderr state. | Create a project | `initialize_layerstack` | [`layerstack.rs`](../../../../engine/crates/layerfs-persistence/src/history/layerstack.rs) | | Fork | `fork(ForkRequest)`: from `Layer(id)` (no head) or `Commit { branch, commit }`, which must be in that Branch's ancestry, else `NotInHistory` | [`branch.rs`](../../../../engine/crates/layerfs-persistence/src/history/branch.rs) | | Commit | `commit_branch(CommitRequest)` against the expected head and base | [`commit.rs`](../../../../engine/crates/layerfs-persistence/src/history/commit.rs) | -| Publish | `add_layer`: the Commit's root becomes the stack head (overwrite-only at this level; the SDK's `branch.publish` refuses a stale base first unless `force`); Layers it does not contain are counted in `overwrote_count` and paged by `overwritten` | [`layerstack.rs`](../../../../engine/crates/layerfs-persistence/src/history/layerstack.rs) | +| Publish | `add_layer`: the Commit's root becomes the stack head (overwrite-only); Layers it does not contain are counted in `overwrote_count` and paged by `overwritten` | [`layerstack.rs`](../../../../engine/crates/layerfs-persistence/src/history/layerstack.rs) | | Merge | `merge_branch`: a new Branch whose first state is a node (fast-forward) or a two-parent Commit | [`merge.rs`](../../../../engine/crates/layerfs-persistence/src/history/merge.rs) | | Remove | `remove_layerstack`: the one removal; packs, objects, file digests and the allocation scope stay | [`removal.rs`](../../../../engine/crates/layerfs-persistence/src/history/removal.rs) | @@ -112,7 +112,7 @@ database. `HistoryCatalogConfig` holds `binding_key` (1–128 bytes, hashed into | Kind | Methods | | --- | --- | -| Point reads | `layer_stack[_named]`, `branch[_named]`, `branch_snapshot`, `commit`, `layer`, `published_layer` (the Layer a Branch's Commit was published as) | +| Point reads | `layer_stack[_named]`, `branch[_named]`, `branch_snapshot`, `commit`, `layer` | | Paged reads | `layer_stacks`, `branches`, `commit_history`, `layer_history`, `overwritten` | | Ancestry | `merge_base`, `is_ancestor` | | Writes | `initialize_layerstack`, `fork`, `commit_branch`, `add_layer`, `merge_branch`, `remove_layerstack`, `reserve_inodes` | diff --git a/docs/architecture/engine/README.md b/docs/architecture/engine/README.md index 7031ed5431..a223f0cba6 100644 --- a/docs/architecture/engine/README.md +++ b/docs/architecture/engine/README.md @@ -46,7 +46,7 @@ crate except `layerfs-project`. | Topic | Crates | What it covers | Pages | | --- | --- | --- | --- | -| [Store](store/README.md) | `layerfs-persistence` | The one global Store: every project's history and immutable objects in one SQLite file or one PostgreSQL schema, written by one writer at a time. | [SQLite](store/sqlite.md), [PostgreSQL](store/postgresql.md), [Diagnostics](store/diagnostics.md) | +| [Store](store/README.md) | `layerfs-persistence` | The one global Store: every project's history and immutable objects in one SQLite file or one PostgreSQL schema, written by one writer at a time. | [SQLite](store/sqlite.md), [PostgreSQL](store/postgresql.md), [Diagnostics](store/diagnostics.md), [Testing](store/testing.md) | | [Store calls](store-calls/README.md) | `layerfs-store-service` | Typed reads, file changes and Branch history over the Store, run once in the process that opened it, and the SDK facade that names them. | [Reads](store-calls/reads.md) | | [Project Init](project-init/README.md) | `layerfs-project` | Turning one native directory into a project's first LayerStack and Branch: import, construction, then seal and install or a live add. | — | | [Overlay](overlay/README.md) | `layerfs-overlay`, `layerfs-store-service` `overlay/` | Each Workspace's own disposable SQLite file and in-memory open state, the Workspace roster and its one lock. | [Payload](overlay/payload.md), [Lifetimes](overlay/lifetimes.md) | diff --git a/docs/architecture/engine/store-calls/README.md b/docs/architecture/engine/store-calls/README.md index ee2ca382f4..d7eecb0ed3 100644 --- a/docs/architecture/engine/store-calls/README.md +++ b/docs/architecture/engine/store-calls/README.md @@ -147,7 +147,7 @@ The Commit itself is the Workspace Commit; see [Commit](../commit/README.md). | --- | --- | --- | | `branch.fork` | One Branch row through the catalog; no tree copied, no object read. Source is `main`'s head Layer, a Branch, or a Commit/Layer id. `ReservedName`, `NameTaken`. | [`history/branch.rs`](../../../../engine/crates/layerfs-store-service/src/history/branch.rs) | | `branch.merge` | Creates a new Branch `name`; neither source changes. An ancestor side fast-forwards with no Save. Otherwise merge base (`NoMergeBase`), optional merge units, `merge_roots` with `/.lww` rules from `branch`, Save finish and bindings, all before the lane; then one `merge_branch` publish. A conflict drops the Save and answers `Conflict`. | same, [`history/units.rs`](../../../../engine/crates/layerfs-store-service/src/history/units.rs) | -| `branch.publish` | `add_layer` with expected stack head and Branch base: a compare-and-set, no retry. Before it, a publish that would skip a Layer `main` gained since the Branch's base is `HeadMoved` unless `force` (#691); `expectedBase`/`expectedHead` pin `main`'s head and the Branch head. A refused Commit already published answers `UpToDate` (one `published_layer` read, on the refusal path only). `Added` (first 50 overwritten Layers reported), `UpToDate`, `NoChanges`. | [`history/branch.rs`](../../../../engine/crates/layerfs-store-service/src/history/branch.rs) | +| `branch.publish` | `add_layer` with expected stack head and Branch base: a compare-and-set, no retry. `Added` (first 50 overwritten Layers reported), `UpToDate`, `NoChanges`; moved heads are `HeadMoved`. Publish overwrites; skipped Layers are reported, not merged. | [`history/branch.rs`](../../../../engine/crates/layerfs-store-service/src/history/branch.rs) | | `branch.list_commits`, `project.list_branches` | Newest first / byte-name order; catalog pages of `MAXIMUM_PAGE_RECORDS` (128). | same | | `branch.commits`, `branch.get_commit` | Saved history from a Branch-qualified pin (`resolve_context`): `main` follows publication Layers, a Branch its Commit parents; a Commit outside the Branch history is `NoSuchCommit`. | [`history/saved.rs`](../../../../engine/crates/layerfs-store-service/src/history/saved.rs), [`methods/branch/commits.rs`](../../../../engine/crates/layerfs-store-service/src/methods/branch/commits.rs) | diff --git a/docs/architecture/engine/store/README.md b/docs/architecture/engine/store/README.md index b2a670667e..9fd8da18d9 100644 --- a/docs/architecture/engine/store/README.md +++ b/docs/architecture/engine/store/README.md @@ -196,10 +196,16 @@ Source: [`records.rs`](../../../../engine/crates/layerfs-persistence/src/backend | [`binding_hint_blocks.rs`](../../../../engine/crates/layerfs-persistence/tests/binding_hint_blocks.rs) | `cargo +1.85.1 test --locked -p layerfs-persistence --test binding_hint_blocks` | macOS, Linux | Hints merge across blocks without repeats | | [`postgresql_acquisition.rs`](../../../../engine/crates/layerfs-persistence/tests/postgresql_acquisition.rs) | `LAYERFS_TEST_POSTGRES_URL=… cargo +1.85.1 test --locked -p layerfs-persistence --features postgresql --test postgresql_acquisition` | a PostgreSQL server; prints `NOT_RUN` without the variable | Creating a PostgreSQL Store, refusing a second create, and Init's acquisition over it | +The commands above assume the test environment in [Testing](testing.md): `TMPDIR` and +`CARGO_TARGET_DIR` on ext4, xfs or btrfs (apfs or hfs on macOS). +[`tools/ci/test_store_ext4.sh`](../../../../tools/ci/test_store_ext4.sh) sets both +and refuses anything else before cargo starts. + ## Pages | Page | What it covers | | --- | --- | | [SQLite](sqlite.md) | The SQLite backend: schema, sessions, lane, profile, checkpoints, seal, snapshot, heads, acquisition and merge records. | | [PostgreSQL](postgresql.md) | The PostgreSQL backend: schema, open checks and authority, connections, transactions, publication, acquisition, access and status. | -| [Diagnostics](diagnostics.md) | Read-only Store audits: observations, the SQLite and PostgreSQL audits, table coverage and the structural fallback. | \ No newline at end of file +| [Diagnostics](diagnostics.md) | Read-only Store audits: observations, the SQLite and PostgreSQL audits, table coverage and the structural fallback. | +| [Testing](testing.md) | The filesystem the Store suites need, the harness that enforces it, and the PostgreSQL test server. | \ No newline at end of file diff --git a/docs/architecture/engine/store/postgresql.md b/docs/architecture/engine/store/postgresql.md index 688c129bbd..806926d1e8 100644 --- a/docs/architecture/engine/store/postgresql.md +++ b/docs/architecture/engine/store/postgresql.md @@ -70,7 +70,7 @@ Without it, selecting a PostgreSQL Store fails `BackendUnavailable`. | `Light` check | A Sandbox daemon's writer, Workspace and control readers, and `attach_read_only`; a hand-changed column fails the statement that uses it instead | [`bootstrap.rs`](../../../../engine/crates/layerfs-store-service/src/bootstrap.rs), [`owner.rs`](../../../../engine/crates/layerfs-daemon/src/application/owner.rs) | | `binding(selection)` | The binding key a schema records, read in one read-only session, so a home that did not create it can open it | [`store/postgresql.rs`](../../../../engine/crates/layerfs-persistence/src/store/postgresql.rs) | | `attach_read_only(selection)` | One read-only session under the recorded binding, returned for the caller to compare with its own | same | -| `postgresql_access(url, schema)` | Server version, one round trip's latency, `current_user`, whether the schema exists, and each privilege the role lacks: the schema's `USAGE`, the database's `TEMP` (merges stage in temporary tables), each table's `SELECT`/`INSERT`/`UPDATE`/`DELETE` and each sequence's `USAGE` | [`access.rs`](../../../../engine/crates/layerfs-persistence/src/backend/postgresql/access.rs) | +| `postgresql_access(url, schema)` | Server version, one round trip's latency, `current_user`, whether the schema exists, and each privilege the role lacks: the schema's `USAGE` and `CREATE`, the database's `CREATE` (compaction creates the scratch schema) and `TEMP` (merges stage in temporary tables; compaction reads its visited set from them), `pg_read_all_stats` (compaction reads the recorded owner's `pg_stat_activity` row and calls `pg_terminate_backend`), each table's `SELECT`/`INSERT`/`UPDATE`/`DELETE` and each sequence's `USAGE` | [`access.rs`](../../../../engine/crates/layerfs-persistence/src/backend/postgresql/access.rs) | | `postgresql_status(url, schemas)` | Server version, one round trip's latency and each named schema's size | [`status.rs`](../../../../engine/crates/layerfs-persistence/src/backend/postgresql/status.rs) | `access` and `status` open one connection for the call and close it, run @@ -78,6 +78,11 @@ read-only queries only and never retry. An authentication or unknown database error is `Denied`; any other connection failure `Unreachable`. The session keeps the frozen policy and server version the open check read, so `PackPersistence::policy` costs no round trip afterwards. +`compaction_missing(session)` applies the same five Store-wide checks to the +compaction session in one read-only round trip, before the intent, the mark +and the `lfs_gc_` scratch schema; the first privilege the role lacks is +`Unsupported`, naming it (AC-44). It is reachable from a session because a +compaction holds one already and never retains the URL. `PostgresSelection`'s `Debug` redacts the URL. ## Session diff --git a/docs/architecture/engine/store/testing.md b/docs/architecture/engine/store/testing.md new file mode 100644 index 0000000000..d7c6ee0d9e --- /dev/null +++ b/docs/architecture/engine/store/testing.md @@ -0,0 +1,295 @@ +# Testing the Store + +> **Status:** Current architecture guide for LayerFS 2.0.0; maintained with the source. + +The Store suites create real SQLite Stores, and a Store opens only on a local +filesystem that carries its locks. This page is the environment contract, and +the harness that enforces it before cargo spends a build. + +| | | +| --- | --- | +| Harness | [`tools/ci/test_store_ext4.sh`](../../../../tools/ci/test_store_ext4.sh) | +| Suites | `layerfs-persistence`, `layerfs-store-service`, `layerfs-store`, and the `store_*` targets of `layerfs-api` | +| Guard | [`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs) | +| CI | [`.github/workflows/store-ext4.yml`](../../../../.github/workflows/store-ext4.yml) | +| Related | [Store](README.md), [SQLite](sqlite.md), [PostgreSQL](postgresql.md), [Diagnostics](diagnostics.md) | + +## Why the tests need ext4 + +`kernel_guard::check` runs before a Store file is opened. It admits direct +opening only when the Store's own directory is a real directory (not a +symlink), owned by the current effective user, with mode `0700`, and the +filesystem holding it is `ext4`, `xfs` or `btrfs` on Linux, or `apfs` or `hfs` +on macOS. Anything else is `OpenRefusal::Unsupported` with the reason +`filesystem 0x… at … does not carry SQLite locks; direct Store access needs +ext4, xfs or btrfs` +([`kernel_guard.rs`](../../../../engine/crates/layerfs-store-service/src/kernel_guard.rs)). + +The allowlist is not arbitrary. Every opener of one Store must share one kernel +and a filesystem with working advisory locks: SQLite's WAL locks and the writer +admission lane's `flock` on the Store's directory +([SQLite](sqlite.md)). `tmpfs`, `overlay`, FUSE mounts and network filesystems +do not coordinate those locks between the processes a suite starts, so a Store +there is refused rather than run without coordination. + +The suites keep their Stores in two directories, and both inherit the +filesystem of the test environment: + +| Directory | In the tests | Usual host | +| --- | --- | --- | +| `TMPDIR` | `std::env::temp_dir()` | `/tmp`, which is tmpfs in most containers | +| `$CARGO_TARGET_DIR/tmp` | `env!("CARGO_TARGET_TMPDIR")` | the checkout's `target/`, an overlay in a container | + +On a host whose `/tmp` is tmpfs, or in a container whose checkout is an +overlay, the guard refuses the Store and suites such as +`layerfs-store-service --test kernel_guard` fail at their "a private directory +on a supported filesystem passes" assertion. That is an environment failure, +not a product failure. Tests that must prove the refusal on purpose use +`/dev/shm` (tmpfs), so pointing `TMPDIR` at ext4 does not weaken them. + +## Run the suites + +The harness requires `LAYERFS_TEST_TMPDIR` on a supported filesystem, refuses +anything else with exit 2 before cargo starts, and points `TMPDIR` (through a +short symlink), `CARGO_TARGET_DIR` and `CARGO_HOME` at it. + +```bash +# A cross-crate subset: the first build is the cost, then minutes. +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh --quick + +# Every Store suite. +LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh + +# Print the cargo commands and the environment, run nothing. +tools/ci/test_store_ext4.sh --list +``` + +`--quick` runs a few targets per suite: + +| Suite | Targets | What they exercise | +| --- | --- | --- | +| `layerfs-persistence` | `heads`, `sqlite_publication` | Branch heads and a publication round trip | +| `layerfs-store-service` | `kernel_guard`, `commit_pipeline` | the guard admits a private ext4 directory and refuses tmpfs; a Commit pipeline | +| `layerfs-store` | `create_directory` | `store.create`'s directory ownership and its guard refusal | +| `layerfs-api` | `store_family` | the Store family's call table | + +The full run is the unfiltered `layerfs-persistence`, `layerfs-store-service` +and `layerfs-store` suites, plus every `store_*.rs` target found under +`api/crates/layerfs-api/tests/`. Other API targets (machines, sandboxes, +Docker) are not Store tests and are not run here. + +## What the harness sets + +| Variable | Value | Why | +| --- | --- | --- | +| `LAYERFS_TEST_TMPDIR` | required, validated | the supported filesystem the run may use | +| `TMPDIR` | a short private wrapper under the system temporary directory, whose `tmp` entry links to `$LAYERFS_TEST_TMPDIR/tmp` | `std::env::temp_dir()` in the tests; Unix-domain socket paths are limited to about 108 bytes | +| `CARGO_TARGET_DIR` | `$LAYERFS_TEST_TMPDIR/target` | build output, and `CARGO_TARGET_TMPDIR` for the tests | +| `CARGO_HOME` | `$LAYERFS_TEST_TMPDIR/cargo-home` | the registry and git checkouts stay with the run, off the checkout's overlay | +| `-j` | `min(nproc, 16)` by default | keeps rustc within memory on a many-core host | +| `CARGO_NET_GIT_FETCH_WITH_CLI` | `true` | fetches the pinned `fuser` git dependency with the git CLI, which honours the host's proxy and credentials | +| `GIT_SSL_NO_VERIFY` | `true` | lets that one git fetch complete through TLS inspection; scoped to this process, not a production setting | +| `--features postgresql` | added to every suite when `LAYERFS_TEST_POSTGRES_URL` is set | the PostgreSQL test files are `#![cfg(feature = "postgresql")]` | + +The `TMPDIR` wrapper exists because a Sandbox run directory is long: a test that +binds a Unix-domain socket under `TMPDIR` otherwise fails with `path must be +shorter than SUN_LEN`. The wrapper is a `mktemp -d` directory under `/tmp` +(override with `LAYERFS_TEST_SYSTEM_TMP`), removed on exit, and holds only the +symlink; `statfs` follows it, so the Stores are still on the supported +filesystem. + +Overrides: `LAYERFS_TEST_JOBS`, `LAYERFS_TEST_CARGO_HOME`, +`LAYERFS_TEST_CARGO_TARGET_DIR` and `LAYERFS_TEST_SYSTEM_TMP`. Arguments after +`--` are appended to every `cargo test`, for example +`tools/ci/test_store_ext4.sh --quick -- --nocapture`. + +## Find a supported directory + +On Linux, ask the mount table: + +```bash +findmnt -n -o FSTYPE --target /path/to/candidate # ext4, xfs or btrfs +``` + +Inside a Docker Sandbox (the `namespaces` runtime), the sandbox run directory +is ext4 while `/tmp` is tmpfs and the checkout is an overlay: `$HOME` and +`/layerfs/data/machine/native/run/` report ext4, so a directory such +as `/layerfs/data/machine/native/run//tmp/layerfs-store-tests` is a +valid `LAYERFS_TEST_TMPDIR`. Never use `/tmp`. + +On macOS the corresponding local filesystems are `apfs` and `hfs`; the +harness reads the mount table there too. + +The build and the Stores live under `LAYERFS_TEST_TMPDIR`, so allow several +gigabytes on that mount. + +## PostgreSQL + +`LAYERFS_TEST_POSTGRES_URL` is a libpq connection string (despite the name), +not a URL: + +```bash +LAYERFS_TEST_POSTGRES_URL='host=127.0.0.1 port=55433 user=postgres password=… dbname=postgres sslmode=disable' \ + LAYERFS_TEST_TMPDIR=/mnt/ext4/layerfs-store-tests tools/ci/test_store_ext4.sh +``` + +### Server and extensions + +Use PostgreSQL 17 or newer. The Store schema itself needs 16 or newer for +`STORAGE PLAIN` ([PostgreSQL](postgresql.md)), and the PostgreSQL suites are +qualified on 17.x, so 17 is the supported version for tests. + +The full-mode doctor calls `amcheck`'s `verify_heapam` and `bt_index_check` for +every heap and ready B-tree relation, and it never installs an extension itself +([Diagnostics](diagnostics.md)). Create the contrib extensions in the test +database before a full audit: + +```sql +CREATE EXTENSION IF NOT EXISTS amcheck; +CREATE EXTENSION IF NOT EXISTS pgstattuple; +``` + +```bash +psql "$LAYERFS_TEST_POSTGRES_URL" -c 'CREATE EXTENSION IF NOT EXISTS amcheck;' +``` + +`amcheck` is the required one: without it a full audit reports each relation as +`store.database.relations=Unknown`, because no supported function exists, and +`store.database.relations.summary` is `Unknown` too. That is missing coverage, +not corruption, but the PostgreSQL compaction tests assert that a rebuilt Store +audits cleanly with no `Fail` or `Unknown` observation. On a fresh cluster that +never created the extension, the five `clean()` assertions in +`postgresql_compact.rs` fail with exactly that finding; the +`assert_doctor_clean` assertions in `postgresql_compact_fixtures.rs` depend on +it too. `pgstattuple` is the companion contrib module; the current diagnostic +calls only `amcheck`, but the CI lane creates both so the scratch server +matches the qualified setup. + +The push lane is SQLite-only and does not need any of this. When +`LAYERFS_TEST_POSTGRES_URL` is set, the harness asks `psql` whether the +extensions exist and warns with the `CREATE EXTENSION` command when `amcheck` +is missing; an absent `psql` or an unreachable server downgrades that to a +message and never fails the run. `LAYERFS_TEST_EXPECT_AMCHECK` (any value) +makes `postgresql_diagnostic` assert `store.database.relations.summary` is +`Pass`; the `store-ext4` full job sets it after creating the extensions. + +### Credentials and TLS + +The PostgreSQL test fixtures and the doctor's admin client connect with +`postgres::Client::connect(…, NoTls)`, not through the Store's TLS policy. The +connection string must therefore carry its own password and must not require a +TLS handshake: use `sslmode=disable` on loopback or a private route, and +`password=…` unless the server uses trust authentication. `sslmode=require` or +`verify-full` is fine for the Store sessions, but the test fixtures reject it. +Do not put a password in a job log; pass the whole connection string through +the environment, as the workflow does with a scratch trust-authenticated +service. + +### The physical doctor's extra servers + +`postgresql_doctor_physical` needs two servers beyond the primary: + +| Variable | What it must be | +| --- | --- | +| `LAYERFS_TEST_POSTGRES_MISSING_URL` | a second database (or server) where `amcheck` is **not** installed; the test asserts that the missing extension is `Unknown` and that the doctor did not install it | +| `LAYERFS_TEST_POSTGRES_REPLICA_URL` | a physical standby of the primary, in recovery (`pg_is_in_recovery()` is true), with the test's schema replicated within 5 s | + +Create the amcheck-free database on the same scratch server, for example: + +```bash +psql "$LAYERFS_TEST_POSTGRES_URL" -c 'CREATE DATABASE layerfs_no_amcheck' +LAYERFS_TEST_POSTGRES_MISSING_URL='host=127.0.0.1 port=5432 user=postgres dbname=layerfs_no_amcheck sslmode=disable' +``` + +Both variables are optional: with the primary URL set, a test that needs one +and finds it unset prints `NOT_RUN: LAYERFS_TEST_POSTGRES_MISSING_URL is unset` +(or the replica variable) and returns. The `store-ext4` full job has no physical +standby and sets neither, so those extra cases print `NOT_RUN` and the target +stays green. Run the target separately with both for the physical coverage. + +Each PostgreSQL test creates and drops its own schema: point the variables at a +scratch server, never at a schema that holds a Store you care about, and make +sure the server is reachable from the process that runs the tests (inside a +Sandbox, `127.0.0.1` is the Sandbox). Without the variable the PostgreSQL test +files print `NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset` and check nothing; +the SQLite Store suites still run and still need the supported filesystem. + +### Compaction tests and per-test bindings + +The T9 PostgreSQL compaction suite (`postgresql_compact.rs`) gives every test +its own catalog binding, `postgresql-compact-`. PostgreSQL advisory locks +are server-wide, not schema-scoped, so two tests that shared a binding would +exclude each other while running in parallel even though each owns its schema. +The per-test binding fix is already in place; keep it when adding a case. Those +tests need only `LAYERFS_TEST_POSTGRES_URL`, `amcheck` and the supported +`LAYERFS_TEST_TMPDIR`, not the physical doctor's two extra URLs. + +## CI + +[`.github/workflows/store-ext4.yml`](../../../../.github/workflows/store-ext4.yml) +runs this harness in the repository's report-only CI. It adds no test +selection: every target it runs is already in the push or nightly lane that +[`tools/ci_tests.py`](../../../../tools/ci_tests.py) chooses; it runs them where +their guard admits a Store. Like the other lanes it is not a required check, an +agent does not wait for it, and a green run is not verification of a change +([AGENTS.md](../../../../AGENTS.md) §4). + +| Job | Trigger | Command | PostgreSQL | +| --- | --- | --- | --- | +| `store ext4 (--quick)` | push to `main` and pull requests touching `core/**`, `engine/**`, `control/**`, `api/crates/**` (not `layerfs-node`), `Cargo.*`, `.config/**`, `tools/ci/**`, `.cargo/**`; a markdown-only change does not run it | `tools/ci/test_store_ext4.sh --quick` | off | +| `store ext4 (--full, PostgreSQL 17)` | `schedule` (04:47 UTC) and manual dispatch | `tools/ci/test_store_ext4.sh --full` | a `postgres:17` service container | + +Both jobs set `LAYERFS_TEST_TMPDIR=/mnt/layerfs-store-tests`. On the +`ubuntu-24.04` runner `/mnt` is a separate ext4 data disk and `/tmp` is tmpfs; +the prepare step creates the directory, hands it to the runner user (it belongs +to `root` on the image) and asserts the filesystem with `findmnt`, so a runner +image without an ext4 `/mnt` fails in that step instead of as a guard refusal +inside a suite. The harness then sets `TMPDIR`, `CARGO_TARGET_DIR` and +`CARGO_HOME` itself, as it does locally. + +The scheduled job sets `LAYERFS_TEST_POSTGRES_URL` to +`host=127.0.0.1 port=5432 user=postgres dbname=postgres sslmode=disable` +against that scratch service container, with trust authentication, so every +suite runs its PostgreSQL cases. Each PostgreSQL test creates and drops its own +schema, nothing outlives the run, and the runner reaches the container's +published port on `127.0.0.1`. The push job leaves the variable unset, so its +PostgreSQL cases print `NOT_RUN` and only the SQLite suites run. + +Before the suites, the full job installs `postgresql-client` and creates +`amcheck` and `pgstattuple` in the service container's database, then sets +`LAYERFS_TEST_EXPECT_AMCHECK=1` so `postgresql_diagnostic` asserts the +full-mode relation summary is `Pass`. A server that did not take the extension +fails in that step with its name, instead of as five `Unknown` findings inside +the compaction suite. The job also runs `postgresql_doctor_physical`. It needs +`LAYERFS_TEST_POSTGRES_MISSING_URL` and `LAYERFS_TEST_POSTGRES_REPLICA_URL` for +its extra cases; the full job provides neither, so those cases print `NOT_RUN` +and the target stays green. Run it separately with both for that coverage +(above). + +The harness moves `CARGO_HOME` and `CARGO_TARGET_DIR` onto +`LAYERFS_TEST_TMPDIR`, so these jobs do not restore the checkout-scoped +`Swatinem/rust-cache` the other workflows use: it would restore a `target/` +that the harness never reads. They install `mold` as the fast lane's `test` job +does, because they link the same test profile from a cold cache, and carry a +60-minute (`--quick`) or 120-minute (`--full`) job timeout. + +## Troubleshooting + +| Symptom | Cause | Fix | +| --- | --- | --- | +| `LAYERFS_TEST_TMPDIR is not set.` | the harness was run without the variable | set it to a directory on a supported filesystem | +| `… is on 'tmpfs', which cannot carry a Store.` | `/tmp` (or another tmpfs/overlay) was chosen | pick ext4, xfs or btrfs on Linux, apfs or hfs on macOS | +| a suite fails with `filesystem 0x… at … does not carry SQLite locks` | `TMPDIR` or `CARGO_TARGET_DIR` escaped the harness (exported by hand) | let the harness set both; do not override them to a scratch directory | +| `NOT_RUN: LAYERFS_TEST_POSTGRES_URL is unset` | no PostgreSQL server | expected; set the variable to run those cases | +| `store.database.relations=Unknown` and a compaction test fails on `clean` | `amcheck` was never created in the test database | `CREATE EXTENSION IF NOT EXISTS amcheck;`, then re-run; the harness warns when `psql` can see it is missing | +| `NOT_RUN: LAYERFS_TEST_POSTGRES_MISSING_URL is unset` (or `…_REPLICA_URL`) from `postgresql_doctor_physical` | the physical target's extra cases need an amcheck-free database and a physical standby; without them those cases skip | expected in the full sweep; set both (see [the physical doctor's extra servers](#the-physical-doctors-extra-servers)) and run that target separately for the physical coverage | +| `error: TLS support is disabled` or psql prompts for a password | the fixtures use `NoTls` and read the conninfo only | put `password=…` in the connection string and use `sslmode=disable` on a private route | +| `fatal: unable to access 'https://github.com/…/fuser.git'` or a TLS error | the pinned `fuser` git dependency could not be fetched | the harness sets `CARGO_NET_GIT_FETCH_WITH_CLI=true` and `GIT_SSL_NO_VERIFY=true`; check egress to `github.com` | +| `has mode 0755 … fix with chmod 700` | a left-over Store directory with group/other access | remove the named directory; the guard never changes permissions | +| `Updating crates.io index` stays silent for minutes | the sandbox network can stall cargo's multiplexed sparse-index connection | re-run with `CARGO_HTTP_MULTIPLEXING=false`; the download cache resumes where it stopped | +| `path must be shorter than SUN_LEN` | a Unix-domain socket path exceeded the kernel limit, usually because `TMPDIR` was set long by hand | use the harness (it keeps `TMPDIR` short) or pass a short `LAYERFS_TEST_TMPDIR` | +| `Store busy before effect` | another writer held the Store | not an environment failure; rerun the suite | + +The repository's test selection and CI lanes are separate: `tools/ci_tests.py` +decides which binaries the push and nightly runs take, and this harness only +gives the Store suites the filesystem they need. diff --git a/docs/architecture/flows/call.md b/docs/architecture/flows/call.md index 46905be63f..791ded8279 100644 --- a/docs/architecture/flows/call.md +++ b/docs/architecture/flows/call.md @@ -48,7 +48,7 @@ retries. A lost answer after the request was sent is `Unknown`, never resent. | # | What happens | Owning topic | | --- | --- | --- | | 1 | The front end makes one library call: the CLI parses `layerfs `; Node and Python pass JSON text. | [Front ends](../api/front-ends/README.md), [Bindings](../api/front-ends/bindings.md) | -| 2 | The call table finds `family.call` (73 calls in 10 families) and checks every argument before any effect. | [Calls](../api/calls/README.md#what-it-does), [SDK](../api/sdk/README.md) | +| 2 | The call table finds `family.call` (76 calls in 10 families) and checks every argument before any effect. | [Calls](../api/calls/README.md#what-it-does), [SDK](../api/sdk/README.md) | | 3 | A folder scope, when the client has one, guards and rewrites the checked arguments. | [Calls: folder scope](../api/calls/README.md#folder-scope) | | 4 | The home is opened (explicit path, else `LAYERFS_HOME`, else `~/.layerfs`). | [Home](../control/home/README.md) | | 5 | The family function reads the Store and project records, refuses a blocking intent and takes this process's lease on the Store. | [Stores and projects](../control/stores-and-projects/README.md#what-it-does), [Home: the `op` intent](../control/home/README.md#the-op-intent) | diff --git a/docs/architecture/flows/merge.md b/docs/architecture/flows/merge.md index 2c7b7630ac..742ac5de29 100644 --- a/docs/architecture/flows/merge.md +++ b/docs/architecture/flows/merge.md @@ -60,7 +60,7 @@ never written. | 4 | `branch.merge` checks its arguments first, then fast-forwards when one side is an ancestor of the other. | [SDK: `branch.merge`](../api/sdk/branch.md#branchmerge), [Store calls: Branch history](../engine/store-calls/README.md#branch-history) | | 5 | Otherwise it finds the merge base, decides merge units, and builds the merged tree with `/.lww` rules in one Save. | [Compare and merge: merge](../core/compare-and-merge/merge.md), [Compare and merge](../core/compare-and-merge/README.md) | | 6 | A conflict drops the Save and creates nothing; a clean merge writes the new Branch at a merge Commit in one transaction that checks both sides are unchanged. | [Store: history calls](../engine/store/README.md#history-calls), [History: operations](../core/history/README.md#operations) | -| 7 | `branch.publish` adds the Branch head (or a named Commit) as a new `main` Layer by compare-and-set on the stack head and Branch base. A publish that would skip a Layer `main` gained since the Branch's base is refused `HeadMoved`; a Branch merged with `main` has `main`'s head as its base and publishes as a fast-forward. Only `force` overwrites, and its skipped Layers are counted and listed, not merged. | [SDK: `branch.publish`](../api/sdk/branch.md#branchpublish), [Store calls: Branch history](../engine/store-calls/README.md#branch-history) | +| 7 | `branch.publish` adds the Branch head (or a named Commit) as a new `main` Layer by compare-and-set on the stack head and Branch base. Publication is overwrite-only: skipped Layers are counted and listed, not merged. | [SDK: `branch.publish`](../api/sdk/branch.md#branchpublish), [Store calls: Branch history](../engine/store-calls/README.md#branch-history) | ## Related diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md index f3a52b14a4..0a1703c9d1 100644 --- a/docs/architecture/glossary.md +++ b/docs/architecture/glossary.md @@ -18,7 +18,7 @@ LayerFS (backend, install, scope), the row gives both. | Branch | A named line of Commits in a project, with a base Layer and an optional head Commit. `main` is not a Branch. | [History: records](core/history/README.md#records) | | Bridge | `layerfs-bridge`: the wire contract between a controller and a Workspace daemon: the authenticated channel, every control and SDK record, the daemon's private setup and the Store install records. | [Bridge](engine/bridge/README.md) | | Bucket | A named place the home records where backups are kept, reached through a driver (local folder, MinIO, R2 or S3 API). Drivers know files by name and nothing about Stores. | [Backups: buckets](control/backups/buckets.md) | -| Call table | The 73 calls in 10 families that every front end exposes, with their arguments, and the one dispatcher they all go through. | [Calls](api/calls/README.md), [SDK](api/sdk/README.md) | +| Call table | The 76 calls in 10 families that every front end exposes, with their arguments, and the one dispatcher they all go through. | [Calls](api/calls/README.md), [SDK](api/sdk/README.md) | | Capture | The Commit step that seals a Workspace's active overlay generation as its published frontier and opens the next one. It copies no rows. | [Commit: what it does](engine/commit/README.md#what-it-does) | | Commit | An immutable history record: a complete filesystem root, its parent, the base Layer it was built from, an optional second parent and metadata. Also the call (`workspace.commit`) that makes one from a Workspace. | [History: records](core/history/README.md#records), [Commit](engine/commit/README.md) | | Construction | Building canonical file and tree objects from input and saving them: Init from a native folder, a Commit from its captured generation. A Commit has one construction producer. | [Commit: construction](engine/commit/construction.md), [Project Init: construction](engine/project-init/README.md#construction), [Files: construction](core/files/README.md#construction) | @@ -38,7 +38,7 @@ LayerFS (backend, install, scope), the row gives both. | Install | (1) Commit install: advancing a Workspace's base to the published root while rows written after the capture stay. (2) Store install: the one-time stream of a sealed Store file to a daemon. | [Commit: what it does](engine/commit/README.md#what-it-does), [Project Init: seal and install](engine/project-init/README.md#seal-and-install) | | Intent | The `op` field a multi-step operation writes into its entity's record before its first effect. A live owner makes other operations `Busy`; a gone owner's uncertain intent makes them `Unresolved`. | [Home: the `op` intent](control/home/README.md#the-op-intent) | | Kernel route | How the kernel reaches a Workspace: a FUSE session (Linux) or a loopback NFSv3 export (macOS). | [Kernel routes](engine/kernel-routes/README.md) | -| Layer | A published root on a project's main line. `branch.publish` adds one; it refuses to skip a Layer `main` gained since the Branch forked unless `force` overwrites. | [History: records](core/history/README.md#records) | +| Layer | A published root on a project's main line. `branch.publish` adds one; publication is overwrite-only. | [History: records](core/history/README.md#records) | | LayerStack | One project's linear timeline of Layers, with its Branches and Commits and one allocation scope. | [History: records](core/history/README.md#records) | | Lease | The file `store//open/` a process holds while it uses a Store, taken under the Store lock. Moves, removes and disconnects refuse `InUse` while a live lease exists. | [Home: locks and leases](control/home/README.md#locks-and-leases) | | Machine | A kernel that Sandboxes and sqlite Stores live on: the built-in `native` and `docker`, or created `lima` and `apple-container` machines. Every machine except `native` on macOS and Linux runs its sqlite Store calls in one worker. | [Machines](control/machines/README.md) | diff --git a/docs/general/parallel-worktrees.md b/docs/general/parallel-worktrees.md index 9d5947c619..f2fabb296a 100644 --- a/docs/general/parallel-worktrees.md +++ b/docs/general/parallel-worktrees.md @@ -209,16 +209,3 @@ record, so its target path must be updated first. Never scan or migrate another worktree's records. Keep an active cache warm and release the old cache through the cleanup procedure at handoff; retain records, sealed bundles and failed-run evidence. - -## After a fuser revision change - -After rebasing across #686 (fuser from its Git fork), or any later fuser `rev` -change, run `prepare` again for each platform before offline builds. A Cargo -home prepared earlier has no checkout of that revision and fails `--offline`. - -## Clippy on the Linux build image - -A Linux build image may lack the Clippy component (the stock -`rust:1.85.1-bookworm` image does), and `cargo` then refuses with -`'cargo-clippy' is not installed`. Run Clippy through `--platform macos`, and -keep Linux for the tests that need a Linux Store or mount. diff --git a/docs/research/README.md b/docs/research/README.md index cccc97bd39..afca002944 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -16,7 +16,6 @@ here is supporting context. - [AI-native filesystem vision](vision/README.md) - [Historical V2 replacement work](history/v2-replacement/README.md) - [Historical V3 engineering work](history/v3/README.md) -- [Agent guide history](history/agents-guides/README.md): status text moved out of the agent guides (2026-11-16) Historical paths are retained for design context and source-seal interpretation; they do not define the current product or roadmap. diff --git a/docs/versioned/2.0.0/calls.md b/docs/versioned/2.0.0/calls.md index 8989091833..9825815e42 100644 --- a/docs/versioned/2.0.0/calls.md +++ b/docs/versioned/2.0.0/calls.md @@ -138,18 +138,14 @@ folder is in place. Events arrive at most every 200 ms. | `get` | `project`, `branch` | — | one Branch and its head Commit | | `fork` | `project`, `name`, `from_branch`, `[from_commit]` | — | a new Branch from another Branch's head or Commit | | `merge` | `project`, `name`, `a`, `b` | `message`, `units` (JSON) | merges two Branches into a new one | -| `publish` | `project`, `branch`, `[commit]` | `expected_base`, `expected_head`, `force` | a Branch's head or Commit as `main`'s next Layer, refusing a stale base | +| `publish` | `project`, `branch`, `[commit]` | — | a Branch's head or Commit as `main`'s next Layer | | `diff` | `project`, `from_branch`, `to_branch` | `paths_only`, `page_size`, `page_pos`, `cursor` | files that differ between two Branches' heads | Run: `fork` answers `{kind: "Forked", branch, base, head}`; `publish` answers `{kind: "Added", source, published_layer, based_on, overwrote_count, overwrote, overwrote_has_more}`; `merge` answers `{kind: "Merged", fast_forward, branch, head, root, sources, merge_base, conflicts, lww, -units, …}`. `publish` is refused `HeadMoved` when `main` gained a Layer since -the Branch forked (merge with `main` into a new Branch and publish that), or -when `main` or the Branch head is not the `expected_base` or `expected_head` -given; `force` overwrites instead. A Commit already published answers -`UpToDate`, and a tree `main` already holds answers `NoChanges`. +units, …}`. ### `commit` (3) diff --git a/engine/AGENTS.md b/engine/AGENTS.md index 577f58ab6f..790bea2898 100644 --- a/engine/AGENTS.md +++ b/engine/AGENTS.md @@ -2,136 +2,297 @@ > **Status:** Current general guide. -Read [repository instructions](../AGENTS.md) first. This guide adds what is -specific to `engine/`: who owns what, the boundaries between crates, and how -to check a change. Current behaviour is in the -[architecture guide](../docs/architecture/README.md); how the engine got here -is in the [archived guide history](../docs/research/history/agents-guides/README.md). +Read [repository instructions](../AGENTS.md) first. This file adds implementation +boundaries for the engine layer under `engine/`; it does not repeat the +product mental model or campaign-specific benchmark procedures. ## Scope and ownership -| Crate | Owns | Architecture | -| --- | --- | --- | -| `layerfs-bridge` | the process facts the home and the Sandbox driver share (`process`), wire and native records, native install and control channels | [Bridge](../docs/architecture/engine/bridge/README.md) | -| `layerfs-daemon` | mounted Workspaces, their overlay connections and locks, mount/Ready/unmount, Commit composition, the direct Store adapter | [Daemon](../docs/architecture/engine/daemon/README.md) | -| `layerfs-fuse`, `layerfs-nfs`, `layerfs-mount-ports` | the kernel routes: FUSE and NFS as peers over the shared mount ports (#535 D3) | [Kernel routes](../docs/architecture/engine/kernel-routes/README.md) | -| `layerfs-overlay` | each Workspace's own overlay SQLite file | [Overlay](../docs/architecture/engine/overlay/README.md) | -| `layerfs-persistence` | global Store writes, SQLite and PostgreSQL (#535 D2) | [Store](../docs/architecture/engine/store/README.md) | -| `layerfs-project` | native import; Project Store Init and install (`layerfs-project::store`) | [Project Init](../docs/architecture/engine/project-init/README.md) | -| `layerfs-store-service` | the SDK Store calls (`src/methods/`) over `read`, `write` and `history` | [Store calls](../docs/architecture/engine/store-calls/README.md) | -| `layerfs-workspace` | the Workspace view and captured construction (`CapturedNamespace`) | [Workspace](../docs/architecture/engine/workspace/README.md), [Commit](../docs/architecture/engine/commit/README.md) | - -- **No engine crate depends on an API or control crate.** Core owns content, - history, storage and telemetry. Since #535 (owner, 2026-11-03, D1, D4) - Sandbox and network code live in the [control layer](../control/AGENTS.md) - (renamed from connect by layerfs-project#101, D-6): the Sandbox runtime - (`layerfs-sandbox-backend`), the machine layer (`layerfs-platform`) and - remote storage (`layerfs-bucket`, with `layerfs-store-service`'s `remote/`). -- **Store service methods** (#536 H3): `src/methods/` holds the method table - (`methods::call`), its argument reader and one file per `file.*`/`branch.*` - call, and is the facade over `read`, `write` and `history`, which know no - SDK method names. Their tests live in store-service's `tests/` - (`concurrent_commits`, `lane_merge` and `merge_report`, which need a daemon, - in `layerfs-daemon`'s). `layerfs-api` keeps its public re-exports of - Project Store Init and install, and its SDK-facing daemon tests include - daemon and Sandbox fixtures from this layer. -- **Retired code stays retired:** the seven `*-legacy` directories and - `layerfs-server` (R7-retire), the v0.1.6 reference and `core/reference-tests` - (R9c; see the [root guide](../AGENTS.md#retired-and-frozen)). The boundary - guard refuses their return. Do not restore predecessor code to supply a - feature: pinned read-only SDK views (303/08 O-10) are deferred, not dropped, - and need a new design on the SQLite overlay. Add a crate only with a real - product boundary and implementation. -- **Facts that shape every change:** each mounted Workspace has its own overlay - file and connection behind its own lock, and the calling thread runs each - short job; there is no SQL owner thread, queue, credit scheme or shared - memory budget (#321). There is no daemon-wide graceful drain, and none is - planned. Privileged command cancellation and client provenance are outside - the owner's scope. -- **Where to start:** cluster-one work with the - [handbook](../docs/general/cluster_one_handbook.md) and the - [CAS/CDC/delta guide](../docs/general/cas_cdc_deltaencoding_handbook.md); - cluster-two work with the engine topics it touches, the - [flows](../docs/architecture/flows/README.md) and +- Engine owns Bridge, daemon, FUSE, NFS, Overlay, Persistence, Project, + Persistence, Project, Store service and Workspace. Core owns content, + history, storage and telemetry. The library `layerfs-api` and its front ends + (`layerfs-cli`, `layerfs-node`, `layerfs-python`) are API crates under + `api/crates`; see the [API guide](../api/AGENTS.md). No engine crate may + depend on them. Since #535 (owner, 2026-11-03, D1, D4) Sandbox and network + code leave the engine for the connect layer, renamed the + [control layer](../control/AGENTS.md) by layerfs-project#101 (D-6): + the Sandbox runtime (now `layerfs-sandbox-backend`), the machine layer (now + `layerfs-platform`) and remote storage (now `layerfs-bucket`, with + `layerfs-store-service`'s `remote/`) moved out in #535 phase 1. The engine keeps + persistence (SQLite and PostgreSQL, D2), the daemon, the overlay, + Workspaces and the kernel routes (FUSE and NFS as peers over + `layerfs-mount-ports`, D3). No engine crate may depend on a control crate. +- `layerfs-store-service` owns the SDK Store calls in `src/methods/` (#536 + H3): the method table (`methods::call`), its argument reader and one file + per `file.*`/`branch.*` call. `read`, `write` and `history` know no SDK + method names; `methods/` is the facade over them. Their tests live in + store-service's `tests/` (`concurrent_commits`, `lane_merge` and + `merge_report`, which need a daemon, in `layerfs-daemon`'s). +- Project Store Init and install belong to `layerfs-project::store`; `layerfs-api` + retains its public re-exports. Its SDK-facing daemon integration tests + include daemon and Sandbox test fixtures from this layer. + The v0.1.6 reference under + root `crates/` and the archived `core/reference-tests` were retired by R9c + (2026-10-10) and are absent at HEAD; recover them at + local tag `reference-v0.1.6-final` (`d296981ac`, `crates` tree `498dd1917812`). + Neither was a dependency, source include or fallback; do not restore them. +- Active cluster-one members are content, storage, history, persistence, project + Init and telemetry. The initial cluster-two SQLite engine is `layerfs-overlay`; + its active membership does not complete Workspace/FUSE/daemon integration. + [Cargo.toml](../Cargo.toml) is the membership authority. + Workspace now exposes immutable base binding/read, effective source-qualified + lookup/stat/paged name merge, prepared actor install and atomic ordinary + namespace operations, bounded writes/truncate/regrow and composed payload + reads. Independent file/captured/operation custody and bounded live reclamation + are implemented through S6, including indexed automatic reclamation (its + physical reservation and headroom were removed by #321: no space is reserved + ahead of use, and a full device rolls the write back as no space); + native/runtime/integrated exits remain + unfinished. See [S6 audit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/S6-EXIT-AUDIT.md). Its relocated + predecessor `layerfs-workspace-legacy` was removed by R7-retire. + Since #321 the daemon holds one overlay file and connection per mounted + Workspace, each behind its own lock, with the calling thread running each + short job; the fair SQL owner thread, its queue, credits and shared memory + budget are removed. See the [terminology guide](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/64-overlay-terminology.md) + and the [#321 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/321/CHECKLIST.md). + Daemon also exposes a direct global Store adapter with a + mount-time reader per Workspace, exact quarantine and read-only bind snapshots, + one immutable cache shared across Workspaces, bounded root + binding and operation-owned exact failures. Concrete opening stays outside + the provider-independent adapter; see the + [direct Store boundary](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/61-direct-store-adapter.md). + The host-mediated SDK/upstream transport is retired; see + [the retirement record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/PRE-S8-F12-20261007.md). + Workspace calls return typed values directly and count SQL/payload/allocation + work under the same lock. Exact attempted failures retain their cause and + backing; before-effect refusals retain their original input. Overlay/Daemon + also expose bounded indexed operation records in the same database, with guarded atomic changes and automatic last-owner + cleanup. Content now exposes a backed file editor over these records and + Workspace supplies an explicit operation/file adapter with first-original + failure custody. Run-aware localized edits reuse the frozen sparse scanner + and bounded positive immutable zero evidence. Streamed directory inputs share + the canonical filesystem algorithm; backed serial state supplies new-parent + membership, rebuilt roots and initial counts/final row streams. On the backed + route validation classifies in 64-row windows and keeps its topology evidence + in indexed records; resident routes keep their resource-derived limits. + Captured local inode/run points retain exact reader root/floor and bounded + forward metadata progress. Captured regular-file normalization now derives + authenticated base facts, coalesces final changes into indexed records and + consumes them once through the retained FileView/fallible edit source. Backed + reference reduction/release uses fixed rows, sealed membership passes and + guarded FIFO/cursor transitions. Captured namespace normalization is the + `CapturedNamespace` producer + ([captured namespace construction](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/78-captured-namespace-construction.md)); + the product Commit constructor calls it + ([product Commit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/79-product-commit.md)). The Store + half of Commit is implemented with exact original failure/unknown custody; + see [Store Commit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/65-store-commit-composition.md). + The external E01 example records original startup work, diagnostics and Stop + without creating a Workspace route. It supplies diagnostic receipt consistency, + not E1/E2 performance admission. Its relocated predecessor was removed by + R7-retire; standalone native executable/Exec integration is unfinished. + Pre-S8 direct-operation accounting now has actual registered macOS/Linux engine + and Store-half Commit runs, independent family/count validation, and supported + phase observations. Numerical latency/residency and exact continuous peaks + remain unqualified; see the [accounting scope](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/PRE-S8-F14-20261007.md). + SDK creates/imports the initial Store, publishes the first Branch and consumes + seal, returning a closed file plus explicit provider/locator/profile metadata. + It retains no Store handle or data service. Native install now streams the + sealed file once, opens it in the daemon and returns both actual SQLite versions; + see [F5 handoff](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/PRE-S8-F5-20261007.md). Authenticated mount + binding, Store-half Commit, status, terminal close, fork and history now compose + the direct ports; see [native control](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/68-native-workspace-control.md). + The prior client/runtime, daemon upstream, Bridge logical data framing and + excluded API-core are retired. Historical receipts keep their original topology + and verdicts. R7-retire (2026-10-10) + removed all seven excluded directories as retirement: `layerfs-server`, + `layerfs-fuse-legacy`, `layerfs-sandbox-legacy`, `layerfs-sdk-legacy`, + `layerfs-daemon-legacy`, `layerfs-bridge-legacy` and + `layerfs-workspace-legacy`. The root workspace lists the active + members across core, engine and api; the boundary guard refuses the return of a removed directory or + package name, and each source is recoverable from the commit named in the + [R7-retire record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R7-RETIRE-COMPLETION-20261010.md). + Pinned read-only SDK views (303/08 O-10) are deferred, not dropped: no + implementation is in the tree, and a kept feature needs a new design on the + SQLite overlay. Do not restore the predecessor code to supply them. + Project native import preserves opaque symlinks, complete membership and hard + links, with indexed acquisition state. The accepted host WAL baseline retains + its recorded speed FAIL; no new timing is implied by SDK composition. + Bridge retains pinned authenticated KK channels, bounded native records and + independent fences and bounded native install/control. FUSE/Exec qualification + and complete kernel mount readiness remain S8. + The replacement Sandbox is an active member with ordinary Engine execution, + owned lifecycle and authenticated SDK/daemon startup. Optional privileged + command cancellation/client provenance is outside the current owner scope. + The replacement Fuse is now active with a fixed shared dispatcher, actual + deferred Owner/Store ports, a read-path callback adapter with complete opcode + accounting, direct mount/session ownership and connection drain. + Its predecessor `layerfs-fuse-legacy` was removed by R7-retire; the last + commit holding that source is `15e33e22c`. The daemon + composes Attach/Locate/Ready and reversible normal unmount; see + [native request service](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/75-native-request-service.md) and + [native mount session](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/76-native-mount-session.md). + Ordinary native mutation is served through the existing Workspace plan and + one publishing Overlay job, with no notification and no writeback cache; see + [native mutation and kernel coherence](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/77-native-mutation-coherence.md). + A control Commit runs the captured namespace producer through the unchanged + driver, and takes the Workspace's overlay lock for each of its jobs; the mounted + proofs and their limits are in the + [R5 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R5-COMPLETION-20261009.md). Forced unmount of one + Workspace is implemented as `ForceUnmount`: a before-effect guard, one abort + write on the connection's own control, the terminal fence, the local drain, + one plain detach, then Revoke and Close; see + [forced teardown](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/80-forced-teardown.md). It is refused where + no abort control is bound, which includes the current Sandbox topology, and a + stop after an effect is `Retained` with no way back. No daemon-wide graceful + drain exists and none is planned. Source acquisitions have their own owner + slots, and a failed cold read ends its own request with `EIO` while the + mount keeps serving; the concurrency, teardown and failure-scope proofs and + their limits are in the [R6 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R6-COMPLETION-20261009.md). + A create that leaves fewer unconsumed inode serials than the daemon's + configured low-water makes one early reservation; every deployment and + harness sets 0 today, which makes none. A new Mount is refused `Capacity` at + `mount:debt` while maintenance is stopped. Both, the proofs added around + them and the rows still open are in the + [R8b record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R8B-COMPLETION-20261010.md). R8b closed not + qualified and R9b without removal. R8c then closed qualified on function, + counts and resources at the owner-rescoped scope, with the deployed + low-water at 256 ([R8c record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R8C-COMPLETION-20261010.md)), + and R9c retired the root reference + ([R9c record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R9C-COMPLETION-20261010.md)). + Add members only with real product boundaries and implementation. +- Cluster-one work starts with the [handbook](../docs/general/cluster_one_handbook.md) and + [CAS/CDC/delta guide](../docs/general/cas_cdc_deltaencoding_handbook.md). Use public contracts, + source pins and limitations; preserve canonical compatibility. +- Cluster-two work starts with the [architecture guide](../docs/architecture/README.md): + the engine topics it touches, the [flows](../docs/architecture/flows/README.md) and [Where each call runs](../docs/architecture/control/README.md#where-each-call-runs). - Required corrections are real scope; research candidates are not - implemented features or excuses for workload caps. Migration, source moves - and retirement are explicit changes, never side effects of a component. + Required corrections are real engineering scope; research candidates are not + implemented features or excuses for accumulated workload caps. +- Closed Stage 0–6 handoffs and prior server/backend plans are historical. + Consult them for a selected compatibility/reference question; do not restart + their loops or inherit their retired topology. Do not revive `layerfs-server`. +- Keep unrelated work intact. Migration, source moves and retirement are explicit + changes, not side effects of implementing a component. ## Architecture and public contracts -- **Overlay naming:** `directory_entry` and `operation_record` (with their - owned and indexed variants) throughout SQL and the public ports. Since #321 - (schema 34) each mounted Workspace has its own overlay file with the same - tables, copied from a closed empty template at mount and deleted at terminal - unmount; the current schema is on the [Overlay](../docs/architecture/engine/overlay/README.md) - page. A naming change authorizes no physical table redesign. -- **Contracts:** public content, storage, history and persistence contracts - govern integrated callers. Stable capture and input, Store-derived policy, - backpressure, Save completion and atomic history publication are separate - obligations. Branch Commit overwrites the head and keeps its captured parent - ([owner supersession](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/BRANCH-OVERWRITE-DECISION-20261007.md)). -- **Project composition:** native import consumes SQLite-backed acquisition - through its backend-neutral port. Init into an existing Store is a live add - through the Store's own writer (2.0, #533); the Init that creates, seals and - installs a Store file stays for Store creation and install. Project's - owner-approved first-party edges (Bridge provisioning types, Persistence) - stay bounded by the guard's allowlist; Project uses no third-party database - driver directly. -- **Source pins:** `docs/architecture/` describes product source, not release - qualification. Record source pins and advance them explicitly; never - silently re-date evidence. +Overlay schema19 uses `directory_entry` and `operation_record` terminology, +including owned/indexed variants, throughout SQL and the active public ports. +Through schema 33 Workspaces shared physical tables partitioned by namespace; +since #321 (schema 34) every mounted Workspace has its own file with the same +tables, copied from a closed empty template at mount and deleted at terminal +unmount. The naming +change authorizes no physical table redesign; generic temporary buffers and +historical receipts retain their distinct terms. See the +[terminology guide](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/64-overlay-terminology.md). +The #320 product sweep (2026-10-14, schema 37) removes accounting triggers, +Workspace/allocator SQL rows and generic caller-minted leases. Workspace +lifecycle/frontier/dirty/base-reader counters are one journaled runtime value, +restored only after known whole-job rollback; unknown outcomes retain custody. +Commit runs/readers/base pins are journaled owner maps; captured generation +holds use a count index. Daemon-bound routing is checked once per call; Overlay +accepts no Route and stores no namespace. Cleanup debt remains SQL-backed after +the [memory-placement review](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/320/CLEANUP-MEMORY-DESIGN-20261014.md). +Resources computes row/length totals on demand and +retains exact owner counts from memory. See the current +[runtime state](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/64-overlay-terminology.md#runtime-workspace-state-and-remembered-sql-custody). + +Schema17 adds native mount/source/lookup/read associations, atomic Workspace +read observations and bounded revoked-lookup retirement. Schema18 adds native +file associations over the existing OpenFile owner and atomic open decisions; see +[native read custody](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/73-native-read-custody.md). This component +does not establish Ready, kernel service or full drain. Schema19 adds native +directory ownership, exact name-boundary cookies, retained parent updates and +bounded live cleanup; see [directory custody](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/74-native-directory-custody.md). + +`docs/architecture/` describes product source, not release qualification. +A source change to boundaries, canonical/physical format, algorithm or named +bound updates the affected architecture/API document in the same change. +Record source pins and advance them explicitly; never silently re-date evidence. +Keep implementation description separate from target proposal and research. + +Public content/storage/history/persistence contracts govern integrated callers. +Stable capture/input, Store-derived policy, backpressure, Save completion and +atomic history publication are separate obligations. Branch Commit overwrites the +head and keeps its captured parent; see the [owner supersession](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/BRANCH-OVERWRITE-DECISION-20261007.md). Immutable objects do +not replace authority, reference closure, mutable history or safe GC. + +Project's native import consumes SQLite-backed acquisition through its +backend-neutral port. Its Store composition lives in `layerfs-project::store`: +Init into an existing Store is a live add through the Store's own writer +(2.0, #533); the older Init that creates, seals and installs a Store file stays +for the Store's own creation and install. The +owner-approved first-party edges include Bridge provisioning types and +Persistence; the exact allowlist still bounds those edges, and Project still +cannot use a third-party database driver directly. Canonical construction stays +in Content, encoding/packing in Storage and database writes in Persistence. +The port and its provider remain the existing indexed acquisition algorithm. +See the [S7/S9 remaining plan](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/IMPLEMENTATION-PLAN-S7-S9-20261006.md). ### Filesystem access and execution ownership -Owner clarification 2026-10-08; implementation and proof requirements, not a -claim that S8 or S10 is qualified. - -- **FUSE serves any permitted process that can see the mount.** Request - admission and Workspace mutation or capture never require an Exec identity, - registered command or LayerFS-launched parent; external executors, - interactive shells and Sandbox execution get the same permissions, - semantics and ownership. -- **Commands belong to their launcher.** Sandbox setup or the external - executor establishes command identity, mount visibility and protection of - Store, Overlay and daemon credentials; execution owns standard I/O, exit - status and caller-requested cancellation. `workspace.exec` checks the - mounted directory and runs the command through the Sandbox runtime - ([where each call runs](../docs/architecture/control/README.md#where-each-call-runs)). - The daemon has no exec supervisor, launcher mode, per-Exec cgroups, command - registration or Exec stream/status/cancellation protocol. The SDK is the - call table in [layerfs-api](../api/crates/layerfs-api/src) - ([the calls](../docs/versioned/2.0.0/calls.md)). -- **FUSE owns lifetimes:** exact request, open, lookup, capture and Commit - lifetimes and complete filesystem and daemon-work drain. Zero registered - commands or shell exit never proves released descriptors, mappings, kernel - references or daemon jobs. Forced teardown kills no caller-owned process. - Normal unmount uses a reversible kernel busy probe while service stays - usable; force refuses active namespace control producers before any effect. -- **Commit** consumes the published frontier through the shared Content, - Storage and Persistence pipeline whatever the launch route. stdout/stderr are - not filesystem state unless written to a file in the Workspace. The old - managed-daemon Exec selections are withdrawn; keep their IDs, pins, receipts - and verdicts. -- **Proofs:** S8 verification includes a process launched outside the Exec API, - with no Exec registration, reading and mutating the mount and holding a - filesystem reference during an unmount attempt; S10 proves such changes - survive Commit and a fresh mount. Use ordinary public filesystem access. -- **FUSE source ownership** (reviewed 2026-10-08): `layerfs-fuse` owns its - native connection and request service (bounded dispatch, parking and - resumption, kernel handlers and replies, coherence); the daemon assembles one - shared FUSE service with its SQL and Store services and keeps the registry, - Ready/unmount and Commit composition. Dependency is daemon → fuse → - workspace, never fuse → daemon. Moving blocking OwnerClient calls behind a - port does not establish deferred service. +Owner clarification 2026-10-08: these are implementation and proof requirements, +not a claim that S8 or S10 is qualified. FUSE serves any permitted process that +can see the mount. Request admission and Workspace mutation/capture must not +require an Exec identity, registered command or LayerFS-launched parent. +Apply the same permissions, filesystem semantics and ownership to external +executors, interactive shells and ordinary Sandbox execution. + +Sandbox setup or the external executor establishes command identity, mount +visibility and protection of Store, Overlay and daemon credentials. Ordinary +runtime execution owns standard I/O, exit status and caller-requested cancellation. +SDK public organization is the eleven operations documented in +[the implemented SDK surface](../docs/general/sdk.md), with operation files under +[layerfs-api/src](../api/crates/layerfs-api/src). Project offers init/fork/ +branches/commits; Sandbox offers create/close; Workspace offers mount/exec/ +commit/status/unmount. Shared control/recovery/diagnostic plumbing lives in +base/ and the hidden internal module. Optional WorkspaceApi.exec selects the +mounted directory and delegates the existing Sandbox launcher; +the daemon has no exec/supervisor, launcher mode, per-Exec cgroups, command +registration or custom Exec stream/status/cancellation protocol. + +FUSE owns exact request/open/lookup/capture/Commit lifetimes and complete +filesystem/daemon-work drain. Zero registered commands or shell exit is never +evidence of released descriptors, mappings, kernel references or daemon jobs. +Forced filesystem teardown does not implicitly kill caller-owned processes. +Normal unmount uses a reversible kernel busy probe while ordinary service stays +usable. Force refuses active namespace control producers before any effect. + +Commit consumes the Workspace's published frontier through the shared Content, +Storage and Persistence pipeline regardless of launch route. stdout/stderr are +not filesystem state unless the command writes them to a file in the Workspace. +The old proposed managed-daemon Exec selections are withdrawn prospectively; +retain their original IDs, source pins, receipts and verdicts. Ordinary runtime +stream/result correctness and filesystem-lifetime proofs keep their real owners. + +S8 verification must include a process launched outside the Exec API, with no +Exec registration, reading and mutating the mount and retaining a filesystem +reference during an unmount attempt. S10 must prove that such changes survive +Commit and a fresh mount. Use ordinary public filesystem access in these proofs. + +Reviewed target source ownership2026-10-08: the replacement `layerfs-fuse` owns +its complete native connection/request service, including bounded dispatch, +parking/resumption, kernel handlers/replies and coherence. Daemon assembles one +shared Fuse service with its existing SQL/Store services, retaining registry, +overall Ready/unmount and Commit composition. Dependency is daemon -> fuse -> +workspace, never Fuse -> daemon. Request dispatch/read ports, mount/Ready and +per-Workspace normal drain are implemented ([R2 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R2-COMPLETION-20261008.md)), +as is ordinary native mutation ([R3 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R3-COMPLETION-20261008.md)); +as is the captured namespace producer with its bounded validation +([R4 record](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R4-COMPLETION-20261008.md)), which the Commit +driver reaches through the product constructor +([product Commit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/79-product-commit.md)). See the +[reviewed ownership](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/R2-R5-SOURCE-OWNERSHIP-REVIEW-20261008.md). +Moving blocking OwnerClient calls behind a port does not establish deferred service. ### Shared construction and completion boundaries -Namespace Init and Workspace Commit share Content, Storage and Persistence -through their public ports, with distinct input adapters and publication -lifecycles (names and paths rechecked 2026-11-16): +Source checked at `5747f0119`, guidance updated 2026-10-08. Namespace Init and +daemon construction share Content, Storage and Persistence through their public +ports. Their input adapters and publication lifecycles have distinct owners: -| Input/operation | Route | +| Input/operation | Existing route | | --- | --- | | Native Init file | Project import calls Content `construct_stream`; bounded output batches feed `Save::accept` | | New captured file | Workspace `CapturedFileEdits` calls Content `construct_runs` over data/zero windows | @@ -141,142 +302,192 @@ lifecycles (names and paths rechecked 2026-11-16): | Captured symlink and metadata | The same producer calls Content `emit_symlink` for a fresh target and patches or builds the portable attribute tree; a stored symlink keeps its base content root | | Object output | Content emits `FinalizedObject`; Storage `SaveSink` implements `FinalizedConsumer` by forwarding to `Save::accept` | -- **One encoder.** Canonical construction stays in Content, encoding and packing - in Storage, Store writes in Persistence; Overlay owns mutable payload, - metadata, operation records and construction scratch. Add no second encoder, - and keep SQLite types and paths out of Content and the daemon's - provider-independent `store/` adapter. Never materialize a native tree or - invoke Project Init to implement a Workspace Commit. -- **Use the real policy.** Use the Store-derived construction policy and - bounded capacities on both routes. An incremental file root need not equal a - fresh reconstruction: retained chunk boundaries can differ. -- **The product Commit:** `BoundWorkspace::commit_captured` runs - [`CapturedNamespace`](crates/layerfs-workspace/src/construction/driver.rs) - inside the Commit driver. It acquires the captured reader and one operation - owner, hands the driver the original cause on failure, and releases both - only once the outcome is known, keeping them with the failure when it is - not ([product Commit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/79-product-commit.md)). -- **Completion boundaries:** `Save::finish()` completes object storage while the - Store stays open; Init then initializes history, and Commit calls - `commit_branch` against its expected head before installing the base - locally. Only the Init that creates a Store file calls - `SqliteHandles::seal()`, which consumes the sole session, checkpoints, closes - and hands off that file; its macOS unused-extent cleanup runs only there and - is no Content/pack format change or live-daemon maintenance. A live daemon - keeps the shared Store open across Saves and Commits. +Use the actual Store-derived construction policy and bounded capacities on +both routes. Fresh construction and incremental edits use appropriate public +entrypoints and common canonical formats; do not assume an incremental file root +must equal a fresh full reconstruction, since retained chunk boundaries can differ. +Overlay owns mutable payload, metadata, operation records and construction scratch +under Workspace prefixes. Content owns canonical algorithms; Storage owns +deduplication, encoding and packs; Persistence owns global Store writes. Keep +SQLite types and paths out of Content and the daemon's provider-independent +`store/` adapter. Do not materialize a native tree or invoke Project Init to +implement a Workspace Commit. Native Init acquisition backing remains a separate +host provisioning facility. + +Current source has captured-file normalization and the Store half of Commit. +`BoundWorkspace::commit` captures once, begins a Save, invokes a caller-supplied +Content constructor, finishes the Save, publishes through History and installs +the known root locally. Full captured namespace assembly, including names, +links, metadata and changed file roots, is +[`CapturedNamespace`](crates/layerfs-workspace/src/construction/driver.rs). +The product constructor `BoundWorkspace::commit_captured` runs it inside that +driver: it acquires the captured reader and one operation owner, hands the +driver the original cause on failure, and releases both owners only after the +driver's outcome is known, keeping them with the failure when it is not +([product Commit](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/79-product-commit.md)). A control Commit +uses it; `Service::execute` still takes a caller's constructor for driver tests. +See [captured-file construction](crates/layerfs-workspace/src/construction/captured/owner.rs), +[the shared Save sink](../core/crates/layerfs-storage/src/save/operation.rs) and +[Store Commit composition](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/65-store-commit-composition.md). + +Keep completion boundaries explicit: `Save::finish()` completes object storage; +Init then initializes history, while Commit calls `commit_branch` against its +expected head before local base installation. SDK Init subsequently calls `SqliteHandles::seal()` to +checkpoint, close and hand off one Store file. The macOS allocation correction +runs only at this sole-owner Store seal; it is not a Content/pack format change +or live-daemon maintenance. Linux daemons keep their shared Store open. The +[seal proof](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/SEAL-ALLOCATION-STRIDE1-20261007.md) retains its exact +platform and benchmark scope; it does not qualify daemon allocation or S10. ## Optimization and performance debugging -Before changing a performance-sensitive path or diagnosing a performance -finding, read the [optimization guide](../docs/general/optimization-guide.md); -its FUSE, SQLite and complexity rules are mandatory. Reject quadratic or worse -scaling; use SQLite-backed mutable indexes and state, not custom duplicate -trees or graphs; account for request, SQL, I/O, copy, residency and cleanup -work. A SQLite claim needs both EXPLAIN and correlated runtime database -profiling. The [optimization handbook](../docs/general/optimization-handbook.md) -is the working procedure. A docs-only change needs no campaign. +Before changing a performance-sensitive path or diagnosing a performance finding, +read the [optimization guide](../docs/general/optimization-guide.md). Its FUSE, +SQLite and complexity rules are mandatory: reject quadratic or worse scaling, +use SQLite-backed mutable indexes/state rather than custom duplicate trees/graphs, +and account for request/SQL/IO/copy/residency/cleanup work. Preserve cluster one's +canonical formats and public APIs; use count-driven evidence and the existing +measurement policy. SQLite debugging/optimization claims require both database +EXPLAIN and correlated runtime database profiling; overall wall time or a plan +alone is insufficient. An unrelated/docs-only change does not require a campaign. +The [optimization handbook](../docs/general/optimization-handbook.md) is the +working procedure on top of those rules: the counters that already exist, the +diagnostic groups, the scaling checks and the current candidate list. ## Product source and external verification -- **`src/` holds production code only** in core, engine, control and api, - including included or generated implementation; shipped runtime SQL and - other shipped formats follow the same rules. -- **Forbidden in product source:** inline tests or benches, test-only cfg or - features, fixtures, mocks, fake clocks, fault injection, test or benchmark - drivers, test-only public APIs, benchmark-selected algorithms and executable - rustdoc test blocks. Platform cfgs, real features, production validation and - actual telemetry are legitimate. -- **Where things go:** public-API tests and their fixtures in package `tests/`, - examples in `examples/`, benchmarks in `benches/`, product-wide harnesses in - [layerfs-benchmark](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark), - development checks in `tools/`. Scaffold no empty placeholder directories. -- **Tests use the real library.** Do not include or recompile private source, - redirect target paths into test directories, import helpers into production - or expose an API only for a test. Test-only dependencies are - dev-dependencies; keep component restrictions such as std-only telemetry. -- **Deterministic observations.** Prefer public behaviour; telemetry tests use - completed reports and structural ordering, with no product fake clock or - narrow sleep-based thresholds. Verify disabled behaviour through its real - allocation and clock path. +The Rust `src/` directories in core, engine and api contain production code +exclusively, including +included/generated implementation. Runtime SQL and other shipped implementation +have the same ownership rules. + +Forbidden in product source: inline tests/benches, test-only cfg/features, +fixtures, mocks, fake clocks, fault injection, test/benchmark drivers, test-only +public APIs, benchmark-selected algorithms and executable rustdoc test blocks. +Platform cfgs, real features, production validation/invariants and actual telemetry +remain legitimate. Put API documentation with the API; examples outside src. + +| Content | Location | +| --- | --- | +| Product implementation | Core/engine crate `src/`, API Rust/JavaScript `src/` and required runtime source | +| Public-API tests and their helpers/fixtures | Package `tests/` | +| Runnable examples | Package `examples/` | +| Package benchmarks | Package `benches/` | +| Product-wide harness/diagnostics | the [layerfs-benchmark](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark) repository; inspect the actual harness manifest/entrypoint | +| Development checks | `tools/` | + +Tests exercise the production library that normal consumers use. Do not +include/recompile private source, redirect target paths into test directories, +import helpers into production or expose an API only to enable a test. +Test-only dependencies belong in dev-dependencies; retain component-specific +restrictions, including std-only telemetry. + +Prefer deterministic public behavior and external observations. Telemetry tests +can use completed reports and structural ordering; do not add a product fake-clock +interface or narrow sleep-based wall thresholds. Verify disabled behavior through +its actual allocation/clock path. Scaffold no empty placeholder directories. ## Production file size and responsibility -- **999 physical lines** at most per new production file, comments and blanks - included; this covers shipped runtime SQL and other formats outside Rust - `src/` (extend guard coverage for a new format). Moving code does not evade - it, and no root `crates/` returns for product work. -- **200 physical lines** at most per product `lib.rs`/`mod.rs`: attributes, - declarations, imports and re-exports, API docs and thin forwarding only. - Definitions, impls, behaviour-encoding state, branching, loops, conversions, - validation, formatting and I/O go in focused implementation files. -- **Split by responsibility** (lookup, transactions, reconstruction, placement, - ownership) before the ceiling, not into numbered files or a renamed god - module. Use ordinary functions and concrete types: no factory or interface - per algorithm, no service locator. Keep real process and provider - boundaries independently usable. Do not minify, expand macros or add - includes to evade these rules. -- Physical lines differ from [production LOC](../AGENTS.md#production-loc-comparison-for-every-commit), - which every commit reports. +All new replacement/application-adapter production files have at most **999 +physical lines**, including comments/blanks. This includes required runtime SQL +or other shipped formats outside Rust src. Extend guard coverage for new formats; +moving implementation does not evade the rule. The legacy root source is +retired; do not recreate a root `crates/` for product work. + +Every product `lib.rs`/`mod.rs` has at most **200 physical lines**. These files +contain attributes, declarations, imports/reexports, API docs and thin forwarding. +Definitions, impls, state/constants encoding behavior, branching, loops, conversions, +validation, formatting and I/O belong in focused named implementation files. + +Split by responsibility before the ceiling: lookup, transactions, reconstruction, +placement and ownership, not numbered files or a renamed god module. Use ordinary +functions/concrete types; do not add a factory/interface per algorithm or a +service locator. Keep actual process/provider boundaries independently usable. +Do not minify, expand macros or add includes to evade size/ownership rules. + +Physical line ceilings differ from production LOC. Follow the root +[per-commit LOC policy](../AGENTS.md#production-loc-comparison-for-every-commit) +using exact parent/staged/committed trees and migration subtotals. Docs, tests, +fixtures, examples and tools do not contribute to production LOC. ## Failure, persistence and dependencies -- **One attempt** ([root rule](../AGENTS.md#4-code-build-and-docs)), including no - error-driven algorithm, backend or reference substitution and no guessed - recovery. Readiness waits and explicit cancellation have their own state - before an attempt and never permit replay after a failed or unknown - publication. Preserve definite-failure atomicity, original errors and exact - uncertain custody: no resend, rollback, deletion or success claim from an - unfenced read. An unsupported required platform or capability fails - explicitly, never as a silent no-op or fallback. -- **SQLite Stores are Disposable/WAL/OFF only**, on macOS and Linux - ([profile](../AGENTS.md#active-persistence-profile--owner-direction-2026-10-07)); - select it explicitly, never by default argument. Disposable claims - process-crash survival only. Open verifies WAL and never converts an existing - Store; select profile and layout before open. WAL stays on throughout Init - and Commit (owner supersession 2026-10-07): no private MEMORY import or - journal promotion. Checkpointing is described on the - [SQLite page](../docs/architecture/engine/store/sqlite.md#checkpoints) - (owner approval 2026-11-07; Durable keeps `wal_autocheckpoint=1000`); a - non-WAL journal was measured and refused - because it broke concurrent sessions and other processes. The measured host - Init regression is retained as FAIL and accepted as the baseline for that - scope. A PostgreSQL Store has no profile; its write setting is - `synchronous_commit` ([PostgreSQL](../docs/architecture/engine/store/postgresql.md)). -- **Seal** consumes sole ownership, checkpoints, closes and verifies one file. +- One attempted operation; no automatic retry, busy handler, refresh/reprepare, + error-driven algorithm/backend/reference substitution or guessed recovery. + Readiness waits and explicit cancellation have their own state before an + attempt; they do not permit replay after failed/unknown publication. +- Preserve definite-failure atomicity, original errors and exact uncertain + custody. No resend, rollback/delete or success claim based on an unfenced read. +- Global Persistence uses **Disposable/WAL/OFF only**, on macOS and Linux, + under the [owner's active-profile rule](../AGENTS.md#active-persistence-profile--owner-direction-2026-10-07). + Durable execution is disabled indefinitely until explicit owner reauthorization; + retained Durable source may compile but no test, diagnostic, measurement or + application invocation may execute it. Select Disposable explicitly rather than + relying on a default argument. Disposable claims process-crash survival only. + Open verifies WAL and never converts an + existing Store. Select profile/layout before open; Postgres stays unavailable. + Owner supersession2026-10-07 keeps WAL throughout Init and Commit; no private + MEMORY import or journal promotion remains. Owner approval, 2026-11-07: + Disposable runs `wal_autocheckpoint=0`; each writable Disposable session's + own checkpoint thread copies a log past 4 MiB with + `wal_checkpoint(PASSIVE)` on a second SQLite connection, off the commit + path. Durable keeps `wal_autocheckpoint=1000`. A non-WAL journal was + measured and refused: it broke concurrent sessions and other processes. The measured host Init regression + is retained as FAIL and accepted as the new baseline for that exact scope. + Host seal consumes sole ownership, checkpoints, closes and verifies one file. Its macOS completion releases unused extents beyond logical EOF through the - existing safe nix API, keeping the file's bytes and identity; it restores no - per-pack preallocation or allocation owner and never runs on a live shared - daemon Store ([seal boundary](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/60-shared-store-foundation.md)). -- **Writers:** several processes open the same Store directly, with no host in - the data path ([routes](../AGENTS.md#where-calls-run)). One Commit runs at a - time per Workspace; Commits on different Workspaces may run concurrently - (owner, 2026-10-12). Bounded before-effect admission queues SQL work within - a Session and coordinates short writer jobs on the Store's parent-directory - inode, on Linux and macOS (#647), so separate writers queue instead of - meeting SQLite's Busy; only an uncoordinated raw SQLite process still meets - the exact Busy refusal. Store files in one directory share this lane. It - gates no whole Save or Commit and replays no failed SQL attempt. Never open - and close a separate main, WAL or SHM descriptor for advisory ownership: - closing a main-file descriptor can cancel SQLite's own POSIX locks. Keep the - admission, lock and publication lane, and shorten what runs inside the lane - ([one writer, short holds](../AGENTS.md#where-calls-run)). Do not extend the - host-mediated SDK runtime, Bridge data codec or daemon upstream. -- **The daemon overlay is a separate profile:** one MEMORY/OFF/EXCLUSIVE - database file per mounted Workspace, opened by one connection behind that - Workspace's lock, sharing no connection, page cache or memory budget. It is - not a distributed Store; reader-pool alternatives need their own proofs. -- **Durability claims:** WAL and sync are permitted for a declared global Store - profile. Add no `fsync`/`fdatasync`/`sync_data`/`sync_all` on disposable - Workspace backing; claim only actual completion and durability contracts. -- **Dependencies:** no third-party patch, fork, vendor, registry edit or - replacement dependency except the [fuser Git fork](#fuser-git-source); use - existing capabilities and locked builds, and report an incompatible required - dependency with source evidence. + existing safe nix API, preserving the original file's bytes and identity. + This narrow seal-only correction does not restore per-pack preallocation or + the allocation owner, and is never invoked on a live shared daemon Store; see + the [seal boundary](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/60-shared-store-foundation.md). + See the [foundation checkpoint](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/PRE-S8-F1-F4-20261007.md). +- Target (owner direction 2026-10-07): the same Store opened directly by every + Linux daemon from a shared volume, several writer processes, no host in the + data path, using only Disposable/WAL/OFF. A contended + write still has one SQL attempt and exact failure/unknown custody. Owner + clarification2026-10-12 requires one ongoing Commit per Workspace and allows + concurrent Commits on different Workspaces. Bounded before-effect admission + now queues SQL work within a Session and coordinates short Linux writer jobs + on the existing local Store parent-directory inode; multiple Store files in + one directory share this coarse short-transaction lane. Do not open/close a + separate main/WAL/SHM descriptor for advisory ownership: closing a main-file + descriptor can cancel SQLite's own process POSIX locks. This admission does + not gate whole Saves or Commits or replay + a failed SQL attempt. macOS holds the same parent-directory lane as Linux, + over the same short writer jobs and its writable opens (#647), so separate + macOS writers queue instead of meeting SQLite's Busy; only a writer that + bypasses the lane (an uncoordinated raw SQLite process) retains the exact + Busy refusal. Follow the + [integration contract](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/303/06-cluster-one-integration.md) and its + [deepest-file plan](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/SERVERLESS-STORE-PLAN-20261007.md); do not + extend the host-mediated SDK runtime, Bridge data codec or daemon upstream. +- Store concurrency (owner decision 2026-10-18): one global database and one + writer at a time are the design, not a limitation to engineer around. Keep + the existing admission, directory lock and publication lane; shorten what + runs inside the lane (only head check, merge and publish) instead of adding + writers or databases. Judge speed on uncontended calls; contention must stay + correct, bounded and exact. See the + [Store concurrency model](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/architecture/83-store-concurrency-model.md). +- The daemon overlay is a separate owner/profile from global persistence: + one local database file per mounted Workspace, opened MEMORY/OFF/EXCLUSIVE by + one connection behind that Workspace's lock. Workspaces share no overlay + connection, page cache or memory budget. It is not an implemented distributed Store or a universal + global-Store rule; reader-pool alternatives need their own proofs. +- WAL/sync are permitted for a declared global Store profile. Do not add + fsync/fdatasync/sync_data/sync_all on disposable Workspace backing. Memory + hints do not prove bounds. Claim only actual completion/durability contracts. +- No third-party patch, fork, vendor, registry edit or replacement dependency, + except the owner's pinned [fuser Git fork](#fuser-git-source) below. + Use existing capabilities and locked builds; report an incompatible required + dependency with source evidence. Unsupported required platforms/capabilities + fail explicitly, not via a silent no-op or fallback. ## Checks and completion -For product, API, manifest or runtime-source changes, run from the repository -root with the root manifest: +Run commands from the repository root with the root workspace manifest. For product, +API, manifest or runtime-source changes, cover tests/examples, warning-denying +Clippy and formatting, plus the boundary guard and its self-tests: ```sh cargo +1.85.1 test --locked --all-targets --no-run @@ -287,77 +498,109 @@ python3 -B tools/check_product_boundary.py python3 -B -m unittest discover -s tools -p 'test_*.py' ``` -- **With the [worktree launcher](../docs/general/parallel-worktrees.md)**, run - the same checks per package through `tools/worktree.py cargo` (it refuses - workspace aggregates): tests on Linux where they need a Linux Store or - mount, Clippy on macOS when the Linux build image has none. -- **A bug fix** adds a test that fails on the parent commit and passes on the - fix; run it once against the parent's source and report the result. -- **Run once, at final identity:** the required covering checks; diagnose a - failure from its output and source before a justified repair and rerun. Do - not repeat unchanged passing checks or run an unrelated legacy sweep. For - tooling or harness changes, run the owning scoped tests. For docs-only - changes, check links, anchors, status, claims and whitespace, and say why - Rust checks do not apply. -- **The guard is not a proof.** It checks source text, line caps and common - prohibited constructs (including markers in comments and strings), not Rust - semantics or runtime. Review macros, helpers, dependency and target - declarations and generated inputs; extend scanners for new shipped formats. - A package left out of the workspace is not exercised by passing tests. -- **Test lanes:** [tools/ci_tests.py](../tools/ci_tests.py). Update its `SLOW` - list when a test target is renamed, moved or measured at 5 s or more; - Linux-only daemon targets and the named API mount targets go to the nightly - mount lane. Do not disable discovery. Report exact checks, failures and - gaps; a scan or proposal alone establishes no implementation. -- **Build flags are part of the check.** aarch64 binaries keep the repository - ARMv8 AEAD inputs (`--cfg aes_armv8 --cfg polyval_armv8 --cfg - chacha20_force_neon -C target-feature=+aes,+sha2`). The - [root Cargo config](../.cargo/config.toml) is found from the working - directory, whatever manifest is selected; builds outside the repository or - with explicit RUSTFLAGS repeat the profile. Record flags and config in build - identities; keep the transport's required-profile refusal. A docs build - proves no binary profile. -- **Measurements** also follow the - [measurement workflow](../docs/general/agent-measurement-policy.md) and the - [owning harness guide](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark/blob/main/fs-bench-pro/AGENTS.md); - frozen identities, cache states and budgets are evidence contracts, not - product limits. +Every test invocation obeys the repository's +[2-minute test ceiling](../AGENTS.md#4-code-build-and-docs): run it under an +explicit timeout of at most 120 s, per package when the whole suite cannot fit, +and treat reaching the ceiling as a hang to diagnose, not a run to wait for. + +Migrations and refactors follow the root +[delete-rather-than-nurse rule](../AGENTS.md#4-code-build-and-docs): delete a +test that is tricky to adapt, keep or move only cheap tests of surviving +behaviour, and re-cover any still-valid fix or contract on the new code. +fs-bench-pro (in layerfs-benchmark) is frozen and left broken (owner, 2026-10-18): +do not build, run, check or repair it. + +For docs-only changes, check links/anchors, status/claim accuracy and whitespace; +report why Rust/runtime checks are inapplicable. For tooling/harness changes run +the owning scoped tests. At final implementation identity run required covering +checks once; diagnose a failure from its output/source before a justified repair +and rerun. Do not repeat unchanged passing checks or run an unrelated legacy sweep. + +The guard checks source text, line caps and common prohibited constructs, +including markers embedded in source comments/strings. It is not a Rust semantic +or runtime proof. Review ordinary macros, helpers, dependency/target declarations +and generated inputs; extend scanners for new shipped formats. An excluded +FUSE/daemon package is not exercised by passing active-workspace tests. + +CI reports after a push and never gates it (see the +[root rule](../AGENTS.md#4-code-build-and-docs)); test lane selection is +[tools/ci_tests.py](../tools/ci_tests.py). When a test target is renamed, moved or +measured at 5 s or more, update its `SLOW` list; Linux-only daemon targets and the named API mount targets go to +the nightly mount lane. There is no pre-push gate; +`tools/preflight.sh` is retired. Do not disable discovery or recreate an +equivalent wrapper. Report exact checks, failures and gaps. A scan or proposal +alone does not establish implementation. + +### Build flags are part of the check + +aarch64 binaries retain the repository ARMv8 AEAD build inputs: +`--cfg aes_armv8 --cfg polyval_armv8 --cfg chacha20_force_neon +-C target-feature=+aes,+sha2`. +The [root Cargo config](../.cargo/config.toml) is discovered from the working +directory, independently of the selected manifest. Builds outside the repository or +with explicit RUSTFLAGS must repeat that profile. Record flags/config in build +identities; preserve the transport's required-profile refusal when integrating +it. Documentation builds do not prove the binary profile. + +Measurement work additionally follows the +[agent measurement workflow](../docs/general/agent-measurement-policy.md) and +[owning core harness guide](https://github.com/Ephemeral-AI-Lab/layerfs-benchmark/blob/main/fs-bench-pro/AGENTS.md). Frozen identities, +cache states and budgets are evidence contracts, not product runtime limits. ### Fuser Git source -Owner direction 2026-11-15 (superseding the crates.io-only and local-patch -rules): use [Ephemeral-AI-Lab/fuser](https://github.com/Ephemeral-AI-Lab/fuser) -directly as a Git dependency at revision -`7393bca050fcbd0ed2a03f7e79bec0f8bd9755c4` (package 0.18.0), kept reachable by -the fork's tag `v0.18.0-layerfs.1`. - -- The fork owns its timestamp correction, observable receive-loop lifecycle and - negotiated receive buffers, maintained in that repository with its tests, - never as a second copy or local patch here. Its rulesets forbid deleting or - force-pushing `fuser-0.18.0` and moving or deleting `v*-layerfs.*` tags; tag - every new pinned revision the same way. -- Keep the full `rev` in `layerfs-fuse/Cargo.toml` and the matching Git source - and commit in the root lockfile. No floating branch or tag, registry - fallback, `[patch]`, `[replace]` or local vendored fuser; fail explicitly when - the source is unavailable. The boundary guard refuses any other source, an - override and a lock entry that differs from the manifest; it does not check - the fork's code. -- A revision change updates the manifest, lockfile and - [FUSE architecture page](../docs/architecture/engine/kernel-routes/fuse.md#fuser-git-dependency) - together, needs owner approval ([code review policy](../docs/policy/code-review.md)) - and a fresh `tools/worktree.py prepare` in each worktree. -- Earlier pins, decisions, Docker acceptance and the Linux fractional - signed-minimum FAIL stay in - [the historical records](https://github.com/Ephemeral-AI-Lab/layerfs/tree/8cfb6e273470d0bb2a4ec5a9256fcf4972441eb5/engine/patches/fuser-0.18.0); - switching the dependency does not relabel that evidence. - -### Audited unsafe files - -Each crate below uses `deny(unsafe_code)` with exactly one allowed module; the -guard and its tests enforce the path, and no other FFI or dependency change is -authorized. - -| Crate | Allowed module | Why | -| --- | --- | --- | -| `layerfs-persistence` | `src/backend/sqlite/lifecycle/file_control.rs`, macOS only | sets and reads back `SQLITE_FCNTL_PERSIST_WAL` under sole seal ownership and on a live-Store snapshot's own new destination connection (#506); owner authorization 2026-10-07, "Approve the narrowly audited seal wrapper" ([decision](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/SEAL-PERSIST-WAL-DECISION-20261007.md)); no manual sidecar deletion | -| `layerfs-bridge` | `src/process/darwin.rs`, macOS only | `proc_pidinfo`, `proc_listallpids` and the `sysctl` boot id, each with its SAFETY comment; moved below the drivers by layerfs-project#112 (finding R10, accepted 2026-11-06, #101 M-3) | +Owner direction 2026-11-15 supersedes the earlier crates.io-only and local-patch +rules: use [Ephemeral-AI-Lab/fuser](https://github.com/Ephemeral-AI-Lab/fuser) +directly as a Git dependency. The selected revision is +`7393bca050fcbd0ed2a03f7e79bec0f8bd9755c4` (package version 0.18.0), kept +reachable by the fork's tag `v0.18.0-layerfs.1`. Repository rulesets on the fork +forbid deleting or force-pushing `fuser-0.18.0` and moving or deleting +`v*-layerfs.*` tags; tag every new pinned revision the same way. +The fork owns its timestamp correction, observable receive-loop lifecycle and +negotiated receive buffers. These changes are independent of LayerFS; maintain +them in that repository, not through a second copy or local patch here. + +Keep the full `rev` in `layerfs-fuse/Cargo.toml` and the matching Git source +and commit in the root lockfile. Do not use a floating branch/tag, a registry +fallback, `[patch]`, `[replace]` or a local vendored fuser. A revision change +updates the manifest, lockfile and the +[FUSE architecture page](../docs/architecture/engine/kernel-routes/fuse.md#fuser-git-dependency) +together, needs owner approval ([code review policy](../docs/policy/code-review.md)), +and needs a fresh `tools/worktree.py prepare` in each worktree before its offline +builds. Use locked builds; fail explicitly when the selected source is unavailable. + +The fork's own repository maintains its code and tests; LayerFS uses ordinary +locked dependency builds and integration tests. The boundary guard +(`tools/check_product_boundary.py`) refuses a fuser source other than the fork at +a full `rev`, a `[patch]`/`[replace]`/`paths` override and a lock entry that +differs from the manifest; it does not check the fork's code. The earlier source pins, owner decisions, +Docker acceptance and Linux fractional signed-minimum FAIL remain unchanged in +[the historical records](https://github.com/Ephemeral-AI-Lab/layerfs/tree/8cfb6e273470d0bb2a4ec5a9256fcf4972441eb5/engine/patches/fuser-0.18.0). +Switching the dependency does not relabel that evidence or extend its scope. + +### Authorized Persistence seal file control + +Owner authorization 2026-10-07: "Approve the narrowly audited seal wrapper". +The system macOS SQLite enables persistent WAL and otherwise leaves empty +sidecars after checked close. Persistence uses `deny(unsafe_code)` with one +allowed module, `src/backend/sqlite/lifecycle/file_control.rs`, compiled on macOS +only. It sets and reads back `SQLITE_FCNTL_PERSIST_WAL` under sole seal +ownership, and on a live-Store snapshot's own new destination connection (#506). +No other Persistence module may contain unsafe Rust; the guard and its tests +enforce the exact path. This does not authorize third-party patches, dependency +changes, manual sidecar deletion or other FFI. See the +[decision and diagnostic](https://github.com/Ephemeral-AI-Lab/layerfs/blob/af2ad92bce866b4e3e11365f016b12806828a53b/core/docs/issues/307/SEAL-PERSIST-WAL-DECISION-20261007.md). + +### Bridge process identity file + +The bridge holds the process facts the home and the Sandbox driver share +(`layerfs_bridge::process`), moved below the drivers by layerfs-project#112 +under review finding R10, which the owner accepted on 2026-11-06 (#101 M-3; +compute-plane-2.0 rule 5 and the §6.6 row: "move the process facts, with the +one audited macOS unsafe file and its guard entry, below the drivers"). The +bridge uses `deny(unsafe_code)` with one allowed module, +`src/process/darwin.rs`, compiled on macOS only: `proc_pidinfo`, +`proc_listallpids` and the `sysctl` boot id, each with its SAFETY comment, as +they were in the driver. No other bridge module may contain unsafe Rust; the +guard and its tests enforce the exact path. This authorizes no other FFI or +dependency change. diff --git a/engine/crates/layerfs-bridge/src/control.rs b/engine/crates/layerfs-bridge/src/control.rs index 44a2822f4b..a82f5e6572 100644 --- a/engine/crates/layerfs-bridge/src/control.rs +++ b/engine/crates/layerfs-bridge/src/control.rs @@ -181,7 +181,7 @@ pub use crate::control_sdk::{ }; pub use crate::control_types::{ Activity, Answer, Call, CleanupObservation, ControlCode, ControlRefusal, LocalObservation, - Reply, Request, WorkspaceStatus, WorkspaceToken, HISTORY_WINDOW, + MountPlace, Reply, Request, WorkspaceStatus, WorkspaceToken, HISTORY_WINDOW, }; pub use crate::control_unmount::{DirtyReport, UnmountControl}; diff --git a/engine/crates/layerfs-bridge/src/control_request.rs b/engine/crates/layerfs-bridge/src/control_request.rs index 5c18098636..f49f9efdac 100644 --- a/engine/crates/layerfs-bridge/src/control_request.rs +++ b/engine/crates/layerfs-bridge/src/control_request.rs @@ -1,6 +1,6 @@ //! One correlated bounded control request, never an immutable-content upload. use crate::{ - control::{Call, ControlError, Request, HISTORY_WINDOW}, + control::{Call, ControlError, MountPlace, Request, HISTORY_WINDOW}, control_history::*, wire::{Reader, Writer}, }; @@ -51,6 +51,28 @@ impl Call { out.blob(project.as_bytes())?; out.blob(branch.as_bytes())?; } + Request::MountPlaced { + workspace, + branch, + place, + } => { + out.byte(16)?; + out.put(&workspace.to_bytes())?; + out.put(&branch.to_bytes())?; + put_place(&mut out, place)?; + } + Request::MountNamedPlaced { + workspace, + project, + branch, + place, + } => { + out.byte(17)?; + out.put(&workspace.to_bytes())?; + out.blob(project.as_bytes())?; + out.blob(branch.as_bytes())?; + put_place(&mut out, place)?; + } Request::Sdk(value) => { out.byte(20)?; crate::control_sdk::put_call(&mut out, value)?; @@ -169,6 +191,17 @@ impl Call { project: input.text(NAME_FIELD)?, branch: input.text(NAME_FIELD)?, }, + 16 => Request::MountPlaced { + workspace: history(WorkspaceId::from_authority(input.array()?))?, + branch: history(BranchId::from_bytes(input.array()?))?, + place: place(&mut input)?, + }, + 17 => Request::MountNamedPlaced { + workspace: history(WorkspaceId::from_authority(input.array()?))?, + project: input.text(NAME_FIELD)?, + branch: input.text(NAME_FIELD)?, + place: place(&mut input)?, + }, 2 => Request::Commit(crate::control_merge::commit_control(&mut input)?), 20 => Request::Sdk(crate::control_sdk::call(&mut input)?), 3 => Request::Status(token(&mut input)?), @@ -225,6 +258,38 @@ impl Call { Ok(Self { id, request }) } } +/// Writes the known Sandbox and machine names of one placed mount. +fn put_place(out: &mut Writer, place: &MountPlace) -> Result<(), ControlError> { + let flags = u8::from(place.sandbox.is_some()) | (u8::from(place.machine.is_some()) << 1); + out.byte(flags)?; + if let Some(sandbox) = &place.sandbox { + out.blob(sandbox.as_bytes())?; + } + if let Some(machine) = &place.machine { + out.blob(machine.as_bytes())?; + } + Ok(()) +} + +/// Reads the known Sandbox and machine names of one placed mount. +fn place(input: &mut Reader<'_>) -> Result { + let flags = input.byte()?; + if flags & !0b11 != 0 { + return Err(ControlError("mount place")); + } + let sandbox = if flags & 1 != 0 { + Some(input.text(NAME_FIELD)?) + } else { + None + }; + let machine = if flags & 2 != 0 { + Some(input.text(NAME_FIELD)?) + } else { + None + }; + Ok(MountPlace { sandbox, machine }) +} + fn window(limit: u16) -> Result<(), ControlError> { if limit == 0 || limit > HISTORY_WINDOW { Err(ControlError("history processing window")) diff --git a/engine/crates/layerfs-bridge/src/control_types.rs b/engine/crates/layerfs-bridge/src/control_types.rs index 141beadc5d..c6d6e3aa00 100644 --- a/engine/crates/layerfs-bridge/src/control_types.rs +++ b/engine/crates/layerfs-bridge/src/control_types.rs @@ -13,6 +13,37 @@ pub struct WorkspaceToken { /// Original local namespace returned by the owner; never reused by this daemon. pub namespace: i64, } +/// The Sandbox and machine a mount belongs to, when the caller knows them. +/// The holder report of a live mount shows them beside its Workspace; a +/// caller that knows neither leaves both absent and the report keeps the +/// Workspace alone. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct MountPlace { + /// The Sandbox the mounting daemon serves, when known. + pub sandbox: Option, + /// The machine that Sandbox runs on, when known. + pub machine: Option, +} + +impl MountPlace { + /// The place a caller names, by the names it knows (`None` when not). + /// An empty name is no name: only a real one is reported. + #[must_use] + pub fn new(sandbox: Option<&str>, machine: Option<&str>) -> Self { + let known = |name: Option<&str>| name.filter(|name| !name.is_empty()).map(str::to_owned); + Self { + sandbox: known(sandbox), + machine: known(machine), + } + } + + /// True when either name is known: a mount then reports what it knows. + #[must_use] + pub fn known(&self) -> bool { + self.sandbox.is_some() || self.machine.is_some() + } +} + /// One explicitly requested control operation. #[derive(Clone, Debug, Eq, PartialEq)] pub enum Request { @@ -58,6 +89,28 @@ pub enum Request { /// The Branch's name in that project, as the caller gave it. branch: String, }, + /// [`Request::Mount`] whose caller knows the Sandbox and machine its + /// daemon serves: a live mount's holders then show all three. + MountPlaced { + /// New authority incarnation. + workspace: WorkspaceId, + /// Selected Branch. + branch: BranchId, + /// The Sandbox and machine the mount belongs to, as known. + place: MountPlace, + }, + /// [`Request::MountNamed`] whose caller knows the Sandbox and machine + /// its daemon serves. + MountNamedPlaced { + /// New authority incarnation. + workspace: WorkspaceId, + /// The project's name, as the caller gave it. + project: String, + /// The Branch's name in that project, as the caller gave it. + branch: String, + /// The Sandbox and machine the mount belongs to, as known. + place: MountPlace, + }, /// One SDK call answered by a value or a typed SDK refusal. Sdk(crate::control_sdk::SdkCall), /// Capture the published frontier, construct it in the daemon, merge it diff --git a/engine/crates/layerfs-bridge/tests/control_records.rs b/engine/crates/layerfs-bridge/tests/control_records.rs index a708864895..7b6aa9cad5 100644 --- a/engine/crates/layerfs-bridge/tests/control_records.rs +++ b/engine/crates/layerfs-bridge/tests/control_records.rs @@ -57,6 +57,19 @@ fn commands_are_bounded_exact_and_reject_every_truncated_prefix() { project: "project".into(), branch: "Not A Name".into(), }, + // #G4: a mount that knows where it runs travels with both names + Request::MountPlaced { + workspace: token.workspace, + branch: binding.branch.id, + place: MountPlace::new(Some("sbx-1"), Some("docker")), + }, + // a name the caller knows alone still travels exactly + Request::MountNamedPlaced { + workspace: token.workspace, + project: "project".into(), + branch: "work".into(), + place: MountPlace::new(None, Some("machine-1")), + }, Request::Commit(CommitControl { token, force: false, diff --git a/engine/crates/layerfs-daemon/src/application/diagnostics.rs b/engine/crates/layerfs-daemon/src/application/diagnostics.rs index 6df30ad60c..68a1af0b41 100644 --- a/engine/crates/layerfs-daemon/src/application/diagnostics.rs +++ b/engine/crates/layerfs-daemon/src/application/diagnostics.rs @@ -397,5 +397,7 @@ fn operation_code(operation: &Request) -> u64 { Request::Cleanup(_) => 13, Request::Sdk(_) => 15, Request::MountNamed { .. } => 16, + Request::MountPlaced { .. } => 17, + Request::MountNamedPlaced { .. } => 18, } } diff --git a/engine/crates/layerfs-daemon/src/application/retained.rs b/engine/crates/layerfs-daemon/src/application/retained.rs index ff7011dd4d..75e24e72fc 100644 --- a/engine/crates/layerfs-daemon/src/application/retained.rs +++ b/engine/crates/layerfs-daemon/src/application/retained.rs @@ -278,6 +278,8 @@ fn kind(request: &layerfs_bridge::control::Request) -> &'static str { match request { Request::Mount { .. } => "mount", Request::MountNamed { .. } => "mount", + Request::MountPlaced { .. } => "mount", + Request::MountNamedPlaced { .. } => "mount", Request::Commit(_) => "commit", Request::Status(_) => "status", Request::Unmount(_) => "unmount", diff --git a/engine/crates/layerfs-daemon/src/control/failure.rs b/engine/crates/layerfs-daemon/src/control/failure.rs index ba948b0207..01730e05e1 100644 --- a/engine/crates/layerfs-daemon/src/control/failure.rs +++ b/engine/crates/layerfs-daemon/src/control/failure.rs @@ -159,6 +159,8 @@ impl Failure { fn history(error: &HistoryError) -> (ControlCode, Option) { match error.cause() { HistoryError::Busy => (ControlCode::Busy, None), + HistoryError::MountsActive(_) | HistoryError::BusyOp(_) => (ControlCode::Busy, None), + HistoryError::Unresolved(_) => (ControlCode::Unknown, None), HistoryError::HeadMoved(value) => (ControlCode::HeadMoved, Some(**value)), HistoryError::UnknownOutcome => (ControlCode::Unknown, None), HistoryError::Missing(_) => (ControlCode::Missing, None), diff --git a/engine/crates/layerfs-daemon/src/control/operations.rs b/engine/crates/layerfs-daemon/src/control/operations.rs index 394d64e5e2..8188165975 100644 --- a/engine/crates/layerfs-daemon/src/control/operations.rs +++ b/engine/crates/layerfs-daemon/src/control/operations.rs @@ -9,7 +9,7 @@ use crate::store::{ CommitError, CommitFailure, CommitOptions, CommitSuccess, NamedBindRequest, }; use layerfs_bridge::control::{ - Activity, ConflictReport, ControlCode, MergedCommit, Reply, Request, WorkspaceToken, + Activity, ConflictReport, ControlCode, MergedCommit, MountPlace, Reply, Request, WorkspaceToken, }; use layerfs_content::filesystem::FilesystemRootId; use layerfs_content::merge::{Conflict, ConflictKind}; @@ -102,9 +102,20 @@ impl Service { workspace: *workspace, branch: *branch, }; - self.mount(BindIntent::Id(request), timing) + self.mount(BindIntent::Id(request), MountPlace::default(), timing) }) } + Request::MountPlaced { + workspace, + branch, + place, + } => crate::telemetry::timed("sandbox.mount.bind", |timing| { + let request = BindRequest { + workspace: *workspace, + branch: *branch, + }; + self.mount(BindIntent::Id(request), place.clone(), timing) + }), Request::MountNamed { workspace, project, @@ -115,7 +126,20 @@ impl Service { project: project.clone(), branch: branch.clone(), }; - self.mount(BindIntent::Named(request), timing) + self.mount(BindIntent::Named(request), MountPlace::default(), timing) + }), + Request::MountNamedPlaced { + workspace, + project, + branch, + place, + } => crate::telemetry::timed("sandbox.mount.bind", |timing| { + let request = NamedBindRequest { + workspace: *workspace, + project: project.clone(), + branch: branch.clone(), + }; + self.mount(BindIntent::Named(request), place.clone(), timing) }), Request::Status(token) => self.status(*token), Request::Cleanup(token) => self.cleanup(*token), @@ -146,6 +170,7 @@ impl Service { pub(crate) fn mount( &self, intent: BindIntent, + place: MountPlace, timing: &layerfs_telemetry::timer::TimingScope<'_, layerfs_telemetry::timer::Active>, ) -> Result { let workspace = intent.workspace(); @@ -177,8 +202,11 @@ impl Service { entries.insert(workspace, Entry::Binding); } let bound = match crate::telemetry::phase(timing, "store.bind", || match intent { - BindIntent::Id(request) => self.store.bind(self.owner.clone(), request), - BindIntent::Named(request) => self.store.bind_named(self.owner.clone(), request), + BindIntent::Id(request) => self.store.bind_placed(self.owner.clone(), request, place), + BindIntent::Named(request) => { + self.store + .bind_named_placed(self.owner.clone(), request, place) + } }) { Ok(value) => value, Err(value) => { diff --git a/engine/crates/layerfs-daemon/src/control/unmount.rs b/engine/crates/layerfs-daemon/src/control/unmount.rs index 10b5dd4322..84352a6fdf 100644 --- a/engine/crates/layerfs-daemon/src/control/unmount.rs +++ b/engine/crates/layerfs-daemon/src/control/unmount.rs @@ -150,6 +150,7 @@ impl Service { Err(error) => { let failure = match error { crate::store::CloseError::Owner(cause) => Failure::Owner(cause), + crate::store::CloseError::Intent(cause) => Failure::History(cause), crate::store::CloseError::Reader(cause) => Failure::Workspace( layerfs_workspace::WorkspaceError::Service(Box::new(cause)), ), diff --git a/engine/crates/layerfs-daemon/src/operator/mod.rs b/engine/crates/layerfs-daemon/src/operator/mod.rs index 9aead7c370..7408c42927 100644 --- a/engine/crates/layerfs-daemon/src/operator/mod.rs +++ b/engine/crates/layerfs-daemon/src/operator/mod.rs @@ -5,3 +5,9 @@ pub(crate) use dispatch::{admits, dispatch}; pub(crate) use layerfs_store_service::operator::{snapshot, WorkspaceView}; mod workspace; + +/// The installed Store fixture the operator unit test binds without a kernel. +#[cfg(test)] +#[allow(dead_code)] +#[path = "../../tests/support/installed_store.rs"] +mod installed_store; diff --git a/engine/crates/layerfs-daemon/src/operator/workspace.rs b/engine/crates/layerfs-daemon/src/operator/workspace.rs index ad7218a6c2..536cb89986 100644 --- a/engine/crates/layerfs-daemon/src/operator/workspace.rs +++ b/engine/crates/layerfs-daemon/src/operator/workspace.rs @@ -5,13 +5,16 @@ use crate::{ }; use layerfs_bridge::control::{SdkRefusal, SdkValue}; use layerfs_content::{ - compare::TreeTable, filesystem::FilesystemRootId, object::inode_leaf::InodeKind, + compare::{EntryFacts, TreeTable}, + filesystem::FilesystemRootId, + object::inode_leaf::InodeKind, }; use layerfs_store_service::{ history::lookup::{self as args, Answer}, operator::args::{paging, text}, read::{ snapshot::{self, Kind, Snap}, + visibility::Visibility, window::Walker, }, }; @@ -80,6 +83,46 @@ impl<'a> Live<'a> { } Ok(None) } + + /// The next live entry that is visible at the base node. A path the markers + /// hide is absent unless the overlay holds a local inode there: a + /// re-creation after the bound node is an ordinary addition, as a Commit's + /// is, while an inherited entry of a mount older than the marker is hidden. + fn next_visible(&mut self, seen: &Visibility) -> Result> { + loop { + let Some((path, stat)) = self.next()? else { + return Ok(None); + }; + if seen.hidden(&path).is_some() + && self + .op + .overlay() + .inode(self.view.source(), stat.serial) + .map_err(args::failed)? + .is_none() + { + continue; + } + return Ok(Some((path, stat))); + } + } +} + +/// The base walk, less every path the markers hide at the base node: a removed +/// path is absent from `changes`, like a read of it, and so is its subtree. +struct VisibleBase<'a> { + walker: Walker<'a>, + seen: &'a Visibility, +} +impl VisibleBase<'_> { + fn next(&mut self) -> Result> { + loop { + match self.walker.next()? { + Some((path, _)) if self.seen.hidden(&path).is_some() => continue, + other => return Ok(other), + } + } + } } fn selected(service: &Service, args: &SdkValue) -> Result> { @@ -155,24 +198,43 @@ fn scan( ) -> Result<()> { let binding = workspace.snapshot().map_err(args::failed)?; let root = binding.effective_root; + let node = binding.branch.head_commit.map_or( + layerfs_history::NodeId::Layer(binding.branch.base_layer), + layerfs_history::NodeId::Commit, + ); + // The base node `history_serial`, as every `Snap` carries it for the + // `remove_file` visibility rule; 0 is the same unknown fallback that + // `snapshot::resolve` takes. + let serial = match service + .store + .published(|history| history.node_history_serial(node)) + { + Ok(Some(serial)) => serial, + _ => 0, + }; let snap = Snap { kind: Kind::Commit, label: "Workspace base".into(), - node: binding.branch.head_commit.map_or( - layerfs_history::NodeId::Layer(binding.branch.base_layer), - layerfs_history::NodeId::Commit, - ), + node, root, tree: TreeTable::open(op.ports(), FilesystemRootId(root)).map_err(args::content)?, + serial, }; let pending = workspace .pending_conflicts() .map_err(args::failed)? .unwrap_or_default(); - let mut base = Walker::new(op.ports(), &snap, "/")?; + // §4.3: the base walk is path-aware, so a path the markers hide at the + // base node is absent from `changes` instead of a `Removed` row against + // the mount's whiteout. The live side keeps a local re-creation. + let seen = Visibility::for_snap(&service.store, &snap); + let mut base = VisibleBase { + walker: Walker::new(op.ports(), &snap, "/")?, + seen: &seen, + }; let mut live = Live::new(view, op); let mut work = layerfs_content::filesystem::attributes::AttributeReadWork::default(); - let (mut a, mut b) = (base.next()?, live.next()?); + let (mut a, mut b) = (base.next()?, live.next_visible(&seen)?); while a.is_some() || b.is_some() { let order = match (&a, &b) { (Some((a, _)), Some((b, _))) => a.split('/').cmp(b.split('/')), @@ -187,14 +249,14 @@ fn scan( } std::cmp::Ordering::Greater => { let (p, e) = b.take().expect("live"); - b = live.next()?; + b = live.next_visible(&seen)?; (p, None, Some(e)) } std::cmp::Ordering::Equal => { let (p, x) = a.take().expect("base"); let (_, y) = b.take().expect("live"); a = base.next()?; - b = live.next()?; + b = live.next_visible(&seen)?; (p, Some(x), Some(y)) } }; @@ -247,16 +309,20 @@ fn scan( break; } } - let _ = service; Ok(()) } pub(crate) fn changes(service: &Service, args: &SdkValue) -> Answer { let workspace = selected(service, args)?; + changes_of(service, &workspace, args) +} + +/// `changes` over an already selected Workspace; a test binds one directly. +fn changes_of(service: &Service, workspace: &BoundWorkspace, args: &SdkValue) -> Answer { let (limit, pos) = paging(args)?; - with_source(&workspace, |op, view| { + with_source(workspace, |op, view| { let (mut seen, mut items, mut spent, mut more) = (0u64, Vec::new(), 0, false); - scan(service, &workspace, op, view, |path, kind, markers| { + scan(service, workspace, op, view, |path, kind, markers| { if seen < pos { seen += 1; return Ok(true); @@ -305,3 +371,125 @@ pub(crate) fn overlay(service: &Service, args: &SdkValue) -> Answer { ("changes", SdkValue::Null), ])) } + +#[cfg(test)] +mod tests { + //! `workspace.changes` over a bound Workspace, without a kernel mount: the + //! path-awareness of its base walk. + use super::*; + use crate::control::Service; + use crate::{Owner, OwnerConfig}; + use layerfs_bridge::control::SdkValue; + use layerfs_history::{PathRemovalKind, PathRemovalRequest, WorkspaceId}; + use layerfs_storage::ReservationBlocks; + use layerfs_store_service::{ + bootstrap::open_store_observed, store::BindRequest, write::mutation::Mutation, + }; + use std::fs; + + use crate::operator::installed_store as installed; + + fn listed(answer: &SdkValue) -> Vec<(String, String)> { + let Some(SdkValue::List(items)) = answer.get("items") else { + panic!("no items: {answer:?}"); + }; + items + .iter() + .map(|item| { + ( + item.get_text("path").expect("path").to_owned(), + item.get_text("kind").expect("kind").to_owned(), + ) + }) + .collect() + } + + /// A file and a directory removed by `project.remove_file` markers at the + /// bound node are absent from `changes`, subtree and all; a visible + /// change is still listed, and a post-bound re-creation is an addition. + #[test] + fn a_removed_file_and_a_hidden_directory_are_absent_from_changes() { + let fixture = installed::Fixture::built("changes-visibility", |source| { + fs::write(source.join("visible.txt"), b"visible\n").unwrap(); + fs::write(source.join("hidden.txt"), b"hidden\n").unwrap(); + fs::create_dir(source.join("hidden-dir")).unwrap(); + fs::write(source.join("hidden-dir/inner.txt"), b"inner\n").unwrap(); + 4 + }); + let opened = open_store_observed( + fixture.config.clone(), + installed::BINDING, + installed::CURSOR, + 64, + 8 * 1024 * 1024, + ReservationBlocks::default(), + ) + .unwrap(); + let stack = opened + .store + .history() + .branch_snapshot(fixture.branch) + .unwrap() + .unwrap() + .branch + .stack; + for path in ["hidden.txt", "hidden-dir"] { + let outcome = opened + .store + .history() + .remove_path(&PathRemovalRequest { + stack, + path: path.as_bytes().to_vec(), + removed_ms: 1, + }) + .unwrap(); + assert_eq!(outcome.kind, PathRemovalKind::Removed, "{path}"); + } + let owner = Owner::start( + &fixture.directory.join("overlay.sqlite"), + layerfs_overlay::ProfileConfig::default(), + OwnerConfig::default(), + ) + .unwrap(); + let bound = opened + .store + .bind( + owner.client(), + BindRequest { + branch: fixture.branch, + workspace: WorkspaceId::from_authority([57; 32]).unwrap(), + }, + ) + .unwrap() + .workspace; + // Bind wrote the whiteouts; a visible change and one re-creation follow. + let mut mutation = Mutation::new(&bound).unwrap(); + mutation.write("/visible.txt", b"after\n", None).unwrap(); + mutation.finish().unwrap(); + let mut mutation = Mutation::new(&bound).unwrap(); + mutation.write("/hidden.txt", b"again\n", None).unwrap(); + mutation.finish().unwrap(); + + let service = Service::new(opened.store.clone(), &owner); + let answer = changes_of( + &service, + &bound, + &SdkValue::map([("pageSize", SdkValue::Int(50))]), + ) + .unwrap(); + assert_eq!( + listed(&answer), + [ + ("/hidden.txt".to_owned(), "Added".to_owned()), + ("/visible.txt".to_owned(), "Modified".to_owned()), + ] + ); + assert_eq!(answer.get("hasMore"), Some(&SdkValue::Bool(false))); + + drop(service); + bound.close().unwrap(); + owner.stop().unwrap(); + drop(opened); + fixture.cleanup(); + } +} diff --git a/engine/crates/layerfs-daemon/tests/mount_holders.rs b/engine/crates/layerfs-daemon/tests/mount_holders.rs new file mode 100644 index 0000000000..a04962a3bb --- /dev/null +++ b/engine/crates/layerfs-daemon/tests/mount_holders.rs @@ -0,0 +1,127 @@ +//! #G4: a daemon mount registers the Sandbox and machine beside its +//! Workspace, and a mount that knows neither still registers the Workspace +//! alone. `MountsActive` reports exactly what the intent placed. +#[allow(dead_code)] +#[path = "support/control_fixture.rs"] +mod fixture; +#[allow(dead_code)] +#[path = "support/host_install.rs"] +mod support; + +use layerfs_bridge::control::{MountPlace, Reply, Request, SdkValue, WorkspaceToken}; +use layerfs_history::{BranchId, ForkRequest, ForkSource, HistoryName, LayerStackId, WorkspaceId}; +use layerfs_store_service::history::{lookup, removal}; + +/// The fixture's Store with a `work` Branch forked from the project's head. +fn work(f: &fixture::Fixture) -> (LayerStackId, BranchId) { + let store = &f.installed.opened.store; + let stack = LayerStackId::from_authority([54; 16]); + let base = store + .history() + .layer_stack(stack) + .unwrap() + .unwrap() + .head_layer; + let branch = BranchId::from_authority([64; 16]); + store + .history() + .fork(&ForkRequest { + stack, + branch, + name: HistoryName::new("work").unwrap(), + source: ForkSource::Layer(base), + }) + .unwrap(); + (stack, branch) +} + +/// Executes one mount request and returns the bound token. +fn bound(f: &fixture::Fixture, request: Request) -> WorkspaceToken { + match f.service.execute_control(&request).unwrap().reply { + Reply::Bound { token, .. } => token, + other => panic!("{other:?}"), + } +} + +/// A `workspace.mount`-shaped named bind that knows its Sandbox and machine. +fn bind_named_placed(f: &fixture::Fixture, tag: u8, place: MountPlace) -> WorkspaceToken { + bound( + f, + Request::MountNamedPlaced { + workspace: WorkspaceId::from_authority([tag; 32]).unwrap(), + project: "project".to_owned(), + branch: "work".to_owned(), + place, + }, + ) +} + +/// A named bind whose caller knows neither the Sandbox nor the machine. +fn bind_named(f: &fixture::Fixture, tag: u8) -> WorkspaceToken { + bound( + f, + Request::MountNamed { + workspace: WorkspaceId::from_authority([tag; 32]).unwrap(), + project: "project".to_owned(), + branch: "work".to_owned(), + }, + ) +} + +fn unmount(f: &fixture::Fixture, token: WorkspaceToken) { + let reply = f + .service + .execute_control(&Request::Unmount(layerfs_bridge::control::UnmountControl { + token, + discard: true, + })) + .unwrap() + .reply; + assert_eq!(reply, Reply::Unmounted(token)); +} + +/// The one holder a live mount leaves in `MountsActive`. +fn holder(f: &fixture::Fixture, stack: &layerfs_history::LayerStackRecord) -> SdkValue { + let refused = removal::remove(&f.installed.opened.store, stack, "work") + .expect_err("the live mount refuses the removal"); + assert_eq!(refused.code, "MountsActive", "{refused:?}"); + let SdkValue::List(holders) = refused.detail.get("holders").expect("holders") else { + panic!("{refused:?}"); + }; + assert_eq!(holders.len(), 1, "{holders:?}"); + holders[0].clone() +} + +/// The fixture project's live stack record, as the removal names it. +fn stack(f: &fixture::Fixture) -> layerfs_history::LayerStackRecord { + lookup::project(&f.installed.opened.store, "project").expect("project") +} + +#[test] +fn a_placed_daemon_mount_registers_sandbox_machine_and_workspace() { + let f = fixture::Fixture::new("g4-mount-place"); + work(&f); + let token = bind_named_placed(&f, 7, MountPlace::new(Some("g4sbx"), Some("docker"))); + let holder = holder(&f, &stack(&f)); + assert_eq!(holder.get_text("kind"), Some("mount")); + assert_eq!(holder.get_text("sandbox"), Some("g4sbx")); + assert_eq!(holder.get_text("machine"), Some("docker")); + let workspace = layerfs_bridge::sdk_values::hex(&[7; 32]); + assert_eq!(holder.get_text("workspace"), Some(workspace.as_str())); + unmount(&f, token); + f.cleanup(); +} + +#[test] +fn a_mount_with_no_known_context_registers_the_workspace_alone() { + let f = fixture::Fixture::new("g4-mount-unknown"); + work(&f); + let token = bind_named(&f, 8); + let holder = holder(&f, &stack(&f)); + assert_eq!(holder.get_text("kind"), Some("mount")); + assert_eq!(holder.get_text("sandbox"), None); + assert_eq!(holder.get_text("machine"), None); + assert!(holder.get_text("workspace").is_some()); + unmount(&f, token); + f.cleanup(); +} diff --git a/engine/crates/layerfs-persistence/Cargo.toml b/engine/crates/layerfs-persistence/Cargo.toml index 090f56a2be..5502b2e1d8 100644 --- a/engine/crates/layerfs-persistence/Cargo.toml +++ b/engine/crates/layerfs-persistence/Cargo.toml @@ -7,6 +7,8 @@ rust-version.workspace = true license.workspace = true [dependencies] +# S8 advisory keys: blake3("layerfs/advisory/v1\0" || catalog_id || kind || id). +blake3 = { version = "=1.8.5", default-features = false } sha2 = "=0.11.0" layerfs-storage = { path = "../../../core/crates/layerfs-storage" } layerfs-history = { path = "../../../core/crates/layerfs-history", default-features = false } diff --git a/engine/crates/layerfs-persistence/sql/postgresql/gc.sql b/engine/crates/layerfs-persistence/sql/postgresql/gc.sql new file mode 100644 index 0000000000..b80cbe1420 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/gc.sql @@ -0,0 +1,84 @@ + +CREATE TABLE branch_retired ( + branch_id BYTEA PRIMARY KEY CHECK (length(branch_id) = 17), + removed_ms BIGINT NOT NULL CHECK (removed_ms >= 0), + FOREIGN KEY (branch_id) REFERENCES branch(branch_id) ON DELETE CASCADE +); +CREATE TABLE layer_stack_retired ( + layer_stack_id BYTEA PRIMARY KEY CHECK (length(layer_stack_id) = 17), + deleted_ms BIGINT NOT NULL CHECK (deleted_ms >= 0), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +); +CREATE TABLE path_removed ( + layer_stack_id BYTEA NOT NULL CHECK (length(layer_stack_id) = 17), + path_key BYTEA NOT NULL CHECK (length(path_key) = 32), + path BYTEA NOT NULL CHECK (length(path) BETWEEN 1 AND 4096), + frontier_serial BIGINT NOT NULL CHECK (frontier_serial >= 0), + removed_ms BIGINT NOT NULL CHECK (removed_ms >= 0), + PRIMARY KEY (layer_stack_id, path_key), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +); +CREATE TABLE project_epoch ( + layer_stack_id BYTEA PRIMARY KEY CHECK (length(layer_stack_id) = 17), + epoch BIGINT NOT NULL DEFAULT 0 CHECK (epoch >= 0), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +); +CREATE TABLE gc_intent ( + op_id BYTEA PRIMARY KEY CHECK (length(op_id) = 16), + kind TEXT NOT NULL CHECK (kind IN ('mount','init','merge','removal','compaction')), + scope_kind TEXT NOT NULL CHECK (scope_kind IN ('store','project','branch')), + scope_id BYTEA, + workspace TEXT, + sandbox TEXT, + machine TEXT, + project TEXT, + branch TEXT, + owner_runtime TEXT, + owner_boot TEXT, + state TEXT NOT NULL CHECK (state IN ('live','uncertain','done')), + uncertain BOOLEAN NOT NULL, + phase TEXT, + generation BIGINT, + artifact TEXT, + high_water BIGINT, + evidence TEXT, + updated_ms BIGINT NOT NULL, + UNIQUE (scope_kind, scope_id, owner_boot) +); +CREATE TABLE gc_op ( + id BIGINT PRIMARY KEY CHECK (id = 1), + generation BIGINT NOT NULL, + phase TEXT NOT NULL, + scratch_schema TEXT, + mark_serial BIGINT, + mark_pack_id BIGINT, + mark_digest BYTEA, + mark_totals BYTEA, + mark_stamp BIGINT, + started_ms BIGINT NOT NULL, + dead_canonical BIGINT NOT NULL DEFAULT 0, + dead_stored BIGINT NOT NULL DEFAULT 0, + dead_metadata BIGINT NOT NULL DEFAULT 0, + dead_logical BIGINT NOT NULL DEFAULT 0, + totals_applied BOOLEAN NOT NULL DEFAULT FALSE, + artifact TEXT, + pid BIGINT, + backend_start TEXT, + incarnation BIGINT +); +CREATE TABLE gc_dead ( + kind TEXT NOT NULL, + id BYTEA NOT NULL, + PRIMARY KEY (kind, id) +); +CREATE TABLE kept_node ( + layer_stack_id BYTEA NOT NULL CHECK (length(layer_stack_id) = 17), + kind TEXT NOT NULL CHECK (kind IN ('commit','layer','branch','stack')), + node_id BYTEA NOT NULL, + serial BIGINT NOT NULL DEFAULT 0 CHECK (serial >= 0), + PRIMARY KEY (layer_stack_id, kind, node_id), + CHECK ( + (kind IN ('commit','layer') AND length(node_id) = 33) + OR (kind IN ('branch','stack') AND length(node_id) = 17) + ) +); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot.sql index bb079ef25c..8a36f19368 100644 --- a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot.sql +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot.sql @@ -1 +1 @@ -SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM {s}.branch b LEFT JOIN {s}.layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN {s}.layer l ON l.layer_id = b.base_layer_id LEFT JOIN {s}."commit" c ON c.commit_id = b.head_commit_id WHERE b.branch_id = $1; +SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM {s}.branch b LEFT JOIN {s}.layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN {s}.layer l ON l.layer_id = b.base_layer_id LEFT JOIN {s}."commit" c ON c.commit_id = b.head_commit_id WHERE b.branch_id = $1 AND NOT EXISTS (SELECT 1 FROM {s}.branch_retired r WHERE r.branch_id = b.branch_id) AND NOT EXISTS (SELECT 1 FROM {s}.layer_stack_retired d WHERE d.layer_stack_id = b.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot_named.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot_named.sql index 8ff1a3808b..715134482e 100644 --- a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot_named.sql +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/branch_snapshot_named.sql @@ -1 +1 @@ -SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM {s}.layer_stack p LEFT JOIN {s}.branch b ON p.name = $1 AND b.layer_stack_id = p.layer_stack_id AND b.name = $2 LEFT JOIN {s}.layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN {s}.layer l ON l.layer_id = b.base_layer_id LEFT JOIN {s}."commit" c ON c.commit_id = b.head_commit_id WHERE p.name = $1; +SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM {s}.layer_stack p LEFT JOIN {s}.branch b ON p.name = $1 AND b.layer_stack_id = p.layer_stack_id AND b.name = $2 AND NOT EXISTS (SELECT 1 FROM {s}.branch_retired r WHERE r.branch_id = b.branch_id) LEFT JOIN {s}.layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN {s}.layer l ON l.layer_id = b.base_layer_id LEFT JOIN {s}."commit" c ON c.commit_id = b.head_commit_id WHERE p.name = $1 AND NOT EXISTS (SELECT 1 FROM {s}.layer_stack_retired d WHERE d.layer_stack_id = p.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_read.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_read.sql new file mode 100644 index 0000000000..67853fc6f2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_read.sql @@ -0,0 +1 @@ +SELECT epoch FROM project_epoch WHERE layer_stack_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_share.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_share.sql new file mode 100644 index 0000000000..e42a6762c2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_epoch_share.sql @@ -0,0 +1 @@ +SELECT epoch FROM project_epoch WHERE layer_stack_id = $1 FOR SHARE; diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_exclusive.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_exclusive.sql new file mode 100644 index 0000000000..255c909a83 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_exclusive.sql @@ -0,0 +1 @@ +SELECT 1 AS ok WHERE pg_try_advisory_lock($1::bigint); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_shared.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_shared.sql new file mode 100644 index 0000000000..12a63f9809 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_session_shared.sql @@ -0,0 +1 @@ +SELECT 1 AS ok WHERE pg_try_advisory_lock_shared($1::bigint); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_exclusive.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_exclusive.sql new file mode 100644 index 0000000000..b70b5de73b --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_exclusive.sql @@ -0,0 +1 @@ +SELECT 1 AS ok WHERE pg_try_advisory_xact_lock($1::bigint); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_shared.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_shared.sql new file mode 100644 index 0000000000..5844d19a06 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_lock_xact_shared.sql @@ -0,0 +1 @@ +SELECT 1 AS ok WHERE pg_try_advisory_xact_lock_shared($1::bigint); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_exclusive.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_exclusive.sql new file mode 100644 index 0000000000..36e9fa061a --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_exclusive.sql @@ -0,0 +1 @@ +SELECT pg_advisory_unlock($1::bigint) AS ok; diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_shared.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_shared.sql new file mode 100644 index 0000000000..a3fdbed9f2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/gc_unlock_session_shared.sql @@ -0,0 +1 @@ +SELECT pg_advisory_unlock_shared($1::bigint) AS ok; diff --git a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/layerstack_stack_by_name.sql b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/layerstack_stack_by_name.sql index cc5cfea883..263f881223 100644 --- a/engine/crates/layerfs-persistence/sql/postgresql/queries/history/layerstack_stack_by_name.sql +++ b/engine/crates/layerfs-persistence/sql/postgresql/queries/history/layerstack_stack_by_name.sql @@ -1 +1 @@ -SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM {s}.layer_stack WHERE name = $1; +SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM {s}.layer_stack WHERE name = $1 AND NOT EXISTS (SELECT 1 FROM {s}.layer_stack_retired r WHERE r.layer_stack_id = {s}.layer_stack.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/postgresql/schema.sql b/engine/crates/layerfs-persistence/sql/postgresql/schema.sql index 5b15c1bb69..d007e98f17 100644 --- a/engine/crates/layerfs-persistence/sql/postgresql/schema.sql +++ b/engine/crates/layerfs-persistence/sql/postgresql/schema.sql @@ -11,7 +11,8 @@ CREATE TABLE store_policy ( chunk_delta_max_depth bigint NOT NULL CHECK (chunk_delta_max_depth BETWEEN 0 AND 50), metadata_delta_max_depth bigint NOT NULL CHECK (metadata_delta_max_depth BETWEEN 0 AND 50), next_pack_id bigint NOT NULL DEFAULT 1 CHECK (next_pack_id > 0), - next_ordinal bigint NOT NULL DEFAULT 1 CHECK (next_ordinal BETWEEN 1 AND 4294967296) + next_ordinal bigint NOT NULL DEFAULT 1 CHECK (next_ordinal BETWEEN 1 AND 4294967296), + trace_salt bytea NOT NULL DEFAULT decode(repeat('00',32),'hex') CHECK (length(trace_salt)=32) ); CREATE TABLE pack ( pack_id bigint PRIMARY KEY CHECK (pack_id > 0), @@ -70,6 +71,7 @@ CREATE TABLE history_meta ( binding_key bytea NOT NULL CHECK (octet_length(binding_key) BETWEEN 1 AND 128), identity_format bigint NOT NULL CHECK (identity_format = 3), schema_version bigint NOT NULL CHECK (schema_version = 2), + next_history_serial bigint NOT NULL DEFAULT 1, schema_source text NOT NULL, schema_definition text NOT NULL ); @@ -96,6 +98,7 @@ CREATE TABLE layer ( overwrote bytea NOT NULL, source_commit_id bytea CHECK (source_commit_id IS NULL OR (octet_length(source_commit_id) = 33 AND get_byte(source_commit_id, 0) = 18)), + history_serial bigint NOT NULL DEFAULT 0, CHECK ( (parent_layer_id IS NULL AND source_branch_id IS NULL AND source_commit_id IS NULL) OR (parent_layer_id IS NOT NULL AND source_branch_id IS NOT NULL AND source_commit_id IS NOT NULL) @@ -126,6 +129,7 @@ CREATE TABLE "commit" ( new_metadata bigint NOT NULL DEFAULT 0 CHECK (new_metadata >= 0), lww bytea NOT NULL, displaced_id bytea CHECK (displaced_id IS NULL OR octet_length(displaced_id) = 33), + history_serial bigint NOT NULL DEFAULT 0, UNIQUE (layer_stack_id, commit_id) ); CREATE TABLE branch ( diff --git a/engine/crates/layerfs-persistence/sql/sqlite/gc.sql b/engine/crates/layerfs-persistence/sql/sqlite/gc.sql new file mode 100644 index 0000000000..ee565544b9 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/gc.sql @@ -0,0 +1,96 @@ +CREATE TABLE branch_retired ( + branch_id BLOB PRIMARY KEY + CHECK (length(branch_id) = 17 AND substr(branch_id, 1, 1) = X'11'), + removed_ms INTEGER NOT NULL CHECK (removed_ms >= 0), + FOREIGN KEY (branch_id) REFERENCES branch(branch_id) ON DELETE CASCADE +) STRICT, WITHOUT ROWID; + +CREATE TABLE layer_stack_retired ( + layer_stack_id BLOB PRIMARY KEY + CHECK (length(layer_stack_id) = 17 AND substr(layer_stack_id, 1, 1) = X'31'), + deleted_ms INTEGER NOT NULL CHECK (deleted_ms >= 0), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +) STRICT, WITHOUT ROWID; + +CREATE TABLE path_removed ( + layer_stack_id BLOB NOT NULL + CHECK (length(layer_stack_id) = 17 AND substr(layer_stack_id, 1, 1) = X'31'), + path_key BLOB NOT NULL CHECK (length(path_key) = 32), + path BLOB NOT NULL CHECK (length(path) BETWEEN 1 AND 4096), + frontier_serial INTEGER NOT NULL CHECK (frontier_serial >= 0), + removed_ms INTEGER NOT NULL CHECK (removed_ms >= 0), + PRIMARY KEY (layer_stack_id, path_key), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +) STRICT, WITHOUT ROWID; + +CREATE TABLE project_epoch ( + layer_stack_id BLOB PRIMARY KEY + CHECK (length(layer_stack_id) = 17 AND substr(layer_stack_id, 1, 1) = X'31'), + epoch INTEGER NOT NULL DEFAULT 0 CHECK (epoch >= 0), + FOREIGN KEY (layer_stack_id) REFERENCES layer_stack(layer_stack_id) ON DELETE CASCADE +) STRICT, WITHOUT ROWID; + +CREATE TABLE gc_intent ( + op_id BLOB PRIMARY KEY CHECK (length(op_id) = 16), + kind TEXT NOT NULL CHECK (kind IN ('mount','init','merge','removal','compaction')), + scope_kind TEXT NOT NULL CHECK (scope_kind IN ('store','project','branch')), + scope_id BLOB, + workspace TEXT, + sandbox TEXT, + machine TEXT, + project TEXT, + branch TEXT, + owner_runtime TEXT, + owner_boot TEXT, + state TEXT NOT NULL CHECK (state IN ('live','uncertain','done')), + uncertain INTEGER NOT NULL CHECK (uncertain IN (0,1)), + phase TEXT, + generation INTEGER, + artifact TEXT, + high_water INTEGER, + evidence TEXT, + updated_ms INTEGER NOT NULL, + UNIQUE (scope_kind, scope_id, owner_boot) +) STRICT; + +CREATE TABLE gc_op ( + id INTEGER PRIMARY KEY CHECK (id = 1), + generation INTEGER NOT NULL, + phase TEXT NOT NULL, + scratch_schema TEXT, + mark_serial INTEGER, + mark_pack_id INTEGER, + mark_digest BLOB, + mark_totals BLOB, + mark_stamp INTEGER, + started_ms INTEGER NOT NULL, + dead_canonical INTEGER NOT NULL DEFAULT 0, + dead_stored INTEGER NOT NULL DEFAULT 0, + dead_metadata INTEGER NOT NULL DEFAULT 0, + dead_logical INTEGER NOT NULL DEFAULT 0, + totals_applied INTEGER NOT NULL DEFAULT 0, + artifact TEXT, + pid INTEGER, + backend_start TEXT, + incarnation INTEGER +) STRICT; + +CREATE TABLE gc_dead ( + kind TEXT NOT NULL, + id BLOB NOT NULL, + PRIMARY KEY (kind, id) +) STRICT, WITHOUT ROWID; +CREATE TABLE kept_node ( + layer_stack_id BLOB NOT NULL + CHECK (length(layer_stack_id) = 17 AND substr(layer_stack_id, 1, 1) = X'31'), + kind TEXT NOT NULL CHECK (kind IN ('commit','layer','branch','stack')), + node_id BLOB NOT NULL, + serial INTEGER NOT NULL DEFAULT 0 CHECK (serial >= 0), + PRIMARY KEY (layer_stack_id, kind, node_id), + CHECK ( + (kind = 'commit' AND length(node_id) = 33 AND substr(node_id, 1, 1) = X'12') + OR (kind = 'layer' AND length(node_id) = 33 AND substr(node_id, 1, 1) = X'32') + OR (kind = 'branch' AND length(node_id) = 17 AND substr(node_id, 1, 1) = X'11') + OR (kind = 'stack' AND length(node_id) = 17 AND substr(node_id, 1, 1) = X'31') + ) +) STRICT, WITHOUT ROWID; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/history.sql b/engine/crates/layerfs-persistence/sql/sqlite/history.sql index 6a587b78cc..7c3ec88f1c 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/history.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/history.sql @@ -6,6 +6,7 @@ CREATE TABLE history_meta ( binding_key BLOB NOT NULL CHECK (length(binding_key) BETWEEN 1 AND 128), identity_format INTEGER NOT NULL CHECK (identity_format = 3), schema_version INTEGER NOT NULL CHECK(schema_version=1), + next_history_serial INTEGER NOT NULL DEFAULT 1, schema_source TEXT NOT NULL, schema_definition TEXT NOT NULL ) STRICT; @@ -50,6 +51,7 @@ CREATE TABLE layer ( source_commit_id IS NULL OR (length(source_commit_id) = 33 AND substr(source_commit_id, 1, 1) = X'12') ), + history_serial INTEGER NOT NULL DEFAULT 0, CHECK ( (parent_layer_id IS NULL AND source_branch_id IS NULL AND source_commit_id IS NULL) OR @@ -102,6 +104,7 @@ CREATE TABLE "commit" ( new_metadata INTEGER NOT NULL DEFAULT 0 CHECK(new_metadata>=0), lww BLOB NOT NULL, displaced_id BLOB CHECK(displaced_id IS NULL OR length(displaced_id)=33), + history_serial INTEGER NOT NULL DEFAULT 0, FOREIGN KEY (layer_stack_id, base_layer_id) REFERENCES layer(layer_stack_id, layer_id) DEFERRABLE INITIALLY DEFERRED, FOREIGN KEY (layer_stack_id, parent_commit_id) diff --git a/engine/crates/layerfs-persistence/sql/sqlite/metadata.sql b/engine/crates/layerfs-persistence/sql/sqlite/metadata.sql index 64671b6172..93c874272f 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/metadata.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/metadata.sql @@ -6,7 +6,8 @@ CREATE TABLE store_policy ( chunk_delta_max_depth INTEGER NOT NULL CHECK(chunk_delta_max_depth BETWEEN 0 AND 50), metadata_delta_max_depth INTEGER NOT NULL CHECK(metadata_delta_max_depth BETWEEN 0 AND 50), next_pack_id INTEGER NOT NULL DEFAULT 1 CHECK(next_pack_id>0), - next_ordinal INTEGER NOT NULL DEFAULT 1 CHECK(next_ordinal BETWEEN 1 AND 4294967296) + next_ordinal INTEGER NOT NULL DEFAULT 1 CHECK(next_ordinal BETWEEN 1 AND 4294967296), + trace_salt BLOB NOT NULL DEFAULT (X'0000000000000000000000000000000000000000000000000000000000000000') CHECK(length(trace_salt)=32) ) STRICT; CREATE TABLE object_location ( object_id BLOB PRIMARY KEY CHECK(length(object_id)=32), diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id.sql index 8bb8c308fd..1f9cc22f93 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id.sql @@ -1 +1 @@ -SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE branch_id = $1; +SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE branch_id = $1 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = branch.branch_id) AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id = branch.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id_any.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id_any.sql new file mode 100644 index 0000000000..8bb8c308fd --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_id_any.sql @@ -0,0 +1 @@ +SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE branch_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_name.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_name.sql index f32a794a16..0eadc60e31 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_name.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_by_name.sql @@ -1 +1 @@ -SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 AND name = $2; +SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 AND name = $2 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = branch.branch_id) AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id = branch.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_first_page.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_first_page.sql index b31a7ac3cb..948b07f14a 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_first_page.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_first_page.sql @@ -1 +1 @@ -SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 ORDER BY name LIMIT $2; +SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = branch.branch_id) AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id = branch.layer_stack_id) ORDER BY name LIMIT $2; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_name_taken.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_name_taken.sql index 66493a918d..e0f54d1707 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_name_taken.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_name_taken.sql @@ -1 +1 @@ -SELECT 1 FROM branch WHERE layer_stack_id = $1 AND name = $2; +SELECT b.name, CASE WHEN r.branch_id IS NULL THEN 0 ELSE 1 END FROM branch b LEFT JOIN branch_retired r ON r.branch_id = b.branch_id WHERE b.layer_stack_id = $1 AND b.name = $2; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_next_page.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_next_page.sql index 9530b4f910..c37d2b136e 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_next_page.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_branch_next_page.sql @@ -1 +1 @@ -SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 AND name > $2 ORDER BY name LIMIT $3; +SELECT branch_id, layer_stack_id, name, base_layer_id, head_commit_id, forked_from_id FROM branch WHERE layer_stack_id = $1 AND name > $2 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = branch.branch_id) AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id = branch.layer_stack_id) ORDER BY name LIMIT $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_retire_insert.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_retire_insert.sql new file mode 100644 index 0000000000..700f5dd810 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_retire_insert.sql @@ -0,0 +1 @@ +INSERT INTO branch_retired (branch_id, removed_ms) VALUES ($1, $2) ON CONFLICT(branch_id) DO NOTHING RETURNING branch_id; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot.sql index 146b8b8c6a..08db9eb02a 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot.sql @@ -1 +1 @@ -SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM branch b LEFT JOIN layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN layer l ON l.layer_id = b.base_layer_id LEFT JOIN "commit" c ON c.commit_id = b.head_commit_id WHERE b.branch_id = $1; +SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM branch b LEFT JOIN layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN layer l ON l.layer_id = b.base_layer_id LEFT JOIN "commit" c ON c.commit_id = b.head_commit_id WHERE b.branch_id = $1 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = b.branch_id) AND NOT EXISTS (SELECT 1 FROM layer_stack_retired d WHERE d.layer_stack_id = b.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot_named.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot_named.sql index d44de96eba..beb7aa52ee 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot_named.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/branch_snapshot_named.sql @@ -1 +1 @@ -SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM layer_stack p LEFT JOIN branch b ON p.name = $1 AND b.layer_stack_id = p.layer_stack_id AND b.name = $2 LEFT JOIN layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN layer l ON l.layer_id = b.base_layer_id LEFT JOIN "commit" c ON c.commit_id = b.head_commit_id WHERE p.name = $1; +SELECT b.branch_id, b.layer_stack_id, b.name, b.base_layer_id, b.head_commit_id, b.forked_from_id, s.layer_stack_id, s.name, s.scope_id, s.profile_id, s.head_layer_id, l.root_id, c.commit_id, c.layer_stack_id, c.root_id, c.parent_commit_id, c.base_layer_id, c.second_parent_id, c.branch_id, c.via, c.message, c.merged_from_id, c.created_ms, c.logical, c.new_canonical, c.new_stored, c.new_metadata, c.lww, c.displaced_id FROM layer_stack p LEFT JOIN branch b ON p.name = $1 AND b.layer_stack_id = p.layer_stack_id AND b.name = $2 AND NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id = b.branch_id) LEFT JOIN layer_stack s ON s.layer_stack_id = b.layer_stack_id LEFT JOIN layer l ON l.layer_id = b.base_layer_id LEFT JOIN "commit" c ON c.commit_id = b.head_commit_id WHERE p.name = $1 AND NOT EXISTS (SELECT 1 FROM layer_stack_retired d WHERE d.layer_stack_id = p.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/commit_insert_commit.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/commit_insert_commit.sql index 48d2df4768..9af2640f05 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/commit_insert_commit.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/commit_insert_commit.sql @@ -1 +1 @@ -INSERT INTO "commit" (commit_id, layer_stack_id, root_id, parent_commit_id, base_layer_id, second_parent_id, branch_id, via, message, merged_from_id, created_ms, logical, new_canonical, new_stored, new_metadata, lww, displaced_id) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17) ON CONFLICT (commit_id) DO NOTHING RETURNING 1; +INSERT INTO "commit" (commit_id, layer_stack_id, root_id, parent_commit_id, base_layer_id, second_parent_id, branch_id, via, message, merged_from_id, created_ms, logical, new_canonical, new_stored, new_metadata, lww, displaced_id, history_serial) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18) ON CONFLICT (commit_id) DO NOTHING RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_branch_stack_any.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_branch_stack_any.sql new file mode 100644 index 0000000000..2d1e79787e --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_branch_stack_any.sql @@ -0,0 +1 @@ +SELECT layer_stack_id FROM branch WHERE branch_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_read.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_read.sql new file mode 100644 index 0000000000..67853fc6f2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_read.sql @@ -0,0 +1 @@ +SELECT epoch FROM project_epoch WHERE layer_stack_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_share.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_share.sql new file mode 100644 index 0000000000..67853fc6f2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_epoch_share.sql @@ -0,0 +1 @@ +SELECT epoch FROM project_epoch WHERE layer_stack_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_inode_blocks.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_inode_blocks.sql new file mode 100644 index 0000000000..433ca5fb2c --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_inode_blocks.sql @@ -0,0 +1 @@ +SELECT length(body) FROM inode_value_block ORDER BY first_ordinal diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql new file mode 100644 index 0000000000..3fb3e03c82 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_branch.sql @@ -0,0 +1,10 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND ( + scope_kind = 'store' + OR (scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'branch' AND scope_id = $2) + ) + AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql new file mode 100644 index 0000000000..684af7e2ea --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_project.sql @@ -0,0 +1,13 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND ( + scope_kind = 'store' + OR (scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'branch' AND ( + (project = $2) + OR scope_id IN (SELECT branch_id FROM branch WHERE layer_stack_id = $1) + )) + ) + AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_store.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_store.sql new file mode 100644 index 0000000000..994f81301b --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_all_store.sql @@ -0,0 +1,5 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND op_id <> $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_get.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_get.sql new file mode 100644 index 0000000000..b4a0f1d551 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_get.sql @@ -0,0 +1,5 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND op_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_insert.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_insert.sql new file mode 100644 index 0000000000..adc87b0b7d --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_insert.sql @@ -0,0 +1,8 @@ +INSERT INTO gc_intent (op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, owner_runtime, owner_boot, state, uncertain, phase, generation, artifact, high_water, evidence, updated_ms) +VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, ($13 <> 0), $14, NULL, NULL, NULL, NULL, $15) +ON CONFLICT(op_id) DO UPDATE SET + state = excluded.state, + uncertain = excluded.uncertain, + phase = excluded.phase, + updated_ms = excluded.updated_ms +RETURNING op_id; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_list.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_list.sql new file mode 100644 index 0000000000..56091ddb25 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_list.sql @@ -0,0 +1,6 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND scope_kind = $1 AND scope_id = $2 +ORDER BY updated_ms, op_id; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql new file mode 100644 index 0000000000..cfce4edba7 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_branch.sql @@ -0,0 +1,11 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND kind IN ('removal', 'compaction') + AND ( + scope_kind = 'store' + OR (scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'branch' AND scope_id = $2) + ) + AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql new file mode 100644 index 0000000000..5ea9c9f72c --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_project.sql @@ -0,0 +1,14 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND kind IN ('removal', 'compaction') + AND ( + scope_kind = 'store' + OR (scope_kind = 'project' AND scope_id = $1) + OR (scope_kind = 'branch' AND ( + (project = $2) + OR scope_id IN (SELECT branch_id FROM branch WHERE layer_stack_id = $1) + )) + ) + AND op_id <> $3; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_store.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_store.sql new file mode 100644 index 0000000000..655f4bf031 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_ops_store.sql @@ -0,0 +1,6 @@ +SELECT op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, branch, + owner_runtime, owner_boot, state, uncertain, phase +FROM gc_intent +WHERE state <> 'done' + AND op_id <> $1 + AND kind IN ('removal', 'compaction'); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_release.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_release.sql new file mode 100644 index 0000000000..4874b5ef1d --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_release.sql @@ -0,0 +1 @@ +DELETE FROM gc_intent WHERE op_id = $1 RETURNING op_id; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_uncertain.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_uncertain.sql new file mode 100644 index 0000000000..b47218d8b2 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_intent_uncertain.sql @@ -0,0 +1 @@ +UPDATE gc_intent SET state = 'uncertain', uncertain = TRUE, updated_ms = $1 WHERE op_id = $2 RETURNING op_id; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_kept_roots.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_kept_roots.sql new file mode 100644 index 0000000000..180f300089 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_kept_roots.sql @@ -0,0 +1,7 @@ +SELECT c.root_id FROM kept_node k + JOIN "commit" c ON c.commit_id=k.node_id + WHERE k.kind='commit' +UNION +SELECT l.root_id FROM kept_node k + JOIN layer l ON l.layer_id=k.node_id + WHERE k.kind='layer' diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_branches.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_branches.sql new file mode 100644 index 0000000000..a20e525e28 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_branches.sql @@ -0,0 +1,4 @@ +SELECT b.branch_id,b.head_commit_id,b.base_layer_id FROM branch b + WHERE NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id=b.branch_id) + AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id=b.layer_stack_id) + ORDER BY b.branch_id diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_stacks.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_stacks.sql new file mode 100644 index 0000000000..0a20c54b38 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_live_stacks.sql @@ -0,0 +1,3 @@ +SELECT s.layer_stack_id,s.head_layer_id FROM layer_stack s + WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=s.layer_stack_id) + ORDER BY s.layer_stack_id diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_object_locations.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_object_locations.sql new file mode 100644 index 0000000000..a96c9ecc9d --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_object_locations.sql @@ -0,0 +1,2 @@ +SELECT object_id,pack_id,group_number,record_number FROM object_location + ORDER BY pack_id,group_number,record_number diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_tuple_read.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_tuple_read.sql new file mode 100644 index 0000000000..5c235efcef --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/gc_tuple_read.sql @@ -0,0 +1,6 @@ +SELECT h.catalog_incarnation,h.next_history_serial,p.next_pack_id,p.next_ordinal, + t.logical,t.canonical,t.stored,t.metadata, + (SELECT COALESCE(MAX(stamp),0) FROM content_signature), + (SELECT COUNT(*) FROM "commit")+(SELECT COUNT(*) FROM layer) + FROM history_meta h, store_policy p, store_totals t + WHERE h.id=1 AND p.id=1 AND t.id=1 diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_clear.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_clear.sql new file mode 100644 index 0000000000..2829711e8c --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_clear.sql @@ -0,0 +1 @@ +DELETE FROM kept_node diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_mark.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_mark.sql new file mode 100644 index 0000000000..7dacb749e4 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_mark.sql @@ -0,0 +1,81 @@ +WITH RECURSIVE +roots(kind,node_id) AS ( + SELECT 'stack',s.layer_stack_id FROM layer_stack s + WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=s.layer_stack_id) + UNION + SELECT 'layer',l.layer_id FROM layer l + WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=l.layer_stack_id) + UNION + SELECT 'branch',b.branch_id FROM branch b + WHERE NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id=b.branch_id) + AND NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=b.layer_stack_id) +), +edges(from_kind,from_id,to_kind,to_id) AS ( + SELECT 'branch',b.branch_id,'commit',b.head_commit_id FROM branch b + JOIN "commit" c ON c.commit_id=b.head_commit_id + UNION ALL + SELECT 'branch',b.branch_id,'layer',b.base_layer_id FROM branch b + UNION ALL + SELECT 'branch',b.branch_id,'commit',b.forked_from_id FROM branch b + JOIN "commit" c ON c.commit_id=b.forked_from_id + UNION ALL + SELECT 'branch',b.branch_id,'layer',b.forked_from_id FROM branch b + JOIN layer l ON l.layer_id=b.forked_from_id + UNION ALL + SELECT 'layer',l.layer_id,'layer',l.parent_layer_id FROM layer l + WHERE l.parent_layer_id IS NOT NULL + UNION ALL + SELECT 'layer',l.layer_id,'commit',l.source_commit_id FROM layer l + WHERE l.source_commit_id IS NOT NULL + UNION ALL + SELECT 'layer',l.layer_id,'branch',l.source_branch_id FROM layer l + WHERE l.source_branch_id IS NOT NULL + UNION ALL + SELECT 'commit',c.commit_id,'commit',c.parent_commit_id FROM "commit" c + WHERE c.parent_commit_id IS NOT NULL + UNION ALL + SELECT 'commit',c.commit_id,'commit',c.second_parent_id FROM "commit" c + JOIN "commit" s ON s.commit_id=c.second_parent_id + UNION ALL + SELECT 'commit',c.commit_id,'layer',c.second_parent_id FROM "commit" c + JOIN layer l ON l.layer_id=c.second_parent_id + UNION ALL + SELECT 'commit',c.commit_id,'layer',c.base_layer_id FROM "commit" c + UNION ALL + SELECT 'commit',c.commit_id,'branch',c.branch_id FROM "commit" c + WHERE c.branch_id IS NOT NULL + UNION ALL + SELECT 'commit',c.commit_id,'commit',c.merged_from_id FROM "commit" c + JOIN "commit" s ON s.commit_id=c.merged_from_id + UNION ALL + SELECT 'commit',c.commit_id,'layer',c.merged_from_id FROM "commit" c + JOIN layer l ON l.layer_id=c.merged_from_id + UNION ALL + SELECT 'commit',c.commit_id,'commit',c.displaced_id FROM "commit" c + JOIN "commit" s ON s.commit_id=c.displaced_id + UNION ALL + SELECT 'commit',c.commit_id,'layer',c.displaced_id FROM "commit" c + JOIN layer l ON l.layer_id=c.displaced_id +), +closure(kind,node_id) AS ( + SELECT kind,node_id FROM roots + UNION + SELECT e.to_kind,e.to_id + FROM closure k JOIN edges e ON e.from_kind=k.kind AND e.from_id=k.node_id +) +INSERT INTO kept_node(layer_stack_id,kind,node_id,serial) +SELECT s.layer_stack_id,'stack',s.layer_stack_id,0 + FROM closure k JOIN layer_stack s ON s.layer_stack_id=k.node_id + WHERE k.kind='stack' +UNION ALL +SELECT b.layer_stack_id,'branch',b.branch_id,0 + FROM closure k JOIN branch b ON b.branch_id=k.node_id + WHERE k.kind='branch' +UNION ALL +SELECT l.layer_stack_id,'layer',l.layer_id,l.history_serial + FROM closure k JOIN layer l ON l.layer_id=k.node_id + WHERE k.kind='layer' +UNION ALL +SELECT c.layer_stack_id,'commit',c.commit_id,c.history_serial + FROM closure k JOIN "commit" c ON c.commit_id=k.node_id + WHERE k.kind='commit' diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_read.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_read.sql new file mode 100644 index 0000000000..3673d561ce --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/kept_node_read.sql @@ -0,0 +1 @@ +SELECT layer_stack_id,kind,node_id,serial FROM kept_node ORDER BY layer_stack_id,kind,node_id diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_bump_project_epoch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_bump_project_epoch.sql new file mode 100644 index 0000000000..0ef48580ea --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_bump_project_epoch.sql @@ -0,0 +1 @@ +UPDATE project_epoch SET epoch = epoch + 1 WHERE layer_stack_id = $1 RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_deleted_ms.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_deleted_ms.sql new file mode 100644 index 0000000000..860a613de8 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_deleted_ms.sql @@ -0,0 +1 @@ +SELECT deleted_ms FROM layer_stack_retired WHERE layer_stack_id = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_layer.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_layer.sql index c483c0caf3..7d908b00d7 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_layer.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_layer.sql @@ -1 +1 @@ -INSERT INTO layer (layer_id,layer_stack_id,parent_layer_id,root_id,source_branch_id,source_commit_id,logical, overwrote) VALUES ($1,$2,$3,$4,$5,$6,$7, $8) RETURNING 1; +INSERT INTO layer (layer_id,layer_stack_id,parent_layer_id,root_id,source_branch_id,source_commit_id,logical, overwrote, history_serial) VALUES ($1,$2,$3,$4,$5,$6,$7, $8, $9) RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_project_epoch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_project_epoch.sql new file mode 100644 index 0000000000..9aa115b2dd --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_project_epoch.sql @@ -0,0 +1 @@ +INSERT INTO project_epoch (layer_stack_id, epoch) VALUES ($1, 0) RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_retired.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_retired.sql new file mode 100644 index 0000000000..2bf5257bbe --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_insert_retired.sql @@ -0,0 +1 @@ +INSERT INTO layer_stack_retired (layer_stack_id, deleted_ms) VALUES ($1, $2) ON CONFLICT (layer_stack_id) DO NOTHING RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_id.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_id.sql index bda0abe24a..688aa805c1 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_id.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_id.sql @@ -1 +1 @@ -SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE layer_stack_id = $1; +SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE layer_stack_id = $1 AND NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id = layer_stack.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_name.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_name.sql index 0d92910086..f4e015667c 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_name.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_by_name.sql @@ -1 +1 @@ -SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE name = $1; +SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE name = $1 AND NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id = layer_stack.layer_stack_id); diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_first_page.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_first_page.sql index 6e4c239eec..1e9afc88ef 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_first_page.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_first_page.sql @@ -1 +1 @@ -SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack ORDER BY name LIMIT $1; +SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id = layer_stack.layer_stack_id) ORDER BY name LIMIT $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_name_taken.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_name_taken.sql index 875ddc4086..b1e577c213 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_name_taken.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_name_taken.sql @@ -1 +1 @@ -SELECT 1 FROM layer_stack WHERE name = $1; +SELECT s.name, CASE WHEN r.layer_stack_id IS NULL THEN 0 ELSE 1 END FROM layer_stack s LEFT JOIN layer_stack_retired r ON r.layer_stack_id = s.layer_stack_id WHERE s.name = $1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_next_page.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_next_page.sql index 1bcd9ffd33..f8d2ed28f7 100644 --- a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_next_page.sql +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/layerstack_stack_next_page.sql @@ -1 +1 @@ -SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE name > $1 ORDER BY name LIMIT $2; +SELECT layer_stack_id, name, scope_id, profile_id, head_layer_id FROM layer_stack WHERE name > $1 AND NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id = layer_stack.layer_stack_id) ORDER BY name LIMIT $2; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_advance_epoch.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_advance_epoch.sql new file mode 100644 index 0000000000..15fa42d851 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_advance_epoch.sql @@ -0,0 +1 @@ +UPDATE project_epoch SET epoch=epoch+1 WHERE layer_stack_id=$1 RETURNING 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_marker.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_marker.sql new file mode 100644 index 0000000000..049788375c --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_marker.sql @@ -0,0 +1 @@ +SELECT path,frontier_serial,removed_ms FROM path_removed WHERE layer_stack_id=$1 AND path_key=$2; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_markers.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_markers.sql new file mode 100644 index 0000000000..d3bd1e7c8a --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_markers.sql @@ -0,0 +1 @@ +SELECT path,frontier_serial,removed_ms FROM path_removed WHERE layer_stack_id=$1 ORDER BY path; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_upsert.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_upsert.sql new file mode 100644 index 0000000000..f9171232e1 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/paths_upsert.sql @@ -0,0 +1 @@ +INSERT INTO path_removed(layer_stack_id,path_key,path,frontier_serial,removed_ms) VALUES($1,$2,$3,$4,$5) ON CONFLICT(layer_stack_id,path_key) DO UPDATE SET path=excluded.path, frontier_serial=excluded.frontier_serial, removed_ms=excluded.removed_ms; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_high_water.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_high_water.sql new file mode 100644 index 0000000000..c76bf13a1e --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_high_water.sql @@ -0,0 +1 @@ +SELECT next_history_serial - 1 FROM history_meta WHERE id=1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_next_serial.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_next_serial.sql new file mode 100644 index 0000000000..a7f0c03ba9 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_next_serial.sql @@ -0,0 +1 @@ +UPDATE history_meta SET next_history_serial=next_history_serial+1 WHERE id=1 RETURNING next_history_serial-1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_node_serial.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_node_serial.sql new file mode 100644 index 0000000000..5a3ff1e15c --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_node_serial.sql @@ -0,0 +1 @@ +SELECT history_serial FROM "commit" WHERE commit_id=$1 UNION ALL SELECT history_serial FROM layer WHERE layer_id=$1 LIMIT 1; diff --git a/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_stack_high_water.sql b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_stack_high_water.sql new file mode 100644 index 0000000000..fab8fefa98 --- /dev/null +++ b/engine/crates/layerfs-persistence/sql/sqlite/queries/history/position_stack_high_water.sql @@ -0,0 +1 @@ +SELECT COALESCE(MAX(history_serial),0) FROM (SELECT history_serial FROM "commit" WHERE layer_stack_id=$1 UNION ALL SELECT history_serial FROM layer WHERE layer_stack_id=$1) AS serials; diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/access.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/access.rs index 417d654060..488b0fee19 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/access.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/access.rs @@ -1,11 +1,13 @@ //! What a role may do in a Store's schema, for `store.attach`'s check of a -//! machine's connection: the server's version, one round trip's latency, -//! the role, and each privilege a Sandbox's writes need that it lacks. One -//! connection opened for the call and closed after it, read-only queries -//! only, no retry. -use crate::backend::postgresql::session::connection::Connector; +//! machine's connection and for a PostgreSQL compaction's preflight: the +//! server's version, one round trip's latency, the role, and each privilege +//! the Store's writes and compaction need that it lacks. One connection +//! opened for the call and closed after it, read-only queries only, no retry. +use crate::backend::postgresql::session::connection::{Connector, Session}; use crate::backend::postgresql::status::PostgresStatusError; +use crate::backend::records::{BackendError, Param}; use crate::PostgresSelection; +use layerfs_history::error::HistoryResult; use std::time::{Duration, Instant}; /// What the server answered for a role and a schema. @@ -20,18 +22,26 @@ pub struct PostgresAccess { /// Whether the database has the schema. pub schema: bool, /// Each privilege the role lacks, as ` on `, in a - /// fixed order: the schema's `USAGE`, the database's `TEMP`, then each - /// table's `SELECT`, `INSERT`, `UPDATE`, `DELETE` and each sequence's - /// `USAGE`. Empty when the role has them all (or there is no schema). + /// fixed order: the schema's `USAGE` and `CREATE`, the database's + /// `CREATE` and `TEMP`, `pg_read_all_stats`, then each table's `SELECT`, + /// `INSERT`, `UPDATE`, `DELETE` and each sequence's `USAGE`. Empty when + /// the role has them all (or there is no schema). pub missing: Vec, } -/// The role, the schema's `USAGE` (NULL without the schema) and the -/// database's `TEMP` (a merge stages in temporary tables). +/// The role, the schema's `USAGE` and `CREATE` (NULL without the schema), the +/// database's `CREATE` (a compaction creates the `lfs_gc_` scratch +/// schema) and `TEMP` (a merge stages in temporary tables, and a compaction +/// reads its visited set from them), and `pg_read_all_stats` (a compaction +/// reads another backend's `pg_stat_activity` row). const ROLE: &str = "SELECT current_user::text, \ CASE WHEN EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = $1::text) \ THEN has_schema_privilege($1::text, 'USAGE') END, \ - has_database_privilege(current_database(), 'TEMP')"; + CASE WHEN EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = $1::text) \ + THEN has_schema_privilege($1::text, 'CREATE') END, \ + has_database_privilege(current_database(), 'CREATE'), \ + has_database_privilege(current_database(), 'TEMP'), \ + pg_has_role('pg_read_all_stats', 'MEMBER')"; /// Each table and sequence privilege of the schema the role lacks. const MISSING: &str = "SELECT p.privilege || ' on ' || $1::text || '.' || c.relname \ @@ -44,6 +54,49 @@ const MISSING: &str = "SELECT p.privilege || ' on ' || $1::text || '.' || c.reln ELSE has_table_privilege(c.oid, p.privilege) END \ ORDER BY c.relkind DESC, c.relname, p.at"; +/// The five Store-wide privileges a compaction needs before it names or +/// creates its scratch schema, in the order [`compaction_missing`] reports a +/// missing one: the schema's `USAGE` and `CREATE`, the database's `CREATE` +/// and `TEMP`, and `pg_read_all_stats`. `CREATE` on the schema is the +/// `ALTER TABLE ... SET SCHEMA` of Phase B; `CREATE` on the database is the +/// scratch schema itself; `pg_read_all_stats` is the recorded owner's +/// `pg_stat_activity` row and its `pg_terminate_backend` proof. +const COMPACTION: &str = "SELECT \ + has_schema_privilege($1::text, 'USAGE')::int, \ + has_schema_privilege($1::text, 'CREATE')::int, \ + has_database_privilege(current_database(), 'CREATE')::int, \ + has_database_privilege(current_database(), 'TEMP')::int, \ + pg_has_role('pg_read_all_stats', 'MEMBER')::int"; + +/// The privilege named for each [`COMPACTION`] column, in its order. +const COMPACTION_NAMES: [&str; 5] = [ + "USAGE on the Store schema", + "CREATE on the Store schema", + "CREATE on the database", + "TEMP on the database", + "pg_read_all_stats", +]; + +/// The first Store-wide privilege `session`'s role lacks for a PostgreSQL +/// compaction, or `None` when it has them all: one read-only round trip, +/// taken before the mark and before the `lfs_gc_` scratch schema is +/// named or created. The caller reports the returned name as `Unsupported` +/// (AC-44). +pub(crate) fn compaction_missing(session: &Session) -> HistoryResult> { + session.run(false, |tx| { + let rows = tx.query(COMPACTION, vec![Param::Text(tx.schema.to_owned())])?; + let Some(row) = rows.first() else { + return Err(BackendError::Integrity.into()); + }; + for (at, privilege) in COMPACTION_NAMES.iter().enumerate() { + if row.get::(at)? == 0 { + return Ok(Some(*privilege)); + } + } + Ok(None) + }) +} + /// Reads what the role `url` logs in as may do in `schema`. pub fn access(url: &str, schema: &str) -> Result { let connector = Connector::new(&PostgresSelection::new(url, "public")) @@ -67,14 +120,26 @@ pub fn access(url: &str, schema: &str) -> Result = row.try_get(1).map_err(failed)?; - let temp: bool = row.try_get(2).map_err(failed)?; + let create_schema: Option = row.try_get(2).map_err(failed)?; + let create_database: bool = row.try_get(3).map_err(failed)?; + let temp: bool = row.try_get(4).map_err(failed)?; + let read_all_stats: bool = row.try_get(5).map_err(failed)?; let mut missing = Vec::new(); if usage == Some(false) { missing.push(format!("USAGE on schema {schema}")); } + if create_schema == Some(false) { + missing.push(format!("CREATE on schema {schema}")); + } + if !create_database { + missing.push("CREATE on the database".to_owned()); + } if !temp { missing.push("TEMP on the database".to_owned()); } + if !read_all_stats { + missing.push("pg_read_all_stats".to_owned()); + } if usage == Some(true) { for row in client.query(MISSING, &[&schema]).map_err(failed)? { missing.push(row.try_get(0).map_err(failed)?); diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/compact.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/compact.rs new file mode 100644 index 0000000000..0ae5ebc265 --- /dev/null +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/compact.rs @@ -0,0 +1,1560 @@ +//! §8 PostgreSQL Store compaction: Phase M mark, Phase A build, Phase B swap +//! and Phase C cleanup. +//! +//! One call takes the T6 Store-scoped exclusive intent (a session advisory +//! key held through cleanup), records the §8 mark tuple as its first +//! statement, runs the T7.2 mark, and decides from the wholly dead pack +//! bytes. A `rebuild` copies only retained `pack`/`object_location` rows into +//! a scratch schema, swaps the two tables in one short transaction at +//! `G -> G + 1`, and deletes only the ids the mark persisted in `gc_dead`. +//! The op row in `gc_op` names the scratch schema before it is created, so a +//! crash (or a lost COMMIT reply) is judged by the next `store.compact`: +//! generation `G` removes the artifact, `G + 1` resumes cleanup. + +use super::access::compaction_missing; +use super::session::{ + connection::Session, + transaction::{Mode, Transaction}, +}; +use crate::backend::records::Param; +use crate::backend::sqlite::compact::{ + CompactFailpoint, CompactKeptWaste, CompactPath, CompactReceipt, CompactRequest, + CompactResidue, CompactZeroReason, +}; +use crate::compact_metrics::{ + self, CompactOutcome, CompactPhase, CompactRefusal, CompactRunObservation, +}; +use crate::history::GcTuple; +use crate::{MarkResult, PostgresHandles}; +use layerfs_history::error::{HistoryError, HistoryResult}; +use layerfs_history::records::{GcIntent, GcIntentKind, GcScopeKind}; +use layerfs_history::HistoryCatalog; +use std::sync::Arc; +use std::time::{Instant, SystemTime, UNIX_EPOCH}; + +/// The §3 rebuild threshold: rebuild when dead * 10 >= stored. +const THRESHOLD: u64 = 10; +/// `lfs_gc_`: the deterministic scratch schema name. +const SCRATCH_PREFIX: &str = "lfs_gc_"; + +/// The three wholly dead domains the swap records before COMMIT. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +struct DeadTotals { + canonical: i64, + stored: i64, + metadata: i64, + logical: i64, +} + +/// One compaction op row, as the next call judges it. +#[derive(Clone, Debug)] +struct OpRow { + generation: i64, + artifact: Option, + dead: DeadTotals, + totals_applied: bool, + pid: Option, + backend_start: Option, +} + +/// What Phase A leaves for Phase B. +struct Built { + scratch: String, + scratch_bytes: u64, + dead: DeadTotals, +} + +/// What the swap records for the report and Phase C. +struct Swapped { + physical_before: u64, + physical_after: u64, + peak_temp: u64, + dead: DeadTotals, +} + +/// The phase clock and §11 values one measured PostgreSQL compaction observes. +/// +/// Phase M times the intent, the mark and the wholly-dead-pack decision, Phase +/// A the scratch copy, Phase B the swap, and Phase C the cleanup — also when a +/// later call resumes an installed `G + 1` leftover. The `pg_` phase values +/// keep these distinct from the SQLite §7 phases in the process totals. +struct RunMetrics { + started: Instant, + phase: Option<(CompactPhase, Instant)>, + phase_nanos: Vec<(CompactPhase, u64)>, + generation_before: u64, + generation_after: u64, + dead_bytes_bound: u64, + dead_bytes_refined: u64, + kept_waste: CompactKeptWaste, + residue_bytes: u64, + leftover_settled: bool, +} + +impl RunMetrics { + fn start() -> Self { + Self { + started: Instant::now(), + phase: None, + phase_nanos: Vec::new(), + generation_before: 0, + generation_after: 0, + dead_bytes_bound: 0, + dead_bytes_refined: 0, + kept_waste: CompactKeptWaste::default(), + residue_bytes: 0, + leftover_settled: false, + } + } + + /// Ends the current phase and starts `phase`; a phase is inclusive wall + /// time, never an exclusive CPU decomposition. + fn begin_phase(&mut self, phase: CompactPhase) { + self.end_phase(); + self.phase = Some((phase, Instant::now())); + } + + fn end_phase(&mut self) { + if let Some((phase, started)) = self.phase.take() { + self.phase_nanos.push(( + phase, + u64::try_from(started.elapsed().as_nanos()).unwrap_or(u64::MAX), + )); + } + } + + /// Records this run once, whatever its result. The outcome and refusal + /// come from the typed error, so a `Busy`/`Unresolved` refusal is counted + /// without changing the error the caller receives. + fn finish(mut self, result: &HistoryResult) { + self.end_phase(); + let total_nanos = u64::try_from(self.started.elapsed().as_nanos()).unwrap_or(u64::MAX); + let (outcome, refusal) = match result { + Ok(receipt) => { + // A resumed `G + 1` round reports the original run's + // generation, so the receipt is the authority here. + self.generation_before = receipt.generation_before; + self.generation_after = receipt.generation_after; + self.dead_bytes_bound = receipt.dead_bytes_bound; + self.dead_bytes_refined = receipt.dead_bytes_refined; + self.kept_waste = receipt.kept_waste.clone(); + self.residue_bytes = receipt.residue.bytes; + let outcome = match receipt.path { + CompactPath::Rebuild => CompactOutcome::Rebuild, + CompactPath::None => CompactOutcome::None, + }; + (outcome, None) + } + Err(error) => { + if !error.unknown() { + self.generation_after = self.generation_before; + } + ( + if error.unknown() { + CompactOutcome::Uncertain + } else { + CompactOutcome::Failed + }, + match error { + HistoryError::Busy | HistoryError::BusyOp(_) => Some(CompactRefusal::Busy), + HistoryError::Unresolved(_) => Some(CompactRefusal::Unresolved), + _ => None, + }, + ) + } + }; + compact_metrics::record_run(&CompactRunObservation { + outcome, + generation_before: self.generation_before, + generation_after: self.generation_after, + dead_bytes_bound: self.dead_bytes_bound, + dead_bytes_refined: self.dead_bytes_refined, + kept_waste: self.kept_waste, + residue_bytes: self.residue_bytes, + phase_nanos: self.phase_nanos, + total_nanos, + leftover_settled: self.leftover_settled, + refusal, + }); + } +} + +fn now_ms() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |elapsed| { + i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX) + }) +} + +fn hex(bytes: &[u8]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(bytes.len() * 2); + for byte in bytes { + let _ = write!(out, "{byte:02x}"); + } + out +} + +fn scratch_name(op_id: &[u8; 16]) -> String { + format!("{SCRATCH_PREFIX}{}", hex(op_id)) +} + +fn quote_ident(name: &str) -> String { + format!("\"{}\"", name.replace('"', "\"\"")) +} + +/// One write transaction on the Store session; scratch/DDL work never waits +/// for the publication lane (the session advisory key is the exclusion). +fn stage( + session: &Arc, + body: impl FnOnce(&Transaction<'_>) -> HistoryResult, +) -> HistoryResult { + session.run_as(Mode::Stage, body) +} + +fn scalar(tx: &Transaction<'_>, sql: &str, params: Vec) -> HistoryResult { + let rows = tx.query(sql, params)?; + if rows.len() != 1 { + return Err(HistoryError::Integrity("compaction scalar")); + } + rows[0].get(0).map_err(Into::into) +} + +fn scalar_session(session: &Arc, sql: &str, params: Vec) -> HistoryResult { + stage(session, |tx| scalar(tx, sql, params)) +} + +fn read_generation(session: &Arc, schema: &str) -> HistoryResult { + scalar_session( + session, + &format!("SELECT catalog_incarnation FROM {schema}.history_meta WHERE id=1"), + Vec::new(), + ) +} + +fn read_op(session: &Arc, schema: &str) -> HistoryResult> { + stage(session, |tx| { + let rows = tx.query( + &format!( + "SELECT generation,artifact,dead_canonical,dead_stored,dead_metadata,dead_logical,totals_applied,pid,backend_start FROM {schema}.gc_op WHERE id=1" + ), + Vec::new(), + )?; + let Some(row) = rows.first() else { + return Ok(None); + }; + Ok(Some(OpRow { + generation: row.get(0)?, + artifact: row.get(1)?, + dead: DeadTotals { + canonical: row.get(2)?, + stored: row.get(3)?, + metadata: row.get(4)?, + logical: row.get(5)?, + }, + totals_applied: row.get::(6)? != 0, + pid: row.get(7)?, + backend_start: row.get(8)?, + })) + }) +} + +fn set_phase(session: &Arc, schema: &str, phase: &str) -> HistoryResult<()> { + stage(session, |tx| { + tx.query( + &format!("UPDATE {schema}.gc_op SET phase=$1 WHERE id=1"), + vec![Param::Text(phase.to_owned())], + )?; + Ok(()) + }) +} + +fn stop( + request: &CompactRequest, + point: CompactFailpoint, + session: &Arc, + schema: &str, + phase: &str, +) -> HistoryResult<()> { + if request.failpoint != Some(point) { + return Ok(()); + } + set_phase(session, schema, phase)?; + Err(HistoryError::UnknownOutcome) +} + +/// The set of live object ids and live pack ids, as session temporary tables +/// the Phase A copy and the dead-set query read. +fn load_visited(session: &Arc, schema: &str, mark: &MarkResult) -> HistoryResult<()> { + let objects: Vec> = mark + .objects() + .objects() + .iter() + .map(|id| id.as_bytes().to_vec()) + .collect(); + let packs: Vec = mark.objects().packs().to_vec(); + stage(session, |tx| { + tx.batch( + "DROP TABLE IF EXISTS pg_temp.gc_visited;\ + DROP TABLE IF EXISTS pg_temp.gc_live_pack;\ + CREATE TEMP TABLE pg_temp.gc_visited(object_id bytea PRIMARY KEY) ON COMMIT PRESERVE ROWS;\ + CREATE TEMP TABLE pg_temp.gc_live_pack(pack_id bigint PRIMARY KEY) ON COMMIT PRESERVE ROWS;", + )?; + let bytes = objects.iter().map(Vec::len).sum::() as u64; + tx.typed( + "INSERT INTO pg_temp.gc_visited(object_id) SELECT unnest($1::bytea[])", + &[&objects], + bytes, + )?; + tx.typed( + "INSERT INTO pg_temp.gc_live_pack(pack_id) SELECT unnest($1::bigint[])", + &[&packs], + 8 * packs.len() as u64, + )?; + let _ = schema; + Ok(()) + }) +} + +/// Phase M: write `gc_op` (phase mark) and the persisted `gc_dead` set in +/// batches. The set is a membership, not a predicate, so a row created after +/// the mark is never collected. +fn persist_mark( + session: &Arc, + schema: &str, + mark: &MarkResult, + tuple: &GcTuple, + scratch: &str, + request: &CompactRequest, +) -> HistoryResult { + let digest = mark.live_heads_digest().to_vec(); + stage(session, |tx| { + tx.query(&format!("DELETE FROM {schema}.gc_dead"), Vec::new())?; + tx.batch(&format!( + "INSERT INTO {schema}.gc_dead(kind,id) \ + SELECT 'commit',c.commit_id FROM {schema}.\"commit\" c \ + WHERE NOT EXISTS (SELECT 1 FROM {schema}.kept_node k WHERE k.kind='commit' AND k.node_id=c.commit_id) \ + UNION ALL \ + SELECT 'layer',l.layer_id FROM {schema}.layer l \ + WHERE NOT EXISTS (SELECT 1 FROM {schema}.kept_node k WHERE k.kind='layer' AND k.node_id=l.layer_id) \ + UNION ALL \ + SELECT 'branch',b.branch_id FROM {schema}.branch b \ + WHERE NOT EXISTS (SELECT 1 FROM {schema}.kept_node k WHERE k.kind='branch' AND k.node_id=b.branch_id) \ + UNION ALL \ + SELECT 'stack',s.layer_stack_id FROM {schema}.layer_stack s \ + WHERE NOT EXISTS (SELECT 1 FROM {schema}.kept_node k WHERE k.kind='stack' AND k.node_id=s.layer_stack_id) \ + UNION ALL \ + SELECT 'signature',int8send(cs.slot) FROM {schema}.content_signature cs \ + WHERE NOT EXISTS (SELECT 1 FROM pg_temp.gc_visited v WHERE v.object_id=cs.object_id) \ + UNION ALL \ + SELECT 'digest',fd.digest FROM {schema}.file_digest fd \ + WHERE NOT EXISTS (SELECT 1 FROM pg_temp.gc_visited v WHERE v.object_id=fd.root)" + ))?; + let logical = scalar( + tx, + &format!( + "SELECT COALESCE((SELECT SUM(c.logical)::bigint FROM {schema}.\"commit\" c \ + WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='commit' AND d.id=c.commit_id)),0) \ + + COALESCE((SELECT SUM(l.logical)::bigint FROM {schema}.layer l \ + WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='layer' AND d.id=l.layer_id)),0)" + ), + Vec::new(), + )?; + let started = now_ms(); + tx.query( + &format!( + "INSERT INTO {schema}.gc_op \ + (id,generation,phase,scratch_schema,mark_serial,mark_pack_id,mark_digest,mark_totals,mark_stamp,started_ms,dead_canonical,dead_stored,dead_metadata,dead_logical,totals_applied,artifact,pid,backend_start,incarnation) \ + VALUES (1,$1,'mark',$2,$3,$4,$5,int8send($6)||int8send($7)||int8send($8)||int8send($9),$10,$11,0,0,0,$12,FALSE,$2,pg_backend_pid(),(SELECT backend_start::text FROM pg_stat_activity WHERE pid=pg_backend_pid()),$1) \ + ON CONFLICT (id) DO UPDATE SET generation=EXCLUDED.generation,phase=EXCLUDED.phase,scratch_schema=EXCLUDED.scratch_schema,mark_serial=EXCLUDED.mark_serial,mark_pack_id=EXCLUDED.mark_pack_id,mark_digest=EXCLUDED.mark_digest,mark_totals=EXCLUDED.mark_totals,mark_stamp=EXCLUDED.mark_stamp,started_ms=EXCLUDED.started_ms,dead_canonical=0,dead_stored=0,dead_metadata=0,dead_logical=EXCLUDED.dead_logical,totals_applied=FALSE,artifact=EXCLUDED.artifact,pid=EXCLUDED.pid,backend_start=EXCLUDED.backend_start,incarnation=EXCLUDED.incarnation" + ), + vec![ + Param::I64(tuple.generation), + Param::Text(scratch.to_owned()), + Param::I64(tuple.next_history_serial), + Param::I64(tuple.next_pack_id), + Param::Bytes(digest), + Param::I64(tuple.logical), + Param::I64(tuple.canonical), + Param::I64(tuple.stored), + Param::I64(tuple.metadata), + Param::I64(tuple.stamp), + Param::I64(started), + Param::I64(logical), + ], + )?; + let _ = request; + Ok(DeadTotals { + logical, + ..DeadTotals::default() + }) + }) +} + +fn clear_round(session: &Arc, schema: &str) -> HistoryResult<()> { + stage(session, |tx| { + tx.batch(&format!( + "DELETE FROM {schema}.gc_dead; DELETE FROM {schema}.gc_op;" + ))?; + Ok(()) + }) +} + +/// The stored bytes of every pack the mark retained, in the current Store. +fn live_stored(session: &Arc, schema: &str) -> HistoryResult { + scalar_session( + session, + &format!( + "SELECT COALESCE(SUM(p.length)::bigint,0) FROM {schema}.pack p \ + WHERE EXISTS (SELECT 1 FROM pg_temp.gc_live_pack v WHERE v.pack_id=p.pack_id)" + ), + Vec::new(), + ) +} + +fn total_stored(session: &Arc, schema: &str) -> HistoryResult { + scalar_session( + session, + &format!("SELECT COALESCE(SUM(length)::bigint,0) FROM {schema}.pack"), + Vec::new(), + ) +} + +fn retained_totals(session: &Arc, schema: &str) -> HistoryResult<(i64, i64, i64)> { + stage(session, |tx| { + let canonical = scalar( + tx, + &format!( + "SELECT COALESCE(SUM(l.canonical_length)::bigint,0) FROM {schema}.object_location l \ + WHERE EXISTS (SELECT 1 FROM pg_temp.gc_visited v WHERE v.object_id=l.object_id)" + ), + Vec::new(), + )?; + let stored = scalar( + tx, + &format!( + "SELECT COALESCE(SUM(p.length)::bigint,0) FROM {schema}.pack p \ + WHERE EXISTS (SELECT 1 FROM pg_temp.gc_live_pack v WHERE v.pack_id=p.pack_id)" + ), + Vec::new(), + )?; + let metadata = scalar( + tx, + &format!( + "SELECT COALESCE(SUM(p.length)::bigint,0) FROM {schema}.pack p \ + WHERE p.domain=0 AND EXISTS (SELECT 1 FROM pg_temp.gc_live_pack v WHERE v.pack_id=p.pack_id)" + ), + Vec::new(), + )?; + Ok((canonical, stored, metadata)) + }) +} + +fn relation_bytes(session: &Arc, schema: &str, names: &[&str]) -> HistoryResult { + let list = names + .iter() + .map(|name| format!("'{name}'")) + .collect::>() + .join(","); + stage(session, |tx| { + let rows = tx.query( + &format!( + "SELECT COALESCE(SUM(pg_total_relation_size(c.oid))::bigint,0) FROM pg_class c \ + JOIN pg_namespace n ON n.oid=c.relnamespace \ + WHERE n.nspname=$1 AND c.relname IN ({list})" + ), + vec![Param::Text(schema.to_owned())], + )?; + let value: i64 = rows[0].get(0)?; + Ok(u64::try_from(value).unwrap_or(0)) + }) +} + +fn table_storage( + tx: &Transaction<'_>, + schema: &str, + table: &str, +) -> HistoryResult<(String, Vec)> { + { + let rows = tx.query( + "SELECT COALESCE((SELECT t.spcname FROM pg_tablespace t WHERE t.oid=c.reltablespace),''), \ + COALESCE(array_to_string(c.reloptions,','),'') \ + FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace \ + WHERE n.nspname=$1 AND c.relname=$2", + vec![Param::Text(schema.to_owned()), Param::Text(table.to_owned())], + )?; + if rows.len() != 1 { + return Err(HistoryError::Integrity("compaction source table")); + } + let tablespace: String = rows[0].get(0)?; + let reloptions: String = rows[0].get(1)?; + let options = reloptions + .split(',') + .filter(|option| !option.is_empty()) + .map(str::to_owned) + .collect(); + Ok((tablespace, options)) + } +} + +fn create_scratch(session: &Arc, schema: &str, scratch: &str) -> HistoryResult<()> { + let exists = scalar_session( + session, + "SELECT count(*) FROM pg_namespace WHERE nspname=$1", + vec![Param::Text(scratch.to_owned())], + )?; + if exists != 0 { + return Err(HistoryError::Exists("compaction scratch schema")); + } + stage(session, |tx| { + tx.batch(&format!("CREATE SCHEMA {scratch}"))?; + for table in ["pack", "object_location"] { + let (tablespace, options) = table_storage(tx, schema, table)?; + let mut sql = format!( + "CREATE TABLE {scratch}.{table} (LIKE {schema}.{table} INCLUDING STORAGE INCLUDING COMPRESSION INCLUDING CONSTRAINTS)" + ); + if !options.is_empty() { + sql.push_str(&format!(" WITH ({})", options.join(", "))); + } + if !tablespace.is_empty() { + sql.push_str(&format!(" TABLESPACE {}", quote_ident(&tablespace))); + } + tx.batch(&sql)?; + } + tx.batch(&format!( + "ALTER TABLE {scratch}.pack ADD PRIMARY KEY (pack_id)" + ))?; + Ok(()) + }) +} + +/// Phase A: copy retained rows in pack-id batches, each its own transaction; +/// a retried batch first deletes its own range, so the copy is idempotent. +fn build( + session: &Arc, + schema: &str, + scratch: &str, + mark: &MarkResult, + tuple: &GcTuple, +) -> HistoryResult { + create_scratch(session, schema, scratch)?; + let packs: Vec = mark.objects().packs().to_vec(); + let chunk = 512usize; + for batch in packs.chunks(chunk) { + let lo = batch[0]; + let hi = batch[batch.len() - 1]; + stage(session, |tx| { + tx.batch(&format!( + "DELETE FROM {scratch}.pack WHERE pack_id BETWEEN {lo} AND {hi};\ + DELETE FROM {scratch}.object_location WHERE pack_id BETWEEN {lo} AND {hi};" + ))?; + tx.query( + &format!( + "INSERT INTO {scratch}.pack SELECT p.* FROM {schema}.pack p \ + WHERE p.pack_id BETWEEN $1 AND $2 \ + AND EXISTS (SELECT 1 FROM pg_temp.gc_live_pack v WHERE v.pack_id=p.pack_id)" + ), + vec![Param::I64(lo), Param::I64(hi)], + )?; + tx.query( + &format!( + "INSERT INTO {scratch}.object_location SELECT l.* FROM {schema}.object_location l \ + WHERE l.pack_id BETWEEN $1 AND $2 \ + AND EXISTS (SELECT 1 FROM pg_temp.gc_visited v WHERE v.object_id=l.object_id)" + ), + vec![Param::I64(lo), Param::I64(hi)], + )?; + Ok(()) + })?; + } + stage(session, |tx| { + tx.batch(&format!( + "CREATE INDEX object_location_prefix ON {scratch}.object_location \ + ((('x' || encode(substring(object_id FROM 1 FOR 8), 'hex'))::bit(64)::bigint));\ + ALTER TABLE {scratch}.object_location \ + ADD FOREIGN KEY (pack_id) REFERENCES {scratch}.pack(pack_id);\ + ANALYZE {scratch}.pack; ANALYZE {scratch}.object_location;" + ))?; + Ok(()) + })?; + let (objects, distinct, pack_rows) = stage(session, |tx| { + let objects = scalar( + tx, + &format!("SELECT count(*) FROM {scratch}.object_location"), + Vec::new(), + )?; + let distinct = scalar( + tx, + &format!("SELECT count(DISTINCT object_id) FROM {scratch}.object_location"), + Vec::new(), + )?; + let pack_rows = scalar( + tx, + &format!("SELECT count(*) FROM {scratch}.pack"), + Vec::new(), + )?; + Ok((objects, distinct, pack_rows)) + })?; + if distinct != mark.objects().len() as i64 || objects != distinct { + return Err(HistoryError::Integrity("compaction object count")); + } + if pack_rows != mark.objects().packs().len() as i64 { + return Err(HistoryError::Integrity("compaction pack count")); + } + let (canonical, stored, metadata) = retained_totals(session, schema)?; + let dead = DeadTotals { + canonical: tuple.canonical - canonical, + stored: tuple.stored - stored, + metadata: tuple.metadata - metadata, + logical: 0, + }; + let scratch_bytes = relation_bytes(session, scratch, &["pack", "object_location"])?; + Ok(Built { + scratch: scratch.to_owned(), + scratch_bytes, + dead, + }) +} + +/// The §6.4 live-heads digest, computed inside one transaction (the mark's +/// SQL is the same vector). +fn digest(tx: &Transaction<'_>) -> HistoryResult<[u8; 32]> { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"layerfs/live-heads/v1\0"); + let stacks = tx.query( + "SELECT s.layer_stack_id, s.head_layer_id FROM layer_stack s \ + WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=s.layer_stack_id) \ + ORDER BY s.layer_stack_id", + Vec::new(), + )?; + for row in &stacks { + let id: Vec = row.get(0)?; + let head: Vec = row.get(1)?; + if id.len() != 17 || head.len() != 33 { + return Err(HistoryError::Integrity("live-heads stack width")); + } + hasher.update(&id); + hasher.update(&head); + } + let branches = tx.query( + "SELECT b.branch_id, b.head_commit_id, b.base_layer_id FROM branch b \ + WHERE NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id=b.branch_id) \ + AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id=b.layer_stack_id) \ + ORDER BY b.branch_id", + Vec::new(), + )?; + for row in &branches { + let id: Vec = row.get(0)?; + let head: Option> = row.get(1)?; + let base: Vec = row.get(2)?; + if id.len() != 17 || base.len() != 33 { + return Err(HistoryError::Integrity("live-heads branch width")); + } + hasher.update(&id); + match head { + Some(head) if head.len() == 33 => hasher.update(&head), + Some(_) => return Err(HistoryError::Integrity("live-heads commit width")), + None => hasher.update(&[0u8; 33]), + }; + hasher.update(&base); + } + Ok(*hasher.finalize().as_bytes()) +} + +/// The strength order of §8 step 10: off < local < remote_write < on < +/// remote_apply. +fn sync_rank(setting: &str) -> u8 { + match setting { + "local" => 1, + "remote_write" => 2, + "on" => 3, + "remote_apply" => 4, + _ => 0, + } +} + +fn sync_name(rank: u8) -> &'static str { + match rank { + 1 => "local", + 2 => "remote_write", + 3 => "on", + 4 => "remote_apply", + _ => "off", + } +} + +/// §8 step 10: the swap waits iff the effective level is at least +/// `remote_write` and `synchronous_standby_names` is non-empty; then a named +/// standby must be streaming with `sync_state` sync or quorum. +fn standby_satisfied(rank: u8, names: &str, streaming: i64) -> bool { + if rank < 2 || names.trim().is_empty() { + return true; + } + streaming > 0 +} + +/// The effective `synchronous_commit` and whether the standby predicate +/// applies, read from the server and the Store's frozen setting. +fn effective_sync_rank(session: &Arc) -> HistoryResult { + stage(session, |tx| { + let rows = tx.query("SELECT current_setting('synchronous_commit')", Vec::new())?; + let server: String = rows[0].get(0)?; + let stored = session.settings.synchronous_commit.setting(); + Ok(sync_rank(&server).max(sync_rank(stored))) + }) +} + +/// §8 step 10: the standby predicate checked before Phase M. +fn standby_precheck(session: &Arc, rank: u8) -> HistoryResult<()> { + stage(session, |tx| { + let rows = tx.query( + "SELECT current_setting('synchronous_standby_names')", + Vec::new(), + )?; + let names: String = rows[0].get(0)?; + standby_check(tx, rank, &names) + }) +} + +fn standby_check(tx: &Transaction<'_>, rank: u8, names: &str) -> HistoryResult<()> { + if rank < 2 || names.trim().is_empty() { + return Ok(()); + } + let streaming = scalar( + tx, + "SELECT count(*) FROM pg_stat_replication WHERE state='streaming' AND sync_state IN ('sync','quorum')", + Vec::new(), + )?; + if !standby_satisfied(rank, names, streaming) { + return Err(HistoryError::Busy); + } + Ok(()) +} + +/// The recorded owner backend's state when it is still alive: `idle` means it +/// is not executing the op, so §9's dead-owner rule applies; any other state +/// is a live owner and stays `Busy`. +fn current_backend_pid(session: &Arc) -> HistoryResult { + scalar_session(session, "SELECT pg_backend_pid()", Vec::new()) +} + +fn owner_state(session: &Arc, op: &OpRow) -> HistoryResult> { + let (Some(pid), Some(start)) = (op.pid, op.backend_start.as_deref()) else { + return Ok(None); + }; + stage(session, |tx| { + let rows = tx.query( + "SELECT state::text FROM pg_stat_activity \ + WHERE pid=$1 AND backend_start::text=$2", + vec![Param::I64(pid), Param::Text(start.to_owned())], + )?; + rows.first() + .map(|row| row.get(0)) + .transpose() + .map_err(Into::into) + }) +} + +/// §12 PG privileges and reply: the two-argument `pg_terminate_backend(pid, +/// backend_start)` proof, scoped to this database and never the caller. Used +/// only for a recorded owner the server reports `idle` (it cannot finish the +/// op); a live owner is `Busy`, never killed. +fn terminate_owner(session: &Arc, op: &OpRow) -> HistoryResult { + let (Some(pid), Some(start)) = (op.pid, op.backend_start.as_deref()) else { + return Ok(false); + }; + stage(session, |tx| { + let rows = tx.query( + "SELECT pg_terminate_backend(a.pid, 30000) FROM pg_stat_activity a \ + WHERE a.pid=$1 AND a.backend_start::text=$2 AND a.datname=current_database() \ + AND a.pid<>pg_backend_pid()", + vec![Param::I64(pid), Param::Text(start.to_owned())], + )?; + let terminated: Option = rows.first().map(|row| row.get(0)).transpose()?; + Ok(terminated.unwrap_or(0) != 0) + }) +} + +fn drop_scratch(session: &Arc, scratch: &str) -> HistoryResult<()> { + stage(session, |tx| { + tx.batch(&format!("DROP SCHEMA IF EXISTS {scratch} CASCADE"))?; + Ok(()) + }) +} + +fn compaction_intent(session: &Arc, schema: &str) -> HistoryResult> { + stage(session, |tx| { + let rows = tx.query( + &format!( + "SELECT op_id FROM {schema}.gc_intent WHERE kind='compaction' ORDER BY updated_ms LIMIT 1" + ), + Vec::new(), + )?; + let Some(row) = rows.first() else { + return Ok(None); + }; + let bytes: Vec = row.get(0)?; + let op: [u8; 16] = bytes + .as_slice() + .try_into() + .map_err(|_| HistoryError::Integrity("compaction intent op"))?; + Ok(Some(op)) + }) +} + +/// §9: judge a recorded leftover. `G` removes the artifact and clears the +/// op; `G + 1` finishes Phase C and answers the installed outcome. `None` +/// means there was nothing to resume. +fn settle_leftover( + handles: &PostgresHandles, + session: &Arc, + schema: &str, + metrics: &mut RunMetrics, +) -> HistoryResult> { + let Some(op) = read_op(session, schema)? else { + return Ok(None); + }; + let current = read_generation(session, schema)?; + if current == op.generation { + // The caller's own session is the recorded owner when it retries its + // own uncertain round: adopt it without terminating itself. + if op.pid != Some(current_backend_pid(session)?) { + if let Some(state) = owner_state(session, &op)? { + if state != "idle" { + return Err(HistoryError::Busy); + } + // The backend is alive but not executing the op: terminate it + // with the (pid, backend_start) pair (§12), then adopt it as a + // dead owner. + if !terminate_owner(session, &op)? { + return Err(HistoryError::Busy); + } + } + } + metrics.begin_phase(CompactPhase::PostgresCleanup); + if let Some(artifact) = &op.artifact { + drop_scratch(session, artifact)?; + } + clear_round(session, schema)?; + stage(session, |tx| { + tx.batch(&format!( + "DELETE FROM {schema}.gc_intent WHERE kind='compaction'" + ))?; + Ok(()) + })?; + metrics.end_phase(); + metrics.leftover_settled = true; + return Ok(None); + } + if current != op.generation + 1 { + return Err(HistoryError::Integrity("compaction op generation")); + } + metrics.begin_phase(CompactPhase::PostgresCleanup); + let op_id = compaction_intent(session, schema)?; + cleanup(handles, session, schema, op.dead, op.totals_applied, op_id)?; + metrics.end_phase(); + metrics.leftover_settled = true; + Ok(Some(report( + CompactPath::Rebuild, + u64::try_from(op.generation).unwrap_or(0), + u64::try_from(current).unwrap_or(0), + 0, + 0, + u64::try_from(op.dead.logical).unwrap_or(0), + 0, + 0, + CompactKeptWaste::default(), + 0, + CompactResidue::default(), + 0, + 0, + ))) +} + +/// Phase B: lock every base table, re-check the mark tuple, swap the two +/// payload tables, bump the generation and drop the scratch schema in one +/// short transaction. `55P03` is `Busy`; any tuple change is `Conflict` with +/// no writes. +fn swap( + _handles: &PostgresHandles, + session: &Arc, + schema: &str, + tuple: &GcTuple, + mark: &MarkResult, + built: &Built, +) -> HistoryResult { + let physical_before = relation_bytes(session, schema, &["pack", "object_location"])?; + let rank = effective_sync_rank(session)?; + let tables = tables_of(session, schema)?; + let locked = tables + .iter() + .map(|table| format!("{schema}.{}", quote_ident(table))) + .collect::>() + .join(", "); + let scratch = built.scratch.clone(); + let result = stage(session, |tx| -> HistoryResult { + tx.batch(&format!( + "SET LOCAL synchronous_commit TO {}", + sync_name(rank) + ))?; + tx.batch(&format!( + "LOCK TABLE {locked} IN ACCESS EXCLUSIVE MODE NOWAIT" + ))?; + // The tuple the mark recorded, re-read under the lock. Any publication + // after the mark moved one of these, so nothing is written. + let now = read_tuple(tx, schema)?; + if now != *tuple { + return Err(HistoryError::Conflict("Store moved after the mark")); + } + if digest(tx)? != mark.live_heads_digest() { + return Err(HistoryError::Conflict("live heads moved after the mark")); + } + // Copy the owner (and a default ACL, when one exists) before the swap. + copy_owner(tx, schema, &scratch, "pack")?; + copy_owner(tx, schema, &scratch, "object_location")?; + tx.batch(&format!( + "DROP TABLE {schema}.object_location;\ + DROP TABLE {schema}.pack;\ + ALTER TABLE {scratch}.object_location SET SCHEMA {schema};\ + ALTER TABLE {scratch}.pack SET SCHEMA {schema};\ + CREATE TRIGGER pack_immutable BEFORE UPDATE OR DELETE ON {schema}.pack \ + FOR EACH ROW EXECUTE FUNCTION {schema}.pack_immutable();" + ))?; + verify_swap(tx, schema, mark, tuple, &built.dead)?; + let applied = scalar( + tx, + &format!("SELECT totals_applied FROM {schema}.gc_op WHERE id=1"), + Vec::new(), + )?; + if applied != 0 { + return Err(HistoryError::Integrity("compaction totals already applied")); + } + tx.query( + &format!( + "UPDATE {schema}.gc_op SET phase='swap',dead_canonical=$1,dead_stored=$2,dead_metadata=$3 WHERE id=1" + ), + vec![ + Param::I64(built.dead.canonical), + Param::I64(built.dead.stored), + Param::I64(built.dead.metadata), + ], + )?; + tx.query( + &format!( + "UPDATE {schema}.history_meta SET catalog_incarnation={} WHERE id=1", + tuple.generation + 1 + ), + Vec::new(), + )?; + tx.batch(&format!("DROP SCHEMA {scratch} CASCADE"))?; + let names: String = tx + .query( + "SELECT current_setting('synchronous_standby_names')", + Vec::new(), + )? + .first() + .ok_or(HistoryError::Integrity("standby names"))? + .get(0)?; + standby_check(tx, rank, &names)?; + Ok(Swapped { + physical_before, + physical_after: 0, + peak_temp: built.scratch_bytes, + dead: built.dead, + }) + }); + let result = match result { + Ok(swapped) => swapped, + Err(HistoryError::Busy) => { + // §8 step 5: roll back first, then drop the scratch schema in a + // new transaction, and report Busy with the holder detail. + let _ = drop_scratch(session, &scratch); + return Err(HistoryError::Busy); + } + Err(other) => return Err(other), + }; + let physical_after = relation_bytes(session, schema, &["pack", "object_location"])?; + Ok(Swapped { + physical_after, + ..result + }) +} + +fn tables_of(session: &Arc, schema: &str) -> HistoryResult> { + stage(session, |tx| { + let rows = tx.query( + "SELECT c.relname::text FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace \ + WHERE n.nspname=$1 AND c.relkind='r' ORDER BY c.relname", + vec![Param::Text(schema.to_owned())], + )?; + rows.iter() + .map(|row| row.get::(0).map_err(HistoryError::from)) + .collect() + }) +} + +fn read_tuple(tx: &Transaction<'_>, schema: &str) -> HistoryResult { + let rows = tx.query( + &format!( + "SELECT h.catalog_incarnation,h.next_history_serial,p.next_pack_id,p.next_ordinal,\ + t.logical,t.canonical,t.stored,t.metadata,\ + (SELECT COALESCE(MAX(stamp),0) FROM {schema}.content_signature),\ + (SELECT COUNT(*) FROM {schema}.\"commit\")+(SELECT COUNT(*) FROM {schema}.layer) \ + FROM {schema}.history_meta h, {schema}.store_policy p, {schema}.store_totals t \ + WHERE h.id=1 AND p.id=1 AND t.id=1" + ), + Vec::new(), + )?; + if rows.len() != 1 { + return Err(HistoryError::Integrity("Store tuple")); + } + let row = &rows[0]; + Ok(GcTuple { + generation: row.get(0)?, + next_history_serial: row.get(1)?, + next_pack_id: row.get(2)?, + next_ordinal: row.get(3)?, + logical: row.get(4)?, + canonical: row.get(5)?, + stored: row.get(6)?, + metadata: row.get(7)?, + stamp: row.get(8)?, + history_rows: row.get(9)?, + }) +} + +fn copy_owner(tx: &Transaction<'_>, schema: &str, scratch: &str, table: &str) -> HistoryResult<()> { + let rows = tx.query( + "SELECT pg_get_userbyid(c.relowner)::text, COALESCE(array_to_string(c.relacl,E'\\n'),'') \ + FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace \ + WHERE n.nspname=$1 AND c.relname=$2", + vec![ + Param::Text(schema.to_owned()), + Param::Text(table.to_owned()), + ], + )?; + if rows.len() != 1 { + return Err(HistoryError::Integrity("compaction owner")); + } + let owner: String = rows[0].get(0)?; + tx.batch(&format!( + "ALTER TABLE {scratch}.{} OWNER TO {}", + quote_ident(table), + quote_ident(&owner) + ))?; + let acl: String = rows[0].get(1)?; + for line in acl.lines().filter(|line| !line.is_empty()) { + if let Some(grant) = grant_of(line, schema, table) { + tx.batch(&grant)?; + } + } + Ok(()) +} + +/// One `relacl` entry as a `GRANT` on `schema.table`, or `None` when the +/// entry is the owner's own implicit grant (`owner=arwdDxt/owner`). +fn grant_of(line: &str, schema: &str, table: &str) -> Option { + let (grantee, rest) = line.split_once('=')?; + let (privileges, grantor) = rest.split_once('/')?; + if grantee.is_empty() { + return None; + } + // The owner's implicit self-grant is re-created by ALTER TABLE OWNER. + if grantee == grantor { + return None; + } + let names: Vec<&str> = privileges + .chars() + .filter_map(|letter| { + Some(match letter { + 'r' => "SELECT", + 'w' => "UPDATE", + 'a' => "INSERT", + 'd' => "DELETE", + 'D' => "TRUNCATE", + 'x' => "REFERENCES", + 't' => "TRIGGER", + _ => return None, + }) + }) + .collect(); + if names.is_empty() { + return None; + } + let target = if grantee.is_empty() { + "PUBLIC".to_owned() + } else { + quote_ident(grantee) + }; + Some(format!( + "GRANT {} ON TABLE {schema}.{} TO {target}", + names.join(","), + quote_ident(table) + )) +} + +fn verify_swap( + tx: &Transaction<'_>, + schema: &str, + mark: &MarkResult, + tuple: &GcTuple, + dead: &DeadTotals, +) -> HistoryResult<()> { + let objects = scalar( + tx, + &format!("SELECT count(*) FROM {schema}.object_location"), + Vec::new(), + )?; + let distinct = scalar( + tx, + &format!("SELECT count(DISTINCT object_id) FROM {schema}.object_location"), + Vec::new(), + )?; + let packs = scalar( + tx, + &format!("SELECT count(*) FROM {schema}.pack"), + Vec::new(), + )?; + if objects != mark.objects().len() as i64 + || distinct != objects + || packs != mark.objects().packs().len() as i64 + { + return Err(HistoryError::Integrity("compaction swapped count")); + } + let canonical = scalar( + tx, + &format!("SELECT COALESCE(SUM(canonical_length)::bigint,0) FROM {schema}.object_location"), + Vec::new(), + )?; + let stored = scalar( + tx, + &format!("SELECT COALESCE(SUM(length)::bigint,0) FROM {schema}.pack"), + Vec::new(), + )?; + let metadata = scalar( + tx, + &format!("SELECT COALESCE(SUM(length)::bigint,0) FROM {schema}.pack WHERE domain=0"), + Vec::new(), + )?; + if canonical != tuple.canonical - dead.canonical + || stored != tuple.stored - dead.stored + || metadata != tuple.metadata - dead.metadata + { + return Err(HistoryError::Integrity("compaction swapped totals")); + } + let logical = scalar( + tx, + &format!("SELECT logical FROM {schema}.store_totals WHERE id=1"), + Vec::new(), + )?; + let sum = scalar( + tx, + &format!( + "SELECT (SELECT COALESCE(SUM(logical)::bigint,0) FROM {schema}.\"commit\")+(SELECT COALESCE(SUM(logical)::bigint,0) FROM {schema}.layer)" + ), + Vec::new(), + )?; + if logical != sum { + return Err(HistoryError::Integrity( + "Store totals disagree with the history rows", + )); + } + if digest(tx)? != mark.live_heads_digest() { + return Err(HistoryError::Conflict("live heads moved after the mark")); + } + Ok(()) +} + +/// Phase C: delete only the persisted `gc_dead` members, settle the totals +/// once, and clear the op. The Store is usable at `G + 1` throughout. +fn cleanup( + handles: &PostgresHandles, + session: &Arc, + schema: &str, + dead: DeadTotals, + totals_applied: bool, + op_id: Option<[u8; 16]>, +) -> HistoryResult<()> { + stage(session, |tx| { + tx.batch(&format!( + "DELETE FROM {schema}.\"commit\" c WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='commit' AND d.id=c.commit_id);\ + DELETE FROM {schema}.layer l WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='layer' AND d.id=l.layer_id);\ + DELETE FROM {schema}.branch b WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='branch' AND d.id=b.branch_id);\ + DELETE FROM {schema}.layer_stack s WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='stack' AND d.id=s.layer_stack_id);\ + DELETE FROM {schema}.layer_lineage ll WHERE NOT EXISTS (SELECT 1 FROM {schema}.layer l WHERE l.layer_id=ll.layer_id);\ + DELETE FROM {schema}.commit_lineage cl WHERE NOT EXISTS (SELECT 1 FROM {schema}.\"commit\" c WHERE c.commit_id=cl.commit_id);\ + DELETE FROM {schema}.absorbed a WHERE NOT EXISTS (SELECT 1 FROM {schema}.commit_lineage cl WHERE cl.run=a.run);\ + DELETE FROM {schema}.reach r WHERE r.key NOT IN (SELECT layer_stack_id FROM {schema}.layer_stack UNION SELECT run FROM {schema}.commit_lineage);\ + DELETE FROM {schema}.branch_retired br WHERE NOT EXISTS (SELECT 1 FROM {schema}.branch b WHERE b.branch_id=br.branch_id);\ + DELETE FROM {schema}.layer_stack_retired lr WHERE NOT EXISTS (SELECT 1 FROM {schema}.layer_stack s WHERE s.layer_stack_id=lr.layer_stack_id);\ + DELETE FROM {schema}.path_removed pr WHERE NOT EXISTS (SELECT 1 FROM {schema}.layer_stack s WHERE s.layer_stack_id=pr.layer_stack_id);\ + DELETE FROM {schema}.project_epoch pe WHERE NOT EXISTS (SELECT 1 FROM {schema}.layer_stack s WHERE s.layer_stack_id=pe.layer_stack_id);\ + DELETE FROM {schema}.content_signature cs WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='signature' AND d.id=int8send(cs.slot));\ + DELETE FROM {schema}.file_digest fd WHERE EXISTS (SELECT 1 FROM {schema}.gc_dead d WHERE d.kind='digest' AND d.id=fd.digest);\ + DELETE FROM {schema}.binding_hint_block;\ + DELETE FROM {schema}.init_operation;\ + DELETE FROM {schema}.init_entry;\ + DELETE FROM {schema}.init_host_file;" + ))?; + if !totals_applied { + tx.query( + &format!( + "UPDATE {schema}.store_totals SET \ + canonical=canonical-$1,stored=stored-$2,metadata=metadata-$3,logical=logical-$4 WHERE id=1" + ), + vec![ + Param::I64(dead.canonical), + Param::I64(dead.stored), + Param::I64(dead.metadata), + Param::I64(dead.logical), + ], + )?; + tx.query( + &format!( + "UPDATE {schema}.gc_op SET totals_applied=TRUE,phase='cleanup' WHERE id=1" + ), + Vec::new(), + )?; + } + let totals = tx.query( + &format!( + "SELECT logical,canonical,stored,metadata FROM {schema}.store_totals WHERE id=1" + ), + Vec::new(), + )?; + let logical: i64 = totals[0].get(0)?; + let canonical: i64 = totals[0].get(1)?; + let stored: i64 = totals[0].get(2)?; + let metadata: i64 = totals[0].get(3)?; + let sums = tx.query( + &format!( + "SELECT (SELECT COALESCE(SUM(logical)::bigint,0) FROM {schema}.\"commit\")+(SELECT COALESCE(SUM(logical)::bigint,0) FROM {schema}.layer),\ + (SELECT COALESCE(SUM(canonical_length)::bigint,0) FROM {schema}.object_location),\ + (SELECT COALESCE(SUM(length)::bigint,0) FROM {schema}.pack),\ + (SELECT COALESCE(SUM(length)::bigint,0) FROM {schema}.pack WHERE domain=0)" + ), + Vec::new(), + )?; + let sum_logical: i64 = sums[0].get(0)?; + let sum_canonical: i64 = sums[0].get(1)?; + let sum_stored: i64 = sums[0].get(2)?; + let sum_metadata: i64 = sums[0].get(3)?; + if logical != sum_logical + || canonical != sum_canonical + || stored != sum_stored + || metadata != sum_metadata + { + return Err(HistoryError::Integrity("compaction settled totals")); + } + tx.batch(&format!( + "DELETE FROM {schema}.gc_dead; DELETE FROM {schema}.gc_op;" + ))?; + Ok(()) + })?; + if let Some(op) = op_id { + let _ = handles.history.gc_release(&op); + } else { + stage(session, |tx| { + tx.batch(&format!( + "DELETE FROM {schema}.gc_intent WHERE kind='compaction'" + ))?; + Ok(()) + })?; + } + Ok(()) +} + +/// One round after admission: mark, decide, build, swap, cleanup. +fn round( + handles: &PostgresHandles, + session: &Arc, + schema: &str, + request: &CompactRequest, + metrics: &mut RunMetrics, +) -> HistoryResult { + metrics.begin_phase(CompactPhase::PostgresMark); + let (mark, tuple) = handles.history.mark_gc()?; + load_visited(session, schema, &mark)?; + let stored = u64::try_from(total_stored(session, schema)?).unwrap_or(0); + let live = u64::try_from(live_stored(session, schema)?).unwrap_or(0); + let dead_bytes = stored.saturating_sub(live); + let scratch = scratch_name(&request.op_id); + let mark_dead = persist_mark(session, schema, &mark, &tuple, &scratch, request)?; + let generation = u64::try_from(tuple.generation).unwrap_or(0); + let kept = CompactKeptWaste { + dead_in_retained_packs_bytes: mark.objects().waste().dead_in_retained_packs_bytes(), + delta_bases_bytes: mark.objects().waste().delta_bases_bytes(), + delta_base_references: mark + .objects() + .waste() + .delta_base_references() + .iter() + .map(|id| *id.as_bytes()) + .collect(), + inode_blocks_bytes: mark.objects().waste().inode_blocks_bytes(), + }; + let rebuild = stored > 0 && dead_bytes.saturating_mul(THRESHOLD) >= stored; + if !rebuild { + metrics.end_phase(); + clear_round(session, schema)?; + let _ = handles.history.gc_release(&request.op_id); + return Ok(report( + CompactPath::None, + generation, + generation, + dead_bytes, + dead_bytes, + 0, + 0, + 0, + kept, + 0, + CompactResidue::default(), + stored, + mark.history().len() as u64, + )); + } + metrics.end_phase(); + stop( + request, + CompactFailpoint::PostgresAfterMark, + session, + schema, + "mark", + )?; + metrics.begin_phase(CompactPhase::PostgresBuild); + let mut built = build(session, schema, &scratch, &mark, &tuple)?; + metrics.end_phase(); + built.dead.logical = mark_dead.logical; + stop( + request, + CompactFailpoint::PostgresAfterBuild, + session, + schema, + "build", + )?; + metrics.begin_phase(CompactPhase::PostgresSwap); + let swapped = swap(handles, session, schema, &tuple, &mark, &built)?; + metrics.end_phase(); + stop( + request, + CompactFailpoint::PostgresAfterSwap, + session, + schema, + "swap", + )?; + let logical_discarded = u64::try_from(swapped.dead.logical).unwrap_or(0); + metrics.begin_phase(CompactPhase::PostgresCleanup); + cleanup( + handles, + session, + schema, + swapped.dead, + false, + Some(request.op_id), + )?; + metrics.end_phase(); + stop( + request, + CompactFailpoint::PostgresAfterCleanup, + session, + schema, + "cleanup", + )?; + let shrink = swapped + .physical_before + .saturating_sub(swapped.physical_after); + Ok(report( + CompactPath::Rebuild, + generation, + generation + 1, + dead_bytes, + dead_bytes, + logical_discarded, + 0, + shrink, + kept, + swapped.peak_temp, + CompactResidue::default(), + stored, + mark.history().len() as u64, + )) +} + +#[allow(clippy::too_many_arguments)] +fn report( + path: CompactPath, + generation_before: u64, + generation_after: u64, + dead_bytes: u64, + dead_refined: u64, + logical_discarded: u64, + backend_reusable: u64, + physical_shrink: u64, + kept_waste: CompactKeptWaste, + peak_temp_bytes: u64, + residue: CompactResidue, + total_stored: u64, + history_rows: u64, +) -> CompactReceipt { + let mut zero_reasons = Vec::new(); + if dead_bytes == 0 { + let reason = if total_stored == 0 { + "empty-store" + } else { + "no-waste" + }; + zero_reasons.push(CompactZeroReason { + field: "deadBytesBound", + reason, + }); + zero_reasons.push(CompactZeroReason { + field: "deadBytesRefined", + reason, + }); + } + if logical_discarded == 0 { + let reason = if history_rows == 0 { + "no-history" + } else if path == CompactPath::None { + "none-path" + } else { + "no-waste" + }; + zero_reasons.push(CompactZeroReason { + field: "logicalDiscarded", + reason, + }); + } + if physical_shrink == 0 { + zero_reasons.push(CompactZeroReason { + field: "physicalShrink", + reason: if path == CompactPath::None { + "none-path" + } else { + "no-waste" + }, + }); + } + zero_reasons.push(CompactZeroReason { + field: "backendReusable", + reason: "postgresql-in-place", + }); + if kept_waste.is_empty() { + zero_reasons.push(CompactZeroReason { + field: "keptWaste", + reason: "no-waste", + }); + } + if peak_temp_bytes == 0 { + zero_reasons.push(CompactZeroReason { + field: "peakTempBytes", + reason: "none-path", + }); + } + CompactReceipt { + path, + generation_before, + generation_after, + dead_bytes_bound: dead_bytes, + dead_bytes_refined: dead_refined, + logical_discarded, + backend_reusable, + physical_shrink, + kept_waste, + peak_temp_bytes, + residue, + estimate: true, + zero_reasons, + } +} + +impl PostgresHandles { + /// Runs one §8 PostgreSQL Store compaction on this Store's session. + /// + /// The call takes the Store's exclusive intent (a session advisory key) + /// through cleanup, marks at `G`, and on the rebuild path copies the two + /// payload tables, swaps them in one short transaction at `G + 1`, and + /// deletes only the persisted dead set. The caller keeps its session; the + /// Store is usable at `G + 1` from the swap on. + pub fn compact(&self, request: &CompactRequest) -> HistoryResult { + let mut metrics = RunMetrics::start(); + let result = self.compact_measured(request, &mut metrics); + metrics.finish(&result); + result + } + + /// The measured body of [`Self::compact`]; `metrics` observes it. + fn compact_measured( + &self, + request: &CompactRequest, + metrics: &mut RunMetrics, + ) -> HistoryResult { + let session = self.storage.session.clone(); + let schema = session.settings.schema.clone(); + // AC-44: a restricted role is refused before the intent, the mark and + // the scratch schema; the missing privilege is named, never a raw + // `42501` from whichever statement happened to run first. + if let Some(missing) = compaction_missing(&session)? { + return Err(HistoryError::Unsupported(missing)); + } + let generation = read_generation(&session, &schema)?; + metrics.generation_before = u64::try_from(generation).unwrap_or(0); + if let Some(receipt) = settle_leftover(self, &session, &schema, metrics)? { + return Ok(receipt); + } + let intent = GcIntent::operation( + request.op_id, + GcIntentKind::Compaction, + GcScopeKind::Store, + self.history.catalog_id.as_slice().to_vec(), + ) + .owned( + request.owner_runtime.as_deref(), + request.owner_boot.as_deref(), + ) + .with_phase(Some("mark")); + self.history.gc_register(&intent)?; + let result = (|| { + let rank = effective_sync_rank(&session)?; + standby_precheck(&session, rank)?; + round(self, &session, &schema, request, metrics) + })(); + if result.is_err() { + let _ = self.history.gc_release(&request.op_id); + } + result + } +} + +#[cfg(test)] +mod tests { + use super::{standby_satisfied, sync_name, sync_rank}; + + #[test] + fn the_standby_predicate_waits_only_for_a_named_standby() { + // Below remote_write, or with no names, no standby is required. + assert!(standby_satisfied(0, "", 0)); + assert!(standby_satisfied(1, "", 0)); + assert!(standby_satisfied(2, "", 0)); + assert!(standby_satisfied(4, " ", 0)); + // At or above remote_write with names, a streaming sync/quorum + // standby must exist. + assert!(!standby_satisfied(2, "FIRST 1 (s1)", 0)); + assert!(!standby_satisfied(4, "ANY 1 (s1)", 0)); + assert!(standby_satisfied(2, "FIRST 1 (s1)", 1)); + assert!(standby_satisfied(3, "ANY 2 (s1,s2)", 1)); + } + + #[test] + fn synchronous_commit_strength_is_the_spec_order() { + assert_eq!(sync_rank("off"), 0); + assert_eq!(sync_rank("local"), 1); + assert_eq!(sync_rank("remote_write"), 2); + assert_eq!(sync_rank("on"), 3); + assert_eq!(sync_rank("remote_apply"), 4); + assert_eq!(sync_name(4), "remote_apply"); + assert_eq!(sync_name(0), "off"); + } +} diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/history/statements.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/history/statements.rs index 0063bf9f73..bc66630699 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/history/statements.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/history/statements.rs @@ -12,6 +12,30 @@ pub(crate) fn statement(key: &str) -> Result<&'static str, BackendError> { "statistics_totals" => Ok(include_str!( "../../../../sql/postgresql/queries/history/statistics_totals.sql" )), + "gc_epoch_read" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_epoch_read.sql" + )), + "gc_epoch_share" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_epoch_share.sql" + )), + "gc_lock_xact_shared" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_lock_xact_shared.sql" + )), + "gc_lock_xact_exclusive" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_lock_xact_exclusive.sql" + )), + "gc_lock_session_shared" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_lock_session_shared.sql" + )), + "gc_lock_session_exclusive" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_lock_session_exclusive.sql" + )), + "gc_unlock_session_shared" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_unlock_session_shared.sql" + )), + "gc_unlock_session_exclusive" => Ok(include_str!( + "../../../../sql/postgresql/queries/history/gc_unlock_session_exclusive.sql" + )), other => crate::backend::sqlite::session::query::history(other), } } diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/mechanics.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/mechanics.rs index 7189700f7e..3bca07b93e 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/mechanics.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/mechanics.rs @@ -16,6 +16,9 @@ use layerfs_storage::{ use postgres::types::ToSql; impl HistoryStatements for Transaction<'_> { + fn mechanics(&self) -> &dyn Mechanics { + self + } fn history(&self, key: &str, params: Vec) -> Result, BackendError> { match history::statements::qualified(key) { Some(sql) => self.query(&sql.replace("{s}", self.schema), params), diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/mod.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/mod.rs index 98439899fc..74225ff555 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/mod.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/mod.rs @@ -2,6 +2,7 @@ //! lane, objects, metadata and history statements, and Init's acquisition. pub(crate) mod access; pub(crate) mod acquisition; +pub(crate) mod compact; pub(crate) mod history; pub(crate) mod lane; mod mechanics; diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/schema.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/schema.rs index 329a1c5568..6bc014d0e9 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/schema.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/schema.rs @@ -9,10 +9,17 @@ //! tables are absent: group-row layouts are SQLite physical choices. A //! schema made by [`create`] also has Init's acquisition tables (#533 step //! 10b, `acquisition.sql`), recorded in its schema source; one an earlier -//! release imported from SQLite has none and refuses acquisition. A merge's -//! records live in the writer connection's temporary tables +//! release imported from SQLite has none and refuses acquisition. A Store +//! written before the GC tables gains them at its first writable open +//! ([`add_gc`]), and one written before the position columns gains them, +//! with the T1.4 serial backfill, at that same open +//! ([`add_position_columns`]); any other schema mismatch is still refused. +//! A merge's records live in the writer connection's temporary tables //! (`merge_records.rs`), not here. -use super::session::{connection::Session, transaction::Transaction}; +use super::session::{ + connection::Session, + transaction::{Mode, Transaction}, +}; use crate::backend::records::{BackendError, Param}; use crate::PostgresCheck; use layerfs_history::{CatalogId, HistoryCatalogConfig}; @@ -22,7 +29,24 @@ use postgres::SimpleQueryRow; #[path = "schema_diagnostic.rs"] mod diagnostic; -pub(crate) const SCHEMA: &str = include_str!("../../../sql/postgresql/schema.sql"); +pub(crate) const SCHEMA: &str = concat!( + include_str!("../../../sql/postgresql/schema.sql"), + include_str!("../../../sql/postgresql/gc.sql") +); +/// The Store tables a schema had before the GC tables ([`GC`]) were appended. +const PRE_GC_SCHEMA: &str = include_str!("../../../sql/postgresql/schema.sql"); +/// The `history_meta` position column as `schema.sql` writes it; it sits on +/// its own line, so removing the line leaves the text an older Store recorded. +const NEXT_SERIAL: &str = " next_history_serial bigint NOT NULL DEFAULT 1,\n"; +/// The `commit` and `layer` position column as `schema.sql` writes it; it +/// sits on its own line in each of the two tables. +const HISTORY_SERIAL: &str = " history_serial bigint NOT NULL DEFAULT 0,\n"; +/// The `store_policy` position salt column, with the comma the column before +/// it gains, as `schema.sql` writes them; it ends that table's column list. +const TRACE_SALT: &str = ",\n trace_salt bytea NOT NULL DEFAULT decode(repeat('00',32),'hex') CHECK (length(trace_salt)=32)"; +/// The GC marker, position and admission tables; a Store written before them +/// gains them at open ([`add_gc`]). +const GC: &str = include_str!("../../../sql/postgresql/gc.sql"); /// Init's acquisition tables, created after [`SCHEMA`] in a new schema. const ACQUISITION: &str = include_str!("../../../sql/postgresql/acquisition.sql"); /// The acquisition tables, in name order. @@ -32,8 +56,38 @@ const ACQUISITION_TABLES: [&str; 3] = ["init_entry", "init_host_file", "init_ope /// (#91) and object locations in narrow rows under an 8-byte-prefix index /// (#90); a version 1 schema is refused at open, never converted. pub(crate) const SCHEMA_VERSION: i64 = 2; -/// Every table of one Store schema. -pub(crate) const TABLES: [&str; 19] = [ +/// Every table of one Store schema, in name order. +pub(crate) const TABLES: [&str; 27] = [ + "absorbed", + "binding_hint_block", + "branch", + "branch_retired", + "commit", + "commit_lineage", + "content_signature", + "file_digest", + "gc_dead", + "gc_intent", + "gc_op", + "history_meta", + "inode_value_block", + "kept_node", + "layer", + "layer_lineage", + "layer_stack", + "layer_stack_retired", + "object_location", + "pack", + "path_removed", + "project_epoch", + "reach", + "scope_allocator", + "store_lane", + "store_policy", + "store_totals", +]; +/// The tables a Store schema had before the GC tables were appended. +const PRE_GC_TABLES: [&str; 19] = [ "absorbed", "binding_hint_block", "branch", @@ -77,10 +131,41 @@ fn source(acquisition: bool) -> String { } } +/// The recorded schema source of a Store written before the GC tables. +fn pre_gc_source(acquisition: bool) -> String { + match acquisition { + true => format!("{PRE_GC_SCHEMA}{ACQUISITION}"), + false => PRE_GC_SCHEMA.to_owned(), + } +} + +/// `text` as a Store wrote it before the position columns ([`HISTORY_SERIAL`] +/// in `commit` and `layer`, [`TRACE_SALT`] in `store_policy`) existed. +fn without_position_columns(text: String) -> String { + text.replacen(HISTORY_SERIAL, "", 2) + .replacen(TRACE_SALT, "", 1) +} + +/// Whether `recorded` is `current` or an earlier revision of it a Store may +/// have written: before [`NEXT_SERIAL`], before the position columns, or +/// before both. An additive migration matches one of those and refuses any +/// text no release wrote. +fn is_earlier_source(recorded: &str, current: String) -> bool { + let without_columns = without_position_columns(current.clone()); + [ + current.clone(), + current.replacen(NEXT_SERIAL, "", 1), + without_columns.clone(), + without_columns.replacen(NEXT_SERIAL, "", 1), + ] + .iter() + .any(|revision| revision == recorded) +} + /// Creates the new schema `tx.schema` with the Store and acquisition tables, -/// its policy row and its catalog row, inside the caller's transaction. A -/// schema of that name that already exists is refused before anything is -/// written; nothing is merged into it. +/// its policy row with one random trace salt and its catalog row, inside the +/// caller's transaction. A schema of that name that already exists is +/// refused before anything is written; nothing is merged into it. pub(crate) fn create( tx: &Transaction<'_>, policy: StoragePolicy, @@ -101,7 +186,7 @@ pub(crate) fn create( "CREATE SCHEMA {name}; SET LOCAL search_path TO {name}; {SCHEMA}{ACQUISITION}" ))?; tx.query( - "INSERT INTO store_policy(id,schema_version,format_profile,small_file_threshold_bytes,whole_file_delta_max_depth,chunk_delta_max_depth,metadata_delta_max_depth) VALUES(1,$1,$2,$3,$4,$5,$6)", + "INSERT INTO store_policy(id,schema_version,format_profile,small_file_threshold_bytes,whole_file_delta_max_depth,chunk_delta_max_depth,metadata_delta_max_depth,trace_salt) VALUES(1,$1,$2,$3,$4,$5,$6,decode(md5(random()::text||clock_timestamp()::text)||md5(clock_timestamp()::text||random()::text),'hex'))", vec![ Param::I64(SCHEMA_VERSION), Param::I64(i64::from(policy.format_profile())), @@ -126,6 +211,338 @@ pub(crate) fn create( Ok(()) } +/// The `kept_node` table as `gc.sql` writes it: one statement appended to the +/// GC script, so removing exactly this text leaves the source a Store written +/// before T7.1 recorded. +fn kept_node_table() -> &'static str { + let start = GC + .find("CREATE TABLE kept_node (") + .expect("the GC schema holds kept_node"); + let end = start + GC[start..].find(";\n").expect("kept_node ends") + 2; + &GC[start..end] +} + +/// The recorded source of a Store written before [`kept_node_table`]: the +/// current source with that one statement removed. +fn pre_kept_node_source(acquisition: bool) -> String { + source(acquisition).replacen(kept_node_table(), "", 1) +} + +/// Adds the `kept_node` history-closure table (T7.1) to a Store written +/// before it, then records the current schema: an additive migration under +/// the same conditions as [`add_gc`]. A schema that already has the table is +/// left alone; a recorded source or definition that is not an earlier +/// revision of the current one is refused, never migrated. The table is empty +/// until a mark writes it. +pub(crate) fn add_kept_node(session: &Session) -> Result<(), PersistenceError> { + // A Store that already has the table is left alone: one statement, no + // transaction and no lane wait. + let present = session.run_as::<_, BackendError>(Mode::Statement, |tx| { + let sql = format!( + "SELECT 1 FROM information_schema.tables WHERE table_schema='{}' AND table_name='kept_node' AND table_type='BASE TABLE'", + tx.schema + ); + Ok(!tx.query(&sql, vec![])?.is_empty()) + })?; + if present { + return Ok(()); + } + session.run_as(Mode::Write, |tx| -> Result<(), PersistenceError> { + // Re-check under the lane: another process may have migrated first. + let present = tx.query( + "SELECT 1 FROM information_schema.tables WHERE table_schema=current_schema() AND table_name='kept_node' AND table_type='BASE TABLE'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let [row] = rows.as_slice() else { + return Err(BackendError::Integrity.into()); + }; + let recorded_source: String = row.get(0)?; + let acquisition = if is_earlier_source(&recorded_source, pre_kept_node_source(false)) { + false + } else if is_earlier_source(&recorded_source, pre_kept_node_source(true)) { + true + } else { + return Err(BackendError::Integrity.into()); + }; + if row.get::(1)? != definition(tx)? { + return Err(BackendError::Integrity.into()); + } + tx.batch(kept_node_table())?; + let definition = definition(tx)?; + tx.query( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2 WHERE id=1", + vec![Param::Text(source(acquisition)), Param::Text(definition)], + )?; + Ok(()) + }) +} + +/// Adds the GC marker, position and admission tables to a Store written +/// before them, then records the current schema: an additive migration under +/// the same conditions as the SQLite Store's `add_gc`. A schema that already +/// has `gc_intent` is left alone; a recorded source, table set or definition +/// that is not the pre-GC schema is refused, never migrated. +pub(crate) fn add_gc(session: &Session) -> Result<(), PersistenceError> { + // A Store that already has the GC tables is left alone: one statement, + // no transaction and no lane wait. + let present = session.run_as::<_, BackendError>(Mode::Statement, |tx| { + let sql = format!( + "SELECT 1 FROM information_schema.tables WHERE table_schema='{}' AND table_name='gc_intent' AND table_type='BASE TABLE'", + tx.schema + ); + Ok(!tx.query(&sql, vec![])?.is_empty()) + })?; + if present { + return Ok(()); + } + session.run_as(Mode::Write, |tx| -> Result<(), PersistenceError> { + // Re-check under the lane: another process may have migrated first. + let present = tx.query( + "SELECT 1 FROM information_schema.tables WHERE table_schema=current_schema() AND table_name='gc_intent' AND table_type='BASE TABLE'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let [row] = rows.as_slice() else { + return Err(BackendError::Integrity.into()); + }; + let recorded_source: String = row.get(0)?; + let acquisition = if is_earlier_source(&recorded_source, pre_gc_source(false)) { + false + } else if is_earlier_source(&recorded_source, pre_gc_source(true)) { + true + } else { + return Err(BackendError::Integrity.into()); + }; + let tables = tx.query(TABLE_NAMES, vec![])?; + let actual: Vec = tables.iter().map(|r| r.get(0)).collect::>()?; + let mut expected = PRE_GC_TABLES.to_vec(); + if acquisition { + expected.extend(ACQUISITION_TABLES); + } + expected.sort_unstable(); + if !actual.iter().map(String::as_str).eq(expected) { + return Err(BackendError::Integrity.into()); + } + if row.get::(1)? != definition(tx)? { + return Err(BackendError::Integrity.into()); + } + tx.batch(GC)?; + let definition = definition(tx)?; + tx.query( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2 WHERE id=1", + vec![Param::Text(source(acquisition)), Param::Text(definition)], + )?; + Ok(()) + }) +} + +/// Adds the position column `history_meta.next_history_serial` (T1.4) to a +/// Store written before it, then records the current schema: an additive +/// migration under the same conditions as [`add_gc`]. A schema that already +/// has the column is left alone; a recorded source or definition that is not +/// an earlier revision of the current one is refused, never migrated. The +/// `commit`/`layer` serial columns and their backfill follow in +/// [`add_position_columns`], the next step of the same open; only the column +/// and one `project_epoch` row per project are recorded here. +pub(crate) fn add_position_state(session: &Session) -> Result<(), PersistenceError> { + // A Store that already has the column is left alone: one statement, no + // transaction and no lane wait. + let present = session.run_as::<_, BackendError>(Mode::Statement, |tx| { + let sql = format!( + "SELECT 1 FROM information_schema.columns WHERE table_schema='{}' AND table_name='history_meta' AND column_name='next_history_serial'", + tx.schema + ); + Ok(!tx.query(&sql, vec![])?.is_empty()) + })?; + if present { + return Ok(()); + } + session.run_as(Mode::Write, |tx| -> Result<(), PersistenceError> { + // Re-check under the lane: another process may have migrated first. + let present = tx.query( + "SELECT 1 FROM information_schema.columns WHERE table_schema=current_schema() AND table_name='history_meta' AND column_name='next_history_serial'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let [row] = rows.as_slice() else { + return Err(BackendError::Integrity.into()); + }; + let recorded_source: String = row.get(0)?; + let acquisition = if is_earlier_source(&recorded_source, source(false)) { + false + } else if is_earlier_source(&recorded_source, source(true)) { + true + } else { + return Err(BackendError::Integrity.into()); + }; + if row.get::(1)? != definition(tx)? { + return Err(BackendError::Integrity.into()); + } + tx.batch("ALTER TABLE history_meta ADD COLUMN next_history_serial bigint NOT NULL DEFAULT 1;")?; + tx.batch( + "INSERT INTO project_epoch(layer_stack_id, epoch) SELECT s.layer_stack_id, 0 FROM layer_stack s WHERE NOT EXISTS (SELECT 1 FROM project_epoch e WHERE e.layer_stack_id = s.layer_stack_id);", + )?; + let definition = definition(tx)?; + tx.query( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2 WHERE id=1", + vec![Param::Text(source(acquisition)), Param::Text(definition)], + )?; + Ok(()) + }) +} + +/// The ALTERs an old Store needs for the position columns, the one random +/// trace salt, and the T1.4 serial backfill. `gen_random_bytes` is used when +/// the server can reach it; without pgcrypto two md5 digests of the clock and +/// `random()` stand in for the same 32 bytes. +const POSITION_COLUMNS: &str = concat!( + "ALTER TABLE \"commit\" ADD COLUMN history_serial bigint NOT NULL DEFAULT 0;", + "ALTER TABLE layer ADD COLUMN history_serial bigint NOT NULL DEFAULT 0;", + "ALTER TABLE store_policy ADD COLUMN trace_salt bytea NOT NULL DEFAULT decode(repeat('00',32),'hex') CHECK (length(trace_salt)=32);", + "DO $$ BEGIN ", + "UPDATE store_policy SET trace_salt=gen_random_bytes(32) WHERE id=1; ", + "EXCEPTION WHEN undefined_function THEN ", + "UPDATE store_policy SET trace_salt=decode(md5(random()::text||clock_timestamp()::text)||md5(clock_timestamp()::text||random()::text),'hex') WHERE id=1; ", + "END $$;" +); + +/// Adds the position columns T1.2c introduced to a Store written before them: +/// `commit.history_serial` and `layer.history_serial` (default 0) and +/// `store_policy.trace_salt` (32 random bytes), then backfills the serials +/// with T1.4's semantics in the same transaction. An additive migration under +/// the same conditions as [`add_gc`]: a schema that already has +/// `commit.history_serial` is left alone, and a recorded source or definition +/// that is not an earlier revision of the current one is refused, never +/// migrated. +pub(crate) fn add_position_columns(session: &Session) -> Result<(), PersistenceError> { + // A Store that already has the columns is left alone: one statement, no + // transaction and no lane wait. + let present = session.run_as::<_, BackendError>(Mode::Statement, |tx| { + let sql = format!( + "SELECT 1 FROM information_schema.columns WHERE table_schema='{}' AND table_name='commit' AND column_name='history_serial'", + tx.schema + ); + Ok(!tx.query(&sql, vec![])?.is_empty()) + })?; + if present { + return Ok(()); + } + session.run_as(Mode::Write, |tx| -> Result<(), PersistenceError> { + // Re-check under the lane: another process may have migrated first. + let present = tx.query( + "SELECT 1 FROM information_schema.columns WHERE table_schema=current_schema() AND table_name='commit' AND column_name='history_serial'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let [row] = rows.as_slice() else { + return Err(BackendError::Integrity.into()); + }; + let recorded_source: String = row.get(0)?; + let acquisition = if is_earlier_source(&recorded_source, source(false)) { + false + } else if is_earlier_source(&recorded_source, source(true)) { + true + } else { + return Err(BackendError::Integrity.into()); + }; + if row.get::(1)? != definition(tx)? { + return Err(BackendError::Integrity.into()); + } + tx.batch(POSITION_COLUMNS)?; + backfill_position_serials(tx)?; + let definition = definition(tx)?; + tx.query( + "UPDATE history_meta SET schema_source=$1,schema_definition=$2 WHERE id=1", + vec![Param::Text(source(acquisition)), Param::Text(definition)], + )?; + Ok(()) + }) +} + +/// The T1.4 serial backfill: Commits take the next Store serials in +/// `(created_ms, commit_id)` order, then each project's genesis Layer takes +/// the next one in stack-id order, every other Layer republishes its source +/// Commit's serial, existing serials are kept and `next_history_serial` never +/// falls below `MAX(serial) + 1`. +fn backfill_position_serials(tx: &Transaction<'_>) -> Result<(), BackendError> { + let next: i64 = tx + .query( + "SELECT next_history_serial FROM history_meta WHERE id=1", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let commit_max: i64 = tx + .query( + "SELECT COALESCE(MAX(history_serial),0) FROM \"commit\"", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let layer_max: i64 = tx + .query("SELECT COALESCE(MAX(history_serial),0) FROM layer", vec![])? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let base = next.max(commit_max.max(layer_max) + 1); + tx.query( + &format!( + "WITH ordered AS (SELECT commit_id,{base}+ROW_NUMBER() OVER (ORDER BY created_ms,commit_id)-1 AS serial FROM \"commit\" WHERE history_serial=0) UPDATE \"commit\" AS c SET history_serial=ordered.serial FROM ordered WHERE ordered.commit_id=c.commit_id AND c.history_serial=0" + ), + vec![], + )?; + let after_commits: i64 = tx + .query( + "SELECT COALESCE(MAX(history_serial),0)+1 FROM \"commit\"", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + tx.query( + &format!( + "WITH ordered AS (SELECT layer_id,{after_commits}+ROW_NUMBER() OVER (ORDER BY layer_stack_id,layer_id)-1 AS serial FROM layer WHERE history_serial=0 AND parent_layer_id IS NULL) UPDATE layer AS l SET history_serial=ordered.serial FROM ordered WHERE ordered.layer_id=l.layer_id AND l.history_serial=0 AND l.parent_layer_id IS NULL" + ), + vec![], + )?; + tx.query( + "UPDATE layer AS l SET history_serial=(SELECT c.history_serial FROM \"commit\" AS c WHERE c.layer_stack_id=l.layer_stack_id AND c.commit_id=l.source_commit_id) WHERE l.history_serial=0 AND l.source_commit_id IS NOT NULL", + vec![], + )?; + tx.query( + "UPDATE history_meta SET next_history_serial=GREATEST(next_history_serial,(SELECT COALESCE(MAX(history_serial),0)+1 FROM (SELECT history_serial FROM \"commit\" UNION ALL SELECT history_serial FROM layer) AS assigned)) WHERE id=1", + vec![], + )?; + Ok(()) +} + /// What an open's check read: the catalog's incarnation, whether the schema /// has the acquisition tables, the recorded binding, the frozen policy and /// the server's version. diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/schema_diagnostic.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/schema_diagnostic.rs index eee4764b7f..32e5f2cdee 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/schema_diagnostic.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/schema_diagnostic.rs @@ -12,6 +12,8 @@ branch name text NO branch base_layer_id bytea NO branch forked_from_id bytea YES branch head_commit_id bytea YES +branch_retired branch_id bytea NO +branch_retired removed_ms bigint NO commit commit_id bytea NO commit layer_stack_id bytea NO commit root_id bytea NO @@ -29,6 +31,7 @@ commit new_stored bigint NO commit new_metadata bigint NO commit lww bytea NO commit displaced_id bytea YES +commit history_serial bigint NO commit_lineage commit_id bytea NO commit_lineage run bytea NO commit_lineage depth bigint NO @@ -41,12 +44,53 @@ content_signature signature bytea NO file_digest digest bytea NO file_digest length bigint NO file_digest root bytea NO +gc_dead kind text NO +gc_dead id bytea NO +gc_intent op_id bytea NO +gc_intent kind text NO +gc_intent scope_kind text NO +gc_intent scope_id bytea YES +gc_intent workspace text YES +gc_intent sandbox text YES +gc_intent machine text YES +gc_intent project text YES +gc_intent branch text YES +gc_intent owner_runtime text YES +gc_intent owner_boot text YES +gc_intent state text NO +gc_intent uncertain boolean NO +gc_intent phase text YES +gc_intent generation bigint YES +gc_intent artifact text YES +gc_intent high_water bigint YES +gc_intent evidence text YES +gc_intent updated_ms bigint NO +gc_op id bigint NO +gc_op generation bigint NO +gc_op phase text NO +gc_op scratch_schema text YES +gc_op mark_serial bigint YES +gc_op mark_pack_id bigint YES +gc_op mark_digest bytea YES +gc_op mark_totals bytea YES +gc_op mark_stamp bigint YES +gc_op started_ms bigint NO +gc_op dead_canonical bigint NO +gc_op dead_stored bigint NO +gc_op dead_metadata bigint NO +gc_op dead_logical bigint NO +gc_op totals_applied boolean NO +gc_op artifact text YES +gc_op pid bigint YES +gc_op backend_start text YES +gc_op incarnation bigint YES history_meta id bigint NO history_meta catalog_id bytea NO history_meta catalog_incarnation bigint NO history_meta binding_key bytea NO history_meta identity_format bigint NO history_meta schema_version bigint NO +history_meta next_history_serial bigint NO history_meta schema_source text NO history_meta schema_definition text NO init_entry operation_id bigint NO @@ -83,6 +127,10 @@ init_operation removed_bytes bigint NO inode_value_block first_ordinal bigint NO inode_value_block last_ordinal bigint NO inode_value_block body bytea NO +kept_node layer_stack_id bytea NO +kept_node kind text NO +kept_node node_id bytea NO +kept_node serial bigint NO layer layer_id bytea NO layer layer_stack_id bytea NO layer parent_layer_id bytea YES @@ -91,6 +139,7 @@ layer source_branch_id bytea YES layer logical bigint NO layer overwrote bytea NO layer source_commit_id bytea YES +layer history_serial bigint NO layer_lineage layer_id bytea NO layer_lineage layer_stack_id bytea NO layer_lineage height bigint NO @@ -100,6 +149,8 @@ layer_stack name text NO layer_stack scope_id bytea NO layer_stack profile_id bytea NO layer_stack head_layer_id bytea NO +layer_stack_retired layer_stack_id bytea NO +layer_stack_retired deleted_ms bigint NO object_location pack_id bigint NO object_location canonical_length integer NO object_location role smallint NO @@ -111,6 +162,13 @@ pack domain bigint NO pack digest bytea NO pack length bigint NO pack body bytea NO +path_removed layer_stack_id bytea NO +path_removed path_key bytea NO +path_removed path bytea NO +path_removed frontier_serial bigint NO +path_removed removed_ms bigint NO +project_epoch layer_stack_id bytea NO +project_epoch epoch bigint NO reach key bytea NO reach x bigint NO reach height bigint NO @@ -127,6 +185,7 @@ store_policy chunk_delta_max_depth bigint NO store_policy metadata_delta_max_depth bigint NO store_policy next_pack_id bigint NO store_policy next_ordinal bigint NO +store_policy trace_salt bytea NO store_totals id bigint NO store_totals logical bigint NO store_totals canonical bigint NO diff --git a/engine/crates/layerfs-persistence/src/backend/postgresql/status.rs b/engine/crates/layerfs-persistence/src/backend/postgresql/status.rs index c9b7d7a7a2..69eeb53eb6 100644 --- a/engine/crates/layerfs-persistence/src/backend/postgresql/status.rs +++ b/engine/crates/layerfs-persistence/src/backend/postgresql/status.rs @@ -2,7 +2,12 @@ //! its version, one round trip's latency and the size of each named schema //! (tables and materialized views with their indexes and TOAST), on one //! connection opened for the call and closed after it, with no retry. +//! +//! It also reads a Store's compaction op — the `gc_op` row with its +//! `gc_intent` — for `store.status` (T10.5): one query, with no Store open, +//! schema change, artifact read or scratch-schema read. use crate::backend::postgresql::session::connection::Connector; +use crate::report::{CompactStatus, POSTGRES_COMPACT_PHASES}; use crate::PostgresSelection; use std::time::{Duration, Instant}; @@ -80,3 +85,182 @@ pub fn status(url: &str, schemas: &[String]) -> Result, + /// The owning backend's `backend_start`, when the row records one. + pub owner_backend_start: Option, + /// The owning process runtime `gc_intent` recorded, when it left one. + pub owner_runtime: Option, + /// The owning process boot id `gc_intent` recorded, when it left one. + pub owner_boot: Option, + /// The `gc_intent` row's own state (`live`, `uncertain` or `done`), when + /// it is still there; a crash leaves `live`, so this is evidence, not + /// liveness. + pub intent_state: Option, + /// The mark's history serial, when recorded. + pub mark_serial: Option, + /// The mark's next pack id, when recorded. + pub mark_pack_id: Option, + /// The mark's live-heads digest, when recorded. + pub mark_digest: Option>, + /// True while the row remains: the run did not settle, so its outcome is + /// unknown. `store.status` reports `busy` while the owner lives and + /// `unresolved` once it is gone. + pub uncertain: bool, + /// True when the recorded owner backend is still alive and not `idle`, + /// the same §9 test a resolving compaction applies. + pub alive: bool, +} + +impl PostgresCompactOpStatus { + /// The `store.status` projection of this operation: `busy` while the + /// owner lives, `unresolved` once it is gone. `uncertain` stays true for + /// every remaining row, live or leftover; `state` separates the two. The + /// phases are PostgreSQL's §8 ones: `mark`, `build`, `swap`, `cleanup`. + #[must_use] + pub fn status(&self) -> CompactStatus { + CompactStatus { + id: format!("op-{}", hex(&self.op_id)), + name: "store.compact", + phase: self.phase.clone(), + started: self.started_ms, + uncertain: self.uncertain, + state: if self.alive { "busy" } else { "unresolved" }, + phases: &POSTGRES_COMPACT_PHASES, + } + } +} + +/// `gc_op` plus its compaction `gc_intent` and the owner's live state, in one +/// query on one status connection. Returns `None` when the Store has no +/// compaction row (idle), or when a Store written before the GC tables has no +/// `gc_op` at all. No Store open, schema mutation, artifact or scratch read +/// happens here. +pub fn compact_status( + url: &str, + schema: &str, +) -> Result, PostgresStatusError> { + let connector = Connector::new(&PostgresSelection::new(url, schema)) + .map_err(|_| PostgresStatusError::Unreachable("the URL does not parse".to_owned()))?; + let mut client = connector + .connect_raw() + .map_err(|error| match error.code() { + Some(code) if code.code().starts_with("28") || code.code() == "3D000" => { + PostgresStatusError::Denied(error.to_string()) + } + _ => PostgresStatusError::Unreachable(error.to_string()), + })?; + let table = quote_ident(schema); + let sql = format!( + "SELECT o.generation,o.phase,o.started_ms,o.pid,o.backend_start,o.artifact,\ + o.mark_serial,o.mark_pack_id,o.mark_digest,\ + i.op_id,i.owner_runtime,i.owner_boot,i.state,\ + EXISTS (SELECT 1 FROM pg_stat_activity a \ + WHERE a.datname=current_database() AND a.pid=o.pid \ + AND a.backend_start::text=o.backend_start \ + AND a.state IS DISTINCT FROM 'idle') \ + FROM {table}.gc_op o \ + LEFT JOIN LATERAL (SELECT op_id,owner_runtime,owner_boot,state \ + FROM {table}.gc_intent WHERE kind='compaction' \ + ORDER BY updated_ms LIMIT 1) i ON TRUE \ + WHERE o.id=1" + ); + let rows = match client.query(&sql, &[]) { + Ok(rows) => rows, + // A Store opened before the GC tables has no row to read: idle. + Err(error) + if matches!( + error.code().map(postgres::error::SqlState::code), + Some("42P01" | "3F000") + ) => + { + let _ = client.close(); + return Ok(None); + } + Err(error) => return Err(PostgresStatusError::Failed(error.to_string())), + }; + let Some(row) = rows.first() else { + let _ = client.close(); + return Ok(None); + }; + let failed = |error: postgres::Error| PostgresStatusError::Failed(error.to_string()); + let intent: Option> = row.try_get(9).map_err(failed)?; + let artifact: Option = row.try_get(5).map_err(failed)?; + let op = PostgresCompactOpStatus { + op_id: op_identity(intent, artifact.as_deref()), + generation: row.try_get(0).map_err(failed)?, + phase: row.try_get(1).map_err(failed)?, + started_ms: row.try_get(2).map_err(failed)?, + owner_pid: row.try_get(3).map_err(failed)?, + owner_backend_start: row.try_get(4).map_err(failed)?, + owner_runtime: row.try_get(10).map_err(failed)?, + owner_boot: row.try_get(11).map_err(failed)?, + intent_state: row.try_get(12).map_err(failed)?, + mark_serial: row.try_get(6).map_err(failed)?, + mark_pack_id: row.try_get(7).map_err(failed)?, + mark_digest: row.try_get(8).map_err(failed)?, + // A remaining row is an unsettled run: the record's own fact. It is + // never inferred from the owner's liveness. + uncertain: true, + alive: row.try_get(13).map_err(failed)?, + }; + let _ = client.close(); + Ok(Some(op)) +} + +/// The `lfs_gc_` scratch name `gc_op.artifact` records carries the +/// operation identity, so a row whose `gc_intent` was already released still +/// projects a stable `op.id`. +fn op_identity(intent: Option>, artifact: Option<&str>) -> [u8; 16] { + if let Some(bytes) = intent { + if let Ok(op) = <[u8; 16]>::try_from(bytes.as_slice()) { + return op; + } + } + artifact + .and_then(|name| name.strip_prefix("lfs_gc_")) + .and_then(unhex) + .unwrap_or([0; 16]) +} + +fn quote_ident(name: &str) -> String { + format!("\"{}\"", name.replace('"', "\"\"")) +} + +fn hex(bytes: &[u8]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(bytes.len() * 2); + for byte in bytes { + let _ = write!(out, "{byte:02x}"); + } + out +} + +fn unhex(text: &str) -> Option<[u8; 16]> { + if text.len() != 32 { + return None; + } + let mut out = [0u8; 16]; + for (index, byte) in out.iter_mut().enumerate() { + *byte = u8::from_str_radix(text.get(index * 2..index * 2 + 2)?, 16).ok()?; + } + Some(out) +} diff --git a/engine/crates/layerfs-persistence/src/backend/records.rs b/engine/crates/layerfs-persistence/src/backend/records.rs index 9efc76cd55..4cfb62853d 100644 --- a/engine/crates/layerfs-persistence/src/backend/records.rs +++ b/engine/crates/layerfs-persistence/src/backend/records.rs @@ -118,6 +118,8 @@ pub(crate) enum BackendError { #[cfg_attr(not(target_os = "linux"), allow(dead_code))] Cancelled, ReadOnly, + /// §10: the Store path no longer names the file this handle opened. + Stale, Capacity, Integrity, /// A SQLite Store of schema version 1 (before #91): refused at open with @@ -158,6 +160,8 @@ impl From for layerfs_history::HistoryError { Self::OwnershipUnavailable } BackendError::ReadOnly => Self::ContinuityUnavailable, + // §10: the file was replaced or moved under this handle. + BackendError::Stale => Self::StaleStore, BackendError::Capacity => Self::Capacity("persistence"), BackendError::Integrity => Self::Integrity("persistence"), BackendError::SchemaVersion1 => Self::Integrity(SCHEMA_VERSION_1), diff --git a/engine/crates/layerfs-persistence/src/backend/seam.rs b/engine/crates/layerfs-persistence/src/backend/seam.rs index 5108cbed52..e654cf8877 100644 --- a/engine/crates/layerfs-persistence/src/backend/seam.rs +++ b/engine/crates/layerfs-persistence/src/backend/seam.rs @@ -23,6 +23,8 @@ pub(crate) enum Engine { /// Named history statements in one open engine transaction. pub(crate) trait HistoryStatements { fn history(&self, key: &str, params: Vec) -> Result, BackendError>; + /// The same open transaction's physical object and metadata access. + fn mechanics(&self) -> &dyn Mechanics; /// One statement over parallel column arrays, where the engine binds /// arrays (PostgreSQL: one round trip for many rows). `None`: the /// engine has no such statement and the caller runs its per-row one. diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs new file mode 100644 index 0000000000..e3f07fe462 --- /dev/null +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/compact.rs @@ -0,0 +1,2260 @@ +//! §7 SQLite Store compaction: mark, rebuild, immutable verification and the +//! atomic install. +//! +//! One call takes the Store's writer lane before it registers its admission +//! intent, runs the T7.2 mark in the same exclusive window, seals the file +//! (checkpoint, checked close, sidecar check and `(size, mtime, change +//! counter)` capture), and then either stops on the §3 `none` path or builds +//! `.compact`, verifies it through an `immutable=1` URI, and renames it +//! into place at `G → G+1`. The run's phase and mark tuple are kept beside the +//! Store in `.compact-op`, the SQLite equivalent of the PostgreSQL +//! `gc_op` row (§11); the next `store.compact` judges a leftover by the Store +//! generation (§9) and removes the artifact set it names. +//! +//! The T7.2 mark already resolves every logical reference and delta base, so +//! the bytes of packs that hold no reached object are the refined dead bytes: +//! §7's step-4 payload sweep cannot discover another live object on SQLite. +//! `deadBytesRefined` therefore equals `deadBytesBound`, as §11 requires for +//! the `none` path. + +use super::lifecycle::seal::SealedFacts; +use super::schema; +use super::session::connection::{Session, SqlWork}; +use super::session::rows; +use crate::backend::records::BackendError; +use crate::compact_metrics::{ + self, CompactOutcome, CompactPhase, CompactRefusal, CompactRunObservation, +}; +use crate::{KeptWaste, MarkResult, SqliteHandles}; +use layerfs_content::ObjectId; +use layerfs_history::error::{HistoryError, HistoryResult}; +use layerfs_history::records::{GcIntent, GcIntentKind, GcScopeKind}; +use layerfs_history::HistoryCatalog; +use layerfs_storage::port::PersistenceError; +use rusqlite::{params, Connection, OpenFlags}; +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::path::{Path, PathBuf}; +use std::sync::Arc; +use std::time::{Instant, SystemTime, UNIX_EPOCH}; + +/// The sidecar record suffix (§11: SQLite keeps its phase outside the sealed +/// database). +const OP_SUFFIX: &str = ".compact-op"; +/// The staged rebuild Store beside the live one. +const COMPACT_SUFFIX: &str = ".compact"; +/// The §6.3 visited scratch database. +const VISITED_SUFFIX: &str = ".compact-visited"; +/// Upper bound on the rollback-journal header: SQLite pads it to the +/// filesystem's sector size and writes a header for each transaction. Two +/// sectors cover the prune and rewrite headers. +const JOURNAL_HEADER_BOUND: u64 = 8192; + +/// The full SQLite artifact set of §9, without the variable `-mj*` journals. +const ARTIFACT_SUFFIXES: [&str; 7] = [ + COMPACT_SUFFIX, + ".compact-journal", + ".compact-wal", + ".compact-shm", + VISITED_SUFFIX, + ".compact-visited-journal", + ".compact-vacuum", +]; + +/// The mark tuple a compaction records before its first checkpoint (§8 Phase M +/// on PostgreSQL; the same first-statement tuple in the SQLite sidecar here). +#[derive(Clone, Debug, Eq, PartialEq)] +struct MarkTuple { + catalog_id: Vec, + generation: i64, + next_history_serial: i64, + next_pack_id: i64, + next_ordinal: i64, + logical: i64, + canonical: i64, + stored: i64, + metadata: i64, + stamp: i64, + history_rows: i64, +} + +/// The first-statement tuple, in the column order every reader decodes. +const TUPLE_SQL: &str = "SELECT h.catalog_id,h.catalog_incarnation,h.next_history_serial,\ +p.next_pack_id,p.next_ordinal,t.logical,t.canonical,t.stored,t.metadata,\ +(SELECT COALESCE(MAX(stamp),0) FROM content_signature),\ +(SELECT COUNT(*) FROM \"commit\")+(SELECT COUNT(*) FROM layer) \ +FROM history_meta h, store_policy p, store_totals t \ +WHERE h.id=1 AND p.id=1 AND t.id=1"; + +/// The §6.4 live-heads digest input, in identity order. +const LIVE_STACKS: &str = "SELECT s.layer_stack_id,s.head_layer_id FROM layer_stack s \ +WHERE NOT EXISTS (SELECT 1 FROM layer_stack_retired r WHERE r.layer_stack_id=s.layer_stack_id) \ +ORDER BY s.layer_stack_id"; +/// The marker-free Branches, in identity order. +const LIVE_BRANCHES: &str = "SELECT b.branch_id,b.head_commit_id,b.base_layer_id FROM branch b \ +WHERE NOT EXISTS (SELECT 1 FROM branch_retired r WHERE r.branch_id=b.branch_id) \ +AND NOT EXISTS (SELECT 1 FROM layer_stack_retired s WHERE s.layer_stack_id=b.layer_stack_id) \ +ORDER BY b.branch_id"; + +/// Which §3 path a compaction took. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum CompactPath { + /// Below the 10% wholly-dead threshold: mark only, nothing written. + None, + /// A rebuild installed at `G → G+1`. + Rebuild, +} + +impl CompactPath { + /// The report's `path` text. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::None => "none", + Self::Rebuild => "rebuild", + } + } +} + +/// A test-only stop point of the run, so a crash between phases can be +/// exercised. The run leaves the state a crash would leave and reports an +/// unknown outcome; the next `store.compact` must recover it (§9). +#[doc(hidden)] +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub enum CompactFailpoint { + /// Before the seal, while the open session, the writer lane and the + /// admission intent are still held. + BeforeSeal, + /// After the seal returns and before the sealed file is read back. + BeforeSealRead, + /// After the seal and the sealed-state comparison, before any artifact. + AfterSeal, + /// Inside the build, before the visited scratch or the copy is written. + BeforeCopy, + /// Inside the build, immediately before `VACUUM INTO` starts the copy. + /// SQLite runs that copy as one uninterruptible call, so a real-process + /// `SIGKILL` cannot land inside it; the real-kill arm stops here with the + /// visited scratch present and the staged file not yet created. The + /// in-process `DuringCopy` arm keeps the torn-target state. + BeforeVacuum, + /// Inside the build, after `VACUUM INTO` produced `.compact` and + /// before the copy is pruned: the state a crash during the copy leaves. + DuringCopy, + /// After the staged `.compact` is built and compacted. + AfterBuild, + /// The staged Store's `VACUUM INTO` meets a bounded filesystem (ENOSPC). + CapacityAtBuild, + /// After the staged file is switched to WAL and checkpointed. + AfterWalSwitch, + /// Inside the verification, after the schema and row-count checks. + DuringVerify, + /// After the immutable verification passes. + AfterVerify, + /// Immediately before the rename would run. + BeforeInstall, + /// After the rename and before the directory fsync (rename/journal). + DuringRename, + /// After the rename and directory fsync. + AfterInstall, + /// Inside the settle, after the artifact set is removed and before the op + /// record. + DuringSettle, + /// PostgreSQL: after Phase M wrote the op and the dead set, before Phase A. + PostgresAfterMark, + /// PostgreSQL: after Phase A built and verified the scratch tables. + PostgresAfterBuild, + /// PostgreSQL: after Phase B committed the swap, before Phase C. + PostgresAfterSwap, + /// PostgreSQL: after Phase C settled the op. + PostgresAfterCleanup, +} + +impl CompactFailpoint { + /// The phase the sidecar records for this stop point. + const fn phase(self) -> &'static str { + match self { + Self::BeforeSeal | Self::BeforeSealRead | Self::AfterSeal => "mark", + Self::BeforeCopy + | Self::BeforeVacuum + | Self::DuringCopy + | Self::AfterBuild + | Self::CapacityAtBuild + | Self::AfterWalSwitch => "build", + Self::DuringVerify | Self::AfterVerify | Self::BeforeInstall => "verify", + Self::DuringRename | Self::AfterInstall | Self::DuringSettle => "install", + Self::PostgresAfterMark => "mark", + Self::PostgresAfterBuild => "build", + Self::PostgresAfterSwap => "swap", + Self::PostgresAfterCleanup => "cleanup", + } + } +} + +/// Inputs one `store.compact` attempt uses. +#[derive(Clone, Debug, Default)] +pub struct CompactRequest { + /// 16-byte operation identity, written as the admission intent's `op_id`. + pub op_id: [u8; 16], + /// Owning runtime token, for the op and intent records. + pub owner_runtime: Option, + /// Owning boot token, for the op and intent records. + pub owner_boot: Option, + /// The owning process id, so `store.status` can tell a live run from a + /// leftover (§11). The kernel start time and boot id, when known, keep a + /// reused id from passing as the owner. + pub owner_pid: Option, + /// The owner's kernel start time (the lease's second field). + pub owner_pid_start: Option, + /// The owner's kernel boot id (the lease's third field). + pub owner_pid_boot: Option, + /// A test-only stop point; production callers leave it `None`. + pub failpoint: Option, + /// A test-only hook called after verification and immediately before the + /// §10 install fence, so a test can replace the Store under the sealed + /// handle. Production callers leave it `None`. + #[doc(hidden)] + pub before_install_hook: Option, +} + +/// The `keptWaste` §11 part of a compaction report. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct CompactKeptWaste { + /// Bytes of unreferenced records inside packs the mark retained. + pub dead_in_retained_packs_bytes: u64, + /// Bytes of objects reached only as a delta base. + pub delta_bases_bytes: u64, + /// The objects counted by [`Self::delta_bases_bytes`], in ascending order. + pub delta_base_references: Vec<[u8; 32]>, + /// Bytes of `inode_value_block` rows, which 2.0 keeps in full. + pub inode_blocks_bytes: u64, +} + +impl CompactKeptWaste { + /// One mark's kept-waste accounting. + fn from_mark(waste: &KeptWaste) -> Self { + Self { + dead_in_retained_packs_bytes: waste.dead_in_retained_packs_bytes(), + delta_bases_bytes: waste.delta_bases_bytes(), + delta_base_references: waste + .delta_base_references() + .iter() + .map(|id| *id.as_bytes()) + .collect(), + inode_blocks_bytes: waste.inode_blocks_bytes(), + } + } + + /// Whether every part is zero. + #[must_use] + pub fn is_empty(&self) -> bool { + self.dead_in_retained_packs_bytes == 0 + && self.delta_bases_bytes == 0 + && self.inode_blocks_bytes == 0 + } +} + +/// The `residue` §11 part of a compaction report. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct CompactResidue { + /// Bytes left behind by the artifact set after settle. + pub bytes: u64, + /// The artifact file names that remain. + pub artifacts: Vec, + /// Why anything remains, when it does. + pub reason: Option, +} + +/// One zero report field and its §11 `zeroReason`. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct CompactZeroReason { + /// The report field the reason explains. + pub field: &'static str, + /// One word of the §11 closed vocabulary. + pub reason: &'static str, +} + +impl CompactZeroReason { + /// The §10 wire key this reason names: the §11 logical name rendered + /// snake_case, the same mapping the report serializer uses. + #[must_use] + pub fn wire_field(self) -> &'static str { + match self.field { + "deadBytesBound" => "dead_bytes_bound", + "deadBytesRefined" => "dead_bytes_refined", + "logicalDiscarded" => "logical_discarded", + "backendReusable" => "backend_reusable", + "physicalShrink" => "physical_shrink", + "keptWaste" => "kept_waste", + "peakTempBytes" => "peak_temp_bytes", + other => other, + } + } +} + +/// The §11 report `store.compact` returns. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct CompactReceipt { + /// `none` or `rebuild`. + pub path: CompactPath, + /// The generation the mark ran at. + pub generation_before: u64, + /// The installed generation: equal on `none`. + pub generation_after: u64, + /// Bytes in wholly dead packs after the metadata walk; the path's input. + pub dead_bytes_bound: u64, + /// The same bytes after the payload sweep. + pub dead_bytes_refined: u64, + /// Collected history rows' logical bytes. + pub logical_discarded: u64, + /// SQLite free pages of the new (rebuild) or live (`none`) Store. + pub backend_reusable: u64, + /// Old file size minus new. + pub physical_shrink: u64, + /// The bytes the mark keeps that no retained root needs. + pub kept_waste: CompactKeptWaste, + /// Peak temporary bytes the run needed. + pub peak_temp_bytes: u64, + /// The artifact set left after settle; empty on success. + pub residue: CompactResidue, + /// §13: the report is an estimate, not a measurement. + pub estimate: bool, + /// One `zeroReason` per zero report field. + pub zero_reasons: Vec, +} + +/// One recorded compaction run beside the Store. +#[derive(Clone, Debug)] +struct RunOp { + op_id: [u8; 16], + generation: i64, + phase: String, + started_ms: i64, + owner_pid: Option, + owner_pid_start: Option, + owner_pid_boot: Option, + tuple: MarkTuple, + live_heads_digest: [u8; 32], +} + +impl RunOp { + fn encode(&self) -> String { + format!( + "version=1\nop_id={}\ngeneration={}\nphase={}\nstarted_ms={}\n\ +owner_pid={}\nowner_pid_start={}\nowner_pid_boot={}\n\ +catalog_id={}\nnext_history_serial={}\nnext_pack_id={}\nnext_ordinal={}\n\ +mark_serial={}\nmark_pack_id={}\nmark_digest={}\nmark_totals={},{},{},{}\nmark_stamp={}\nhistory_rows={}\n\ +live_heads_digest={}\n", + hex(&self.op_id), + self.generation, + self.phase, + self.started_ms, + self.owner_pid.map_or_else(String::new, |pid| pid.to_string()), + self.owner_pid_start.map_or_else(String::new, |start| start.to_string()), + self.owner_pid_boot.map_or_else(String::new, |boot| format!("{boot:032x}")), + hex(&self.tuple.catalog_id), + self.tuple.next_history_serial, + self.tuple.next_pack_id, + self.tuple.next_ordinal, + self.tuple.next_history_serial.saturating_sub(1), + self.tuple.next_pack_id, + hex(&self.live_heads_digest), + self.tuple.logical, + self.tuple.canonical, + self.tuple.stored, + self.tuple.metadata, + self.tuple.stamp, + self.tuple.history_rows, + hex(&self.live_heads_digest), + ) + } + + fn write(&self, store: &Path) -> HistoryResult<()> { + let path = op_path(store); + let mut temporary = path.as_os_str().to_os_string(); + temporary.push(".tmp"); + let temporary = PathBuf::from(temporary); + std::fs::write(&temporary, self.encode()).map_err(io_error)?; + if let Ok(file) = std::fs::File::open(&temporary) { + let _ = file.sync_all(); + } + std::fs::rename(&temporary, &path).map_err(io_error)?; + if let Some(parent) = path.parent() { + let _ = std::fs::File::open(parent).and_then(|directory| directory.sync_all()); + } + Ok(()) + } + + fn read(store: &Path) -> Option { + let text = std::fs::read_to_string(op_path(store)).ok()?; + let mut values = BTreeMap::new(); + for line in text.lines() { + let (key, value) = line.split_once('=')?; + values.insert(key, value); + } + if values.get("version") != Some(&"1") { + return None; + } + let op_id = unhex::<16>(values.get("op_id")?)?; + let generation: i64 = values.get("generation")?.parse().ok()?; + let phase = (*values.get("phase")?).to_owned(); + let started_ms: i64 = values.get("started_ms")?.parse().ok()?; + let owner_pid = values + .get("owner_pid") + .filter(|text| !text.is_empty()) + .and_then(|text| text.parse().ok()); + let owner_pid_start = values + .get("owner_pid_start") + .filter(|text| !text.is_empty()) + .and_then(|text| text.parse().ok()); + let owner_pid_boot = values + .get("owner_pid_boot") + .filter(|text| !text.is_empty()) + .and_then(|text| u128::from_str_radix(text, 16).ok()); + let catalog_id = unhex_vec(values.get("catalog_id")?)?; + let tuple = MarkTuple { + catalog_id, + generation, + next_history_serial: values.get("next_history_serial")?.parse().ok()?, + next_pack_id: values.get("next_pack_id")?.parse().ok()?, + next_ordinal: values.get("next_ordinal")?.parse().ok()?, + logical: values.get("mark_totals")?.split(',').next()?.parse().ok()?, + canonical: values.get("mark_totals")?.split(',').nth(1)?.parse().ok()?, + stored: values.get("mark_totals")?.split(',').nth(2)?.parse().ok()?, + metadata: values.get("mark_totals")?.split(',').nth(3)?.parse().ok()?, + stamp: values.get("mark_stamp")?.parse().ok()?, + history_rows: values.get("history_rows")?.parse().ok()?, + }; + let live_heads_digest = unhex::<32>(values.get("live_heads_digest")?)?; + Some(Self { + op_id, + generation, + phase, + started_ms, + owner_pid, + owner_pid_start, + owner_pid_boot, + tuple, + live_heads_digest, + }) + } +} + +/// The operation a Store's `.compact-op` records, as `store.status` +/// (T10.1) projects it: the operation identity, the generation the run started +/// at, its phase, its owner and whether its outcome is known. A settled run +/// removes the record, so [`compact_op_status`] returns `None`. +#[doc(hidden)] +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct CompactOpStatus { + /// The 16-byte operation identity. + pub op_id: [u8; 16], + /// The generation the run started at. + pub generation: i64, + /// The recorded phase: `admission`, `mark`, `build`, `verify` or `install`. + pub phase: String, + /// When the run started, in Unix milliseconds. + pub started_ms: i64, + /// The owning process id, when the run recorded one. + pub owner_pid: Option, + /// The owner's kernel start time, when recorded. + pub owner_pid_start: Option, + /// The owner's kernel boot id, when recorded. + pub owner_pid_boot: Option, + /// True while the record remains: the run did not settle, so its outcome + /// is unknown. `store.status` reports `busy` while the owner lives and + /// `unresolved` once it is gone. + pub uncertain: bool, +} + +impl CompactOpStatus { + /// The `store.status` projection of this operation; `alive` says whether + /// the owning process is still running. A live owner is `busy`, a gone one + /// left an uncertain `unresolved` outcome. `uncertain` stays the record's + /// own fact: it is true for every unsettled run, live or leftover. + #[must_use] + pub fn status(&self, alive: bool) -> crate::report::CompactStatus { + // A read in the admission window still projects a §11 phase: the run + // is about to mark, and `admission` is not one of the four. + let phase = if self.phase == "admission" { + "mark".to_owned() + } else { + self.phase.clone() + }; + crate::report::CompactStatus { + id: format!("op-{}", hex(&self.op_id)), + name: "store.compact", + phase, + started: self.started_ms, + uncertain: self.uncertain, + state: if alive { "busy" } else { "unresolved" }, + phases: &crate::report::SQLITE_COMPACT_PHASES, + } + } +} + +/// Reads the operation `.compact-op` records, or `None` when the Store +/// has no compaction record. `store.status` (T10.1) uses this to show the +/// operation, its phase and its uncertain outcome; a settled run removes the +/// record (§9). +#[doc(hidden)] +#[must_use] +pub fn compact_op_status(store: &Path) -> Option { + RunOp::read(store).map(|op| CompactOpStatus { + op_id: op.op_id, + generation: op.generation, + phase: op.phase, + started_ms: op.started_ms, + owner_pid: op.owner_pid, + owner_pid_start: op.owner_pid_start, + owner_pid_boot: op.owner_pid_boot, + uncertain: true, + }) +} + +fn now_ms() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |elapsed| { + i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX) + }) +} + +fn hex(bytes: &[u8]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(bytes.len() * 2); + for byte in bytes { + let _ = write!(out, "{byte:02x}"); + } + out +} + +fn unhex_vec(text: &str) -> Option> { + if text.len() % 2 != 0 { + return None; + } + (0..text.len()) + .step_by(2) + .map(|index| u8::from_str_radix(&text[index..index + 2], 16).ok()) + .collect() +} + +fn unhex(text: &str) -> Option<[u8; N]> { + let bytes = unhex_vec(text)?; + bytes.try_into().ok() +} + +fn with_suffix(path: &Path, suffix: &str) -> PathBuf { + let mut name = path.as_os_str().to_os_string(); + name.push(suffix); + PathBuf::from(name) +} + +fn compact_path(store: &Path) -> PathBuf { + with_suffix(store, COMPACT_SUFFIX) +} + +fn visited_path(store: &Path) -> PathBuf { + with_suffix(store, VISITED_SUFFIX) +} + +fn op_path(store: &Path) -> PathBuf { + with_suffix(store, OP_SUFFIX) +} + +/// The §9 SQLite artifact set: the fixed suffixes plus every multi-database +/// super-journal the staged file may have left (`.compact-mj*`). +fn artifact_paths(store: &Path) -> Vec { + let mut paths: Vec = ARTIFACT_SUFFIXES + .iter() + .map(|suffix| with_suffix(store, suffix)) + .collect(); + let name = store + .file_name() + .map_or_else(|| store.as_os_str().to_os_string(), |name| name.to_os_string()); + let mut prefix = name; + prefix.push(".compact-mj"); + let prefix = prefix.to_string_lossy().into_owned(); + if let Some(parent) = store.parent() { + if let Ok(entries) = std::fs::read_dir(parent) { + for entry in entries.flatten() { + if entry.file_name().to_string_lossy().starts_with(&prefix) { + paths.push(entry.path()); + } + } + } + } + paths +} + +fn io_error(error: std::io::Error) -> HistoryError { + match error.raw_os_error() { + Some(28) | Some(122) | Some(27) | Some(69) => HistoryError::Capacity("disk space"), + _ => HistoryError::Integrity("Store compaction I/O"), + } +} + +fn db_error(error: rusqlite::Error) -> HistoryError { + rows::error(error).into() +} + +fn seal_error(error: PersistenceError) -> HistoryError { + match error { + PersistenceError::Busy => HistoryError::Busy, + PersistenceError::Refused { status } if status == "Capacity" => { + HistoryError::Capacity("Store compaction") + } + PersistenceError::Refused { status } if status == "Store sidecar remains after seal" => { + HistoryError::Conflict("Store sidecar remains after seal") + } + PersistenceError::Refused { .. } | PersistenceError::Malformed => { + HistoryError::Integrity("Store seal") + } + PersistenceError::Uncertain => HistoryError::UnknownOutcome, + PersistenceError::Missing | PersistenceError::BackendUnavailable => { + HistoryError::Unsupported("SQLite Store compaction") + } + } +} + +/// The read-only URI of one database file that must not be changed while it is +/// read. Path bytes are percent-encoded so `?`, `#` and `%` do not misdirect +/// the URI (§7 step 6). +#[cfg(unix)] +fn immutable_uri(path: &Path) -> String { + use std::os::unix::ffi::OsStrExt; + let mut uri = String::from("file:"); + for byte in path.as_os_str().as_bytes() { + match byte { + b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' | b'/' => { + uri.push(char::from(*byte)); + } + _ => { + use std::fmt::Write as _; + let _ = write!(uri, "%{byte:02X}"); + } + } + } + uri.push_str("?immutable=1"); + uri +} + +fn open_immutable(path: &Path) -> HistoryResult { + #[cfg(unix)] + { + let connection = Connection::open_with_flags( + immutable_uri(path), + OpenFlags::SQLITE_OPEN_READ_ONLY + | OpenFlags::SQLITE_OPEN_URI + | OpenFlags::SQLITE_OPEN_NO_MUTEX, + ) + .map_err(db_error)?; + connection + .busy_timeout(std::time::Duration::ZERO) + .map_err(db_error)?; + Ok(connection) + } + #[cfg(not(unix))] + { + let _ = path; + Err(HistoryError::Unsupported("SQLite Store compaction")) + } +} + +fn live_tuple(session: &Arc) -> HistoryResult { + session + .run::<_, BackendError>(false, |tx| { + let rows = tx.query(TUPLE_SQL, vec![])?; + let row = rows.first().ok_or(BackendError::Integrity)?; + Ok(MarkTuple { + catalog_id: row.get(0)?, + generation: row.get(1)?, + next_history_serial: row.get(2)?, + next_pack_id: row.get(3)?, + next_ordinal: row.get(4)?, + logical: row.get(5)?, + canonical: row.get(6)?, + stored: row.get(7)?, + metadata: row.get(8)?, + stamp: row.get(9)?, + history_rows: row.get(10)?, + }) + }) + .map_err(Into::into) +} + +fn file_tuple(connection: &Connection) -> HistoryResult { + connection + .query_row(TUPLE_SQL, params![], |row| { + Ok(MarkTuple { + catalog_id: row.get(0)?, + generation: row.get(1)?, + next_history_serial: row.get(2)?, + next_pack_id: row.get(3)?, + next_ordinal: row.get(4)?, + logical: row.get(5)?, + canonical: row.get(6)?, + stored: row.get(7)?, + metadata: row.get(8)?, + stamp: row.get(9)?, + history_rows: row.get(10)?, + }) + }) + .map_err(db_error) +} + +fn pack_lengths(session: &Arc) -> HistoryResult> { + session + .run::<_, BackendError>(false, |tx| { + let rows = tx.query("SELECT pack_id,length FROM pack", vec![])?; + let mut lengths = BTreeMap::new(); + for row in &rows { + let id: i64 = row.get(0)?; + let length: i64 = row.get(1)?; + lengths.insert( + id, + u64::try_from(length).map_err(|_| BackendError::Integrity)?, + ); + } + Ok(lengths) + }) + .map_err(Into::into) +} + +fn object_packs(session: &Arc) -> HistoryResult> { + session + .run::<_, BackendError>(false, |tx| { + let rows = tx.query("SELECT object_id,pack_id FROM object_location", vec![])?; + let mut packs = BTreeMap::new(); + for row in &rows { + let bytes: Vec = row.get(0)?; + let pack: i64 = row.get(1)?; + let id = ObjectId::from_bytes(&bytes).map_err(|_| BackendError::Integrity)?; + packs.insert(id, pack); + } + Ok(packs) + }) + .map_err(Into::into) +} + +fn live_page_metrics(session: &Arc) -> HistoryResult<(u64, u64)> { + session + .run::<_, BackendError>(false, |tx| { + let free = tx.query("PRAGMA freelist_count", vec![])?; + let page = tx.query("PRAGMA page_size", vec![])?; + let free = free.first().ok_or(BackendError::Integrity)?.get::(0)?; + let page = page.first().ok_or(BackendError::Integrity)?.get::(0)?; + Ok(( + u64::try_from(free).map_err(|_| BackendError::Integrity)?, + u64::try_from(page).map_err(|_| BackendError::Integrity)?, + )) + }) + .map_err(Into::into) +} + +/// The rollback-journal upper bound of one transaction on a `pages`-page file: +/// one record per modified page (`page_size + 8` bytes: page number, page image +/// and checksum) plus the header allowance. A page is journaled at most once +/// per transaction, so the staged copy's page count bounds both the prune and +/// the rewrite journal, and the bound never under-reports the observed file. +const fn journal_bound_bytes(pages: u64, page_size: u64) -> u64 { + pages + .saturating_mul(page_size.saturating_add(8)) + .saturating_add(JOURNAL_HEADER_BOUND) +} + +/// The staged file's page count and page size, before the prune frees pages. +fn file_page_extent(connection: &Connection) -> HistoryResult<(u64, u64)> { + let pages: i64 = connection + .query_row("PRAGMA page_count", params![], |row| row.get(0)) + .map_err(db_error)?; + let page: i64 = connection + .query_row("PRAGMA page_size", params![], |row| row.get(0)) + .map_err(db_error)?; + Ok(( + u64::try_from(pages).map_err(|_| HistoryError::Integrity("page count"))?, + u64::try_from(page).map_err(|_| HistoryError::Integrity("page size"))?, + )) +} + +fn file_page_metrics(connection: &Connection) -> HistoryResult<(u64, u64)> { + let free: i64 = connection + .query_row("PRAGMA freelist_count", params![], |row| row.get(0)) + .map_err(db_error)?; + let page: i64 = connection + .query_row("PRAGMA page_size", params![], |row| row.get(0)) + .map_err(db_error)?; + Ok(( + u64::try_from(free).map_err(|_| HistoryError::Integrity("freelist count"))?, + u64::try_from(page).map_err(|_| HistoryError::Integrity("page size"))?, + )) +} + +fn file_heads_digest(connection: &Connection) -> HistoryResult<[u8; 32]> { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"layerfs/live-heads/v1\0"); + let mut stacks = connection.prepare(LIVE_STACKS).map_err(db_error)?; + let mut rows = stacks.query(params![]).map_err(db_error)?; + while let Some(row) = rows.next().map_err(db_error)? { + let id: Vec = row.get(0).map_err(db_error)?; + let head: Vec = row.get(1).map_err(db_error)?; + if id.len() != 17 || head.len() != 33 { + return Err(HistoryError::Integrity("live-heads stack width")); + } + hasher.update(&id); + hasher.update(&head); + } + drop(rows); + drop(stacks); + let mut branches = connection.prepare(LIVE_BRANCHES).map_err(db_error)?; + let mut rows = branches.query(params![]).map_err(db_error)?; + while let Some(row) = rows.next().map_err(db_error)? { + let id: Vec = row.get(0).map_err(db_error)?; + let head: Option> = row.get(1).map_err(db_error)?; + let base: Vec = row.get(2).map_err(db_error)?; + if id.len() != 17 || base.len() != 33 { + return Err(HistoryError::Integrity("live-heads branch width")); + } + hasher.update(&id); + match head { + Some(head) if head.len() == 33 => hasher.update(&head), + Some(_) => return Err(HistoryError::Integrity("live-heads commit width")), + None => hasher.update(&[0u8; 33]), + }; + hasher.update(&base); + } + Ok(*hasher.finalize().as_bytes()) +} + +/// Writes the §6.3 visited set and the retained pack set to the scratch +/// database the §7 copy joins against. The scratch runs `journal_mode=OFF`, so +/// it leaves no journal of its own. +fn write_visited( + scratch: &Path, + mark: &MarkResult, + packs: &BTreeMap, +) -> HistoryResult { + if std::fs::symlink_metadata(scratch).is_ok() { + return Err(HistoryError::Exists("staged compaction artifact")); + } + let connection = Connection::open_with_flags( + scratch, + OpenFlags::SQLITE_OPEN_READ_WRITE + | OpenFlags::SQLITE_OPEN_CREATE + | OpenFlags::SQLITE_OPEN_NO_MUTEX, + ) + .map_err(db_error)?; + connection + .busy_timeout(std::time::Duration::ZERO) + .map_err(db_error)?; + connection + .execute_batch( + "PRAGMA journal_mode=OFF; PRAGMA synchronous=OFF;\ +CREATE TABLE visited (\ + object_id BLOB PRIMARY KEY CHECK(length(object_id)=32),\ + pack_id INTEGER NOT NULL\ +) STRICT, WITHOUT ROWID;\ +CREATE TABLE live_pack (pack_id INTEGER PRIMARY KEY) STRICT, WITHOUT ROWID;", + ) + .map_err(db_error)?; + connection.execute_batch("BEGIN IMMEDIATE").map_err(db_error)?; + { + let mut visited = connection + .prepare("INSERT OR IGNORE INTO visited(object_id,pack_id) VALUES(?1,?2)") + .map_err(db_error)?; + let mut live = connection + .prepare("INSERT OR IGNORE INTO live_pack(pack_id) VALUES(?1)") + .map_err(db_error)?; + for pack in mark.objects().packs() { + live.execute(params![pack]).map_err(db_error)?; + } + for id in mark.objects().objects() { + let pack = packs + .get(id) + .ok_or(HistoryError::Integrity("mark object locator"))?; + visited + .execute(params![id.as_bytes().as_slice(), pack]) + .map_err(db_error)?; + } + } + connection.execute_batch("COMMIT").map_err(db_error)?; + connection.close().map_err(|(_, error)| db_error(error))?; + for suffix in ["-journal", "-wal", "-shm"] { + let mut sidecar = scratch.as_os_str().to_os_string(); + sidecar.push(suffix); + if std::fs::symlink_metadata(sidecar).is_ok() { + return Err(HistoryError::Integrity("visited scratch sidecar")); + } + } + Ok(std::fs::metadata(scratch).map_err(io_error)?.len()) +} + +/// What the staged rebuild produced, for the report and the install fence. +struct Built { + target: PathBuf, + target_bytes: u64, + /// The staged copy's extent right after `VACUUM INTO`, before the prune. + staged_bytes: u64, + /// The rollback-journal upper bound the staged page count implies. + journal_bound_bytes: u64, + visited_bytes: u64, + logical: u64, + canonical: u64, + stored: u64, + metadata: u64, + free_bytes: u64, +} + +impl Built { + /// §11 peak temporary bytes: the run's whole artifact footprint below the + /// rename, as a documented upper bound rather than a sampled peak. + /// + /// The staged copy is the whole sealed Store (`VACUUM INTO`), so it keeps + /// the source extent until the rewrite's final truncate. The rewrite then + /// writes the new Store into SQLite's temp database (the process temp + /// directory, unlinked) while rewriting the staged file in place, and both + /// the prune and the rewrite journal the pages they overwrite. The journal + /// term bounds either journal by one record per staged page + /// (`page_size + 8` bytes each: page number, image and checksum) plus the + /// header allowance, so it never under-reports the observed journal. The + /// sum over-reports the measured 50 GB peak by a few percent; §13 already + /// marks the report an estimate. + fn peak_temp_bytes(&self) -> u64 { + self.staged_bytes + .saturating_add(self.journal_bound_bytes) + .saturating_add(self.target_bytes) + .saturating_add(self.visited_bytes) + } +} + +/// Escaped SQL text literal for an `ATTACH` path (the statement cannot bind). +fn quote(text: &str) -> String { + text.replace('\'', "''") +} + +fn table_present(connection: &Connection, name: &str) -> HistoryResult { + let found: i64 = connection + .query_row( + "SELECT count(*) FROM sqlite_schema WHERE type='table' AND name=?1", + params![name], + |row| row.get(0), + ) + .map_err(db_error)?; + Ok(found == 1) +} + +/// The sealed Store and the mark a staged build is measured against. +struct BuildInput<'a> { + facts: &'a SealedFacts, + mark: &'a MarkResult, + tuple: &'a MarkTuple, + packs: &'a BTreeMap, + layout: crate::SqlitePackLayout, + synchronous: i64, +} + +/// The §7 steps 2–5: build the staged Store, copy only retained rows, compact +/// it, and switch it to WAL. +fn build( + input: BuildInput<'_>, + capacity: bool, + request: &CompactRequest, + op: &RunOp, +) -> HistoryResult { + let BuildInput { + facts, + mark, + tuple, + packs, + layout, + synchronous, + } = input; + let store = &facts.path; + let target = compact_path(store); + let visited = visited_path(store); + for staged in [&target, &visited] { + if std::fs::symlink_metadata(staged).is_ok() { + return Err(HistoryError::Exists("staged compaction artifact")); + } + } + stop_at(request, CompactFailpoint::BeforeCopy, op, store)?; + let visited_bytes = write_visited(&visited, mark, packs)?; + if capacity { + // §7 step 3 on a bounded filesystem: `VACUUM INTO` has already created + // the staged file when the write meets ENOSPC. The abort path removes + // it and the live Store is unchanged. + std::fs::write(&target, b"staged").map_err(io_error)?; + return Err(io_error(std::io::Error::from_raw_os_error(28))); + } + + // A real-process crash arm stops here: the visited scratch is written and + // `VACUUM INTO` has not started. See `BeforeVacuum`. + stop_at(request, CompactFailpoint::BeforeVacuum, op, store)?; + let source = open_immutable(store)?; + let target_text = target + .to_str() + .ok_or(HistoryError::InvalidInput("compaction path"))?; + source + .execute("VACUUM INTO ?1", params![target_text]) + .map_err(db_error)?; + source + .close() + .map_err(|(_, error)| db_error(error))?; + // The copy produced the staged file but has not pruned or verified it. + stop_at(request, CompactFailpoint::DuringCopy, op, store)?; + // The staged copy holds the source's whole extent until the final + // `VACUUM` truncates it; §11 counts it in the peak temp. + let staged_bytes = std::fs::metadata(&target).map_err(io_error)?.len(); + + let connection = Connection::open_with_flags( + &target, + OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::SQLITE_OPEN_NO_MUTEX, + ) + .map_err(db_error)?; + connection + .busy_timeout(std::time::Duration::ZERO) + .map_err(db_error)?; + connection + .execute_batch(&format!( + "PRAGMA journal_mode=DELETE; PRAGMA synchronous={synchronous};" + )) + .map_err(db_error)?; + // The prune and the rewrite journal the pages they overwrite; one record + // per staged page bounds either journal before the staged file shrinks. + let (staged_pages, page_size) = file_page_extent(&connection)?; + let journal_bound_bytes = journal_bound_bytes(staged_pages, page_size); + // The copied published-pack rows may be deleted in the artifact; the live + // immutability triggers are restored before the file is verified. + // `sqlite_sequence` is the acquisition operation counter: the copy keeps + // every row the source had, and the sequence never falls (§4.1, §7). + let sequences: Vec<(String, i64)> = if table_present(&connection, "sqlite_sequence")? { + let mut statement = connection + .prepare("SELECT name,seq FROM sqlite_sequence") + .map_err(db_error)?; + let mut rows = statement.query(params![]).map_err(db_error)?; + let mut found = Vec::new(); + while let Some(row) = rows.next().map_err(db_error)? { + found.push(( + row.get::<_, String>(0).map_err(db_error)?, + row.get::<_, i64>(1).map_err(db_error)?, + )); + } + found + } else { + Vec::new() + }; + let triggers: Vec = { + let mut statement = connection + .prepare( + "SELECT sql FROM sqlite_schema \ +WHERE type='trigger' AND name LIKE '%immutable%' AND sql IS NOT NULL", + ) + .map_err(db_error)?; + let mut rows = statement.query(params![]).map_err(db_error)?; + let mut found = Vec::new(); + while let Some(row) = rows.next().map_err(db_error)? { + found.push(row.get::<_, String>(0).map_err(db_error)?); + } + found + }; + connection + .execute_batch( + "DROP TRIGGER IF EXISTS pack_immutable_update;\ +DROP TRIGGER IF EXISTS pack_immutable_delete;\ +DROP TRIGGER IF EXISTS pack_unit_immutable_update;\ +DROP TRIGGER IF EXISTS pack_unit_immutable_delete;\ +PRAGMA foreign_keys=OFF;\ +PRAGMA defer_foreign_keys=ON;", + ) + .map_err(db_error)?; + connection + .execute_batch(&format!( + "ATTACH DATABASE '{}' AS scratch;", + quote(visited.to_str().ok_or(HistoryError::InvalidInput("compaction path"))?) + )) + .map_err(db_error)?; + + let units = layout.uses_units(); + let acquisition_tables = table_present(&connection, "init_operation")?; + connection + .execute_batch("BEGIN IMMEDIATE") + .map_err(db_error)?; + let staged = (|| -> HistoryResult<()> { + // §7 step 4: the totals trigger invariant holds before the copy. + let before: (i64, i64) = connection + .query_row( + "SELECT (SELECT logical FROM store_totals WHERE id=1),\ +(SELECT COALESCE(SUM(logical),0) FROM \"commit\")+\ +(SELECT COALESCE(SUM(logical),0) FROM layer)", + params![], + |row| Ok((row.get(0)?, row.get(1)?)), + ) + .map_err(db_error)?; + if before.0 != before.1 { + return Err(HistoryError::Integrity( + "Store totals disagree with the history rows", + )); + } + let mut deletes = String::from( + "DELETE FROM object_location WHERE object_id NOT IN \ +(SELECT object_id FROM scratch.visited);\ +DELETE FROM content_signature WHERE object_id NOT IN \ +(SELECT object_id FROM scratch.visited);\ +DELETE FROM file_digest WHERE root NOT IN (SELECT object_id FROM scratch.visited);\ +DELETE FROM binding_hint_block;\ +DELETE FROM \"commit\" WHERE commit_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='commit');\ +DELETE FROM layer WHERE layer_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='layer');\ +DELETE FROM branch WHERE branch_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='branch');\ +DELETE FROM layer_stack WHERE layer_stack_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='stack');\ +DELETE FROM layer_lineage WHERE layer_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='layer');\ +DELETE FROM commit_lineage WHERE commit_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='commit');\ +DELETE FROM absorbed WHERE run NOT IN (SELECT run FROM commit_lineage);\ +DELETE FROM reach WHERE key NOT IN \ +(SELECT layer_stack_id FROM layer_stack UNION SELECT run FROM commit_lineage);\ +DELETE FROM branch_retired WHERE branch_id NOT IN \ +(SELECT node_id FROM kept_node WHERE kind='branch');\ +DELETE FROM layer_stack_retired WHERE layer_stack_id NOT IN \ +(SELECT layer_stack_id FROM layer_stack);\ +DELETE FROM path_removed WHERE layer_stack_id NOT IN \ +(SELECT layer_stack_id FROM layer_stack);\ +DELETE FROM project_epoch WHERE layer_stack_id NOT IN \ +(SELECT layer_stack_id FROM layer_stack);\ +DELETE FROM merge_record;\ +DELETE FROM merge_operation;\ +DELETE FROM gc_intent;\ +DELETE FROM gc_dead;\ +DELETE FROM gc_op;", + ); + if units { + deletes.push_str( + "DELETE FROM pack_unit WHERE pack_id NOT IN \ +(SELECT pack_id FROM scratch.live_pack);", + ); + } + deletes.push_str( + "DELETE FROM pack WHERE pack_id NOT IN (SELECT pack_id FROM scratch.live_pack);", + ); + if acquisition_tables { + for table in ["init_operation", "init_entry", "init_host_file"] { + deletes.push_str(&format!("DELETE FROM {table};")); + } + } + for trigger in &triggers { + deletes.push_str(trigger.trim_end_matches(';')); + deletes.push_str(";\n"); + } + deletes.push_str(&format!( + "UPDATE history_meta SET catalog_incarnation={} WHERE id=1;\ +UPDATE store_totals SET \ +logical=(SELECT COALESCE(SUM(logical),0) FROM \"commit\")+\ +(SELECT COALESCE(SUM(logical),0) FROM layer),\ +canonical=(SELECT COALESCE(SUM(canonical_length),0) FROM object_location),\ +stored=(SELECT COALESCE(SUM(length),0) FROM pack),\ +metadata=(SELECT COALESCE(SUM(length),0) FROM pack WHERE domain=0) WHERE id=1;", + tuple.generation + 1 + )); + connection.execute_batch(&deletes).map_err(db_error)?; + Ok(()) + })(); + match staged { + Ok(()) => { + connection.execute_batch("COMMIT").map_err(db_error)?; + } + Err(error) => { + let _ = connection.execute_batch("ROLLBACK"); + let _ = connection.execute_batch("DETACH DATABASE scratch"); + let _ = connection.close(); + return Err(error); + } + } + connection + .execute_batch("DETACH DATABASE scratch") + .map_err(db_error)?; + // Reclaim the deleted pages: a wholly live Store, no freelist. + connection.execute_batch("VACUUM").map_err(db_error)?; + if !sequences.is_empty() && table_present(&connection, "sqlite_sequence")? { + connection + .execute_batch("DELETE FROM sqlite_sequence") + .map_err(db_error)?; + let mut statement = connection + .prepare("INSERT INTO sqlite_sequence(name,seq) VALUES(?1,?2)") + .map_err(db_error)?; + for (name, seq) in &sequences { + statement.execute(params![name, seq]).map_err(db_error)?; + } + } + let totals: (i64, i64, i64, i64) = connection + .query_row( + "SELECT logical,canonical,stored,metadata FROM store_totals WHERE id=1", + params![], + |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)), + ) + .map_err(db_error)?; + connection + .close() + .map_err(|(_, error)| db_error(error))?; + + // §7 step 5: switch to WAL, checkpoint, and leave no sidecar. + let connection = Connection::open_with_flags( + &target, + OpenFlags::SQLITE_OPEN_READ_WRITE | OpenFlags::SQLITE_OPEN_NO_MUTEX, + ) + .map_err(db_error)?; + connection + .busy_timeout(std::time::Duration::ZERO) + .map_err(db_error)?; + let mode: String = connection + .query_row("PRAGMA journal_mode=wal", params![], |row| row.get(0)) + .map_err(db_error)?; + if mode != "wal" { + return Err(HistoryError::Integrity("staged Store is not in WAL mode")); + } + connection + .execute_batch(&format!("PRAGMA synchronous={synchronous}")) + .map_err(db_error)?; + let busy: i64 = connection + .query_row("PRAGMA wal_checkpoint(TRUNCATE)", params![], |row| { + row.get(0) + }) + .map_err(db_error)?; + if busy != 0 { + return Err(HistoryError::Busy); + } + connection + .close() + .map_err(|(_, error)| db_error(error))?; + for suffix in ["-wal", "-shm", "-journal"] { + let mut sidecar = target.as_os_str().to_os_string(); + sidecar.push(suffix); + if std::fs::symlink_metadata(sidecar).is_ok() { + return Err(HistoryError::Integrity("staged Store sidecar")); + } + } + let target_bytes = std::fs::metadata(&target).map_err(io_error)?.len(); + let free_bytes = file_free_bytes(&target)?; + Ok(Built { + target, + target_bytes, + staged_bytes, + journal_bound_bytes, + visited_bytes, + logical: u64::try_from(totals.0).unwrap_or(0), + canonical: u64::try_from(totals.1).unwrap_or(0), + stored: u64::try_from(totals.2).unwrap_or(0), + metadata: u64::try_from(totals.3).unwrap_or(0), + free_bytes, + }) +} + +/// The staged Store and the mark a verification reads it against. +struct VerifyInput<'a> { + store: &'a Path, + built: &'a Built, + mark: &'a MarkResult, + tuple: &'a MarkTuple, + layout: crate::SqlitePackLayout, + acquisition: crate::SqliteAcquisitionSchema, +} + +/// The §7 step 6 verification through an `immutable=1` reader: schema identity, +/// foreign keys, row counts against the mark, both live-heads digests, the +/// allocator tuple and the recomputed totals. `quick_check` and the full doctor +/// stay separate commands. +fn verify( + input: VerifyInput<'_>, + request: &CompactRequest, + op: &RunOp, +) -> HistoryResult<()> { + let VerifyInput { + store, + built, + mark, + tuple, + layout, + acquisition, + } = input; + let connection = open_immutable(&built.target)?; + schema::check( + &connection, + &RefCell::new(SqlWork::default()), + (layout, acquisition), + ) + .map_err(HistoryError::from)?; + let count = |sql: &str| -> HistoryResult { + let value: i64 = connection + .query_row(sql, params![], |row| row.get(0)) + .map_err(db_error)?; + u64::try_from(value).map_err(|_| HistoryError::Integrity("verification count")) + }; + if count("SELECT count(*) FROM pragma_foreign_key_check")? != 0 { + return Err(HistoryError::Integrity("staged Store foreign key")); + } + if count("SELECT count(*) FROM object_location")? != mark.objects().len() as u64 { + return Err(HistoryError::Integrity("staged Store object count")); + } + if count("SELECT count(*) FROM pack")? != mark.objects().packs().len() as u64 { + return Err(HistoryError::Integrity("staged Store pack count")); + } + if count("SELECT count(*) FROM kept_node")? != mark.history().len() as u64 { + return Err(HistoryError::Integrity("staged Store history count")); + } + stop_at(request, CompactFailpoint::DuringVerify, op, store)?; + if file_heads_digest(&connection)? != mark.live_heads_digest() { + return Err(HistoryError::Conflict( + "staged Store live heads differ from the mark", + )); + } + let checked = file_tuple(&connection)?; + if checked.catalog_id != tuple.catalog_id + || checked.generation != tuple.generation + 1 + || checked.next_history_serial != tuple.next_history_serial + || checked.next_pack_id != tuple.next_pack_id + || checked.next_ordinal != tuple.next_ordinal + || checked.stamp > tuple.stamp + { + return Err(HistoryError::Integrity("staged Store allocator tuple")); + } + let totals = connection + .query_row( + "SELECT \ +(SELECT logical FROM store_totals WHERE id=1),\ +(SELECT COALESCE(SUM(logical),0) FROM \"commit\")+\ +(SELECT COALESCE(SUM(logical),0) FROM layer),\ +(SELECT canonical FROM store_totals WHERE id=1),\ +(SELECT COALESCE(SUM(canonical_length),0) FROM object_location),\ +(SELECT stored FROM store_totals WHERE id=1),\ +(SELECT COALESCE(SUM(length),0) FROM pack),\ +(SELECT metadata FROM store_totals WHERE id=1),\ +(SELECT COALESCE(SUM(length),0) FROM pack WHERE domain=0)", + params![], + |row| { + Ok(( + row.get::<_, i64>(0)?, + row.get::<_, i64>(1)?, + row.get::<_, i64>(2)?, + row.get::<_, i64>(3)?, + row.get::<_, i64>(4)?, + row.get::<_, i64>(5)?, + row.get::<_, i64>(6)?, + row.get::<_, i64>(7)?, + )) + }, + ) + .map_err(db_error)?; + if totals.0 != totals.1 + || totals.2 != totals.3 + || totals.4 != totals.5 + || totals.6 != totals.7 + { + return Err(HistoryError::Integrity("staged Store totals")); + } + let built_logical = u64::try_from(checked.logical).unwrap_or(u64::MAX); + let built_canonical = u64::try_from(checked.canonical).unwrap_or(u64::MAX); + let built_stored = u64::try_from(checked.stored).unwrap_or(u64::MAX); + let built_metadata = u64::try_from(checked.metadata).unwrap_or(u64::MAX); + if built_logical != built.logical + || built_canonical != built.canonical + || built_stored != built.stored + || built_metadata != built.metadata + { + return Err(HistoryError::Integrity("staged Store build totals")); + } + connection + .close() + .map_err(|(_, error)| db_error(error))?; + Ok(()) +} + +fn file_free_bytes(target: &Path) -> HistoryResult { + let measure = open_immutable(target)?; + let (free, page) = file_page_metrics(&measure)?; + measure + .close() + .map_err(|(_, error)| db_error(error))?; + Ok(free.saturating_mul(page)) +} + +fn source_state(store: &Path) -> HistoryResult<(u64, SystemTime, u32)> { + let metadata = std::fs::metadata(store).map_err(io_error)?; + let modified = metadata.modified().map_err(io_error)?; + let mut file = std::fs::File::open(store).map_err(io_error)?; + use std::io::{Read as _, Seek as _, SeekFrom}; + let mut header = [0u8; 4]; + file.seek(SeekFrom::Start(24)).map_err(io_error)?; + file.read_exact(&mut header).map_err(io_error)?; + Ok((metadata.len(), modified, u32::from_be_bytes(header))) +} + +/// True when one live or staged file carries a `-wal`, `-shm`, `-journal` or +/// multi-database super-journal (§7 step 7). +fn sidecar_present(path: &Path) -> Option { + for suffix in ["-wal", "-shm", "-journal"] { + let mut sidecar = path.as_os_str().to_os_string(); + sidecar.push(suffix); + let sidecar = PathBuf::from(sidecar); + if std::fs::symlink_metadata(&sidecar).is_ok() { + return Some(sidecar); + } + } + let name = path + .file_name() + .map_or_else(|| path.as_os_str().to_os_string(), |name| name.to_os_string()); + let mut prefix = name; + prefix.push("-mj"); + let prefix = prefix.to_string_lossy().into_owned(); + if let Some(parent) = path.parent() { + if let Ok(entries) = std::fs::read_dir(parent) { + for entry in entries.flatten() { + if entry.file_name().to_string_lossy().starts_with(&prefix) { + return Some(entry.path()); + } + } + } + } + None +} + +/// §7 step 7's fence before the rename: no sidecar, the same `G`, the same +/// catalog identity and the sealed `(size, mtime, change counter)`. +fn install_fence(facts: &SealedFacts, tuple: &MarkTuple) -> HistoryResult<()> { + // §10: the path must still name the sealed file. A replacement is + // `StaleStore` before the rename could install over a different Store. + if let Some(sealed) = facts.identity { + match sealed.names(&facts.path) { + Ok(true) => {} + Ok(false) => return Err(HistoryError::StaleStore), + Err(error) if error.kind() == std::io::ErrorKind::NotFound => { + return Err(HistoryError::StaleStore); + } + Err(_) => return Err(HistoryError::Integrity("Store identity at install")), + } + } + for path in [&facts.path, &compact_path(&facts.path)] { + if sidecar_present(path).is_some() { + return Err(HistoryError::Conflict("Store sidecar at install")); + } + } + let connection = open_immutable(&facts.path)?; + let current = file_tuple(&connection)?; + connection + .close() + .map_err(|(_, error)| db_error(error))?; + if ¤t != tuple { + return Err(HistoryError::Conflict("the sealed Store changed")); + } + let (bytes, modified, change_counter) = source_state(&facts.path)?; + if bytes != facts.bytes || modified != facts.modified || change_counter != facts.change_counter + { + return Err(HistoryError::Conflict("the sealed Store changed")); + } + Ok(()) +} + +/// §7 step 7: `chmod 0600` and `sync_all` before the rename. +fn prepare_target(target: &Path) -> HistoryResult<()> { + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(target, std::fs::Permissions::from_mode(0o600)).map_err(io_error)?; + } + let file = std::fs::OpenOptions::new() + .read(true) + .write(true) + .open(target) + .map_err(io_error)?; + file.sync_all().map_err(io_error)?; + Ok(()) +} + +fn sync_directory(store: &Path) -> HistoryResult<()> { + if let Some(parent) = store.parent() { + let directory = std::fs::File::open(parent).map_err(io_error)?; + directory.sync_all().map_err(io_error)?; + } + Ok(()) +} + +/// Removes the fixed artifact set and reports only what remains, so a +/// successful settle has a zero residue (§11). +fn clear_artifacts(store: &Path) -> CompactResidue { + let mut bytes = 0u64; + let mut left = Vec::new(); + for path in artifact_paths(store) { + let Ok(metadata) = std::fs::symlink_metadata(&path) else { + continue; + }; + if std::fs::remove_file(&path).is_err() && std::fs::symlink_metadata(&path).is_ok() { + // §11: residue is what the settle left behind. An artifact that + // was removed is not residue, so its bytes are not counted. + bytes = bytes.saturating_add(metadata.len()); + left.push( + path.file_name() + .map_or_else(|| path.display().to_string(), |name| { + name.to_string_lossy().into_owned() + }), + ); + } + } + CompactResidue { + bytes, + artifacts: left, + reason: None, + } +} + +/// Settles one run: the artifact set is removed first, the op record last +/// (§9: the op is settled only after removal). +fn settle(store: &Path, request: &CompactRequest, op: &RunOp) -> HistoryResult { + let mut residue = clear_artifacts(store); + // §9: the op settles only after the artifact set is gone. A crash here + // leaves the installed `G + 1` and the record for the next run. + stop_at(request, CompactFailpoint::DuringSettle, op, store)?; + let record_path = op_path(store); + if std::fs::symlink_metadata(&record_path).is_ok() { + let bytes = std::fs::metadata(&record_path).map_or(0, |metadata| metadata.len()); + if std::fs::remove_file(&record_path).is_err() + && std::fs::symlink_metadata(&record_path).is_ok() + { + residue.bytes = residue.bytes.saturating_add(bytes); + residue.artifacts.push(record_path.file_name().map_or_else( + || record_path.display().to_string(), + |name| name.to_string_lossy().into_owned(), + )); + } + } + if !residue.artifacts.is_empty() && residue.reason.is_none() { + residue.reason = Some("the artifact set could not be removed".to_owned()); + } + Ok(residue) +} + +/// Drops every artifact and the op record after a definite failure before the +/// rename; the live Store is unchanged apart from the seal's checkpoint. +fn abort_before_install(store: &Path) { + let residue = clear_artifacts(store); + if residue.artifacts.is_empty() { + let _ = std::fs::remove_file(op_path(store)); + } +} + +/// Releases the admission intent of a definite failure before the seal and +/// then removes the artifact set and the op record. When the release itself +/// fails the op record is kept as the next run's recovery breadcrumb (§9): +/// deleting it would leave a live intent that no later call could settle. +fn abort_run(history: &crate::HistoryProvider, store: &Path, op_id: &[u8; 16]) { + if history.gc_release(op_id).is_ok() { + abort_before_install(store); + } +} + +/// Judges and removes a leftover an earlier run recorded (§9): the artifact set +/// it names and the admission intent it took. The caller already holds the +/// writer lane, so a leftover owner is gone. +fn settle_leftover( + history: &crate::HistoryProvider, + store: &Path, + _generation: u64, + metrics: &mut RunMetrics, +) -> HistoryResult<()> { + let Some(op) = RunOp::read(store) else { + if artifact_paths(store) + .iter() + .any(|path| std::fs::symlink_metadata(path).is_ok()) + { + return Err(HistoryError::Exists("unrecorded compaction artifact")); + } + return Ok(()); + }; + // Adopt the recorded owner's admission intent before its artifact is gone. + history.gc_release(&op.op_id)?; + let residue = clear_artifacts(store); + if !residue.artifacts.is_empty() { + return Err(HistoryError::Integrity( + "recorded compaction artifact could not be removed", + )); + } + if std::fs::symlink_metadata(op_path(store)).is_ok() { + std::fs::remove_file(op_path(store)).map_err(io_error)?; + } + metrics.leftover_settled = true; + Ok(()) +} + +/// A writer held across the seal, install and settle, released on every exit. +struct WriterGuard(Option); + +impl WriterGuard { + fn new(writer: super::lane::writer_admission::Writer) -> Self { + Self(Some(writer)) + } + + fn take(&mut self) -> super::lane::writer_admission::Writer { + self.0.take().expect("a compaction holds its writer") + } + + fn put(&mut self, writer: super::lane::writer_admission::Writer) { + self.0 = Some(writer); + } + + fn release(&mut self) -> HistoryResult<()> { + match self.0.take() { + Some(writer) => writer.release().map_err(|_| HistoryError::UnknownOutcome), + None => Ok(()), + } + } +} + +impl Drop for WriterGuard { + fn drop(&mut self) { + if let Some(writer) = self.0.take() { + let _ = writer.release(); + } + } +} + +/// Set by the real-process crash harness (T12.2's second arm): when present, +/// a reached failpoint connects to this Unix socket, writes one readiness +/// byte and blocks until the harness SIGKILLs the process. Production callers +/// never set it, so a failpoint keeps its in-process behaviour. +const CRASH_GATE_ENV: &str = "LAYERFS_COMPACT_CRASH_GATE"; + +/// Holds a reached failpoint until the test harness kills this process. The +/// variable being absent is a no-op: the in-process stop applies. +#[cfg(unix)] +fn crash_gate() -> HistoryResult<()> { + use std::io::{Read, Write}; + use std::os::unix::net::UnixStream; + let Some(path) = std::env::var_os(CRASH_GATE_ENV) else { + return Ok(()); + }; + let mut gate = UnixStream::connect(path).map_err(io_error)?; + gate.write_all(b"R").map_err(io_error)?; + gate.flush().map_err(io_error)?; + // The harness never releases the gate: it SIGKILLs this process here. + let mut release = [0u8; 1]; + let _ = gate.read(&mut release); + Ok(()) +} + +/// A test-only crash stop: records the phase and leaves the state a crash +/// would leave. +fn stop_at( + request: &CompactRequest, + point: CompactFailpoint, + op: &RunOp, + store: &Path, +) -> HistoryResult<()> { + if request.failpoint != Some(point) { + return Ok(()); + } + let mut stopped = op.clone(); + stopped.phase = point.phase().to_owned(); + stopped.write(store)?; + #[cfg(unix)] + crash_gate()?; + Err(HistoryError::UnknownOutcome) +} + +fn immutable_tuple(path: &Path) -> HistoryResult { + let connection = open_immutable(path)?; + let tuple = file_tuple(&connection)?; + connection + .close() + .map_err(|(_, error)| db_error(error))?; + Ok(tuple) +} + +fn immutable_digest(path: &Path) -> HistoryResult<[u8; 32]> { + let connection = open_immutable(path)?; + let digest = file_heads_digest(&connection)?; + connection + .close() + .map_err(|(_, error)| db_error(error))?; + Ok(digest) +} + +/// §11: a zero field always carries one word of the closed vocabulary. +#[allow(clippy::too_many_arguments)] +fn receipt( + path: CompactPath, + generation_before: u64, + generation_after: u64, + dead_bytes: u64, + logical_discarded: u64, + backend_reusable: u64, + physical_shrink: u64, + kept_waste: CompactKeptWaste, + peak_temp_bytes: u64, + residue: CompactResidue, + total_stored: u64, + history_rows: u64, +) -> CompactReceipt { + let mut zero_reasons = Vec::new(); + if dead_bytes == 0 { + let reason = if total_stored == 0 { + "empty-store" + } else { + "no-waste" + }; + zero_reasons.push(CompactZeroReason { + field: "deadBytesBound", + reason, + }); + zero_reasons.push(CompactZeroReason { + field: "deadBytesRefined", + reason, + }); + } + if logical_discarded == 0 { + let reason = if history_rows == 0 { + "no-history" + } else if path == CompactPath::None { + "none-path" + } else { + "no-waste" + }; + zero_reasons.push(CompactZeroReason { + field: "logicalDiscarded", + reason, + }); + } + if physical_shrink == 0 { + zero_reasons.push(CompactZeroReason { + field: "physicalShrink", + reason: if path == CompactPath::None { + "none-path" + } else { + "no-waste" + }, + }); + } + if backend_reusable == 0 { + zero_reasons.push(CompactZeroReason { + field: "backendReusable", + reason: if path == CompactPath::None { + "none-path" + } else { + "no-waste" + }, + }); + } + if kept_waste.is_empty() { + zero_reasons.push(CompactZeroReason { + field: "keptWaste", + reason: "no-waste", + }); + } + if peak_temp_bytes == 0 { + zero_reasons.push(CompactZeroReason { + field: "peakTempBytes", + reason: "none-path", + }); + } + CompactReceipt { + path, + generation_before, + generation_after, + dead_bytes_bound: dead_bytes, + dead_bytes_refined: dead_bytes, + logical_discarded, + backend_reusable, + physical_shrink, + kept_waste, + peak_temp_bytes, + residue, + estimate: true, + zero_reasons, + } +} + +impl SqliteHandles { + /// Runs one §7 SQLite Store compaction on this Store's own machine. + /// + /// The call consumes the handles like [`Self::seal`]: it checkpoints and + /// closes the sole session, and a rebuild installs a new file at `G + 1`. + /// It takes the Store's exclusive writer lane before its admission intent, + /// so no admitted writer can interleave between the mark, the seal and the + /// rename. The caller reopens the Store afterwards. + /// + /// A definite failure before the rename removes the artifact set and leaves + /// the old Store unchanged apart from the seal's checkpoint. A rename or + /// directory-fsync failure is installed-but-uncertain: the new file and the + /// op record are kept for the next `store.compact` to judge (§9). + pub fn compact(self, request: &CompactRequest) -> HistoryResult { + let mut metrics = RunMetrics::start(); + let result = self.compact_measured(request, &mut metrics); + metrics.finish(&result); + result + } + + /// The measured body of [`Self::compact`]; `metrics` observes it. + fn compact_measured( + self, + request: &CompactRequest, + metrics: &mut RunMetrics, + ) -> HistoryResult { + #[cfg(not(any(target_os = "linux", target_os = "macos")))] + { + let _ = (request, metrics); + return Err(HistoryError::Unsupported("SQLite Store compaction")); + } + #[cfg(any(target_os = "linux", target_os = "macos"))] + { + let SqliteHandles { + storage, + history, + acquisition, + } = self; + drop(acquisition); + let session = storage.session.clone(); + let store = session.path.clone(); + let profile = session.profile.clone(); + let layout = session.layout; + let acquisition_schema = session.acquisition; + let synchronous = profile.synchronous; + + // §7 step 1: the exclusive lane first, so the generation this run + // records cannot move between the mark, the seal and the rename. + let lane = session.hold_lane().map_err(HistoryError::from)?; + // §7 step 1: the sealed source's WAL is emptied before the closure. + // The lane is already held, so no writer can append meanwhile. + session.checkpoint_holding().map_err(HistoryError::from)?; + let live = live_tuple(&session)?; + let generation = u64::try_from(live.generation) + .map_err(|_| HistoryError::Integrity("Store generation"))?; + metrics.generation_before = generation; + settle_leftover(&history, &store, generation, metrics)?; + + let op_id = request.op_id; + let mut op = RunOp { + op_id, + generation: live.generation, + phase: "admission".to_owned(), + started_ms: now_ms(), + owner_pid: request.owner_pid, + owner_pid_start: request.owner_pid_start, + owner_pid_boot: request.owner_pid_boot, + tuple: live.clone(), + live_heads_digest: [0u8; 32], + }; + op.write(&store)?; + let intent = GcIntent::operation( + op_id, + GcIntentKind::Compaction, + GcScopeKind::Store, + history.catalog_id.as_slice().to_vec(), + ) + .owned( + request.owner_runtime.as_deref(), + request.owner_boot.as_deref(), + ) + .with_phase(Some("mark")); + if let Err(error) = history.gc_register(&intent) { + // A definite admission refusal started nothing: the run's op + // record must not outlive it as a false leftover (§9). + let _ = std::fs::remove_file(op_path(&store)); + return Err(error); + } + // §8: the registration, the mark and the totals read are one + // admitted sequence. A definite failure here releases the intent + // before the artifact set and the op record go, so the Store is + // left exactly as it was and no later call meets BusyOp. + metrics.begin_phase(CompactPhase::Mark); + let admitted = + (|| -> HistoryResult<(MarkResult, MarkTuple, u64, u64, CompactKeptWaste, u64)> { + let mark = history.mark()?; + let tuple = live_tuple(&session)?; + op.tuple = tuple.clone(); + op.live_heads_digest = mark.live_heads_digest(); + op.phase = "mark".to_owned(); + op.write(&store)?; + let lengths = pack_lengths(&session)?; + let total = lengths.values().copied().fold(0u64, u64::saturating_add); + let mut live_stored = 0u64; + for pack in mark.objects().packs() { + let length = lengths + .get(pack) + .ok_or(HistoryError::Integrity("mark pack"))?; + live_stored = live_stored.saturating_add(*length); + } + let dead = total.saturating_sub(live_stored); + let kept_waste = CompactKeptWaste::from_mark(mark.objects().waste()); + let history_rows = u64::try_from(tuple.history_rows).unwrap_or(0); + Ok((mark, tuple, total, dead, kept_waste, history_rows)) + })(); + let (mark, tuple, total, dead, kept_waste, history_rows) = match admitted { + Ok(admitted) => admitted, + Err(error) => { + abort_run(&history, &store, &op_id); + return Err(error); + } + }; + let rebuild = total > 0 && dead.saturating_mul(10) >= total; + metrics.end_phase(); + + if !rebuild { + // §3 `none`: mark only. The intent is cleared and the op record + // removed; nothing is rebuilt and the generation is unchanged. + let (free, page) = live_page_metrics(&session)?; + history.gc_release(&op_id)?; + let _ = std::fs::remove_file(op_path(&store)); + drop(lane); + return Ok(receipt( + CompactPath::None, + generation, + generation, + dead, + 0, + free.saturating_mul(page), + 0, + kept_waste, + 0, + CompactResidue::default(), + total, + history_rows, + )); + } + + // §7 step 2: a stop here leaves the open session, the writer lane, + // the admission intent and the op record; the live Store is at `G`. + stop_at(request, CompactFailpoint::BeforeSeal, &op, &store)?; + + // §7 step 2 onward: seal and rebuild. Only the session remains. + let object_packs = match object_packs(&session) { + Ok(packs) => packs, + Err(error) => { + abort_run(&history, &store, &op_id); + return Err(error); + } + }; + // §8/§9: release the admission intent while the Store is still + // reachable. Every failure below runs after the seal, when this + // process can no longer run SQL on the Store; without this release + // a live intent would refuse every later GC operation. The held + // writer lane still excludes writers through the install, and a + // crash leaves the op record for the next run to settle. + history.gc_release(&op_id)?; + drop(history); + drop(storage); + let mut guard = WriterGuard::new(lane.into_writer()); + let session = Arc::try_unwrap(session).map_err(|_| HistoryError::Busy)?; + let writer = guard.take(); + let (facts, writer) = match session.seal_holding(writer) { + Ok(sealed) => sealed, + Err(error) => return Err(seal_error(error)), + }; + guard.put(writer); + // §7 step 1.5: the sealed file is about to be read back. + stop_at(request, CompactFailpoint::BeforeSealRead, &op, &store)?; + + // §7 step 1.5's fence: the seal must not have moved the generation + // or the heads the mark recorded. + let sealed_tuple = match immutable_tuple(&facts.path) { + Ok(tuple) => tuple, + Err(error) => { + abort_before_install(&store); + return Err(error); + } + }; + if sealed_tuple != tuple { + abort_before_install(&store); + return Err(HistoryError::Conflict("the Store changed after the mark")); + } + match immutable_digest(&facts.path) { + Ok(digest) if digest == mark.live_heads_digest() => {} + Ok(_) => { + abort_before_install(&store); + return Err(HistoryError::Conflict( + "the Store heads changed after the mark", + )); + } + Err(error) => { + abort_before_install(&store); + return Err(error); + } + } + stop_at(request, CompactFailpoint::AfterSeal, &op, &store)?; + + metrics.begin_phase(CompactPhase::Build); + op.phase = "build".to_owned(); + op.write(&store)?; + let capacity = request.failpoint == Some(CompactFailpoint::CapacityAtBuild); + let built = match build( + BuildInput { + facts: &facts, + mark: &mark, + tuple: &tuple, + packs: &object_packs, + layout, + synchronous, + }, + capacity, + request, + &op, + ) { + Ok(built) => built, + // A stop point leaves the crash state on purpose: never abort + // an artifact set a recorded run names (§9). + Err(HistoryError::UnknownOutcome) => return Err(HistoryError::UnknownOutcome), + Err(error) => { + abort_before_install(&store); + return Err(error); + } + }; + stop_at(request, CompactFailpoint::AfterBuild, &op, &store)?; + stop_at(request, CompactFailpoint::AfterWalSwitch, &op, &store)?; + metrics.end_phase(); + + metrics.begin_phase(CompactPhase::Verify); + op.phase = "verify".to_owned(); + if let Err(error) = op.write(&store) { + abort_before_install(&store); + return Err(error); + } + if let Err(error) = verify( + VerifyInput { + store: &store, + built: &built, + mark: &mark, + tuple: &tuple, + layout, + acquisition: acquisition_schema, + }, + request, + &op, + ) { + if matches!(error, HistoryError::UnknownOutcome) { + return Err(error); + } + abort_before_install(&store); + return Err(error); + } + stop_at(request, CompactFailpoint::AfterVerify, &op, &store)?; + metrics.end_phase(); + + metrics.begin_phase(CompactPhase::Install); + if let Some(hook) = request.before_install_hook { + hook(&facts.path); + } + if let Err(error) = install_fence(&facts, &tuple) { + abort_before_install(&store); + return Err(error); + } + if let Err(error) = prepare_target(&built.target) { + abort_before_install(&store); + return Err(error); + } + stop_at(request, CompactFailpoint::BeforeInstall, &op, &store)?; + + if std::fs::rename(&built.target, &facts.path).is_err() { + // Installed-but-uncertain: never delete the new Store as if + // nothing happened (§7 step 8, §9). + op.phase = "install".to_owned(); + let _ = op.write(&store); + return Err(HistoryError::UnknownOutcome); + } + // §7 step 7: the rename happened; a crash before the directory + // fsync leaves an installed-but-uncertain `G + 1`. + stop_at(request, CompactFailpoint::DuringRename, &op, &store)?; + if let Err(_error) = sync_directory(&facts.path) { + op.phase = "install".to_owned(); + let _ = op.write(&store); + return Err(HistoryError::UnknownOutcome); + } + op.phase = "install".to_owned(); + let _ = op.write(&store); + stop_at(request, CompactFailpoint::AfterInstall, &op, &store)?; + guard.release()?; + let residue = settle(&store, request, &op)?; + let logical_discarded = u64::try_from(tuple.logical) + .unwrap_or(0) + .saturating_sub(built.logical); + let physical_shrink = facts.bytes.saturating_sub(built.target_bytes); + Ok(receipt( + CompactPath::Rebuild, + generation, + generation.saturating_add(1), + dead, + logical_discarded, + built.free_bytes, + physical_shrink, + kept_waste, + built.peak_temp_bytes(), + residue, + total, + history_rows, + )) + } + } +} + +/// The phase clock and §11 values one measured `compact` run observes. +struct RunMetrics { + started: Instant, + phase: Option<(CompactPhase, Instant)>, + phase_nanos: Vec<(CompactPhase, u64)>, + generation_before: u64, + generation_after: u64, + dead_bytes_bound: u64, + dead_bytes_refined: u64, + kept_waste: CompactKeptWaste, + residue_bytes: u64, + leftover_settled: bool, +} + +impl RunMetrics { + fn start() -> Self { + Self { + started: Instant::now(), + phase: None, + phase_nanos: Vec::new(), + generation_before: 0, + generation_after: 0, + dead_bytes_bound: 0, + dead_bytes_refined: 0, + kept_waste: CompactKeptWaste::default(), + residue_bytes: 0, + leftover_settled: false, + } + } + + /// Ends the current phase and starts `phase`; a phase is inclusive wall + /// time, never an exclusive CPU decomposition. + fn begin_phase(&mut self, phase: CompactPhase) { + self.end_phase(); + self.phase = Some((phase, Instant::now())); + } + + fn end_phase(&mut self) { + if let Some((phase, started)) = self.phase.take() { + self.phase_nanos.push(( + phase, + u64::try_from(started.elapsed().as_nanos()).unwrap_or(u64::MAX), + )); + } + } + + /// Records this run once, whatever its result. The outcome and refusal + /// come from the typed error, so a `Busy`/`Unresolved` refusal is counted + /// without changing the error the caller receives. + fn finish(mut self, result: &HistoryResult) { + self.end_phase(); + let total_nanos = + u64::try_from(self.started.elapsed().as_nanos()).unwrap_or(u64::MAX); + let (outcome, refusal) = match result { + Ok(receipt) => { + self.generation_after = receipt.generation_after; + self.dead_bytes_bound = receipt.dead_bytes_bound; + self.dead_bytes_refined = receipt.dead_bytes_refined; + self.kept_waste = receipt.kept_waste.clone(); + self.residue_bytes = receipt.residue.bytes; + let outcome = match receipt.path { + CompactPath::Rebuild => CompactOutcome::Rebuild, + CompactPath::None => CompactOutcome::None, + }; + (outcome, None) + } + Err(error) => { + if !error.unknown() { + self.generation_after = self.generation_before; + } + ( + if error.unknown() { + CompactOutcome::Uncertain + } else { + CompactOutcome::Failed + }, + match error { + HistoryError::Busy => Some(CompactRefusal::Busy), + HistoryError::Unresolved(_) => Some(CompactRefusal::Unresolved), + _ => None, + }, + ) + } + }; + compact_metrics::record_run(&CompactRunObservation { + outcome, + generation_before: self.generation_before, + generation_after: self.generation_after, + dead_bytes_bound: self.dead_bytes_bound, + dead_bytes_refined: self.dead_bytes_refined, + kept_waste: self.kept_waste, + residue_bytes: self.residue_bytes, + phase_nanos: self.phase_nanos, + total_nanos, + leftover_settled: self.leftover_settled, + refusal, + }); + } +} + +#[cfg(test)] +mod tests { + use super::{journal_bound_bytes, io_error, Built}; + use layerfs_history::HistoryError; + + /// §7 step 3 on a bounded filesystem: `ENOSPC`, `EDQUOT` and `EFBIG` are + /// the report's `Capacity` refusal, never a corruption verdict. + #[test] + fn bounded_filesystem_errors_are_capacity() { + for code in [28, 122, 27, 69] { + let error = io_error(std::io::Error::from_raw_os_error(code)); + assert!( + matches!(error, HistoryError::Capacity(_)), + "errno {code}: {error:?}" + ); + } + } + + /// Every other I/O failure keeps the integrity classification. + #[test] + fn another_io_error_is_integrity() { + let error = io_error(std::io::Error::from_raw_os_error(5)); + assert!(matches!(error, HistoryError::Integrity(_)), "{error:?}"); + } + + /// §11 `peakTempBytes` on the 50 GB arm (T-G66): the staged copy holds the + /// source extent, the rewrite holds that copy beside the new Store, and the + /// rollback journal is bounded by the staged page count. The receipt must + /// cover the measured 143.1 GB pre-rebuild peak and the 44.6 GB journal the + /// old `new + visited` formula dropped. + #[test] + fn peak_temp_covers_the_staged_copy_and_the_rollback_journal() { + let page_size = 4096; + // 50,862,854,144 B staged copy = the sealed Store's page count. + let staged_pages = 12_417_689; + let staged_bytes = staged_pages * page_size; + let target_bytes = 45_763_203_072; + let visited_bytes = 20_365_312; + let journal = journal_bound_bytes(staged_pages, page_size); + assert_eq!(journal, 50_962_203_848); + let built = Built { + target: std::path::PathBuf::new(), + target_bytes, + staged_bytes, + journal_bound_bytes: journal, + visited_bytes, + logical: 0, + canonical: 0, + stored: 0, + metadata: 0, + free_bytes: 0, + }; + let peak = built.peak_temp_bytes(); + assert_eq!(peak, 147_608_626_376); + assert!(peak >= target_bytes + journal + visited_bytes); + assert!( + peak >= target_bytes + 44_630_503_928 + visited_bytes, + "the bound must cover the 50 GB arm's observed 44.6 GB journal" + ); + assert!( + peak >= 143_100_000_000, + "the bound must cover the measured 143.1 GB sampled 50 GB peak" + ); + } +} diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/lane/lane.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/lane/lane.rs index 1c31440b0b..3d58695311 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/lane/lane.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/lane/lane.rs @@ -38,6 +38,17 @@ impl Session { } } +impl LaneHold { + /// Takes the cross-process writer lock out of the hold and releases the + /// connection turn, so a seal can consume the session while the lane is + /// still held (§7 step 1). The caller becomes the lane's owner. + pub(crate) fn into_writer(mut self) -> Writer { + self.writer + .take() + .expect("a held Store lane owns its writer") + } +} + impl Drop for LaneHold { fn drop(&mut self) { if let Some(writer) = self.writer.take() { diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/identity.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/identity.rs new file mode 100644 index 0000000000..43eac9148c --- /dev/null +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/identity.rs @@ -0,0 +1,51 @@ +//! §10 Store-file identity: the `(dev, ino)` fence a SQLite handle applies +//! before it reads or writes, and the install fence re-applies to the sealed +//! source. +use std::path::Path; + +/// The `(device, inode)` pair naming one Store file at one moment (§10). +/// +/// A transaction compares the pair recorded at open with the pair the Store +/// path names now; a replacement or a move is `StaleStore`. Together with the +/// held writer lane this is the SQLite fence of §10: an admitted writer cannot +/// be in flight at install, and a connection that bypassed admission is caught +/// at its next transaction. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub(crate) struct FileIdentity { + /// The filesystem device holding the file. + pub(crate) dev: u64, + /// The file's inode number on that device. + pub(crate) ino: u64, +} + +impl FileIdentity { + /// Captures the identity of the file `path` currently names. + /// + /// `Ok(None)` means this platform has no `(dev, ino)` pair; the fence then + /// has nothing to compare and callers keep their other facts. `Err` is a + /// path that could not be inspected at all. + pub(crate) fn capture(path: &Path) -> Result, std::io::Error> { + let metadata = std::fs::metadata(path)?; + #[cfg(unix)] + { + use std::os::unix::fs::MetadataExt as _; + Ok(Some(Self { + dev: metadata.dev(), + ino: metadata.ino(), + })) + } + #[cfg(not(unix))] + { + let _ = metadata; + Ok(None) + } + } + + /// §10: whether `path` still names this exact file. + pub(crate) fn names(&self, path: &Path) -> Result { + match Self::capture(path)? { + Some(current) => Ok(current == *self), + None => Ok(true), + } + } +} diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/mod.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/mod.rs index 1895897203..a23a4ce8cb 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/mod.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/mod.rs @@ -4,6 +4,7 @@ pub(crate) mod file_control; #[cfg(any(target_os = "macos", target_os = "linux"))] pub(crate) mod headroom; +pub(crate) mod identity; pub(crate) mod reclamation; pub(crate) mod seal; #[cfg(target_os = "macos")] diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/seal.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/seal.rs index f9a02f37c0..6370074a43 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/seal.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/lifecycle/seal.rs @@ -1,12 +1,95 @@ //! Sole-owner host seal; never available through the daemon's Store ports. +use crate::backend::sqlite::lane::writer_admission::Writer; +use crate::backend::sqlite::lifecycle::identity::FileIdentity; use crate::backend::sqlite::session::connection::Session; use crate::backend::sqlite::session::query; use crate::backend::sqlite::session::rows; use crate::{backend::records::BackendError, SealedStore}; use layerfs_storage::port::PersistenceError; +use std::io::{Read, Seek, SeekFrom}; +use std::path::{Path, PathBuf}; +use std::time::SystemTime; + +/// The identity of one closed Store file at the moment its last connection +/// closed, captured under the writer lane (§7 step 1). +#[derive(Clone, Debug)] +pub(crate) struct SealedFacts { + /// The closed database file; no sidecar was present when it was captured. + pub(crate) path: PathBuf, + /// Provisioning profile the file was closed under. + pub(crate) profile: crate::SqlitePersistenceProfile, + /// SQLite version that created/sealed the file. + pub(crate) sqlite_version: String, + /// Main-file bytes after the WAL was checkpointed and the connection closed. + pub(crate) bytes: u64, + /// Main-file modification time at the same moment. + pub(crate) modified: SystemTime, + /// The database header change counter (big-endian bytes 24..28). + pub(crate) change_counter: u32, + /// The file's §10 `(dev, ino)` while the lane was still held. + pub(crate) identity: Option, +} + +impl SealedFacts { + /// The public sealed-Store handoff this identity describes. + pub(crate) fn into_store(self) -> SealedStore { + SealedStore { + path: self.path, + profile: self.profile, + sqlite_version: self.sqlite_version, + bytes: self.bytes, + } + } +} + +fn read_change_counter(path: &Path) -> Result { + let refused = |error: std::io::Error| PersistenceError::Refused { + status: error.to_string(), + }; + let mut file = std::fs::File::open(path).map_err(refused)?; + let mut bytes = [0u8; 4]; + file.seek(SeekFrom::Start(24)).map_err(refused)?; + file.read_exact(&mut bytes).map_err(refused)?; + Ok(u32::from_be_bytes(bytes)) +} impl Session { - pub(crate) fn seal(mut self) -> Result { + /// Consumes the sole session, checkpoints once, closes and verifies one file. + /// macOS then releases unused allocation beyond the original file's logical + /// end, without copying its contents or changing its identity or length. + /// + /// A retained provider/Storage/Reader/Save refuses with `Busy` before any + /// checkpoint. Another process can obstruct checkpoint or keep sidecars; + /// neither case triggers a retry or deletion. Provisioning must prevent + /// new openers throughout sealing and handoff. This is not live Store + /// reclamation. Uncertain transfer/temporary-close outcomes retain the owned + /// `.layerfs-allocation-*` sibling; no automatic retry or deletion follows. + pub(crate) fn seal(self) -> Result { + let writer = { + let mut state = self + .state + .lock() + .map_err(|_| PersistenceError::Uncertain)?; + state.writer_hold.take() + }; + let writer = match writer { + Some(writer) => writer, + None => Writer::acquire(&self.path)?, + }; + let (facts, writer) = self.seal_holding(writer)?; + writer.release().map_err(|_| PersistenceError::Uncertain)?; + Ok(facts.into_store()) + } + + /// [`Self::seal`] under a caller-held writer lane (§7 step 1: the guard is + /// passed into the seal, never acquired a second time). The lane is returned + /// so a compaction can keep it through the rename. The checkpoint, checked + /// close, sidecar check and the sealed `(size, mtime, change counter)` + /// capture all run while the lane is held. + pub(crate) fn seal_holding( + mut self, + writer: Writer, + ) -> Result<(SealedFacts, Writer), PersistenceError> { if !self.writable { return Err(BackendError::ReadOnly.into()); } @@ -19,13 +102,6 @@ impl Session { if state.quarantined || !state.connection.is_autocommit() { return Err(PersistenceError::Uncertain); } - // The same advisory lane as a write transaction: a seal is the sole - // owner's offline handoff, so no other opener may write while the - // checkpoint, close and sidecar removal below run. - if state.writer_hold.is_none() { - state.writer_hold = - Some(crate::backend::sqlite::lane::writer_admission::Writer::acquire(&self.path)?); - } #[cfg(target_os = "macos")] let identity = super::seal_allocation::Identity::capture(&self.path)?; #[cfg(target_os = "macos")] @@ -68,22 +144,39 @@ impl Session { } } } - if let Some(writer) = state.writer_hold.take() { - writer.release().map_err(|_| PersistenceError::Uncertain)?; - } #[cfg(target_os = "macos")] - let bytes = super::seal_allocation::release(&self.path, identity)?; + let released = super::seal_allocation::release(&self.path, identity)?; #[cfg(not(target_os = "macos"))] - let bytes = std::fs::metadata(&self.path) + let released = 0u64; + let metadata = std::fs::metadata(&self.path).map_err(|error| PersistenceError::Refused { + status: error.to_string(), + })?; + let modified = metadata + .modified() .map_err(|error| PersistenceError::Refused { status: error.to_string(), - })? - .len(); - Ok(SealedStore { - path: self.path, - profile: self.profile.persistence, - sqlite_version: self.profile.sqlite_version, - bytes, - }) + })?; + let bytes = if released == 0 { + metadata.len() + } else { + released + }; + let change_counter = read_change_counter(&self.path)?; + let identity = + FileIdentity::capture(&self.path).map_err(|error| PersistenceError::Refused { + status: error.to_string(), + })?; + Ok(( + SealedFacts { + path: self.path.clone(), + profile: self.profile.persistence, + sqlite_version: self.profile.sqlite_version.clone(), + bytes, + modified, + change_counter, + identity, + }, + writer, + )) } } diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/mechanics.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/mechanics.rs index ef0b9c1464..1407870041 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/mechanics.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/mechanics.rs @@ -15,6 +15,9 @@ impl HistoryStatements for Transaction<'_> { fn history(&self, key: &str, params: Vec) -> Result, BackendError> { Transaction::history(self, key, params) } + fn mechanics(&self) -> &dyn Mechanics { + self + } } impl Mechanics for Transaction<'_> { diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/mod.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/mod.rs index 2cb0925bbd..d79e929597 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/mod.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/mod.rs @@ -1,6 +1,7 @@ //! SQLite-only connection, transaction, query, schema and physical mechanics, //! grouped by role (#506 A1). pub(crate) mod acquisition; +pub(crate) mod compact; pub(crate) mod heads; pub(crate) mod lane; pub(crate) mod lifecycle; diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/schema.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/schema.rs index 5d87c51a72..d5685f4960 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/schema.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/schema.rs @@ -15,6 +15,33 @@ pub(crate) const LINEAGE: &str = include_str!("../../../sql/sqlite/lineage.sql") pub(crate) const SCRATCH: &str = include_str!("../../../sql/sqlite/merge_scratch.sql"); /// Whole-content file digests (#364); a Store written before them gains them at open. pub(crate) const DIGESTS: &str = include_str!("../../../sql/sqlite/file_digest.sql"); +/// GC markers, positions and admission records; a Store written before them +/// gains them at open. +pub(crate) const GC: &str = include_str!("../../../sql/sqlite/gc.sql"); +/// The position columns T1.2a/T1.4 append, as `("table", "column", ALTER)`; +/// a Store written before them gains them at open. +pub(crate) const POSITION_COLUMNS: [(&str, &str, &str); 4] = [ + ( + "\"commit\"", + "history_serial", + "ALTER TABLE \"commit\" ADD COLUMN history_serial INTEGER NOT NULL DEFAULT 0", + ), + ( + "layer", + "history_serial", + "ALTER TABLE layer ADD COLUMN history_serial INTEGER NOT NULL DEFAULT 0", + ), + ( + "store_policy", + "trace_salt", + "ALTER TABLE store_policy ADD COLUMN trace_salt BLOB NOT NULL DEFAULT (X'0000000000000000000000000000000000000000000000000000000000000000') CHECK(length(trace_salt)=32)", + ), + ( + "history_meta", + "next_history_serial", + "ALTER TABLE history_meta ADD COLUMN next_history_serial INTEGER NOT NULL DEFAULT 1", + ), +]; const UNIT_INDEX: &str = include_str!("../../../sql/sqlite/objects_units_index.sql"); const UNITS: &str = include_str!("../../../sql/sqlite/objects_units.sql"); const ACQUISITION: &str = include_str!("../../../sql/sqlite/acquisition/schema.sql"); @@ -34,6 +61,7 @@ pub(super) fn scripts((layout, acquisition): Selection) -> Vec { LINEAGE.to_owned(), SCRATCH.to_owned(), DIGESTS.to_owned(), + GC.to_owned(), ]; if acquisition == crate::SqliteAcquisitionSchema::Tables { scripts.push(ACQUISITION.to_owned()); @@ -60,6 +88,165 @@ pub(crate) fn definition(c: &Connection, w: &RefCell) -> Result &'static str { + let start = HISTORY + .find(" next_history_serial INTEGER NOT NULL DEFAULT 1") + .expect("history schema holds the next serial column"); + let end = start + HISTORY[start..].find('\n').expect("column line ends") + 1; + &HISTORY[start..end] +} + +/// The `kept_node` table as `gc.sql` writes it: one appended statement at the +/// end of the GC script, so removing exactly this text leaves the source a +/// Store written before T7.1 recorded. +fn kept_node_table() -> &'static str { + let start = GC + .find("CREATE TABLE kept_node (") + .expect("the GC schema holds kept_node"); + let end = start + GC[start..].find(";\n").expect("kept_node ends") + 2; + &GC[start..end] +} + +/// The `commit` and `layer` position column as `history.sql` writes it; it +/// appears once in each of the two tables. +fn history_serial_column() -> &'static str { + let start = HISTORY + .find(" history_serial INTEGER NOT NULL DEFAULT 0") + .expect("history schema holds the position column"); + let end = start + HISTORY[start..].find('\n').expect("column line ends") + 1; + &HISTORY[start..end] +} + +/// The `store_policy` position salt column as `metadata.sql` writes it, +/// together with the comma that ends `next_ordinal`: it was appended as the +/// table's last column, so a Store written before it recorded neither the +/// line nor the comma. +fn trace_salt_column() -> &'static str { + let start = METADATA + .find(",\n trace_salt BLOB NOT NULL DEFAULT") + .expect("metadata schema holds the salt column"); + // The search starts past the comma and newline; the newline that ends the + // column is kept, since it is also the one before the table's closing + // `) STRICT;` that the pre-T1.2a text held. + let line = start + 2; + let end = line + METADATA[line..].find('\n').expect("column line ends"); + &METADATA[start..end] +} + +/// `source` as a Store written before the position columns recorded it: the +/// two `history_serial` columns, `store_policy.trace_salt` and +/// `history_meta.next_history_serial` removed. The table migrations compare +/// against this so a Store from before those columns still matches its +/// recorded source. +fn without_position_columns(source: String) -> String { + source + .replacen(history_serial_column(), "", 2) + .replacen(trace_salt_column(), "", 1) + .replacen(next_history_serial_column(), "", 1) +} + +/// The ALTERs and salt backfill an old Store needs; existing rows keep serial +/// 0 and the Store keeps one random salt. +fn add_position_columns(tx: &Transaction<'_>) -> Result<(), BackendError> { + for (_, _, alter) in POSITION_COLUMNS.iter().take(3) { + tx.query(alter, vec![])?; + } + tx.query( + "UPDATE store_policy SET trace_salt=randomblob(32) WHERE id=1", + vec![], + )?; + Ok(()) +} + +/// The serials and epochs a Store written before T1.4 needs: Commits take the +/// next Store serials in `(created_ms, commit_id)` order, then each project's +/// genesis Layer takes the next one in stack-id order; every other Layer +/// republishes its source Commit and carries that Commit's serial. Existing +/// serials are kept, `project_epoch` gets one zero row per project and +/// `next_history_serial` never falls below `MAX(serial) + 1`. +fn backfill_position_state(tx: &Transaction<'_>) -> Result<(), BackendError> { + let next: i64 = tx + .query( + "SELECT next_history_serial FROM history_meta WHERE id=1", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let commit_max: i64 = tx + .query( + "SELECT COALESCE(MAX(history_serial),0) FROM \"commit\"", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let layer_max: i64 = tx + .query("SELECT COALESCE(MAX(history_serial),0) FROM layer", vec![])? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + let base = next.max(commit_max.max(layer_max) + 1); + tx.query( + &format!( + "WITH ordered(commit_id,serial) AS ( \ + SELECT commit_id,{base}+ROW_NUMBER() OVER (ORDER BY created_ms,commit_id)-1 \ + FROM \"commit\" WHERE history_serial=0) \ + UPDATE \"commit\" SET history_serial=( \ + SELECT ordered.serial FROM ordered \ + WHERE ordered.commit_id=\"commit\".commit_id) \ + WHERE history_serial=0" + ), + vec![], + )?; + let after_commits: i64 = tx + .query( + "SELECT COALESCE(MAX(history_serial),0)+1 FROM \"commit\"", + vec![], + )? + .first() + .ok_or(BackendError::Integrity)? + .get(0)?; + tx.query( + &format!( + "WITH ordered(layer_id,serial) AS ( \ + SELECT layer_id,{after_commits}+ROW_NUMBER() OVER ( \ + ORDER BY layer_stack_id,layer_id)-1 \ + FROM layer WHERE history_serial=0 AND parent_layer_id IS NULL) \ + UPDATE layer SET history_serial=( \ + SELECT ordered.serial FROM ordered \ + WHERE ordered.layer_id=layer.layer_id) \ + WHERE history_serial=0 AND parent_layer_id IS NULL" + ), + vec![], + )?; + tx.query( + "UPDATE layer SET history_serial=( \ + SELECT \"commit\".history_serial FROM \"commit\" \ + WHERE \"commit\".layer_stack_id=layer.layer_stack_id \ + AND \"commit\".commit_id=layer.source_commit_id) \ + WHERE history_serial=0 AND source_commit_id IS NOT NULL", + vec![], + )?; + tx.query( + "INSERT INTO project_epoch(layer_stack_id,epoch) \ + SELECT s.layer_stack_id,0 FROM layer_stack s \ + WHERE NOT EXISTS ( \ + SELECT 1 FROM project_epoch e WHERE e.layer_stack_id=s.layer_stack_id)", + vec![], + )?; + tx.query( + "UPDATE history_meta SET next_history_serial=MAX(next_history_serial,( \ + SELECT COALESCE(MAX(history_serial),0)+1 FROM ( \ + SELECT history_serial FROM \"commit\" \ + UNION ALL SELECT history_serial FROM layer))) WHERE id=1", + vec![], + )?; + Ok(()) +} pub(crate) fn check( c: &Connection, w: &RefCell, @@ -91,8 +278,16 @@ pub(crate) fn check( "commit_lineage", "content_signature", "file_digest", + "gc_dead", + "gc_intent", + "gc_op", + "project_epoch", + "branch_retired", + "layer_stack_retired", + "path_removed", "history_meta", "inode_value_block", + "kept_node", "layer", "layer_lineage", "layer_stack", @@ -137,13 +332,54 @@ impl super::session::connection::Session { for script in scripts(selection) { tx.bootstrap(&script)?; } tx.query(&format!("PRAGMA application_id={APPLICATION_ID}"),vec![])?; tx.query(&format!("PRAGMA user_version={version}"),vec![])?; - tx.query(&format!("INSERT INTO store_policy(id,schema_version,format_profile,small_file_threshold_bytes,whole_file_delta_max_depth,chunk_delta_max_depth,metadata_delta_max_depth) VALUES(1,{version},?1,?2,?3,?4,?5)"),vec![Param::I64(i64::from(policy.format_profile())),Param::I64(policy.small_file_threshold_bytes() as i64),Param::I64(i64::from(policy.whole_file_delta_max_depth())),Param::I64(i64::from(policy.chunk_delta_max_depth())),Param::I64(i64::from(policy.metadata_delta_max_depth()))])?; + tx.query(&format!("INSERT INTO store_policy(id,schema_version,format_profile,small_file_threshold_bytes,whole_file_delta_max_depth,chunk_delta_max_depth,metadata_delta_max_depth,trace_salt) VALUES(1,{version},?1,?2,?3,?4,?5,randomblob(32))"),vec![Param::I64(i64::from(policy.format_profile())),Param::I64(policy.small_file_threshold_bytes() as i64),Param::I64(i64::from(policy.whole_file_delta_max_depth())),Param::I64(i64::from(policy.chunk_delta_max_depth())),Param::I64(i64::from(policy.metadata_delta_max_depth()))])?; let definition=definition(tx.connection,tx.work)?; tx.query(&format!("INSERT INTO history_meta(id,catalog_id,catalog_incarnation,binding_key,identity_format,schema_version,schema_source,schema_definition) VALUES(1,?1,?2,?3,3,{version},?4,?5)"),vec![Param::Bytes(catalog_id.as_slice().to_vec()),Param::I64(history.incarnation as i64),Param::Bytes(history.binding_key.clone()),Param::Text(source(selection)),Param::Text(definition)])?; Ok(()) })?; Ok(()) } + /// Adds the three position columns T1.2a introduced to a Store written + /// before them: `commit.history_serial`, `layer.history_serial` (default 0) + /// and `store_policy.trace_salt` (32 random bytes). It is an additive + /// migration (REBUILD.md kind 2) under the same recorded-schema gate as + /// [`Self::add_binding_hints`]; because it runs before the GC tables are + /// added, the recorded source it matches is the live one with `GC` stripped. + pub(crate) fn add_gc_columns(&self) -> Result<(), BackendError> { + self.run::<_, BackendError>(true, |tx| { + let present = tx.query( + "SELECT 1 FROM pragma_table_info('commit') WHERE name='history_serial'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let Some(row) = rows.first() else { + return Ok(()); + }; + let current = without_position_columns(source((self.layout, self.acquisition))) + .replacen(GC, "", 1); + if row.get::(0)? != current + || row.get::(1)? != definition(tx.connection, tx.work)? + { + return Ok(()); + } + add_position_columns(tx)?; + let definition = definition(tx.connection, tx.work)?; + tx.query( + "UPDATE history_meta SET schema_source=?1,schema_definition=?2 WHERE id=1", + vec![ + Param::Text(source((self.layout, self.acquisition)).replacen(GC, "", 1)), + Param::Text(definition), + ], + )?; + Ok(()) + }) + } /// Adds the binding hint table (#352 `49499abac`, blocks since #91) to a Store written /// before it existed, then records the current schema: an additive /// migration (REBUILD.md kind 2). Only a Store whose recorded schema is @@ -169,10 +405,11 @@ impl super::session::connection::Session { }; // The schema this migration records is the one before the // lineage and merge tables; later migrations add those. - let current = source((self.layout, self.acquisition)) + let current = without_position_columns(source((self.layout, self.acquisition))) .replacen(DIGESTS, "", 1) .replacen(SCRATCH, "", 1) - .replacen(LINEAGE, "", 1); + .replacen(LINEAGE, "", 1) + .replacen(GC, "", 1); let table = HISTORY .find("CREATE TABLE binding_hint_block (") .and_then(|start| Some((start, start + HISTORY[start..].find(";\n")? + 2))) @@ -216,9 +453,10 @@ impl super::session::connection::Session { let Some(row) = rows.first() else { return Ok(()); }; - let current = source((self.layout, self.acquisition)) + let current = without_position_columns(source((self.layout, self.acquisition))) .replacen(DIGESTS, "", 1) - .replacen(SCRATCH, "", 1); + .replacen(SCRATCH, "", 1) + .replacen(GC, "", 1); if row.get::(0)? != current.replacen(LINEAGE, "", 1) || row.get::(1)? != definition(tx.connection, tx.work)? { @@ -253,7 +491,9 @@ impl super::session::connection::Session { let Some(row) = rows.first() else { return Ok(()); }; - let current = source((self.layout, self.acquisition)).replacen(DIGESTS, "", 1); + let current = without_position_columns(source((self.layout, self.acquisition))) + .replacen(DIGESTS, "", 1) + .replacen(GC, "", 1); if row.get::(0)? != current.replacen(SCRATCH, "", 1) || row.get::(1)? != definition(tx.connection, tx.work)? { @@ -288,7 +528,8 @@ impl super::session::connection::Session { let Some(row) = rows.first() else { return Ok(()); }; - let current = source((self.layout, self.acquisition)); + let current = without_position_columns(source((self.layout, self.acquisition))) + .replacen(GC, "", 1); if row.get::(0)? != current.replacen(DIGESTS, "", 1) || row.get::(1)? != definition(tx.connection, tx.work)? { @@ -303,6 +544,119 @@ impl super::session::connection::Session { Ok(()) }) } + /// Adds the GC marker, position and admission tables to a Store written + /// before them, then records the current schema: an additive migration + /// under the same conditions as [`Self::add_binding_hints`]. + pub(crate) fn add_gc(&self) -> Result<(), BackendError> { + self.run::<_, BackendError>(true, |tx| { + let present = tx.query( + "SELECT 1 FROM sqlite_schema WHERE type='table' AND name='gc_intent'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let Some(row) = rows.first() else { + return Ok(()); + }; + let current = source((self.layout, self.acquisition)); + if row.get::(0)? != current.replacen(GC, "", 1) + || row.get::(1)? != definition(tx.connection, tx.work)? + { + return Ok(()); + } + tx.bootstrap(GC)?; + let definition = definition(tx.connection, tx.work)?; + tx.query( + "UPDATE history_meta SET schema_source=?1,schema_definition=?2 WHERE id=1", + vec![Param::Text(current), Param::Text(definition)], + )?; + Ok(()) + }) + } + /// Adds the `kept_node` history-closure table (T7.1) to a Store written + /// before it, then records the current schema: an additive migration + /// (REBUILD.md kind 2) under the same conditions as + /// [`Self::add_binding_hints`]. The table is empty until a mark writes it. + pub(crate) fn add_kept_node(&self) -> Result<(), BackendError> { + self.run::<_, BackendError>(true, |tx| { + let present = tx.query( + "SELECT 1 FROM sqlite_schema WHERE type='table' AND name='kept_node'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let Some(row) = rows.first() else { + return Ok(()); + }; + let current = source((self.layout, self.acquisition)); + let recorded = row.get::(0)?; + let without = current.replacen(kept_node_table(), "", 1); + let earlier = without.replacen(next_history_serial_column(), "", 1); + if (recorded != earlier && recorded != without) + || row.get::(1)? != definition(tx.connection, tx.work)? + { + return Ok(()); + } + tx.bootstrap(kept_node_table())?; + let definition = definition(tx.connection, tx.work)?; + tx.query( + "UPDATE history_meta SET schema_source=?1,schema_definition=?2 WHERE id=1", + vec![Param::Text(current), Param::Text(definition)], + )?; + Ok(()) + }) + } + /// Adds the position state T1.4 introduced (`history_meta.next_history_serial`, + /// appended NOT NULL DEFAULT 1) and backfills the `commit`/`layer` serials + /// and `project_epoch` rows in the same write transaction: an additive + /// migration (REBUILD.md kind 2) under the same recorded-schema gate as + /// [`Self::add_gc_columns`]. `recorded == current` also matches a Store an + /// earlier step of this same open just brought forward, because those steps + /// record the current source before this column is appended. + pub(crate) fn add_position_state(&self) -> Result<(), BackendError> { + self.run::<_, BackendError>(true, |tx| { + let present = tx.query( + "SELECT 1 FROM pragma_table_info('history_meta') WHERE name='next_history_serial'", + vec![], + )?; + if !present.is_empty() { + return Ok(()); + } + let rows = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let Some(row) = rows.first() else { + return Ok(()); + }; + let current = source((self.layout, self.acquisition)); + let before = current.replacen(next_history_serial_column(), "", 1); + let recorded = row.get::(0)?; + if (recorded != before && recorded != current) + || row.get::(1)? != definition(tx.connection, tx.work)? + { + return Ok(()); + } + tx.query(POSITION_COLUMNS[3].2, vec![])?; + backfill_position_state(tx)?; + let definition = definition(tx.connection, tx.work)?; + tx.query( + "UPDATE history_meta SET schema_source=?1,schema_definition=?2 WHERE id=1", + vec![Param::Text(current), Param::Text(definition)], + )?; + Ok(()) + }) + } pub(crate) fn validate( &self, catalog_id: layerfs_history::CatalogId, diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/schema_diagnostic.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/schema_diagnostic.rs index 50d2864f56..7a3ad4d0fc 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/schema_diagnostic.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/schema_diagnostic.rs @@ -3,7 +3,7 @@ use super::{ schema, session::{connection::SqlWork, query, rows, transaction::Transaction}, }; -use crate::backend::records::{BackendError, Param}; +use crate::backend::records::{BackendError, Param, Record}; use std::cell::RefCell; /// The scratch database contains only the finite shipped schema, never Store @@ -19,19 +19,26 @@ pub(crate) fn check( trusted.execute_batch(&script).map_err(rows::error)?; } let work = RefCell::new(SqlWork::default()); - let expected = query::run(&trusted, - "SELECT type,name,sql FROM sqlite_schema WHERE substr(name,1,7)!='sqlite_' ORDER BY type,name", - vec![], &work)?; - let mut definition = String::new(); - for row in &expected { - for index in 0..3 { - definition.push_str(&row.get::(index)?); - definition.push('\n'); - } + let shipped = schema_rows(&trusted, &work)?; + let shipped_definition = definition(&shipped)?; + // A Store the additive position-column migrations brought forward records + // the definition SQLite rewrote: the appended columns end the column list + // instead of sitting where the shipped schema declares them. The doctor + // admits that rewritten schema as well as the shipped one (REBUILD.md kind + // 2), and rejects every other difference. + for (table, column, _) in schema::POSITION_COLUMNS { + trusted + .execute_batch(&format!("ALTER TABLE {table} DROP COLUMN {column}")) + .map_err(rows::error)?; } + for (_, _, alter) in schema::POSITION_COLUMNS { + trusted.execute_batch(alter).map_err(rows::error)?; + } + let migrated = schema_rows(&trusted, &work)?; + let migrated_definition = definition(&migrated)?; let claims = tx.query( - "SELECT count(*) FROM history_meta WHERE id=1 AND typeof(catalog_id)='blob' AND length(catalog_id)=32 AND typeof(catalog_incarnation)='integer' AND typeof(identity_format)='integer' AND typeof(schema_version)='integer' AND typeof(binding_key)='blob' AND length(binding_key) BETWEEN 1 AND 128 AND typeof(schema_source)='text' AND schema_source=?1 AND typeof(schema_definition)='text' AND schema_definition=?2", - vec![Param::Text(schema::source(selection)), Param::Text(definition)], + "SELECT count(*) FROM history_meta WHERE id=1 AND typeof(catalog_id)='blob' AND length(catalog_id)=32 AND typeof(catalog_incarnation)='integer' AND typeof(identity_format)='integer' AND typeof(schema_version)='integer' AND typeof(binding_key)='blob' AND length(binding_key) BETWEEN 1 AND 128 AND typeof(schema_source)='text' AND schema_source=?1 AND typeof(schema_definition)='text'", + vec![Param::Text(schema::source(selection))], )?; if claims .first() @@ -41,6 +48,20 @@ pub(crate) fn check( { return Err(BackendError::Integrity); } + let recorded = tx.query( + "SELECT schema_source,schema_definition FROM history_meta WHERE id=1", + vec![], + )?; + let recorded = recorded + .first() + .filter(|_| recorded.len() == 1) + .ok_or(BackendError::Integrity)?; + let recorded_definition: String = recorded.get(1)?; + if !same_schema(&recorded_definition, &shipped_definition) + && !same_schema(&recorded_definition, &migrated_definition) + { + return Err(BackendError::Integrity); + } let policy = tx.query("SELECT count(*) FROM store_policy WHERE id=1 AND typeof(small_file_threshold_bytes)='integer'", vec![])?; if policy .first() @@ -58,29 +79,111 @@ pub(crate) fn check( .first() .ok_or(BackendError::Integrity)? .get::(0)? - != expected.len() as i64 + != shipped.len() as i64 { return Err(BackendError::Integrity); } - for row in expected { - let matched = tx.query( - "SELECT count(*) FROM sqlite_schema WHERE type=?1 AND name=?2 AND sql=?3", - (0..3) - .map(|index| row.get::(index).map(Param::Text)) - .collect::>()?, + for (index, row) in shipped.iter().enumerate() { + let kind: String = row.get(0)?; + let name: String = row.get(1)?; + let live = tx.query( + "SELECT sql FROM sqlite_schema WHERE type=?1 AND name=?2", + vec![Param::Text(kind), Param::Text(name)], )?; - if matched - .first() - .ok_or(BackendError::Integrity)? - .get::(0)? - != 1 - { + let live: String = live.first().ok_or(BackendError::Integrity)?.get(0)?; + let shipped_sql: String = row.get(2)?; + let migrated_sql: String = migrated[index].get(2)?; + if !same_schema(&live, &shipped_sql) && !same_schema(&live, &migrated_sql) { return Err(BackendError::Integrity); } } Ok(()) } +/// The schema rows the shipped scripts create, ordered as recorded. +fn schema_rows( + connection: &rusqlite::Connection, + work: &RefCell, +) -> Result, BackendError> { + query::run( + connection, + "SELECT type,name,sql FROM sqlite_schema WHERE substr(name,1,7)!='sqlite_' ORDER BY type,name", + vec![], + work, + ) +} + +/// The recorded definition text for one row set. +fn definition(rows: &[Record]) -> Result { + let mut definition = String::new(); + for row in rows { + for index in 0..3 { + definition.push_str(&row.get::(index)?); + definition.push('\n'); + } + } + Ok(definition) +} + +/// Whether two schema texts carry the same SQL. SQLite rewrites a table's +/// stored definition when a column is appended, moving only whitespace and a +/// separator; every token must still match, so no other schema is admitted. +fn same_schema(left: &str, right: &str) -> bool { + tokens(left) == tokens(right) +} + +/// The SQL tokens of a schema text, with whitespace excluded. A quoted +/// identifier, string or blob stays one token, as does a run of identifier +/// characters; every other byte is one token. +fn tokens(sql: &str) -> Vec<&str> { + let bytes = sql.as_bytes(); + let mut tokens = Vec::new(); + let mut index = 0; + while index < bytes.len() { + let start = index; + match bytes[index] { + byte if byte.is_ascii_whitespace() => { + index += 1; + continue; + } + quote @ (b'\'' | b'"' | b'`') => { + index += 1; + while index < bytes.len() { + if bytes[index] == quote { + index += 1; + if index < bytes.len() && bytes[index] == quote { + index += 1; + continue; + } + break; + } + index += 1; + } + } + b'[' => { + index += 1; + while index < bytes.len() && bytes[index] != b']' { + index += 1; + } + index = (index + 1).min(bytes.len()); + } + byte if byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'$' => { + index += 1; + while index < bytes.len() + && (bytes[index].is_ascii_alphanumeric() + || bytes[index] == b'_' + || bytes[index] == b'$') + { + index += 1; + } + } + _ => index += 1, + } + tokens.push(&sql[start..index]); + } + tokens +} + /// Derive storage-class checks from trusted declarations. SQLite affinity does /// not forbid a corrupt integer cell from holding arbitrarily large text. /// Scalar predicates reject that state before generic row conversion copies it. diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/session/checkpoint.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/session/checkpoint.rs index 151d5e3da3..ae2af52d8f 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/session/checkpoint.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/session/checkpoint.rs @@ -68,6 +68,40 @@ impl Session { } } +impl Session { + /// One `PRAGMA wal_checkpoint(TRUNCATE)` for a caller that already holds the + /// Store's writer lane (§7 step 1). No lane and no turn are taken here; a + /// nonzero `busy` is reported, never retried. + pub(crate) fn checkpoint_holding(&self) -> Result<(), BackendError> { + if !self.writable { + return Err(BackendError::ReadOnly); + } + let _pass = self.background.as_ref().map(|pass| pass.hold()); + let mut state = self.state.lock().map_err(|_| BackendError::Unknown)?; + super::thread_work::attributed(&mut state, |state| { + if state.quarantined || !state.connection.is_autocommit() { + state.quarantined = true; + return Err(BackendError::Unknown); + } + let rows = query::run( + &state.connection, + "PRAGMA wal_checkpoint(TRUNCATE)", + vec![], + &state.work, + )?; + if !state.connection.is_autocommit() { + state.quarantined = true; + return Err(BackendError::Unknown); + } + let busy = rows.first().ok_or(BackendError::Integrity)?.get::(0)?; + if busy != 0 { + return Err(BackendError::Busy); + } + Ok(()) + }) + } +} + /// The length of the Store's `-wal` file; zero when there is none. pub(crate) fn wal_bytes(path: &std::path::Path) -> Result { let mut wal = path.as_os_str().to_os_string(); diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/session/connection.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/session/connection.rs index c080697dae..608efa6d47 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/session/connection.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/session/connection.rs @@ -3,6 +3,7 @@ use super::profile; use super::query; use super::rows; use crate::backend::records::BackendError; +use crate::backend::sqlite::lifecycle::identity::FileIdentity; use crate::SqlitePersistenceProfile; use rusqlite::{limits::Limit, Connection, OpenFlags}; use std::{ @@ -165,6 +166,9 @@ pub(crate) struct Session { pub(crate) profile: ConnectionProfile, pub(crate) layout: crate::SqlitePackLayout, pub(crate) acquisition: crate::SqliteAcquisitionSchema, + /// The `(dev, ino)` identity the path named when this handle opened (§10). + /// `None` on a platform without one; the fence then has nothing to compare. + pub(crate) identity: Option, pub(crate) path: PathBuf, } impl Session { @@ -331,6 +335,8 @@ impl Session { let background = (writable && selected == SqlitePersistenceProfile::Disposable) .then(|| super::background::Checkpointer::start(path)) .transpose()?; + // §10: the record every later transaction is fenced against. + let identity = FileIdentity::capture(path).map_err(|_| BackendError::Integrity)?; Ok(Self { diagnostic, background, @@ -347,6 +353,7 @@ impl Session { profile, layout, acquisition, + identity, }) } /// Stored schema version: the pack layout's, offset by the acquisition tables. @@ -361,4 +368,19 @@ impl Session { let w = *s.work.borrow(); Ok(w) } + /// §10: the Store path must still name the file this handle opened, or the + /// call is `StaleStore` before it reads or writes anything. + pub(crate) fn check_identity(&self) -> Result<(), BackendError> { + let Some(expected) = self.identity else { + return Ok(()); + }; + match expected.names(&self.path) { + Ok(true) => Ok(()), + Ok(false) => Err(BackendError::Stale), + // A removed Store is as stale as a replaced one: nothing this + // handle opened is left at the path to act on. + Err(error) if error.kind() == std::io::ErrorKind::NotFound => Err(BackendError::Stale), + Err(_) => Err(BackendError::Integrity), + } + } } diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/session/query.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/session/query.rs index 5207567e69..bd64d7a177 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/session/query.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/session/query.rs @@ -45,6 +45,12 @@ pub(crate) fn history(key: &str) -> Result<&'static str, BackendError> { "branch_branch_by_id" => Ok(include_str!( "../../../../sql/sqlite/queries/history/branch_branch_by_id.sql" )), + "branch_branch_by_id_any" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/branch_branch_by_id_any.sql" + )), + "branch_retire_insert" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/branch_retire_insert.sql" + )), "branch_branch_by_name" => Ok(include_str!( "../../../../sql/sqlite/queries/history/branch_branch_by_name.sql" )), @@ -102,6 +108,18 @@ pub(crate) fn history(key: &str) -> Result<&'static str, BackendError> { "layerstack_stack_name_taken" => Ok(include_str!( "../../../../sql/sqlite/queries/history/layerstack_stack_name_taken.sql" )), + "layerstack_insert_project_epoch" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/layerstack_insert_project_epoch.sql" + )), + "layerstack_bump_project_epoch" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/layerstack_bump_project_epoch.sql" + )), + "layerstack_insert_retired" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/layerstack_insert_retired.sql" + )), + "layerstack_deleted_ms" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/layerstack_deleted_ms.sql" + )), "layerstack_stack_next_page" => Ok(include_str!( "../../../../sql/sqlite/queries/history/layerstack_stack_next_page.sql" )), @@ -171,6 +189,99 @@ pub(crate) fn history(key: &str) -> Result<&'static str, BackendError> { "removal_stack" => Ok(include_str!( "../../../../sql/sqlite/queries/history/removal_stack.sql" )), + "position_high_water" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/position_high_water.sql" + )), + "position_stack_high_water" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/position_stack_high_water.sql" + )), + "position_next_serial" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/position_next_serial.sql" + )), + "position_node_serial" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/position_node_serial.sql" + )), + "paths_marker" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/paths_marker.sql" + )), + "paths_markers" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/paths_markers.sql" + )), + "paths_upsert" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/paths_upsert.sql" + )), + "paths_advance_epoch" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/paths_advance_epoch.sql" + )), + "gc_intent_insert" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_insert.sql" + )), + "gc_intent_get" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_get.sql" + )), + "gc_intent_release" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_release.sql" + )), + "gc_intent_uncertain" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_uncertain.sql" + )), + "gc_intent_list" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_list.sql" + )), + "gc_intent_ops_branch" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_ops_branch.sql" + )), + "gc_intent_ops_project" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_ops_project.sql" + )), + "gc_intent_ops_store" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_ops_store.sql" + )), + "gc_intent_all_branch" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_all_branch.sql" + )), + "gc_intent_all_project" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_all_project.sql" + )), + "gc_intent_all_store" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_intent_all_store.sql" + )), + "gc_branch_stack_any" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_branch_stack_any.sql" + )), + "gc_epoch_read" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_epoch_read.sql" + )), + "gc_epoch_share" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_epoch_share.sql" + )), + "gc_kept_roots" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_kept_roots.sql" + )), + "gc_object_locations" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_object_locations.sql" + )), + "gc_live_stacks" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_live_stacks.sql" + )), + "gc_live_branches" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_live_branches.sql" + )), + "gc_inode_blocks" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_inode_blocks.sql" + )), + "gc_tuple_read" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/gc_tuple_read.sql" + )), + "kept_node_clear" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/kept_node_clear.sql" + )), + "kept_node_mark" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/kept_node_mark.sql" + )), + "kept_node_read" => Ok(include_str!( + "../../../../sql/sqlite/queries/history/kept_node_read.sql" + )), _ => Err(BackendError::Integrity), } } diff --git a/engine/crates/layerfs-persistence/src/backend/sqlite/session/transaction.rs b/engine/crates/layerfs-persistence/src/backend/sqlite/session/transaction.rs index 65a1fb1cbd..b06988dae6 100644 --- a/engine/crates/layerfs-persistence/src/backend/sqlite/session/transaction.rs +++ b/engine/crates/layerfs-persistence/src/backend/sqlite/session/transaction.rs @@ -148,6 +148,7 @@ impl Session { if state.quarantined { return Err(BackendError::Unknown.into()); } + self.check_identity().map_err(E::from)?; // An earlier uncertain transaction may still exist. It cannot be // inherited by an independently owned snapshot or guessed complete. if !state.connection.is_autocommit() { @@ -207,6 +208,7 @@ impl Session { if state.quarantined { return Err(BackendError::Unknown.into()); } + self.check_identity().map_err(E::from)?; // An earlier uncertain transaction cannot be inherited or guessed done. if !state.connection.is_autocommit() { state.quarantined = true; @@ -249,6 +251,7 @@ impl Session { if s.quarantined { return Err(BackendError::Unknown.into()); } + self.check_identity().map_err(E::from)?; // A held publication lane already owns the writer for its nested work. if writable && !turn.nested { // State owns this before BEGIN, including across a poisoned unwind. diff --git a/engine/crates/layerfs-persistence/src/compact_metrics.rs b/engine/crates/layerfs-persistence/src/compact_metrics.rs new file mode 100644 index 0000000000..96b42bde6c --- /dev/null +++ b/engine/crates/layerfs-persistence/src/compact_metrics.rs @@ -0,0 +1,581 @@ +//! Bounded metrics and SLO signals for SQLite (§7) and PostgreSQL (§8) +//! Store compaction. +//! +//! Every metric a real `store.compact` or `store.status` path records goes +//! through this module. Label values come from closed enums ([`CompactOutcome`], +//! [`CompactPhase`], [`CompactRefusal`], [`CompactStatusState`]), so the metric +//! cardinality is fixed: no Store name, path, operation id or artifact name is +//! ever a label. A finished run is observed once, in [`record_run`], and +//! recording never changes its result. +//! +//! Production reads the process totals through [`snapshot`]. A test or a +//! diagnostic probe can capture only its own thread with +//! [`CompactMetricsCapture`], so concurrent work on other threads does not +//! pollute the observation. + +use crate::backend::sqlite::compact::CompactKeptWaste; +use std::cell::RefCell; +use std::collections::BTreeMap; +use std::sync::{Mutex, OnceLock}; + +/// The outcome of one Store compaction call. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactOutcome { + /// A rebuild installed at `G -> G + 1`. + Rebuild, + /// The `none` path: mark only, generation unchanged. + None, + /// A definite failure that left the live Store unchanged. + Failed, + /// A failed or stopped run whose persistence outcome is unknown (§9). + Uncertain, +} + +impl CompactOutcome { + /// The bounded `outcome` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Rebuild => "rebuild", + Self::None => "none", + Self::Failed => "failed", + Self::Uncertain => "uncertain", + } + } +} + +/// One phase a run may time. +/// +/// SQLite (§7) reports `mark`, `build`, `verify` and `install`. PostgreSQL +/// (§8) reports its own Phase M (`pg_mark`), Phase A (`pg_build`), Phase B +/// (`pg_swap`) and Phase C (`pg_cleanup`). The two backends' values are +/// distinct, so a process total never blends a SQLite phase with a PostgreSQL +/// phase of a different meaning, and every value stays a closed enum string. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactPhase { + /// The §7 step 1 mark and the wholly-dead-pack decision. + Mark, + /// The staged rebuild's build. + Build, + /// The immutable verification. + Verify, + /// The install and its settle. + Install, + /// PostgreSQL §8 Phase M: the intent, the T7.2 mark and the persisted + /// `gc_dead` set. + PostgresMark, + /// PostgreSQL §8 Phase A: copy the retained payload into the scratch + /// schema. + PostgresBuild, + /// PostgreSQL §8 Phase B: swap `pack`/`object_location` at `G -> G + 1`. + PostgresSwap, + /// PostgreSQL §8 Phase C: delete the persisted dead set and settle the + /// totals, also for a resumed `G + 1` leftover. + PostgresCleanup, +} + +impl CompactPhase { + /// The bounded `phase` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Mark => "mark", + Self::Build => "build", + Self::Verify => "verify", + Self::Install => "install", + Self::PostgresMark => "pg_mark", + Self::PostgresBuild => "pg_build", + Self::PostgresSwap => "pg_swap", + Self::PostgresCleanup => "pg_cleanup", + } + } +} + +/// A refusal that stops a compaction before or during its admission. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactRefusal { + /// A live operation, writer or opener holds the Store. + Busy, + /// A dead or uncertain owner left an operation unresolved. + Unresolved, +} + +impl CompactRefusal { + /// The bounded `code` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Busy => "busy", + Self::Unresolved => "unresolved", + } + } +} + +/// The compaction state `store.status` reads from an unsettled op record. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactStatusState { + /// The owning process still lives. + Busy, + /// The recording owner is gone, so the outcome is unresolved. + Unresolved, +} + +impl CompactStatusState { + /// The bounded `state` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Busy => "busy", + Self::Unresolved => "unresolved", + } + } +} + +/// An SLO objective one finished run evaluates. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactSloObjective { + /// A successful settle left no artifact and zero residue bytes. + ResidueFree, + /// A rebuild advanced exactly one generation; `none` kept it. + Generation, +} + +impl CompactSloObjective { + /// The bounded `objective` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::ResidueFree => "residue_free", + Self::Generation => "generation", + } + } +} + +/// One SLO check's result. +#[derive(Clone, Copy, Debug, Eq, PartialEq, Ord, PartialOrd)] +pub enum CompactSloResult { + /// The run met the objective. + Pass, + /// The run missed the objective. + Fail, +} + +impl CompactSloResult { + /// The bounded `result` label value. + #[must_use] + pub const fn as_str(self) -> &'static str { + match self { + Self::Pass => "pass", + Self::Fail => "fail", + } + } +} + +/// A duration aggregate: how many observations, their sum and their maximum, +/// all in nanoseconds. +#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)] +pub struct DurationStat { + /// Observations counted. + pub count: u64, + /// Saturating sum of the observations. + pub sum_ns: u64, + /// The longest observation. + pub max_ns: u64, +} + +impl DurationStat { + fn observe(&mut self, nanos: u64) { + self.count = self.count.saturating_add(1); + self.sum_ns = self.sum_ns.saturating_add(nanos); + self.max_ns = self.max_ns.max(nanos); + } +} + +/// Everything one finished compaction run reports to the metrics. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct CompactRunObservation { + /// The run's outcome. + pub outcome: CompactOutcome, + /// The generation the mark ran at. + pub generation_before: u64, + /// The generation the run left; equal on `none` and on a failure. + pub generation_after: u64, + /// §11 `deadBytesBound`. + pub dead_bytes_bound: u64, + /// §11 `deadBytesRefined`. + pub dead_bytes_refined: u64, + /// §11 `keptWaste`, whose delta-base references are not labels. + pub kept_waste: CompactKeptWaste, + /// §11 `residue.bytes`. + pub residue_bytes: u64, + /// The completed phases and their inclusive durations. + pub phase_nanos: Vec<(CompactPhase, u64)>, + /// The run's whole duration. + pub total_nanos: u64, + /// Whether this run settled an earlier run's leftover record. + pub leftover_settled: bool, + /// The admission refusal, when the run was refused. + pub refusal: Option, +} + +/// One rendered metric sample: a stable name, bounded label pairs, a value. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct MetricSample { + /// The metric name, for example `compact.operations`. + pub name: &'static str, + /// The bounded label pairs, in sorted key order. + pub labels: Vec<(&'static str, &'static str)>, + /// The sample's counter or gauge value. + pub value: u64, +} + +impl MetricSample { + /// The value of label `key`, when the sample carries it. + #[must_use] + pub fn label(&self, key: &str) -> Option<&'static str> { + self.labels + .iter() + .find(|(name, _)| *name == key) + .map(|(_, value)| *value) + } +} + +/// The last successful run's §11 gauges, the values a report names. +#[derive(Clone, Debug, Eq, PartialEq)] +struct LastRun { + generation_before: u64, + generation_after: u64, + dead_bytes_bound: u64, + dead_bytes_refined: u64, + kept_waste: CompactKeptWaste, + residue_bytes: u64, +} + +/// One process's compaction metric totals. +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct CompactMetrics { + runs: u64, + outcomes: BTreeMap<&'static str, u64>, + refusals: BTreeMap<&'static str, u64>, + settles: BTreeMap<&'static str, u64>, + retries: BTreeMap<&'static str, u64>, + statuses: BTreeMap<&'static str, u64>, + slo: BTreeMap<(&'static str, &'static str), u64>, + phases: BTreeMap<&'static str, DurationStat>, + duration: DurationStat, + last: Option, +} + +impl CompactMetrics { + /// Adds one finished run. + fn observe(&mut self, run: &CompactRunObservation) { + self.runs = self.runs.saturating_add(1); + increment(&mut self.outcomes, run.outcome.as_str()); + if let Some(refusal) = run.refusal { + increment(&mut self.refusals, refusal.as_str()); + } + if run.leftover_settled { + increment(&mut self.settles, "leftover"); + increment(&mut self.retries, "leftover"); + } + for (phase, nanos) in &run.phase_nanos { + self.phases + .entry(phase.as_str()) + .or_default() + .observe(*nanos); + } + self.duration.observe(run.total_nanos); + if !matches!(run.outcome, CompactOutcome::Rebuild | CompactOutcome::None) { + return; + } + increment(&mut self.settles, "run"); + let generation = match run.outcome { + CompactOutcome::Rebuild => { + run.generation_after == run.generation_before.saturating_add(1) + } + CompactOutcome::None => run.generation_after == run.generation_before, + CompactOutcome::Failed | CompactOutcome::Uncertain => false, + }; + increment_pair( + &mut self.slo, + ( + CompactSloObjective::Generation.as_str(), + if generation { + CompactSloResult::Pass.as_str() + } else { + CompactSloResult::Fail.as_str() + }, + ), + ); + increment_pair( + &mut self.slo, + ( + CompactSloObjective::ResidueFree.as_str(), + if run.residue_bytes == 0 { + CompactSloResult::Pass.as_str() + } else { + CompactSloResult::Fail.as_str() + }, + ), + ); + self.last = Some(LastRun { + generation_before: run.generation_before, + generation_after: run.generation_after, + dead_bytes_bound: run.dead_bytes_bound, + dead_bytes_refined: run.dead_bytes_refined, + kept_waste: run.kept_waste.clone(), + residue_bytes: run.residue_bytes, + }); + } + + /// Adds one refusal that stopped a call before a run could be observed. + fn observe_refusal(&mut self, refusal: CompactRefusal) { + increment(&mut self.refusals, refusal.as_str()); + } + + /// Adds one `store.status` read of an unsettled compaction record. + fn observe_status(&mut self, state: CompactStatusState) { + increment(&mut self.statuses, state.as_str()); + } + + /// Every sample this process or capture holds, in stable order. + /// + /// Counters are cumulative since the process started (or the capture + /// started); the gauges are the last successful run's report values. + #[must_use] + pub fn samples(&self) -> Vec { + let mut samples = Vec::new(); + samples.push(sample("compact.runs", &[], self.runs)); + for (outcome, value) in &self.outcomes { + samples.push(sample( + "compact.operations", + &[("outcome", *outcome)], + *value, + )); + } + for (code, value) in &self.refusals { + samples.push(sample("compact.refusals", &[("code", *code)], *value)); + } + for (kind, value) in &self.settles { + samples.push(sample("compact.settles", &[("kind", *kind)], *value)); + } + for (reason, value) in &self.retries { + samples.push(sample("compact.retries", &[("reason", *reason)], *value)); + } + for (state, value) in &self.statuses { + samples.push(sample("compact.status", &[("state", *state)], *value)); + } + for ((objective, result), value) in &self.slo { + samples.push(sample( + "compact.slo", + &[("objective", *objective), ("result", *result)], + *value, + )); + } + for (phase, stat) in &self.phases { + for (statistic, value) in [ + ("count", stat.count), + ("sum", stat.sum_ns), + ("max", stat.max_ns), + ] { + samples.push(sample( + "compact.phase.duration_ns", + &[("phase", *phase), ("statistic", statistic)], + value, + )); + } + } + for (statistic, value) in [ + ("count", self.duration.count), + ("sum", self.duration.sum_ns), + ("max", self.duration.max_ns), + ] { + samples.push(sample( + "compact.duration_ns", + &[("statistic", statistic)], + value, + )); + } + if let Some(last) = &self.last { + samples.push(sample( + "compact.dead_bytes", + &[("kind", "bound")], + last.dead_bytes_bound, + )); + samples.push(sample( + "compact.dead_bytes", + &[("kind", "refined")], + last.dead_bytes_refined, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "dead_in_retained_packs")], + last.kept_waste.dead_in_retained_packs_bytes, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "delta_bases")], + last.kept_waste.delta_bases_bytes, + )); + samples.push(sample( + "compact.kept_waste", + &[("part", "inode_blocks")], + last.kept_waste.inode_blocks_bytes, + )); + samples.push(sample( + "compact.kept_waste_bytes", + &[], + last.kept_waste + .dead_in_retained_packs_bytes + .saturating_add(last.kept_waste.delta_bases_bytes) + .saturating_add(last.kept_waste.inode_blocks_bytes), + )); + samples.push(sample("compact.residue_bytes", &[], last.residue_bytes)); + samples.push(sample( + "compact.generation", + &[("which", "before")], + last.generation_before, + )); + samples.push(sample( + "compact.generation", + &[("which", "after")], + last.generation_after, + )); + } + samples + } +} + +fn increment(map: &mut BTreeMap<&'static str, u64>, key: &'static str) { + let value = map.entry(key).or_insert(0); + *value = value.saturating_add(1); +} + +fn increment_pair( + map: &mut BTreeMap<(&'static str, &'static str), u64>, + key: (&'static str, &'static str), +) { + let value = map.entry(key).or_insert(0); + *value = value.saturating_add(1); +} + +fn sample(name: &'static str, labels: &[(&'static str, &'static str)], value: u64) -> MetricSample { + MetricSample { + name, + labels: labels.to_vec(), + value, + } +} + +thread_local! { + /// This thread's armed capture, if any. + static CAPTURE: RefCell> = const { RefCell::new(None) }; +} + +fn registry() -> &'static Mutex { + static METRICS: OnceLock> = OnceLock::new(); + METRICS.get_or_init(|| Mutex::new(CompactMetrics::default())) +} + +/// Records one finished compaction run in the process totals and, when this +/// thread has an armed [`CompactMetricsCapture`], in that capture too. +pub fn record_run(run: &CompactRunObservation) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe(run); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe(run); + } + }); +} + +/// Records one admission refusal that stopped a call before any run. +pub fn record_refusal(refusal: CompactRefusal) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe_refusal(refusal); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe_refusal(refusal); + } + }); +} + +/// Records one `store.status` read of an unsettled compaction record. +pub fn record_status(state: CompactStatusState) { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .observe_status(state); + CAPTURE.with_borrow_mut(|capture| { + if let Some(metrics) = capture.as_mut() { + metrics.observe_status(state); + } + }); +} + +/// The process's cumulative compaction metrics. +#[must_use] +pub fn snapshot() -> CompactMetrics { + registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) + .clone() +} + +/// Clears the process's cumulative compaction metrics. +pub fn reset() { + *registry() + .lock() + .unwrap_or_else(|poison| poison.into_inner()) = CompactMetrics::default(); +} + +/// Captures the metrics this thread records, leaving the process totals alone. +/// +/// Build one with [`Self::start`], run the compaction or status call on the +/// same thread, and read [`Self::finish`]. A capture nests: starting another +/// restores the outer one when it finishes, and a dropped capture restores it +/// too. +pub struct CompactMetricsCapture { + previous: Option, + finished: bool, +} + +impl CompactMetricsCapture { + /// Arms a capture on this thread, replacing (and saving) an outer one. + #[must_use] + pub fn start() -> Self { + let previous = + CAPTURE.with_borrow_mut(|capture| capture.replace(CompactMetrics::default())); + Self { + previous, + finished: false, + } + } + + /// The metrics this thread has recorded since the capture started. + #[must_use] + pub fn snapshot(&self) -> CompactMetrics { + CAPTURE.with_borrow(Clone::clone).unwrap_or_default() + } + + /// Ends the capture, restoring the outer one, and returns its metrics. + #[must_use] + pub fn finish(mut self) -> CompactMetrics { + let metrics = self.snapshot(); + self.finished = true; + CAPTURE.with_borrow_mut(|capture| *capture = self.previous.take()); + metrics + } +} + +impl Drop for CompactMetricsCapture { + fn drop(&mut self) { + if !self.finished { + CAPTURE.with_borrow_mut(|capture| *capture = self.previous.take()); + } + } +} diff --git a/engine/crates/layerfs-persistence/src/diagnostic/history.rs b/engine/crates/layerfs-persistence/src/diagnostic/history.rs index f15d464906..efa0a74541 100644 --- a/engine/crates/layerfs-persistence/src/diagnostic/history.rs +++ b/engine/crates/layerfs-persistence/src/diagnostic/history.rs @@ -32,7 +32,7 @@ fn inspect( options: Options, observer: &mut dyn FnMut(Observation), ) -> Result<(), BackendError> { - scratch.0.execute_batch("CREATE TABLE nodes(id BLOB PRIMARY KEY,kind INTEGER NOT NULL,stack BLOB NOT NULL,root BLOB NOT NULL,parent BLOB,base BLOB,second BLOB,source BLOB,source_branch BLOB,done INTEGER NOT NULL DEFAULT 0,height INTEGER,depth INTEGER,newest INTEGER,run BLOB,overwrote INTEGER NOT NULL DEFAULT 0) WITHOUT ROWID; CREATE TABLE edges(child BLOB NOT NULL,parent BLOB NOT NULL,PRIMARY KEY(child,parent)) WITHOUT ROWID; CREATE INDEX parent_edges ON edges(parent,child); CREATE TABLE stacks(id BLOB PRIMARY KEY,scope BLOB NOT NULL,profile BLOB NOT NULL,head BLOB NOT NULL) WITHOUT ROWID; CREATE TABLE branches(id BLOB PRIMARY KEY,stack BLOB NOT NULL,base BLOB NOT NULL,head BLOB,fork BLOB) WITHOUT ROWID; CREATE TABLE contexts(root BLOB,scope BLOB,profile BLOB,PRIMARY KEY(root,scope,profile)) WITHOUT ROWID;").map_err(sql)?; + scratch.0.execute_batch("CREATE TABLE nodes(id BLOB PRIMARY KEY,kind INTEGER NOT NULL,stack BLOB NOT NULL,root BLOB NOT NULL,parent BLOB,base BLOB,second BLOB,source BLOB,source_branch BLOB,done INTEGER NOT NULL DEFAULT 0,height INTEGER,depth INTEGER,newest INTEGER,run BLOB,overwrote INTEGER NOT NULL DEFAULT 0,branch BLOB) WITHOUT ROWID; CREATE TABLE edges(child BLOB NOT NULL,parent BLOB NOT NULL,PRIMARY KEY(child,parent)) WITHOUT ROWID; CREATE INDEX parent_edges ON edges(parent,child); CREATE TABLE stacks(id BLOB PRIMARY KEY,scope BLOB NOT NULL,profile BLOB NOT NULL,head BLOB NOT NULL) WITHOUT ROWID; CREATE TABLE branches(id BLOB PRIMARY KEY,stack BLOB NOT NULL,base BLOB NOT NULL,head BLOB,fork BLOB) WITHOUT ROWID; CREATE TABLE contexts(root BLOB,scope BLOB,profile BLOB,PRIMARY KEY(root,scope,profile)) WITHOUT ROWID;").map_err(sql)?; super::facts::run(view, options, observer)?; let mut failures = 0u64; inventory(view, scratch, options, observer, &mut failures)?; @@ -43,6 +43,7 @@ fn inspect( ("store.history.branches","SELECT b.id,b.base FROM branches b LEFT JOIN nodes n ON n.id=b.base LEFT JOIN stacks s ON s.id=b.stack WHERE n.id IS NULL OR n.kind!=2 OR n.stack!=b.stack OR s.id IS NULL","branch base/stack invalid"), ("store.history.branches","SELECT b.id,b.head FROM branches b LEFT JOIN nodes n ON n.id=b.head WHERE b.head IS NOT NULL AND (n.id IS NULL OR n.kind!=1 OR n.stack!=b.stack)","branch head invalid"), ("store.history.branches","SELECT b.id,b.fork FROM branches b LEFT JOIN nodes n ON n.id=b.fork WHERE b.fork IS NOT NULL AND (n.id IS NULL OR n.stack!=b.stack)","branch fork provenance invalid"), + ("store.history.branches","SELECT n.id,n.branch FROM nodes n LEFT JOIN branches b ON b.id=n.branch WHERE n.kind=1 AND n.branch IS NOT NULL AND (b.id IS NULL OR b.stack!=n.stack)","Commit names absent or cross-stack Branch"), ("store.history.provenance","SELECT n.id,n.source FROM nodes n LEFT JOIN nodes c ON c.id=n.source LEFT JOIN branches b ON b.id=n.source_branch WHERE n.kind=2 AND n.parent IS NOT NULL AND (c.id IS NULL OR c.kind!=1 OR c.stack!=n.stack OR c.root!=n.root OR b.id IS NULL OR b.stack!=n.stack)","Layer source Commit/Branch/root mismatch"), ]{ let mut stmt=scratch.0.prepare(query).map_err(sql)?; @@ -142,7 +143,7 @@ fn inventory( 0=>{let s=crate::history::diagnostic_stack(&row).map_err(|e|e.to_string())?;scratch.0.execute("INSERT INTO stacks(id,scope,profile,head) VALUES(?1,?2,?3,?4)",params![s.id.as_slice(),s.scope.as_bytes().as_slice(),s.profile.as_bytes().as_slice(),s.head_layer.as_slice()]).map_err(|_|"diagnostic scratch".to_owned())?;}, 3=>{let b=crate::history::diagnostic_branch(&row).map_err(|e|e.to_string())?;scratch.0.execute("INSERT INTO branches(id,stack,base,head,fork) VALUES(?1,?2,?3,?4,?5)",params![b.id.as_slice(),b.stack.as_slice(),b.base_layer.as_slice(),b.head_commit.map(|v|v.as_slice().to_vec()),b.forked_from.map(|v|v.as_slice().to_vec())]).map_err(|_|"diagnostic scratch".to_owned())?;}, 2=>{let l=crate::history::diagnostic_layer(&row).map_err(|e|e.to_string())?;scratch.0.execute("INSERT INTO nodes(id,kind,stack,root,parent,source,source_branch,overwrote) VALUES(?1,2,?2,?3,?4,?5,?6,?7)",params![l.id.as_slice(),l.stack.as_slice(),l.root.as_bytes().as_slice(),l.parent.map(|v|v.as_slice().to_vec()),l.source_commit.map(|v|v.as_slice().to_vec()),l.source_branch.map(|v|v.as_slice().to_vec()),i64::try_from(l.overwrote_count).map_err(|_|"Layer overwrite count".to_owned())?]).map_err(|_|"diagnostic scratch".to_owned())?;if LayerId::derive(l.stack,l.parent,l.root)!=l.id{return Err("Layer identity mismatch".to_owned());}}, - _=>{let c=crate::history::diagnostic_commit_graph(&row).map_err(|e|e.to_string())?;scratch.0.execute("INSERT INTO nodes(id,kind,stack,root,parent,base,second) VALUES(?1,1,?2,?3,?4,?5,?6)",params![c.id.as_slice(),c.stack.as_slice(),c.root.as_bytes().as_slice(),c.parent.map(|v|v.as_slice().to_vec()),c.base_layer.as_slice(),c.second_parent.map(|v|v.as_slice().to_vec())]).map_err(|_|"diagnostic scratch".to_owned())?; + _=>{let c=crate::history::diagnostic_commit_graph(&row).map_err(|e|e.to_string())?;scratch.0.execute("INSERT INTO nodes(id,kind,stack,root,parent,base,second,branch) VALUES(?1,1,?2,?3,?4,?5,?6,?7)",params![c.id.as_slice(),c.stack.as_slice(),c.root.as_bytes().as_slice(),c.parent.map(|v|v.as_slice().to_vec()),c.base_layer.as_slice(),c.second_parent.map(|v|v.as_slice().to_vec()),c.meta.branch.map(|v|v.as_slice().to_vec())]).map_err(|_|"diagnostic scratch".to_owned())?; for edge in [c.meta.merged_from,c.meta.displaced.map(layerfs_history::NodeId::Commit)].into_iter().flatten(){scratch.0.execute("INSERT OR IGNORE INTO edges VALUES(?1,?2)",params![c.id.as_slice(),edge.as_slice()]).map_err(|_|"diagnostic scratch".to_owned())?;} if CommitId::derive(c.root,c.parent,c.base_layer,c.second_parent,&c.meta)!=c.id{return Err("Commit v3 identity mismatch".to_owned());} } diff --git a/engine/crates/layerfs-persistence/src/history/admission.rs b/engine/crates/layerfs-persistence/src/history/admission.rs new file mode 100644 index 0000000000..53e0996e97 --- /dev/null +++ b/engine/crates/layerfs-persistence/src/history/admission.rs @@ -0,0 +1,746 @@ +//! Store-side admission for the four GC calls (spec §5). +//! +//! Admission is one Store-DB table and, on SQLite, two short +//! `BEGIN IMMEDIATE` transactions: a mount/Init/merge registers a shared +//! intent, a removal scans the intents in its scope and then writes its +//! marker in the same write transaction, and a compaction registers an +//! exclusive Store intent. A live mount refuses a removal with +//! `MountsActive`; a live operation refuses a mount or another removal with +//! `Busy`; a dead or uncertain owner is `Unresolved`. +//! +//! PostgreSQL adds transaction-scoped advisory keys to a removal's marker +//! transaction and session-scoped shared keys to a mount, so a removal on one +//! machine sees a mount on another. Its `gc_intent` rows carry the same +//! ownership evidence for `MountsActive`/`Busy`/`Unresolved` reports. + +use super::rows::{cell, one, unsigned}; +use super::transaction::Transaction; +use super::{branch, layerstack, params, paths, position}; +use crate::backend::Engine; +use crate::history::provider::HistoryProvider; +use layerfs_history::error::{ + GcHolder, HistoryError, HistoryResult, Missing, MountHolders, OpConflict, +}; +#[cfg(feature = "postgresql")] +use layerfs_history::identity::CatalogId; +use layerfs_history::identity::{BranchId, LayerStackId}; +use layerfs_history::path::path_key; +use layerfs_history::records::{ + GcDeletion, GcIntent, GcIntentKind, GcScopeKind, PathRemovalKind, PathRemovalOutcome, + PathRemovalRequest, +}; +use std::time::{SystemTime, UNIX_EPOCH}; + +const INSERT: &str = "gc_intent_insert"; +#[cfg(feature = "postgresql")] +const GET: &str = "gc_intent_get"; +const RELEASE: &str = "gc_intent_release"; +const UNCERTAIN: &str = "gc_intent_uncertain"; +const LIST: &str = "gc_intent_list"; +const OPS_BRANCH: &str = "gc_intent_ops_branch"; +const OPS_PROJECT: &str = "gc_intent_ops_project"; +const OPS_STORE: &str = "gc_intent_ops_store"; +const ALL_BRANCH: &str = "gc_intent_all_branch"; +const ALL_PROJECT: &str = "gc_intent_all_project"; +const ALL_STORE: &str = "gc_intent_all_store"; +#[cfg(feature = "postgresql")] +const BRANCH_STACK: &str = "gc_branch_stack_any"; +const EPOCH_SHARE: &str = "gc_epoch_share"; + +#[cfg(feature = "postgresql")] +const LOCK_XACT_SHARED: &str = "gc_lock_xact_shared"; +#[cfg(feature = "postgresql")] +const LOCK_XACT_EXCLUSIVE: &str = "gc_lock_xact_exclusive"; +#[cfg(feature = "postgresql")] +const LOCK_SESSION_SHARED: &str = "gc_lock_session_shared"; +#[cfg(feature = "postgresql")] +const LOCK_SESSION_EXCLUSIVE: &str = "gc_lock_session_exclusive"; +#[cfg(feature = "postgresql")] +const UNLOCK_SESSION_SHARED: &str = "gc_unlock_session_shared"; +#[cfg(feature = "postgresql")] +const UNLOCK_SESSION_EXCLUSIVE: &str = "gc_unlock_session_exclusive"; + +/// True when this provider is backed by PostgreSQL. +fn postgres(provider: &HistoryProvider) -> bool { + #[cfg(feature = "postgresql")] + { + matches!(provider.engine, Engine::Postgres(_)) + } + #[cfg(not(feature = "postgresql"))] + { + let _ = provider; + false + } +} + +fn now_ms() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_or(0, |elapsed| { + i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX) + }) +} + +fn hex(bytes: &[u8]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(bytes.len() * 2); + for byte in bytes { + let _ = write!(out, "{byte:02x}"); + } + out +} + +fn kind_of(text: &str) -> HistoryResult { + Ok(match text { + "mount" => GcIntentKind::Mount, + "init" => GcIntentKind::Init, + "merge" => GcIntentKind::Merge, + "removal" => GcIntentKind::Removal, + "compaction" => GcIntentKind::Compaction, + _ => return Err(HistoryError::Integrity("gc intent kind")), + }) +} + +fn scope_of(text: &str) -> HistoryResult { + Ok(match text { + "store" => GcScopeKind::Store, + "project" => GcScopeKind::Project, + "branch" => GcScopeKind::Branch, + _ => return Err(HistoryError::Integrity("gc intent scope")), + }) +} + +fn workspace_of(text: Option) -> HistoryResult> { + let Some(text) = text else { + return Ok(None); + }; + if text.len() != 64 { + return Err(HistoryError::Integrity("gc intent workspace")); + } + let mut body = [0u8; 32]; + for (index, pair) in text.as_bytes().chunks_exact(2).enumerate() { + let digit = |byte: u8| -> HistoryResult { + match byte { + b'0'..=b'9' => Ok(byte - b'0'), + b'a'..=b'f' => Ok(byte - b'a' + 10), + b'A'..=b'F' => Ok(byte - b'A' + 10), + _ => Err(HistoryError::Integrity("gc intent workspace")), + } + }; + body[index] = (digit(pair[0])? << 4) | digit(pair[1])?; + } + Ok(Some(body)) +} + +/// Decodes the fourteen columns every intent query returns, in order: +/// op_id, kind, scope_kind, scope_id, workspace, sandbox, machine, project, +/// branch, owner_runtime, owner_boot, state, uncertain, phase. +fn intent_row(row: &crate::backend::records::Record) -> HistoryResult { + let op_id: Vec = cell(row, 0)?; + let op_id: [u8; 16] = op_id + .as_slice() + .try_into() + .map_err(|_| HistoryError::Integrity("gc intent op_id"))?; + let state: String = cell(row, 11)?; + let uncertain_flag: i64 = cell(row, 12)?; + Ok(GcIntent { + op_id, + kind: kind_of(&cell::(row, 1)?)?, + scope_kind: scope_of(&cell::(row, 2)?)?, + scope_id: cell(row, 3)?, + workspace: workspace_of(cell::>(row, 4)?)?, + sandbox: cell(row, 5)?, + machine: cell(row, 6)?, + project: cell(row, 7)?, + branch: cell(row, 8)?, + owner_runtime: cell(row, 9)?, + owner_boot: cell(row, 10)?, + project_id: None, + phase: cell(row, 13)?, + uncertain: state == "uncertain" || uncertain_flag != 0, + }) +} + +fn entity(intent: &GcIntent) -> String { + match (&intent.project, &intent.branch, intent.scope_kind) { + (_, Some(branch), _) => branch.clone(), + (Some(project), None, _) => project.clone(), + (None, None, GcScopeKind::Store) => "store".to_owned(), + (None, None, _) => hex(&intent.scope_id), + } +} + +fn holder(intent: &GcIntent) -> GcHolder { + GcHolder { + kind: intent.kind, + entity: entity(intent), + workspace: intent.workspace.as_ref().map(|bytes| hex(bytes)), + sandbox: intent.sandbox.clone(), + machine: intent.machine.clone(), + op: hex(&intent.op_id), + } +} + +fn conflict(intent: &GcIntent) -> OpConflict { + OpConflict::new( + intent.kind, + entity(intent), + intent.phase.clone(), + hex(&intent.op_id), + intent.uncertain, + ) +} + +/// The refusal a non-empty conflict set reports: an uncertain owner is +/// `Unresolved`, a live mount is `MountsActive`, any other live operation is +/// `Busy`. +fn classify(found: &[GcIntent]) -> HistoryError { + if let Some(dead) = found.iter().find(|intent| intent.uncertain) { + return HistoryError::Unresolved(Box::new(conflict(dead))); + } + let holders: Vec = found + .iter() + .filter(|intent| intent.kind.shared()) + .map(holder) + .collect(); + if !holders.is_empty() { + return HistoryError::MountsActive(Box::new(MountHolders::new(holders))); + } + match found.first() { + Some(operation) => HistoryError::BusyOp(Box::new(conflict(operation))), + None => HistoryError::Busy, + } +} + +fn query( + tx: &Transaction<'_>, + key: &str, + params: Vec, +) -> HistoryResult> { + tx.query(key, params)?.iter().map(intent_row).collect() +} + +fn conflicts_for(tx: &Transaction<'_>, intent: &GcIntent) -> HistoryResult> { + let shared = intent.kind.shared(); + match intent.scope_kind { + GcScopeKind::Store => query( + tx, + if shared { OPS_STORE } else { ALL_STORE }, + params![intent.op_id.to_vec()], + ), + GcScopeKind::Project => query( + tx, + if shared { OPS_PROJECT } else { ALL_PROJECT }, + params![ + intent.scope_id.clone(), + intent.project.clone(), + intent.op_id.to_vec() + ], + ), + GcScopeKind::Branch => query( + tx, + if shared { OPS_BRANCH } else { ALL_BRANCH }, + params![ + intent.project_id.clone(), + intent.scope_id.clone(), + intent.op_id.to_vec() + ], + ), + } +} + +fn validate_mount(tx: &Transaction<'_>, intent: &GcIntent) -> HistoryResult<()> { + if intent.kind != GcIntentKind::Mount { + return Ok(()); + } + match intent.scope_kind { + GcScopeKind::Store => Ok(()), + GcScopeKind::Project => { + let stack = LayerStackId::from_slice(&intent.scope_id) + .map_err(|_| HistoryError::InvalidInput("GC project scope"))?; + if layerstack::layer_stack(tx, stack)?.is_none() { + return Err(HistoryError::Missing(Missing::LayerStack)); + } + Ok(()) + } + GcScopeKind::Branch => { + let branch = BranchId::from_slice(&intent.scope_id) + .map_err(|_| HistoryError::InvalidInput("GC Branch scope"))?; + if branch::branch(tx, branch)?.is_none() { + return Err(HistoryError::Missing(Missing::Branch)); + } + Ok(()) + } + } +} + +/// One registration in its own write transaction. +fn register_in(tx: &Transaction<'_>, intent: &GcIntent, _postgres: bool) -> HistoryResult<()> { + validate_mount(tx, intent)?; + let found = conflicts_for(tx, intent)?; + if !found.is_empty() { + return Err(classify(&found)); + } + let state = if intent.uncertain { + "uncertain" + } else { + "live" + }; + let uncertain = i64::from(intent.uncertain); + tx.execute( + INSERT, + params![ + intent.op_id.to_vec(), + intent.kind.as_str(), + intent.scope_kind.as_str(), + intent.scope_id.clone(), + intent.workspace.map(|bytes| hex(&bytes)), + intent.sandbox.clone(), + intent.machine.clone(), + intent.project.clone(), + intent.branch.clone(), + intent.owner_runtime.clone(), + intent.owner_boot.clone(), + state, + uncertain, + intent.phase.clone(), + now_ms(), + ], + )?; + Ok(()) +} + +/// The advisory keys a PostgreSQL intent names, Store key first. +#[cfg(feature = "postgresql")] +fn advisory_keys(catalog: CatalogId, intent: &GcIntent) -> Vec<(u8, Vec)> { + let mut keys = vec![(1u8, catalog.as_slice().to_vec())]; + match intent.scope_kind { + GcScopeKind::Store => {} + GcScopeKind::Project => keys.push((2, intent.scope_id.clone())), + GcScopeKind::Branch => { + if let Some(project) = &intent.project_id { + keys.push((2, project.clone())); + } + keys.push((3, intent.scope_id.clone())); + } + } + keys +} + +#[cfg(feature = "postgresql")] +fn advisory_key(catalog: CatalogId, kind: u8, id: &[u8]) -> i64 { + let mut hasher = blake3::Hasher::new(); + hasher.update(b"layerfs/advisory/v1\0"); + hasher.update(catalog.as_slice()); + hasher.update(&[kind]); + hasher.update(id); + let digest = hasher.finalize(); + let mut head = [0u8; 8]; + head.copy_from_slice(&digest.as_bytes()[..8]); + i64::from_be_bytes(head) +} + +#[cfg(feature = "postgresql")] +fn xact_lock(tx: &Transaction<'_>, key: i64, shared: bool) -> HistoryResult<()> { + let found = tx.query( + if shared { + LOCK_XACT_SHARED + } else { + LOCK_XACT_EXCLUSIVE + }, + params![key], + )?; + if found.is_empty() { + return Err(if shared { + HistoryError::MountsActive(Box::new(MountHolders::new(Vec::new()))) + } else { + HistoryError::Busy + }); + } + Ok(()) +} + +/// PostgreSQL: the Store key a removal shares with every mount, taken first. +#[cfg(feature = "postgresql")] +fn lock_store_shared(tx: &Transaction<'_>, catalog: CatalogId) -> HistoryResult<()> { + xact_lock(tx, advisory_key(catalog, 1, catalog.as_slice()), true) +} + +/// PostgreSQL: one project or Branch key. +#[cfg(feature = "postgresql")] +fn lock_scope( + tx: &Transaction<'_>, + catalog: CatalogId, + kind: u8, + id: &[u8], + shared: bool, +) -> HistoryResult<()> { + xact_lock(tx, advisory_key(catalog, kind, id), shared) +} + +fn epoch_share(tx: &Transaction<'_>, postgres: bool, stack: LayerStackId) -> HistoryResult<()> { + if !postgres { + return Ok(()); + } + let found = tx.query(EPOCH_SHARE, [stack.as_slice()])?; + if found.len() != 1 { + return Err(HistoryError::Conflict("project epoch")); + } + Ok(()) +} + +fn release_in(tx: &Transaction<'_>, op_id: &[u8; 16]) -> HistoryResult<()> { + tx.execute(RELEASE, [op_id.as_slice()])?; + Ok(()) +} + +fn uncertain_in(tx: &Transaction<'_>, op_id: &[u8; 16]) -> HistoryResult<()> { + tx.execute(UNCERTAIN, params![now_ms(), op_id.as_slice()])?; + Ok(()) +} + +#[cfg(feature = "postgresql")] +fn get_in(tx: &Transaction<'_>, op_id: &[u8; 16]) -> HistoryResult> { + one(tx, GET, [op_id.as_slice()], intent_row) +} + +/// The PostgreSQL advisory keys one release unlocks, and whether its intent +/// was shared. +#[cfg(feature = "postgresql")] +struct ReleaseKeys { + keys: Vec<(u8, Vec)>, + shared: bool, +} + +#[cfg(feature = "postgresql")] +fn keys_for_release( + tx: &Transaction<'_>, + catalog: CatalogId, + intent: &GcIntent, +) -> HistoryResult { + let mut intent = intent.clone(); + if intent.scope_kind == GcScopeKind::Branch && intent.project_id.is_none() { + intent.project_id = one(tx, BRANCH_STACK, [intent.scope_id.as_slice()], |row| { + cell::>(row, 0) + })?; + } + Ok(ReleaseKeys { + keys: advisory_keys(catalog, &intent), + shared: intent.kind.shared(), + }) +} + +/// Registers one shared (`mount`, `init`, `merge`) or exclusive +/// (`compaction`) intent. +pub(crate) fn register(provider: &HistoryProvider, intent: &GcIntent) -> HistoryResult<()> { + match &provider.engine { + Engine::Sqlite(_) => provider.write(|tx| register_in(tx, intent, false)), + #[cfg(feature = "postgresql")] + Engine::Postgres(session) => { + let keys = advisory_keys(provider.catalog_id, intent); + let shared = intent.kind.shared(); + session_lock(session, provider.catalog_id, &keys, shared)?; + let result = session.run(true, |statements| { + register_in(&Transaction::new(statements), intent, true) + }); + if result.is_err() { + let _ = session_unlock(session, provider.catalog_id, &keys, shared); + } + result + } + } +} + +/// Deletes one intent, and on PostgreSQL releases the session keys it held. +pub(crate) fn release(provider: &HistoryProvider, op_id: &[u8; 16]) -> HistoryResult<()> { + match &provider.engine { + Engine::Sqlite(_) => provider.write(|tx| release_in(tx, op_id)), + #[cfg(feature = "postgresql")] + Engine::Postgres(session) => { + let found = provider.write(|tx| { + let Some(intent) = get_in(tx, op_id)? else { + return Ok(None); + }; + release_in(tx, op_id)?; + Ok(Some(keys_for_release(tx, provider.catalog_id, &intent)?)) + })?; + if let Some(ReleaseKeys { keys, shared }) = found { + let _ = session_unlock(session, provider.catalog_id, &keys, shared); + } + Ok(()) + } + } +} + +/// Marks one intent uncertain; its owner should settle it later. +pub(crate) fn mark_uncertain(provider: &HistoryProvider, op_id: &[u8; 16]) -> HistoryResult<()> { + provider.write(|tx| uncertain_in(tx, op_id)) +} + +/// `branch.remove`: scan the Branch scope and write the marker in one write +/// transaction. +pub(crate) fn remove_branch( + provider: &HistoryProvider, + branch: BranchId, + removed_ms: i64, + intent: &GcIntent, +) -> HistoryResult<()> { + let postgres = postgres(provider); + let catalog = provider.catalog_id; + let _ = catalog; + provider.write(|tx| { + let record = branch::branch(tx, branch)?.ok_or(HistoryError::Missing(Missing::Branch))?; + #[cfg(feature = "postgresql")] + if postgres { + lock_store_shared(tx, catalog)?; + lock_scope(tx, catalog, 2, record.stack.as_slice(), true)?; + let found = query( + tx, + ALL_BRANCH, + params![ + Some(record.stack.as_slice().to_vec()), + branch.as_slice().to_vec(), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + lock_scope(tx, catalog, 3, branch.as_slice(), false)?; + } + epoch_share(tx, postgres, record.stack)?; + let found = query( + tx, + ALL_BRANCH, + params![ + Some(record.stack.as_slice().to_vec()), + branch.as_slice().to_vec(), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + super::removal::mark_branch_removed(tx, branch, removed_ms) + }) +} + +/// `project.delete`: the same-home retry classification, then admission and +/// the marker in one write transaction. +pub(crate) fn delete_stack( + provider: &HistoryProvider, + stack: LayerStackId, + deleted_ms: i64, + intent: &GcIntent, +) -> HistoryResult { + let postgres = postgres(provider); + let catalog = provider.catalog_id; + let _ = catalog; + provider.write(|tx| { + if let Some(recorded) = layerstack::stack_deleted_ms(tx, stack)? { + return Ok(GcDeletion::Retired { + deleted_ms: recorded, + }); + } + let live = layerstack::layer_stack(tx, stack)?; + let Some(record) = live else { + return Ok(match layerstack::stack_deleted_ms(tx, stack)? { + Some(recorded) => GcDeletion::Retired { + deleted_ms: recorded, + }, + None => GcDeletion::Absent, + }); + }; + #[cfg(feature = "postgresql")] + if postgres { + lock_store_shared(tx, catalog)?; + let found = query( + tx, + ALL_PROJECT, + params![ + stack.as_slice().to_vec(), + Some(record.name.as_str().to_owned()), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + lock_scope(tx, catalog, 2, stack.as_slice(), false)?; + } + epoch_share(tx, postgres, stack)?; + let found = query( + tx, + ALL_PROJECT, + params![ + stack.as_slice().to_vec(), + Some(record.name.as_str().to_owned()), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + layerstack::mark_stack_deleted(tx, stack, deleted_ms)?; + Ok(GcDeletion::Marked { deleted_ms }) + }) +} + +/// `project.remove_file`: admission first, then the marker and epoch bump in +/// the same write transaction. +pub(crate) fn remove_path( + provider: &HistoryProvider, + request: &PathRemovalRequest, + intent: &GcIntent, +) -> HistoryResult { + let postgres = postgres(provider); + let catalog = provider.catalog_id; + let _ = catalog; + provider.write(|tx| { + if layerstack::layer_stack(tx, request.stack)?.is_none() { + return Err(HistoryError::Missing(Missing::LayerStack)); + } + #[cfg(feature = "postgresql")] + if postgres { + lock_store_shared(tx, catalog)?; + let found = query( + tx, + ALL_PROJECT, + params![ + request.stack.as_slice().to_vec(), + intent.project.clone(), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + lock_scope(tx, catalog, 2, request.stack.as_slice(), false)?; + } + epoch_share(tx, postgres, request.stack)?; + let found = query( + tx, + ALL_PROJECT, + params![ + request.stack.as_slice().to_vec(), + intent.project.clone(), + intent.op_id.to_vec() + ], + )?; + if !found.is_empty() { + return Err(classify(&found)); + } + let key = path_key(&request.path); + let stored = one( + tx, + "paths_marker", + [request.stack.as_slice(), key.as_slice()], + |row| { + Ok(( + cell::>(row, 0)?, + unsigned(row, 1)?, + cell::(row, 2)?, + )) + }, + )?; + let stack_high = position::stack_high_water(tx, request.stack)?; + if let Some((stored_path, frontier, removed)) = &stored { + if stored_path != &request.path { + return Err(HistoryError::Integrity("path marker key")); + } + if stack_high <= *frontier { + return Ok(PathRemovalOutcome { + kind: PathRemovalKind::UpToDate, + stack: request.stack, + path: stored_path.clone(), + frontier_serial: *frontier, + removed_ms: *removed, + }); + } + } + let frontier = position::high_water(tx)?; + paths::mark( + tx, + request.stack, + &request.path, + frontier, + request.removed_ms, + )?; + let advanced = tx.execute("paths_advance_epoch", [request.stack.as_slice()])?; + if advanced != 1 { + return Err(HistoryError::Conflict("project epoch")); + } + Ok(PathRemovalOutcome { + kind: PathRemovalKind::Removed, + stack: request.stack, + path: request.path.clone(), + frontier_serial: frontier, + removed_ms: request.removed_ms, + }) + }) +} + +/// Every live intent recorded at one scope, for `store.status` and tests. +pub(crate) fn intents( + provider: &HistoryProvider, + scope_kind: GcScopeKind, + scope_id: &[u8], +) -> HistoryResult> { + provider.read(|tx| query(tx, LIST, params![scope_kind.as_str(), scope_id.to_vec()])) +} + +#[cfg(feature = "postgresql")] +fn session_lock( + session: &std::sync::Arc, + catalog: CatalogId, + keys: &[(u8, Vec)], + shared: bool, +) -> HistoryResult<()> { + let mut taken: Vec<(u8, Vec)> = Vec::new(); + for (kind, id) in keys { + let key = advisory_key(catalog, *kind, id); + let found = session.read_statement(|statements| { + Transaction::new(statements).query( + if shared { + LOCK_SESSION_SHARED + } else { + LOCK_SESSION_EXCLUSIVE + }, + params![key], + ) + })?; + if found.is_empty() { + let _ = session_unlock(session, catalog, &taken, shared); + return Err(if shared { + HistoryError::MountsActive(Box::new(MountHolders::new(Vec::new()))) + } else { + HistoryError::Busy + }); + } + taken.push((*kind, id.clone())); + } + Ok(()) +} + +#[cfg(feature = "postgresql")] +fn session_unlock( + session: &std::sync::Arc, + catalog: CatalogId, + keys: &[(u8, Vec)], + shared: bool, +) -> HistoryResult<()> { + for (kind, id) in keys { + let key = advisory_key(catalog, *kind, id); + let _ = session.read_statement(|statements| { + Transaction::new(statements).query( + if shared { + UNLOCK_SESSION_SHARED + } else { + UNLOCK_SESSION_EXCLUSIVE + }, + params![key], + ) + })?; + } + Ok(()) +} diff --git a/engine/crates/layerfs-persistence/src/history/branch.rs b/engine/crates/layerfs-persistence/src/history/branch.rs index e174b8cdf2..2307c13661 100644 --- a/engine/crates/layerfs-persistence/src/history/branch.rs +++ b/engine/crates/layerfs-persistence/src/history/branch.rs @@ -7,7 +7,10 @@ use super::params; use super::transaction::Transaction; -use layerfs_history::error::{HistoryError, HistoryResult, Missing}; +use layerfs_history::error::{ + HistoryError, HistoryResult, HolderKind, HolderState, Missing, NameHolder, NameSource, + NameTakenState, +}; use layerfs_history::identity::{BranchId, CatalogId, HistoryName, LayerStackId}; use layerfs_history::records::{ BranchRecord, BranchSnapshot, ForkRequest, ForkSource, Page, PageResult, @@ -15,13 +18,17 @@ use layerfs_history::records::{ use layerfs_history::NamedSnapshot; use super::query::{self, Context, Cursor, Range}; -use super::rows::{branch_row, commit_row, many, one, sql, stack_row}; +use super::rows::{branch_row, cell, commit_row, many, one, sql, stack_row}; use crate::backend::records::{Record as Row, Value}; use layerfs_content::ObjectId; use layerfs_history::records::{CommitRecord, LayerStackRecord}; const BRANCH_BY_ID: &str = "branch_branch_by_id"; +/// The same row without the visibility filter: fork provenance and rendering +/// keep a retired Branch's name and stack without resolving it for a caller. +const BRANCH_BY_ID_ANY: &str = "branch_branch_by_id_any"; + const BRANCH_BY_NAME: &str = "branch_branch_by_name"; const BRANCH_FIRST_PAGE: &str = "branch_branch_first_page"; @@ -37,6 +44,55 @@ pub(crate) fn branch(tx: &Transaction<'_>, id: BranchId) -> HistoryResult