diff --git a/CMakeLists.txt b/CMakeLists.txt index 33cabce..16f89ff 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -34,7 +34,7 @@ target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in target_compile_features(evo_simulation PUBLIC cxx_std_23) evo_owned_target(evo_simulation) -set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp) +set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp src/world/local_files.cpp) add_library(evo_world STATIC ${evo_world_sources}) add_library(evo::world ALIAS evo_world) target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") @@ -84,6 +84,12 @@ if(BUILD_TESTING) add_test(NAME world-codec-contracts COMMAND evo-world-codec-tests) set_tests_properties(world-codec-contracts PROPERTIES TIMEOUT 120) + add_executable(evo-world-local-files-tests tests/world_local_files_tests.cpp) + target_link_libraries(evo-world-local-files-tests PRIVATE evo::world) + evo_owned_target(evo-world-local-files-tests) + add_test(NAME world-local-files-contracts COMMAND evo-world-local-files-tests) + set_tests_properties(world-local-files-contracts PROPERTIES TIMEOUT 120) + add_executable(evo-world-edit-tests tests/world_edit_tests.cpp) target_link_libraries(evo-world-edit-tests PRIVATE evo::world) evo_owned_target(evo-world-edit-tests) diff --git a/README.md b/README.md index 284eb16..3911f44 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ network service. Dev verification manifests are separate from the simulation. - [Actionable milestones 0–4 and later gates](docs/ROADMAP.md) - [Open design questions](docs/architecture/OPEN_QUESTIONS.md) - [World snapshots and edit journals](docs/world/WORLD_CODEC.md) +- [Local file publication manifest](schemas/local-world-manifest.md) - [Transactional terrain excavation](docs/world/TERRAIN_EDITS.md) - [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md) - [Versioned abiotic base generation](docs/world/BASE_GENERATION.md) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index f15205d..f7a92bd 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -268,7 +268,11 @@ and dirty eviction refusal. M5.5 now implements [atomic excavation](world/TERRAI with per-material volume conservation under [ADR-0046](adr/0046-transactional-excavation.md). M5.6 is complete under [ADR-0047](adr/0047-world-codec.md): [canonical snapshots and edit journals](world/WORLD_CODEC.md) validate geometry, debris -and retry state together. Next is 5.7: local publication, compaction and recovery. +and retry state together. M5.7 implements [single-writer local publication](adr/0048-local-publication.md): +two alternating manifest slots, immutable snapshot/journal payloads, verified detached +recovery, journal replay, checkpoint compaction and injected pre/post-commit interruption. +This is not a production multi-host durability or ownership service. M5.8 remains the +end-to-end deep-edit/restart and cost-evidence gate. **Decisions still open:** final spherical layout, region dimensions, adaptive LOD, field quantization beyond the initial experiment, hydrology and surface extraction. diff --git a/docs/STATUS.md b/docs/STATUS.md index 0cd2eed..993e7e3 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged. ## Completed implementation - Vision, architectural pillars, risks, open-question register, architecture - diagrams, biological contracts, engineering constitution and 47 ADRs. + diagrams, biological contracts, engineering constitution and 48 ADRs. Proposed/deferred choices remain distinct from accepted proof decisions. - M0–M4 task breakdowns with dependencies, acceptance evidence and risks, plus M5–M14 gates in [ROADMAP.md](ROADMAP.md). @@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic | Priority | Work | Completion evidence | |---|---|---| -| 1 | M5.7 local publication and compaction | Verified snapshot/journal replacement, recovery and injected filesystem failures | +| 1 | M5.8 bounded world proof | Deep edit -> checkpoint compaction -> restart with same state/inventory and measured operation costs | | Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report | | 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it | | Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes | @@ -582,5 +582,17 @@ obligations. No mass conversion or durable acknowledgement is claimed. Next: M5. Added bounded canonical world snapshot v1 and edit journal v1, world/frame and base version checks, full geometry/debris/retry restore, semantic validation and detached all-or-nothing replay. [Codec contract](world/WORLD_CODEC.md) and schemas define -memory/trust limits. Dirty flags remain set; no file publication or durable ACK is -implemented. Next: M5.7 local publication, compaction and recovery. +memory/trust limits. The M5.6 codec alone does not publish files or issue durable +acknowledgements. M5.7 local publication and recovery are implemented above. + +## M5.7 local publication and recovery + +ADR-0048 adds a single-writer local-filesystem adapter over the M5.6 codec. It uses +immutable checksum-named snapshot/journal blobs and two alternating canonical +manifest slots; replacing the inactive manifest is the publication point. Checkpoints +compact a committed journal only after a caller supplies the recovered/advanced +state. Recovery validates the selected snapshot and complete journal replay into a +detached ChunkStore. Tests cover lock exclusion, journal/restart, compaction, failpoints +before and after publication, malformed manifests and missing published payloads. +FNV remains a corruption detector, and this local adapter makes no host-loss, +multi-region or production durability claim. Filesystem orphan cleanup is deferred. diff --git a/docs/adr/0048-local-publication.md b/docs/adr/0048-local-publication.md new file mode 100644 index 0000000..e9c96a8 --- /dev/null +++ b/docs/adr/0048-local-publication.md @@ -0,0 +1,65 @@ +# ADR-0048: Local snapshot and journal publication + +## Status +Accepted for M5.7 single-process development files. Not the M7 production durable store. + +## Context +M5.6 provides canonical bounded buffers. Bytes become current only after a recoverable +manifest points to verified payloads. A previous committed snapshot must survive while +a replacement is prepared and published. + +## Decision +Use a trusted host-supplied root, then derive a directory from hex world/frame IDs. +Hold an exclusive OS lock for one writer. Payloads use immutable content-addressed +names containing the M5.6 FNV checksum; always compare complete bytes if a name exists. +No object is overwritten. Write a same-directory temporary with exclusive/truncated +access, flush file contents, atomically link/rename to its final payload name, then +flush the directory. + +Maintain two fixed manifest slots. A manifest carries magic/version/length, identity, +monotonic generation, snapshot checksum/covered command, optional journal checksum and +end command, and checksum. Write/flush a temporary manifest and atomically replace only +the inactive slot; flush parent directory. That replacement is the local commit point. +Never alter the active manifest or source payload before that point. If a failure is +ambiguous after publication, poison this handle and require reopen/recovery. A valid +manifest referencing missing/corrupt data fails closed; do not roll back acknowledged +state silently. No automatic orphan deletion in this gate. + +Snapshot checkpoint validates bytes by restoring them under budget before publication. +A journal commit must match the current checkpoint's exact bytes and high-water, and +pass detached replay. Only one journal segment is active per checkpoint; checkpoint +after replay to compact it. Recovery validates the selected manifest and referenced +payloads using M5.6, then replays the optional segment before returning a candidate. +Existing valid manifest stays the source until new publication completes. + +Implement the minimal native OS boundary directly: POSIX lock/write/fsync/link/rename/ +directory fsync; Windows exclusive CreateFile and write-through replacement. No third +party library. Root directory is trusted and locally administered. Files are not +network-safe/authenticated; FNV detects accidental corruption only. + +Provide one-shot failure injection at payload sync, manifest sync, and manifest publish +for deterministic crash-boundary tests. After injected interruption, discard the handle +and reopen. A failure before manifest replacement yields old state; after replacement +yields new state. Allocation/OS errors do not clear dirty state. + +## Alternatives Considered +In-place overwrite can destroy the old checkpoint on short write. A single manifest can +be torn. Renaming the active file to a backup creates a missing-pointer crash interval. +SQLite/database/object-store dependencies are future infrastructure, not a local gate. + +## Benefits +Clear commit point, old-source retention, bounded recovery scan and injected boundary tests. + +## Costs +Two manifests and immutable payloads; orphan accumulation and no concurrent writers. +POSIX/Windows code paths need platform review and Linux CI. + +## Risks +Filesystem/controller hardware may violate flush guarantees. Windows/POSIX/network filesystems +differ. Same-host files do not survive host loss. Fail-closed corruption may require +operator recovery. No production DR/RPO claim. + +## Consequences +Test first checkpoint, journal, compaction, restart continuation, competing lock, corrupt +payload/manifest, every injected boundary, missing sequence and full-disk/OS errors. +Record Linux checks separately. M5.8 performs the whole create/edit/compact/restart proof. diff --git a/docs/adr/README.md b/docs/adr/README.md index 3c5b10c..147e006 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -53,3 +53,5 @@ design. No unadopted candidate is a link dependency of the proof. - [ADR-0046: Transactional excavation](0046-transactional-excavation.md) - accepted for M5.5 atomic local volume transfers and bounded exact-request replay. - [ADR-0047: World codecs](0047-world-codec.md) - accepted for M5.6 bounded canonical snapshots and detached edit-journal replay. + +- [ADR-0048: Local publication](0048-local-publication.md) - accepted for M5.7 single-writer snapshot/journal publication and recovery. diff --git a/docs/architecture/PERSISTENCE_ARCHITECTURE.md b/docs/architecture/PERSISTENCE_ARCHITECTURE.md index 986364d..6b7ec7b 100644 --- a/docs/architecture/PERSISTENCE_ARCHITECTURE.md +++ b/docs/architecture/PERSISTENCE_ARCHITECTURE.md @@ -143,10 +143,22 @@ verified durable failure domain containing the complete causal recovery chain and referenced payloads before acknowledgment; restoring an older backup cannot silently undo permadeath. That admission/DR requirement is a World0 launch gate. +## Implemented M5.7 local file publication boundary + +[ADR-0048](../adr/0048-local-publication.md) and +[the manifest schema](../../schemas/local-world-manifest.md) implement a single-writer +development file backend over the M5.6 codecs. Immutable checksum-named payloads +are installed before alternating manifests; atomic replacement of the inactive +manifest is the commit point. Recovery validates the selected snapshot and replays +its optional one-segment journal into a detached store. Pre-publication failures +retain the previous generation; a post-publication interruption requires reopen +and recovers the new one. Orphan files are retained. This is not the M7 fenced, +multi-worker or host-loss durability contract above. + ## Implemented M5.6 local world codec boundary [ADR-0047](../adr/0047-world-codec.md) and [the codec contract](../world/WORLD_CODEC.md) implement bounded canonical buffers carrying world/frame IDs, base versions, covered command high-water, resident cells, debris and exact retry state. Detached replay -verifies predecessor and final state. This is in-memory codec validation, not the -production durability contract above. File publication/crash recovery is M5.7. +verifies predecessor and final state. This remains an in-memory codec beneath +M5.7's local file publication adapter. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 91d5dfd..3638fad 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1,10 +1,41 @@ # Validation report -Recorded 2026-09-19. Latest verified Linux delivery: **run 1402 passed** on -`4c2cc04ac47d37c6191a9ef02d4bbba716a930dc`. Native checks apply to base commit `8ab48d3` plus the -foundation-delivery working changes committed with this report. Simulation rules -and snapshot format remain version 1; the only C++ change is benchmark metadata. -Results below distinguish executed checks from pending Linux/cluster gates. +Recorded 2026-09-19; subsequent gate evidence is appended by date below. Latest +historical verified Linux delivery at the time of the foundation report was **run +1402** on `4c2cc04ac47d37c6191a9ef02d4bbba716a930dc`. Native check history and later +gate-specific results are kept separate. Results distinguish executed checks from +pending Linux/cluster gates. + +## M5.7 local publication - 2026-09-26 + +Added the single-writer local filesystem adapter and manifest v1 under ADR-0048. +The implementation is in `include/evo/world/local_files.hpp` and +`src/world/local_files.cpp`; `schemas/local-world-manifest.md` defines the durable +bytes. The commit point is replacement of the inactive manifest slot after the +referenced payload has been written, flushed, installed and directory-flushed. +Recovery validates the snapshot and optional journal before returning a new store. +FNV is only a corruption check; this is not host-loss durability or the M7 region +ownership system. + +Executed on Windows x64 / MSVC 19.44.35207: + +- `tools/windows-check.ps1 -Preset release -Action check`: configure/build passed; + 47/47 CTests passed with `NDEBUG`. +- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 and + warnings-as-errors build passed; 47/47 CTests passed. +- `tools/windows-check.ps1 -Preset asan -Action check`: build passed; 47/47 CTests + passed. The Windows preset is not Linux ASan+UBSan evidence. +- `tools/windows-check.ps1 -Preset release -Action format`: passed. +- `git diff --check`: passed before commit. + +New coverage validates checkpoint/journal/recovery, compaction over a published +journal, exclusive writer lock, all three injected publication boundaries, corrupt +manifest and missing published payload failure. Before-manifest failures recover +the previous generation; after-manifest replacement recovers the new generation. +Actual power-cut/full-disk behavior, POSIX syscall path, Linux CI/libFuzzer, and +filesystem-controller flush guarantees remain unverified locally. There is no +automatic orphan cleanup, production storage adapter, Kubernetes deployment or +World0 change. ## Tools and host diff --git a/docs/world/WORLD_CODEC.md b/docs/world/WORLD_CODEC.md index a57d3a2..f727ba9 100644 --- a/docs/world/WORLD_CODEC.md +++ b/docs/world/WORLD_CODEC.md @@ -77,6 +77,11 @@ insufficient memory. A 128-input deterministic fuzz smoke is in CTest; Linux CI validation instead of stopping only at the envelope. Local Windows smoke is not a claim that Linux coverage-guided fuzzing has executed. -Next M5.7: publish/compact local files with verified replacement and failure injection. +M5.7 adds a separate local publication contract in [ADR-0048](../adr/0048-local-publication.md) +and [the manifest schema](../../schemas/local-world-manifest.md). Two alternating +manifest slots select immutable M5.6 snapshot/journal payloads. Recovery validates +the selected snapshot and optional journal into a detached store. The manifest +replacement is the local commit point; this provides no multi-host durability, +production lease, authentication or disaster recovery guarantee. M5.6 does not write files, fsync, delete journals, clear dirty state or recover a live server process. M7 supplies the production durability/ownership path. diff --git a/include/evo/world/local_files.hpp b/include/evo/world/local_files.hpp new file mode 100644 index 0000000..2b244e7 --- /dev/null +++ b/include/evo/world/local_files.hpp @@ -0,0 +1,78 @@ +#pragma once + +#include "evo/world/chunks.hpp" +#include +#include +#include +#include +#include +#include + +namespace evo::world { +enum class LocalFileError : std::uint8_t { + invalid_identity, + busy, + empty, + corrupt_manifest, + corrupt_payload, + identity_mismatch, + invalid_snapshot, + invalid_journal, + stale_checkpoint, + journal_already_published, + generation_exhausted, + io, + interrupted, + poisoned +}; +enum class PublicationInterruption : std::uint8_t { + none, + after_payload_sync, + after_manifest_sync, + after_manifest_publish +}; +struct FileCommit { + std::uint64_t generation{}, covered_command{}, snapshot_checksum{}; + bool has_journal{}; + auto operator<=>(const FileCommit&) const = default; +}; +class LocalWorldFiles { + public: + [[nodiscard]] static std::expected, LocalFileError> + open(const std::filesystem::path& trusted_root, WorldIdentity identity, std::size_t byte_budget, + PublicationInterruption interrupt_once = PublicationInterruption::none); + LocalWorldFiles(const LocalWorldFiles&) = delete; + LocalWorldFiles& operator=(const LocalWorldFiles&) = delete; + LocalWorldFiles(LocalWorldFiles&&) = delete; + LocalWorldFiles& operator=(LocalWorldFiles&&) = delete; + ~LocalWorldFiles(); + [[nodiscard]] std::expected, LocalFileError> recover() const; + [[nodiscard]] std::expected checkpoint(const ChunkStore& store); + [[nodiscard]] std::expected + publish_journal(std::span checkpoint, + std::span journal); + [[nodiscard]] std::optional current() const noexcept; + + private: + struct Lock; + struct Manifest { + std::uint64_t generation{}, snapshot_checksum{}, covered_command{}; + std::uint64_t journal_checksum{}, journal_end{}; + bool has_journal{}; + }; + LocalWorldFiles(std::filesystem::path directory, WorldIdentity identity, std::size_t budget, + PublicationInterruption interruption, std::unique_ptr lock); + [[nodiscard]] std::expected + publish(std::span payload, bool journal, std::uint64_t covered, + std::uint64_t payload_checksum); + std::filesystem::path directory_; + WorldIdentity identity_; + std::size_t budget_; + PublicationInterruption interruption_; + std::unique_ptr lock_; + std::optional manifest_; + std::size_t active_slot_{}; + std::uint64_t generation_high_water_{}; + bool poisoned_{}; +}; +} // namespace evo::world diff --git a/schemas/local-world-manifest.md b/schemas/local-world-manifest.md new file mode 100644 index 0000000..a9f68f6 --- /dev/null +++ b/schemas/local-world-manifest.md @@ -0,0 +1,53 @@ +# Local world manifest v1 + +This is an M5.7 single-host publication record, not a production/world-server +manifest. The encoding is fixed-width little-endian and exactly 88 bytes: + +| Offset | Width | Field | +|---:|---:|---| +| 0 | 8 | magic `0x0031464d574f5645` | +| 8 | 4 | version `1` | +| 12 | 4 | total length `88` | +| 16 | 8 | world identity | +| 24 | 8 | frame identity | +| 32 | 8 | generation, nonzero | +| 40 | 8 | FNV-1a checksum of complete snapshot payload | +| 48 | 8 | snapshot command high-water | +| 56 | 1 | journal-present flag, 0 or 1 | +| 57 | 7 | reserved zero bytes | +| 64 | 8 | FNV-1a checksum of complete journal payload, or zero | +| 72 | 8 | journal final command, or zero | +| 80 | 8 | FNV-1a checksum of bytes 0 through 79 | + +FNV detects accidental corruption only. It is not authentication. Payload names +are derived from their checksum and complete bytes are compared when a name +already exists. A manifest reference is accepted only after the M5.6 snapshot +restore and optional all-or-nothing journal replay succeed. + +## Publication and recovery + +The writer holds the per-world OS lock. It writes a same-directory temporary +payload and flushes it, installs a new immutable payload name, then flushes the +directory. It writes and flushes the inactive manifest temporary and atomically +replaces that manifest slot. The replacement is the commit point. Slots alternate +by generation. Recovery parses both slots and selects the greatest generation; +any malformed present slot or invalid selected payload fails closed. It never +silently falls back from a valid published pointer to an older generation. + +```mermaid +stateDiagram-v2 + [*] --> PreparePayload + PreparePayload --> PayloadSynced + PayloadSynced --> PayloadInstalled + PayloadInstalled --> PrepareInactiveManifest + PrepareInactiveManifest --> ManifestSynced + ManifestSynced --> Published: atomic replace (commit) + ManifestSynced --> PreviousGeneration: failure before replace + Published --> ReopenRequired: ambiguous/post-publication error + Published --> Recoverable: durable slot + referenced payload +``` + +An interruption before replacement recovers the old generation. An interruption +after replacement recovers the new generation. Unknown files and orphan payloads +are ignored; this version does not delete them. OS locks, fsync/write-through and +same-directory rename semantics depend on the local filesystem and storage stack. diff --git a/src/world/local_files.cpp b/src/world/local_files.cpp new file mode 100644 index 0000000..e4d11c0 --- /dev/null +++ b/src/world/local_files.cpp @@ -0,0 +1,420 @@ +#include "evo/world/local_files.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +#ifdef _WIN32 +#define NOMINMAX +#include +#else +#include +#include +#include +#include +#include +#endif + +namespace evo::world { +namespace { +constexpr std::uint64_t manifest_magic = 0x31464d574f5645ULL; +constexpr std::uint32_t manifest_version = 1; +constexpr std::size_t manifest_size = 88; + +std::uint64_t hash(std::span bytes) noexcept { + std::uint64_t value = 14695981039346656037ULL; + for (const auto byte : bytes) { + value = (value ^ byte) * 1099511628211ULL; + } + return value; +} +void put(WorldBytes& out, std::uint64_t value, unsigned width) { + for (unsigned i = 0; i < width; ++i) { + out.push_back(static_cast(value & 0xffU)); + value >>= 8U; + } +} +std::uint64_t get(std::span in, std::size_t offset, unsigned width) { + std::uint64_t value{}; + for (unsigned i = 0; i < width; ++i) { + value |= static_cast(in[offset + i]) << (i * 8U); + } + return value; +} +std::string hex(std::uint64_t value) { + std::ostringstream stream; + stream << std::hex << std::setfill('0') << std::setw(16) << value; + return stream.str(); +} +template WorldBytes encode_manifest(WorldIdentity id, const Manifest& m) { + WorldBytes b; + b.reserve(manifest_size); + put(b, manifest_magic, 8); + put(b, manifest_version, 4); + put(b, manifest_size, 4); + put(b, id.world, 8); + put(b, id.frame, 8); + put(b, m.generation, 8); + put(b, m.snapshot_checksum, 8); + put(b, m.covered_command, 8); + put(b, m.has_journal ? 1 : 0, 1); + for (int i = 0; i < 7; ++i) + put(b, 0, 1); + put(b, m.journal_checksum, 8); + put(b, m.journal_end, 8); + put(b, hash(b), 8); + return b; +} +template +std::expected decode_manifest(std::span b, + WorldIdentity id) { + if (b.size() != manifest_size || get(b, 0, 8) != manifest_magic || + get(b, 8, 4) != manifest_version || get(b, 12, 4) != manifest_size || get(b, 56, 1) > 1 || + get(b, 80, 8) != hash(b.first(80))) { + return std::unexpected(LocalFileError::corrupt_manifest); + } + for (std::size_t i = 57; i < 64; ++i) { + if (b[i] != 0) + return std::unexpected(LocalFileError::corrupt_manifest); + } + if (get(b, 16, 8) != id.world || get(b, 24, 8) != id.frame) + return std::unexpected(LocalFileError::identity_mismatch); + Manifest m{get(b, 32, 8), get(b, 40, 8), get(b, 48, 8), + get(b, 64, 8), get(b, 72, 8), get(b, 56, 1) != 0}; + if (!m.generation || (!m.has_journal && (m.journal_checksum || m.journal_end)) || + (m.has_journal && !m.journal_checksum)) + return std::unexpected(LocalFileError::corrupt_manifest); + return m; +} + +std::expected read_file(const std::filesystem::path& path, + std::size_t max) { + std::error_code ec; + if (!std::filesystem::exists(path, ec)) { + if (!ec) + return std::unexpected(LocalFileError::empty); + return std::unexpected(LocalFileError::io); + } + std::ifstream stream(path, std::ios::binary); + if (!stream) + return std::unexpected(LocalFileError::io); + stream.seekg(0, std::ios::end); + const auto end = stream.tellg(); + if (end < 0 || static_cast(end) > max) + return std::unexpected(LocalFileError::io); + WorldBytes bytes(static_cast(end)); + stream.seekg(0, std::ios::beg); + if (!bytes.empty() && !stream.read(reinterpret_cast(bytes.data()), + static_cast(bytes.size()))) + return std::unexpected(LocalFileError::io); + return bytes; +} + +bool sync_directory(const std::filesystem::path& path) { +#ifdef _WIN32 + (void)path; + return true; // Payload/manifest replacement uses MOVEFILE_WRITE_THROUGH. +#else + const int fd = ::open(path.c_str(), O_RDONLY | O_DIRECTORY); + if (fd < 0) + return false; + const bool ok = ::fsync(fd) == 0; + ::close(fd); + return ok; +#endif +} + +bool write_synced(const std::filesystem::path& path, std::span bytes) { +#ifdef _WIN32 + HANDLE file = CreateFileW(path.c_str(), GENERIC_WRITE, 0, nullptr, CREATE_ALWAYS, + FILE_ATTRIBUTE_NORMAL | FILE_FLAG_WRITE_THROUGH, nullptr); + if (file == INVALID_HANDLE_VALUE) + return false; + std::size_t offset = 0; + bool ok = true; + while (offset < bytes.size()) { + const auto amount = + static_cast(std::min(bytes.size() - offset, 1U << 20U)); + DWORD wrote{}; + if (!WriteFile(file, bytes.data() + offset, amount, &wrote, nullptr) || !wrote) { + ok = false; + break; + } + offset += wrote; + } + ok = FlushFileBuffers(file) != 0 && ok; + CloseHandle(file); + return ok; +#else + const int fd = ::open(path.c_str(), O_WRONLY | O_CREAT | O_TRUNC, 0600); + if (fd < 0) + return false; + std::size_t offset = 0; + bool ok = true; + while (offset < bytes.size()) { + const auto wrote = ::write(fd, bytes.data() + offset, bytes.size() - offset); + if (wrote < 0 && errno == EINTR) + continue; + if (wrote <= 0) { + ok = false; + break; + } + offset += static_cast(wrote); + } + ok = ::fsync(fd) == 0 && ok; + ::close(fd); + return ok; +#endif +} + +bool install_immutable(const std::filesystem::path& temp, const std::filesystem::path& dest) { +#ifdef _WIN32 + return MoveFileExW(temp.c_str(), dest.c_str(), MOVEFILE_WRITE_THROUGH) != 0; +#else + if (::link(temp.c_str(), dest.c_str()) != 0) + return false; + return ::unlink(temp.c_str()) == 0; +#endif +} +bool replace_file(const std::filesystem::path& temp, const std::filesystem::path& dest) { +#ifdef _WIN32 + return MoveFileExW(temp.c_str(), dest.c_str(), + MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) != 0; +#else + return ::rename(temp.c_str(), dest.c_str()) == 0; +#endif +} +} // namespace + +struct LocalWorldFiles::Lock { +#ifdef _WIN32 + HANDLE handle{INVALID_HANDLE_VALUE}; + ~Lock() { + if (handle != INVALID_HANDLE_VALUE) + CloseHandle(handle); + } +#else + int fd{-1}; + ~Lock() { + if (fd >= 0) { + ::flock(fd, LOCK_UN); + ::close(fd); + } + } +#endif +}; + +LocalWorldFiles::LocalWorldFiles(std::filesystem::path directory, WorldIdentity identity, + std::size_t budget, PublicationInterruption interruption, + std::unique_ptr lock) + : directory_{std::move(directory)}, identity_{identity}, budget_{budget}, + interruption_{interruption}, lock_{std::move(lock)} {} +LocalWorldFiles::~LocalWorldFiles() = default; + +std::expected, LocalFileError> +LocalWorldFiles::open(const std::filesystem::path& root, WorldIdentity identity, std::size_t budget, + PublicationInterruption interruption) { + if (!identity.world || !identity.frame || !budget) + return std::unexpected(LocalFileError::invalid_identity); + const auto directory = root / ("world-" + hex(identity.world) + "-" + hex(identity.frame)); + std::error_code ec; + std::filesystem::create_directories(directory, ec); + if (ec || !std::filesystem::is_directory(directory, ec) || ec) + return std::unexpected(LocalFileError::io); + auto lock = std::make_unique(); +#ifdef _WIN32 + lock->handle = CreateFileW((directory / L".lock").c_str(), GENERIC_READ | GENERIC_WRITE, 0, + nullptr, OPEN_ALWAYS, FILE_ATTRIBUTE_HIDDEN, nullptr); + if (lock->handle == INVALID_HANDLE_VALUE) + return std::unexpected(LocalFileError::busy); +#else + lock->fd = ::open((directory / ".lock").c_str(), O_CREAT | O_RDWR, 0600); + if (lock->fd < 0 || ::flock(lock->fd, LOCK_EX | LOCK_NB) != 0) + return std::unexpected(LocalFileError::busy); +#endif + auto result = std::unique_ptr( + new LocalWorldFiles(directory, identity, budget, interruption, std::move(lock))); + for (std::size_t slot = 0; slot < 2; ++slot) { + auto bytes = read_file(directory / ("manifest." + std::to_string(slot)), manifest_size); + if (!bytes) { + if (bytes.error() == LocalFileError::empty) + continue; + return std::unexpected(LocalFileError::io); + } + auto parsed = decode_manifest(*bytes, identity); + if (!parsed) + return std::unexpected(parsed.error()); + if (parsed->generation > result->manifest_.value_or(Manifest{}).generation) { + result->manifest_ = *parsed; + result->active_slot_ = slot; + } + result->generation_high_water_ = + std::max(result->generation_high_water_, parsed->generation); + } + return result; +} + +std::optional LocalWorldFiles::current() const noexcept { + if (!manifest_) + return std::nullopt; + return FileCommit{manifest_->generation, manifest_->covered_command, + manifest_->snapshot_checksum, manifest_->has_journal}; +} + +std::expected, LocalFileError> LocalWorldFiles::recover() const { + if (!manifest_) + return std::unexpected(LocalFileError::empty); + const auto snapshot_path = + directory_ / ("snapshot-" + hex(manifest_->snapshot_checksum) + ".bin"); + auto bytes = read_file(snapshot_path, max_world_snapshot_bytes); + if (!bytes || hash(*bytes) != manifest_->snapshot_checksum) + return std::unexpected(LocalFileError::corrupt_payload); + const auto covered = bytes->size() >= 80 ? get(*bytes, 72, 8) : 0; + if (covered != manifest_->covered_command) + return std::unexpected(LocalFileError::corrupt_manifest); + auto base = ChunkStore::restore(*bytes, identity_, budget_); + if (!base) + return std::unexpected(LocalFileError::invalid_snapshot); + if (!manifest_->has_journal) + return std::move(*base); + auto journal = read_file(directory_ / ("journal-" + hex(manifest_->journal_checksum) + ".bin"), + max_world_journal_bytes); + if (!journal || hash(*journal) != manifest_->journal_checksum) + return std::unexpected(LocalFileError::corrupt_payload); + auto replayed = replay_edit_journal(*bytes, *journal, identity_, budget_); + if (!replayed) + return std::unexpected(LocalFileError::invalid_journal); + const auto final = (**replayed).snapshot(identity_); + if (!final || final->size() < 80 || get(*final, 72, 8) != manifest_->journal_end) + return std::unexpected(LocalFileError::invalid_journal); + return std::move(*replayed); +} + +std::expected +LocalWorldFiles::publish(std::span payload, bool journal, std::uint64_t covered, + std::uint64_t payload_checksum) { + if (poisoned_) + return std::unexpected(LocalFileError::poisoned); + if (generation_high_water_ == UINT64_MAX) + return std::unexpected(LocalFileError::generation_exhausted); + const auto prefix = journal ? "journal-" : "snapshot-"; + const auto payload_path = directory_ / (prefix + hex(payload_checksum) + ".bin"); + std::error_code ec; + if (std::filesystem::exists(payload_path, ec)) { + auto existing = + read_file(payload_path, journal ? max_world_journal_bytes : max_world_snapshot_bytes); + if (!existing || !std::ranges::equal(*existing, payload)) + return std::unexpected(LocalFileError::corrupt_payload); + } else { + const auto temp = directory_ / (std::string{prefix} + ".payload.tmp"); + std::filesystem::remove(temp, ec); + ec.clear(); + if (!write_synced(temp, payload)) + return std::unexpected(LocalFileError::io); + if (interruption_ == PublicationInterruption::after_payload_sync) { + interruption_ = PublicationInterruption::none; + poisoned_ = true; + return std::unexpected(LocalFileError::interrupted); + } + if (!install_immutable(temp, payload_path) || !sync_directory(directory_)) + return std::unexpected(LocalFileError::io); + } + if (interruption_ == PublicationInterruption::after_payload_sync) { + interruption_ = PublicationInterruption::none; + poisoned_ = true; + return std::unexpected(LocalFileError::interrupted); + } + Manifest candidate{}; + candidate.generation = generation_high_water_ + 1; + if (journal) { + if (!manifest_) + return std::unexpected(LocalFileError::empty); + candidate = *manifest_; + candidate.generation = generation_high_water_ + 1; + candidate.has_journal = true; + candidate.journal_checksum = payload_checksum; + candidate.journal_end = covered; + } else { + candidate.snapshot_checksum = payload_checksum; + candidate.covered_command = covered; + } + const auto inactive = manifest_ ? 1U - active_slot_ : 0U; + const auto temp_manifest = directory_ / ("manifest." + std::to_string(inactive) + ".tmp"); + const auto dest_manifest = directory_ / ("manifest." + std::to_string(inactive)); + const auto encoded = encode_manifest(identity_, candidate); + std::filesystem::remove(temp_manifest, ec); + ec.clear(); + if (!write_synced(temp_manifest, encoded)) + return std::unexpected(LocalFileError::io); + if (interruption_ == PublicationInterruption::after_manifest_sync) { + interruption_ = PublicationInterruption::none; + poisoned_ = true; + return std::unexpected(LocalFileError::interrupted); + } + if (!replace_file(temp_manifest, dest_manifest)) + return std::unexpected(LocalFileError::io); + if (!sync_directory(directory_)) { + poisoned_ = true; + return std::unexpected(LocalFileError::io); + } + manifest_ = candidate; + active_slot_ = inactive; + generation_high_water_ = candidate.generation; + if (interruption_ == PublicationInterruption::after_manifest_publish) { + interruption_ = PublicationInterruption::none; + poisoned_ = true; + return std::unexpected(LocalFileError::interrupted); + } + return FileCommit{candidate.generation, candidate.covered_command, candidate.snapshot_checksum, + candidate.has_journal}; +} + +std::expected LocalWorldFiles::checkpoint(const ChunkStore& store) { + if (poisoned_) + return std::unexpected(LocalFileError::poisoned); + auto bytes = store.snapshot(identity_); + if (!bytes) + return std::unexpected(LocalFileError::invalid_snapshot); + auto valid = ChunkStore::restore(*bytes, identity_, budget_); + if (!valid || bytes->size() < 80) + return std::unexpected(LocalFileError::invalid_snapshot); + const auto covered = get(*bytes, 72, 8); + const auto required = + manifest_ ? (manifest_->has_journal ? manifest_->journal_end : manifest_->covered_command) + : 0; + if (covered < required) + return std::unexpected(LocalFileError::stale_checkpoint); + return publish(*bytes, false, covered, hash(*bytes)); +} + +std::expected +LocalWorldFiles::publish_journal(std::span checkpoint, + std::span journal) { + if (poisoned_) + return std::unexpected(LocalFileError::poisoned); + if (!manifest_) + return std::unexpected(LocalFileError::empty); + if (manifest_->has_journal) + return std::unexpected(LocalFileError::journal_already_published); + auto base = read_file(directory_ / ("snapshot-" + hex(manifest_->snapshot_checksum) + ".bin"), + max_world_snapshot_bytes); + if (!base || !std::ranges::equal(*base, checkpoint) || + hash(checkpoint) != manifest_->snapshot_checksum) + return std::unexpected(LocalFileError::stale_checkpoint); + auto replayed = replay_edit_journal(checkpoint, journal, identity_, budget_); + if (!replayed) + return std::unexpected(LocalFileError::invalid_journal); + const auto final = (**replayed).snapshot(identity_); + if (!final || final->size() < 80) + return std::unexpected(LocalFileError::invalid_journal); + const auto end = get(*final, 72, 8); + if (end < manifest_->covered_command) + return std::unexpected(LocalFileError::invalid_journal); + return publish(journal, true, end, hash(journal)); +} +} // namespace evo::world diff --git a/tests/world_local_files_tests.cpp b/tests/world_local_files_tests.cpp new file mode 100644 index 0000000..bc50d58 --- /dev/null +++ b/tests/world_local_files_tests.cpp @@ -0,0 +1,171 @@ +#include "evo/world/local_files.hpp" + +#include +#include +#include +#include +#include +#include +#include + +namespace { +using namespace evo::world; +constexpr WorldIdentity identity{71, 91}; +constexpr std::size_t budget = 2'000'000; +void check(bool ok, std::source_location at = std::source_location::current()) { + if (!ok) + throw std::runtime_error("local world files line " + std::to_string(at.line())); +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +struct TempRoot { + std::filesystem::path path = + std::filesystem::temp_directory_path() / + ("evo-local-files-" + + std::to_string(std::chrono::steady_clock::now().time_since_epoch().count())); + TempRoot() { + std::filesystem::create_directories(path); + } + ~TempRoot() { + std::error_code ignored; + std::filesystem::remove_all(path, ignored); + } +}; +std::unique_ptr make_store() { + auto result = + ChunkStore::create({}, 4, budget, {{VolumeUnits{1'000'000}, VolumeUnits{1'000'000}}}); + CHECK(result); + CHECK((*result)->load({0, 0, -2})); + return std::move(*result); +} +std::filesystem::path world_dir(const std::filesystem::path& root) { + return root / "world-0000000000000047-000000000000005b"; +} +void checkpoint_and_journal_round_trip() { + TempRoot root; + auto files = LocalWorldFiles::open(root.path, identity, budget); + CHECK(files && !(*files)->recover() && (*files)->recover().error() == LocalFileError::empty); + auto original = make_store(); + auto checkpoint = original->snapshot(identity); + CHECK(checkpoint); + auto committed = (*files)->checkpoint(*original); + CHECK(committed && committed->generation == 1 && !committed->has_journal); + + const auto view = original->view({0, 0, -2}); + CHECK(view); + const std::array cuts{{{{0, 0, -2}, {0, 0, 0}, view->revision(), 2}}}; + ExcavationRequest request{1, 1, cuts, 0}; + const auto digest = excavation_digest(request); + CHECK(digest); + request.digest = *digest; + const std::array requests{request}; + auto journal = make_edit_journal(*checkpoint, identity, requests, budget); + CHECK(journal); + auto journal_commit = (*files)->publish_journal(*checkpoint, *journal); + CHECK(journal_commit && journal_commit->generation == 2 && journal_commit->has_journal); + CHECK(!(*files)->publish_journal(*checkpoint, *journal)); + const auto stale_checkpoint = (*files)->checkpoint(*original); + CHECK(!stale_checkpoint && stale_checkpoint.error() == LocalFileError::stale_checkpoint); + auto recovered = (*files)->recover(); + CHECK(recovered); + auto expected = replay_edit_journal(*checkpoint, *journal, identity, budget); + CHECK(expected); + CHECK((*recovered)->snapshot(identity) == (**expected).snapshot(identity)); + (*files).reset(); + + auto reopened = LocalWorldFiles::open(root.path, identity, budget); + CHECK(reopened); + const auto reopened_commit = (*reopened)->current(); + CHECK(reopened_commit.has_value()); + CHECK(reopened_commit.value_or(FileCommit{}).generation == 2); + CHECK((*reopened)->recover()); + auto compacted = (*reopened)->checkpoint(**recovered); + CHECK(compacted && compacted->generation == 3 && !compacted->has_journal); + CHECK((*reopened)->recover()); +} +void interruptions_preserve_commit_point() { + for (const auto point : + {PublicationInterruption::after_payload_sync, PublicationInterruption::after_manifest_sync, + PublicationInterruption::after_manifest_publish}) { + TempRoot root; + { + auto files = LocalWorldFiles::open(root.path, identity, budget); + CHECK(files); + auto initial = make_store(); + CHECK((*files)->checkpoint(*initial)); + } + auto interrupted = LocalWorldFiles::open(root.path, identity, budget, point); + CHECK(interrupted); + auto changed = make_store(); + const auto result = (*interrupted)->checkpoint(*changed); + CHECK(!result && result.error() == LocalFileError::interrupted); + CHECK(!(*interrupted)->checkpoint(*changed)); + (*interrupted).reset(); + auto recovered = LocalWorldFiles::open(root.path, identity, budget); + CHECK(recovered); + const auto commit = (*recovered)->current(); + CHECK(commit.has_value()); + const auto generation = commit.value_or(FileCommit{}).generation; + CHECK(generation == (point == PublicationInterruption::after_manifest_publish ? 2 : 1)); + CHECK((*recovered)->recover()); + } +} +void lock_and_corruption_fail_closed() { + TempRoot root; + auto first = LocalWorldFiles::open(root.path, identity, budget); + CHECK(first); + auto busy = LocalWorldFiles::open(root.path, identity, budget); + CHECK(!busy && busy.error() == LocalFileError::busy); + auto state = make_store(); + CHECK((*first)->checkpoint(*state)); + (*first).reset(); + auto reopened = LocalWorldFiles::open(root.path, identity, budget); + CHECK(reopened && (*reopened)->recover()); + const auto manifest = world_dir(root.path) / "manifest.0"; + { + std::fstream file(manifest, std::ios::binary | std::ios::in | std::ios::out); + CHECK(file); + file.seekp(40); + const char corrupt = '\x7f'; + file.write(&corrupt, 1); + } + (*reopened).reset(); + auto corrupt = LocalWorldFiles::open(root.path, identity, budget); + CHECK(!corrupt && corrupt.error() == LocalFileError::corrupt_manifest); +} +void missing_published_payload_fails_closed() { + TempRoot root; + std::uint64_t checksum{}; + { + auto files = LocalWorldFiles::open(root.path, identity, budget); + CHECK(files); + auto state = make_store(); + auto published = (*files)->checkpoint(*state); + CHECK(published); + checksum = published->snapshot_checksum; + } + const auto payload = world_dir(root.path) / ("snapshot-" + [&] { + constexpr char digits[] = "0123456789abcdef"; + std::string value(16, '0'); + for (int i = 15; i >= 0; --i) { + value[static_cast(i)] = digits[checksum & 15U]; + checksum >>= 4U; + } + return value; + }() + ".bin"); + std::error_code ec; + CHECK(std::filesystem::remove(payload, ec) && !ec); + auto files = LocalWorldFiles::open(root.path, identity, budget); + CHECK(files); + const auto recovered = (*files)->recover(); + CHECK(!recovered && recovered.error() == LocalFileError::corrupt_payload); +} +} // namespace + +int main() try { + checkpoint_and_journal_round_trip(); + interruptions_preserve_commit_point(); + lock_and_corruption_fail_closed(); + missing_published_payload_fails_closed(); +} catch (const std::exception&) { + return 1; +}