diff --git a/CMakeLists.txt b/CMakeLists.txt index 6d5408d..20003b0 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) -add_library(evo_world STATIC src/world/coordinates.cpp src/world/generation.cpp) +add_library(evo_world STATIC src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp) add_library(evo::world ALIAS evo_world) target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_compile_features(evo_world PUBLIC cxx_std_23) @@ -71,6 +71,12 @@ evo_owned_target(evo-sim) include(CTest) if(BUILD_TESTING) + add_executable(evo-world-chunk-tests tests/world_chunk_tests.cpp) + target_link_libraries(evo-world-chunk-tests PRIVATE evo::world) + evo_owned_target(evo-world-chunk-tests) + add_test(NAME world-chunk-contracts COMMAND evo-world-chunk-tests) + set_tests_properties(world-chunk-contracts PROPERTIES TIMEOUT 60) + add_executable(evo-world-generation-tests tests/world_generation_tests.cpp) target_link_libraries(evo-world-generation-tests PRIVATE evo::world) evo_owned_target(evo-world-generation-tests) diff --git a/README.md b/README.md index 7fed3b4..c5faade 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ network service. Dev verification manifests are separate from the simulation. - [Architecture decisions and proposals](docs/adr/README.md) - [Actionable milestones 0–4 and later gates](docs/ROADMAP.md) - [Open design questions](docs/architecture/OPEN_QUESTIONS.md) +- [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md) - [Versioned abiotic base generation](docs/world/BASE_GENERATION.md) - [Actual validation results](docs/engineering/VALIDATION.md) - [Current delivery status and next steps](docs/STATUS.md) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 2567bf1..6013fa1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -262,7 +262,9 @@ M5.2 is complete: [ADR-0043](adr/0043-chunk-layout.md) selects 16-cube uniform/palette/dense storage from the [comparison](engineering/CHUNK_LAYOUT_EVALUATION.md). M5.3 is complete under [ADR-0044](adr/0044-abiotic-generation.md): [versioned abiotic generation](world/BASE_GENERATION.md) with frozen reference fixtures. -Next is 5.4: bounded sparse active chunk ownership and compact resident storage. +M5.4 is complete under [ADR-0045](adr/0045-bounded-chunk-ownership.md): +[bounded ownership](world/CHUNK_OWNERSHIP.md), compact storage, validated revision tokens +and dirty eviction refusal. Next is 5.5: accounted transactional terrain edits. **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 088d7de..2953118 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 44 ADRs. + diagrams, biological contracts, engineering constitution and 45 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.4 sparse active chunk ownership | Bounded compact storage, regeneration, immutable revisioned views and dirty eviction refusal | +| 1 | M5.5 accounted terrain edits | Transaction identity, revisions, matter destinations, atomic changes and retry validation | | 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 | @@ -561,3 +561,10 @@ Added pure seed/address/version generation, a bounded inert material table and compatibility and storage boundaries. Twelve independent reference goldens and signed seam/query-order tests freeze v1. No gameplay, persistence or deployment was added. Next: M5.4 sparse active chunk ownership. + +## M5.4 bounded active chunk ownership + +Added fixed-slot, budgeted ChunkStore and immutable uniform/palette/dense CompactCells. +Revision tokens reject stale and foreign reads. Clean chunks regenerate; dirty pins +refuse eviction. [Ownership contract](world/CHUNK_OWNERSHIP.md) documents memory/lifetime +limits and the absence of cell edits or durability. Next: M5.5 accounted terrain edits. diff --git a/docs/adr/0045-bounded-chunk-ownership.md b/docs/adr/0045-bounded-chunk-ownership.md new file mode 100644 index 0000000..0cea460 --- /dev/null +++ b/docs/adr/0045-bounded-chunk-ownership.md @@ -0,0 +1,63 @@ +# ADR-0045: Bounded local chunk ownership + +## Status +Accepted for M5.4. Single local owner, not distributed region authority or durability. + +## Context +M5.3 produces reproducible base cells; ADR-0043 selects compact 16-cube storage. +Address extent must not drive allocation. Eviction must not lose pending dirty state. + +## Decision +Use a noncopyable/nonmovable ChunkStore created with a fixed slot count (1..4096), +byte budget and immutable BaseDescriptor. A fixed directory bounds metadata and +linear lookup; no implicit eviction, threads or global cache. Loading an absent +chunk regenerates base data. Existing loads are idempotent. Missing capacity returns +backpressure and leaves prior state unchanged. Allocation exceptions reach the host. + +CompactCells is an immutable value with uniform, byte-palette (<=256 distinct keys), +or dense representation. Keys include material and fill. Palette order is first +X-fast occurrence. Packed byte indexes share one exactly-sized uint32 array with +keys; this is an in-memory implementation, not a wire format. Uniform has no payload +allocation. Dense contains 4096 uint32 values. Build publishes only after success. + +Charge sizeof(store), all directory entries, owned payload bytes, and 17 KiB reserved +for construction scratch (4096 logical words plus 256 palette keys). Check budget +before allocating payload. Allocator headers/runtime stack/caller buffers are outside +this accounted budget; report it as accounted bytes, never RSS. Array element counts +are exact, no vector growth. The standalone compact factory is outside store budgets. + +Views contain owner, slot and monotonic incarnation/revision token; reads revalidate +before access and return copied cells, never dangling spans. Views must not outlive +their store. Store is immovable; foreign-store views fail. Successful load and first +dirty marking consume nonwrapping tokens; exhaustion rejects changes. Evict/reload +cannot revive an old view. Revision tokens are local, not durable edit revisions. + +mark_dirty is conservative pre-write pinning, changes no geometry and invalidates +old views. Repeated marking of the current dirty view is idempotent. There is no +mark-clean, overwrite, or edit API: M5.5 introduces accounted transactions; later +persistence must prove durable coverage before clearing dirty state. Explicit eviction +requires a current clean view. Destruction is a host shutdown boundary, not durable +storage; the host must not destroy a store with unsaved changes in a running world. + +## Alternatives Considered +Automatic LRU hides eviction decisions and requires pin lifetime accounting. +Shared snapshots can retain unbudgeted payloads. Raw spans invite dangling reads. +Maps complicate allocator accounting; linear fixed slots suffice for this bounded gate. + +## Benefits +Bounded metadata/payloads, reproducible regeneration and explicit stale/dirty refusal. +No edit or persistence shortcut leaks into the geometry library. + +## Costs +Linear lookup, reconstruction scratch reservation and copied point reads. No concurrent +mutation support, auto eviction, persistence or dirty recovery yet. + +## Risks +Accounted bytes exclude allocator overhead and are not an OS ceiling. Owner lifetime +is a caller obligation. Dirty pinning can exhaust capacity intentionally; host must +apply backpressure rather than dropping state. Larger workloads require measurement. + +## Consequences +Test far-apart chunks, uniform/palette/dense equality, exact budget boundaries, +slot exhaustion, invalid input, stale/foreign views and dirty eviction refusal. +Retain existing generator goldens and simulation formats. Next is M5.5. diff --git a/docs/adr/README.md b/docs/adr/README.md index 5869ea4..e21f6fa 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -47,3 +47,5 @@ design. No unadopted candidate is a link dependency of the proof. - [ADR-0043: Bounded chunk layout](0043-chunk-layout.md) - accepted for M5; 16-cube uniform/palette/dense geometry. - [ADR-0044: Abiotic generation](0044-abiotic-generation.md) - accepted for M5.3 synthetic integer base, version retention and material table. + +- [ADR-0045: Bounded chunk ownership](0045-bounded-chunk-ownership.md) - accepted for M5.4 local memory, revision tokens and dirty eviction guards. diff --git a/docs/architecture/WORLD_ARCHITECTURE.md b/docs/architecture/WORLD_ARCHITECTURE.md index 0d36ff5..d0287ca 100644 --- a/docs/architecture/WORLD_ARCHITECTURE.md +++ b/docs/architecture/WORLD_ARCHITECTURE.md @@ -124,3 +124,11 @@ chunk ownership/allocation limits remain M5.4; optional chemistry pages remain M 16-cube queries. Synthetic abiotic strata use global integer addresses and create no life. Unsupported versions fail explicitly. Temporary logical output is not resident storage; bounded chunk ownership/eviction is M5.4. There is no persistence or mesher. + +## Implemented M5.4 ownership boundary + +[ADR-0045](../adr/0045-bounded-chunk-ownership.md) adds compact immutable cells and a +fixed-slot, byte-budgeted local store. [The contract](../world/CHUNK_OWNERSHIP.md) +specifies construction scratch accounting, current-revision read tokens, regeneration +and dirty eviction refusal. No database, distributed lease or durable acknowledgement +is implied. Cell edits remain M5.5 and persistence M5.6/5.7. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index ee68ae2..deba519 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -1471,3 +1471,34 @@ stratigraphy, known/unknown materials, version/edge rejection and extreme addres Fingerprint bytes are explicitly little endian logical fields. Linux CI and UBSan were not run locally; no cross-platform execution result is claimed. No deployment or World0 state change occurred. Next: M5.4 bounded sparse chunk ownership. + +## M5.4 bounded chunk ownership - 2026-09-26 + +Added CompactCells, a fixed-slot ChunkStore, revision-validated read tokens and +conservative dirty pinning under ADR-0045. No cell edit, persistence, distributed +lease or clean acknowledgement API was introduced. Existing goldens remain unchanged. + +Executed on Windows x64 / MSVC 19.44: + +- `tools/windows-check.ps1 -Preset release -Action check`: 43/43 CTest passed. +- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 build and + 43/43 CTest passed. +- `tools/windows-check.ps1 -Preset asan -Action check`: 43/43 CTest passed. +- `tools/windows-check.ps1 -Preset release -Action format`: passed. +- `git diff --check`: passed. + +The initial test oracle mixed unsigned local offsets with a negative integer literal; +corrected to explicit int64 arithmetic. Analysis required explicit optional checks +at reads/eviction and identified an integer-width expression in the test. One narrow +use-after-move suppression exercises the explicitly guaranteed empty-void source. +Final checks above ran after those corrections. + +Coverage includes palette counts through 256 then dense fallback, full logical cell +equality, material/fill distinctions, move validity, extreme/far addresses, exact +accounted budget boundaries, failed-load state preservation, slot pressure, clean +regeneration, stale/foreign tokens and dirty eviction refusal. Counter exhaustion is +guarded but not injected; no allocation-failure fault injector is claimed. Memory +accounting excludes allocator/runtime overhead and is not an RSS cap. + +Linux CI/UBSan and target-host performance have not been run locally. No deployment +or World0 change occurred. Next: M5.5 accounted transactional edits. diff --git a/docs/world/CHUNK_OWNERSHIP.md b/docs/world/CHUNK_OWNERSHIP.md new file mode 100644 index 0000000..0b99f9b --- /dev/null +++ b/docs/world/CHUNK_OWNERSHIP.md @@ -0,0 +1,89 @@ +# M5.4 bounded active chunks + +Implemented by `evo::world`, header `evo/world/chunks.hpp`. +[ADR-0045](../adr/0045-bounded-chunk-ownership.md) scopes local ownership; this is +not a region lease, distributed authority mechanism or durable store. + +## Contract + +Create a store with one immutable BaseDescriptor, 1..4096 slots and an explicit +accounted-byte budget. All operations are single-owner/sequential; callers must not +race reads against mutation. World/frame identity belongs to the containing host. +Different stores are separate local domains; revision numbers are not globally unique. +The owning unique_ptr may move, but the store itself cannot move or copy. + +| Operation | Success | Refusal / invariant | +|---|---|---| +| minimum_bytes(slots) | Store object + fixed directory + 17 KiB scratch reservation | Invalid slot count rejected before multiplication | +| create | Empty store with validated descriptor | Invalid config/version/budget before directory allocation | +| load(address) | Return current token or regenerate and publish one base chunk | Invalid address, slot or byte exhaustion, revision exhaustion; no existing state changes | +| view(address) | Token for loaded address | Missing is explicit; no implicit load | +| read(view, local) | Copy one CellSample | Foreign/stale token or out-of-range local cell; no raw storage pointer | +| mark_dirty(view) | Pin chunk, invalidate previous token, return current token | Stale token or revision exhaustion; repeat on current dirty token is idempotent | +| evict(view) | Free clean payload and directory slot | Stale or dirty token rejected; no auto eviction | + +Views contain owner/slot/revision internally. They are read tokens, not immutable +historical snapshots: every read checks current ownership and revision. Old tokens +fail after dirty marking or eviction/reload. They must not outlive the store, including +an object later allocated at the same address. They cannot authorize persistence or +cross-process operations. Epoch exhaustion is checked before increment; no wraparound. + +Dirty marking currently changes only lifecycle metadata, not geometry. There is no +clear-dirty or cell-edit API. M5.5 must introduce accounted edit transactions; M5.6/5.7 +must establish durable revision coverage before permitting cleanup. Destruction at +host shutdown frees memory and is not a save operation. No production host should +use this in-memory store as its sole durable copy of changes. + +```mermaid +stateDiagram-v2 + Absent --> Clean: load, budget available + Clean --> Absent: explicit current-view eviction + Clean --> Dirty: conservative pin, new revision + Dirty --> Dirty: repeated current-view pin +``` + +Dirty-to-Absent is deliberately unavailable. Capacity pressure returns to the host. +It cannot regenerate modified data to make room. + +## Representation and budgets + +CompactCells accepts exactly 4096 validated CellSample values. It is immutable and +move-only; moves reset the source to uniform void. Material keys and fills both +participate in equality. This geometry utility checks structural cells, not material +table membership or resource authority. ChunkStore loads only M5.3 table-valid base. + +- Uniform: one inline word, zero allocated payload bytes. +- Palette: first-occurrence keys (2..256), plus 4096 byte indexes, stored as keys + followed by 1024 packed uint32 index words. Payload = 4*K+4096 bytes. +- Dense: 4096 uint32 words = 16384 bytes after the 257th distinct key. + +Logical words combine material low 16 bits and fill high 16 bits. Native arrays are +not a wire format. M5.6 must specify canonical serialization independently. + +Fixed directory bytes include optional payload objects and lifecycle metadata for +all configured slots, occupied or not. Accounted bytes add exact allocated payload +array element sizes plus a permanent 17 KiB allowance for load construction scratch: +4096 logical words and 256 palette keys. Load generates through point queries to avoid +an extra dense vector, computes required payload before allocation, then publishes +without throwing. On allocator failure existing state is unchanged; allocation +exceptions propagate to the host. Clean eviction subtracts payload only. + +The allowance remains charged when no load runs. Allocator headers/cookies, ordinary +call frames, caller buffers and OS runtime are excluded: this is not RSS or an OS +memory cap. Standalone CompactCells creation is outside a store's budget. It uses the +same bounded scratch plus output, with no budget parameter. Future replacement/edit +operations must budget old and new buffers simultaneously; they cannot inherit a +claim of in-place promotion from this immutable implementation. + +## Verification and next boundary + +CTest `world-chunk-contracts` checks distinct counts 1/2/255/256/257/4096, every stored +sample, material/fill distinction, invalid lengths/indexes, moved-from validity, +far-apart addresses, clean regeneration, slot and byte backpressure, stale and foreign +tokens, conservative dirty pinning and rejection without changing resident state. +Existing generator goldens remain active. Counter exhaustion is guarded in code but +not forced via a public test-only state injection API. + +M5.5 adds transaction IDs, payload identity, expected revisions, material destinations +and atomic edits. No transactional edit, snapshot, crash recovery, threading, automatic +LRU, renderer or Kubernetes integration is provided by M5.4. diff --git a/include/evo/world/chunks.hpp b/include/evo/world/chunks.hpp new file mode 100644 index 0000000..bd11b18 --- /dev/null +++ b/include/evo/world/chunks.hpp @@ -0,0 +1,102 @@ +#pragma once +#include "evo/world/generation.hpp" +#include +#include +#include +#include +#include + +namespace evo::world { +enum class ChunkError : std::uint8_t { + invalid_config, + invalid_descriptor, + invalid_address, + invalid_cells, + capacity, + memory_budget, + missing, + stale_view, + invalid_local, + dirty, + revision_exhausted +}; +enum class CellLayout : std::uint8_t { uniform, palette, dense }; +class ChunkStore; +// Immutable owned geometry. Construction does not authorize a terrain edit. +class CompactCells { + public: + // Moves reset the source to a readable uniform void chunk. + CompactCells(CompactCells&& other) noexcept; + CompactCells& operator=(CompactCells&& other) noexcept; + CompactCells(const CompactCells&) = delete; + CompactCells& operator=(const CompactCells&) = delete; + [[nodiscard]] static std::expected + create(std::span cells); + [[nodiscard]] std::expected read(std::uint32_t index) const noexcept; + [[nodiscard]] std::size_t payload_bytes() const noexcept; + [[nodiscard]] CellLayout layout() const noexcept { + return layout_; + } + + private: + friend class ChunkStore; + CompactCells() = default; + static std::size_t required_bytes(std::span words) noexcept; + static CompactCells encode(std::span words); + CellLayout layout_{CellLayout::uniform}; + std::uint32_t uniform_{}; + std::uint32_t keys_{}; + std::unique_ptr data_; +}; +// Non-owning token; must not outlive the issuing store. Never exposes storage pointers. +class ChunkView { + public: + [[nodiscard]] std::uint64_t revision() const noexcept { + return revision_; + } + + private: + friend class ChunkStore; + ChunkView(const ChunkStore* owner, std::size_t slot, std::uint64_t revision) + : owner_{owner}, slot_{slot}, revision_{revision} {} + const ChunkStore* owner_; + std::size_t slot_; + std::uint64_t revision_; +}; +class ChunkStore { + public: + static constexpr std::size_t max_slots = 4096; + static constexpr std::size_t scratch_bytes = (4096 + 256) * sizeof(std::uint32_t); + [[nodiscard]] static std::expected, ChunkError> + create(BaseDescriptor descriptor, std::size_t slots, std::size_t byte_budget); + ChunkStore(const ChunkStore&) = delete; + ChunkStore& operator=(const ChunkStore&) = delete; + ChunkStore(ChunkStore&&) = delete; + ChunkStore& operator=(ChunkStore&&) = delete; + ~ChunkStore(); + [[nodiscard]] static std::expected + minimum_bytes(std::size_t slots) noexcept; + [[nodiscard]] std::expected load(ChunkAddress address); + [[nodiscard]] std::expected view(ChunkAddress address) const noexcept; + [[nodiscard]] std::expected read(ChunkView view, + LocalCell local) const noexcept; + // Conservative pin only: no geometry edit or durability acknowledgement. + [[nodiscard]] std::expected mark_dirty(ChunkView view) noexcept; + [[nodiscard]] std::expected evict(ChunkView view) noexcept; + [[nodiscard]] std::size_t accounted_bytes() const noexcept { + return bytes_; + } + [[nodiscard]] std::size_t size() const noexcept { + return size_; + } + + private: + struct Entry; + ChunkStore(BaseDescriptor descriptor, std::size_t slots, std::size_t budget, std::size_t bytes); + [[nodiscard]] bool current(ChunkView view) const noexcept; + BaseDescriptor descriptor_; + std::size_t slots_, budget_, bytes_, size_{}; + std::uint64_t revision_{}; + std::unique_ptr entries_; +}; +} // namespace evo::world diff --git a/src/world/chunks.cpp b/src/world/chunks.cpp new file mode 100644 index 0000000..44d8cd8 --- /dev/null +++ b/src/world/chunks.cpp @@ -0,0 +1,233 @@ +#include "evo/world/chunks.hpp" +#include +#include +#include +#include +#include + +namespace evo::world { +namespace { +std::uint32_t pack(CellSample cell) noexcept { + return cell.material().value | (static_cast(cell.fill()) << 16U); +} +// 257 signals dense fallback. Caller always supplies exactly 4096 valid words. +std::uint32_t collect(std::span words, + std::array& keys) noexcept { + std::uint32_t count = 0; + for (const auto word : words) { + const auto end = keys.begin() + count; + if (std::find(keys.begin(), end, word) == end) { + if (count == 256) { + return 257; + } + keys[count++] = word; + } + } + return count; +} +} // namespace +CompactCells::CompactCells(CompactCells&& other) noexcept { + *this = std::move(other); +} +CompactCells& CompactCells::operator=(CompactCells&& other) noexcept { + if (this != &other) { + layout_ = std::exchange(other.layout_, CellLayout::uniform); + uniform_ = std::exchange(other.uniform_, 0); + keys_ = std::exchange(other.keys_, 0); + data_ = std::move(other.data_); + } + return *this; +} +std::size_t CompactCells::required_bytes(std::span words) noexcept { + std::array keys{}; + const auto count = collect(words, keys); + if (count == 1) { + return 0; + } + return (count > 256 ? 4096 : 1024 + static_cast(count)) * sizeof(std::uint32_t); +} +CompactCells CompactCells::encode(std::span words) { + std::array keys{}; + const auto count = collect(words, keys); + CompactCells result; + if (count == 1) { + result.uniform_ = keys[0]; + } else if (count > 256) { + result.layout_ = CellLayout::dense; + result.data_ = std::make_unique(4096); + std::copy(words.begin(), words.end(), result.data_.get()); + } else { + result.layout_ = CellLayout::palette; + result.keys_ = count; + result.data_ = std::make_unique(1024 + static_cast(count)); + std::copy_n(keys.begin(), count, result.data_.get()); + for (std::size_t i = 0; i < words.size(); ++i) { + const auto key = static_cast( + std::find(keys.begin(), keys.begin() + count, words[i]) - keys.begin()); + result.data_[count + i / 4] |= key << ((i % 4) * 8); + } + } + return result; +} +std::expected CompactCells::create(std::span cells) { + if (cells.size() != base_chunk_cells) { + return std::unexpected{ChunkError::invalid_cells}; + } + std::array words{}; + std::transform(cells.begin(), cells.end(), words.begin(), pack); + return encode(words); +} +std::size_t CompactCells::payload_bytes() const noexcept { + if (layout_ == CellLayout::uniform) { + return 0; + } + return (layout_ == CellLayout::dense ? 4096 : 1024 + static_cast(keys_)) * + sizeof(std::uint32_t); +} +std::expected CompactCells::read(std::uint32_t index) const noexcept { + if (index >= base_chunk_cells) { + return std::unexpected{ChunkError::invalid_local}; + } + auto word = uniform_; + if (layout_ == CellLayout::dense) { + word = data_[index]; + } + if (layout_ == CellLayout::palette) { + const auto key = (data_[keys_ + index / 4] >> ((index % 4) * 8)) & 255U; + word = data_[key]; + } + return *CellSample::create({static_cast(word & 65535U)}, word >> 16U); +} +struct ChunkStore::Entry { + ChunkAddress address{}; + std::optional cells; + std::uint64_t revision{}; + bool dirty{}; +}; +ChunkStore::ChunkStore(BaseDescriptor descriptor, std::size_t slots, std::size_t budget, + std::size_t bytes) + : descriptor_{descriptor}, slots_{slots}, budget_{budget}, bytes_{bytes}, + entries_{std::make_unique(slots)} {} +ChunkStore::~ChunkStore() = default; +std::expected ChunkStore::minimum_bytes(std::size_t slots) noexcept { + if (slots == 0 || slots > max_slots) { + return std::unexpected{ChunkError::invalid_config}; + } + return sizeof(ChunkStore) + slots * sizeof(Entry) + scratch_bytes; +} +std::expected, ChunkError> +ChunkStore::create(BaseDescriptor descriptor, std::size_t slots, std::size_t budget) { + const auto minimum = minimum_bytes(slots); + if (!minimum) { + return std::unexpected{minimum.error()}; + } + if (!base_sample(descriptor, {})) { + return std::unexpected{ChunkError::invalid_descriptor}; + } + if (budget < *minimum) { + return std::unexpected{ChunkError::memory_budget}; + } + return std::unique_ptr{new ChunkStore(descriptor, slots, budget, *minimum)}; +} +bool ChunkStore::current(ChunkView v) const noexcept { + return v.owner_ == this && v.slot_ < slots_ && entries_[v.slot_].cells && + entries_[v.slot_].revision == v.revision_; +} +std::expected ChunkStore::view(ChunkAddress address) const noexcept { + if (!join({address, {}}, base_chunk_edge)) { + return std::unexpected{ChunkError::invalid_address}; + } + for (std::size_t i = 0; i < slots_; ++i) { + if (entries_[i].cells && entries_[i].address == address) { + return ChunkView{this, i, entries_[i].revision}; + } + } + return std::unexpected{ChunkError::missing}; +} +std::expected ChunkStore::load(ChunkAddress address) { + const auto existing = view(address); + if (existing) { + return existing; + } + if (existing.error() != ChunkError::missing) { + return std::unexpected{existing.error()}; + } + if (size_ == slots_) { + return std::unexpected{ChunkError::capacity}; + } + if (revision_ == std::numeric_limits::max()) { + return std::unexpected{ChunkError::revision_exhausted}; + } + std::array words{}; + const auto origin = *join({address, {}}, base_chunk_edge); + for (std::uint32_t i = 0; i < base_chunk_cells; ++i) { + const auto local = *local_from_ordinal(i, base_chunk_edge); + words[i] = pack(*base_sample(descriptor_, + {origin.x + local.x, origin.y + local.y, origin.z + local.z})); + } + const auto payload = CompactCells::required_bytes(words); + if (payload > budget_ - bytes_) { + return std::unexpected{ChunkError::memory_budget}; + } + auto cells = CompactCells::encode(words); // All fallible allocation precedes publication. + for (std::size_t i = 0; i < slots_; ++i) { + auto& entry = entries_[i]; + if (!entry.cells) { + entry.address = address; + entry.cells.emplace(std::move(cells)); + entry.revision = ++revision_; + entry.dirty = false; + bytes_ += payload; + ++size_; + return ChunkView{this, i, entry.revision}; + } + } + return std::unexpected{ChunkError::capacity}; +} +std::expected ChunkStore::read(ChunkView v, + LocalCell local) const noexcept { + if (!current(v)) { + return std::unexpected{ChunkError::stale_view}; + } + const auto i = ordinal(local, base_chunk_edge); + if (!i) { + return std::unexpected{ChunkError::invalid_local}; + } + const auto& cells = entries_[v.slot_].cells; + if (!cells) { + return std::unexpected{ChunkError::stale_view}; + } + return cells->read(*i); +} +std::expected ChunkStore::mark_dirty(ChunkView v) noexcept { + if (!current(v)) { + return std::unexpected{ChunkError::stale_view}; + } + auto& entry = entries_[v.slot_]; + if (entry.dirty) { + return v; + } + if (revision_ == std::numeric_limits::max()) { + return std::unexpected{ChunkError::revision_exhausted}; + } + entry.dirty = true; + entry.revision = ++revision_; + return ChunkView{this, v.slot_, entry.revision}; +} +std::expected ChunkStore::evict(ChunkView v) noexcept { + if (!current(v)) { + return std::unexpected{ChunkError::stale_view}; + } + auto& entry = entries_[v.slot_]; + if (entry.dirty) { + return std::unexpected{ChunkError::dirty}; + } + if (!entry.cells) { + return std::unexpected{ChunkError::stale_view}; + } + bytes_ -= entry.cells->payload_bytes(); + entry.cells.reset(); + --size_; + return {}; +} +} // namespace evo::world diff --git a/tests/world_chunk_tests.cpp b/tests/world_chunk_tests.cpp new file mode 100644 index 0000000..5b694bf --- /dev/null +++ b/tests/world_chunk_tests.cpp @@ -0,0 +1,181 @@ +#include "evo/world/chunks.hpp" +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +using namespace evo::world; +void check(bool condition, std::source_location at = std::source_location::current()) { + if (!condition) { + throw std::runtime_error("world chunk line " + std::to_string(at.line())); + } +} +#define CHECK(...) check(static_cast(__VA_ARGS__)) +template bool refused(const std::expected& r, ChunkError e) { + return !r && r.error() == e; +} +CellSample cell(std::uint16_t id, std::uint32_t fill) { + const auto result = CellSample::create({id}, fill); + CHECK(result); + return *result; +} +void compact_layouts() { + for (const auto count : {1U, 2U, 255U, 256U, 257U, 4096U}) { + std::vector input; + input.reserve(4096); + for (std::uint32_t i = 0; i < 4096; ++i) { + // Same material, distinct fill: palette identity must include both. + input.push_back(cell(1, 1 + i % count)); + } + auto compact = CompactCells::create(input); + CHECK(compact); + CHECK(compact->layout() == (count == 1 + ? CellLayout::uniform + : (count > 256 ? CellLayout::dense : CellLayout::palette))); + CHECK(compact->payload_bytes() == + (count == 1 ? 0 : (count > 256 ? 16384 : 4096 + 4 * count))); + for (std::uint32_t i = 0; i < 4096; ++i) { + const auto value = compact->read(i); + CHECK(value && *value == input[i]); + } + CHECK(refused(compact->read(4096), ChunkError::invalid_local)); + CHECK(refused(compact->read(std::numeric_limits::max()), + ChunkError::invalid_local)); + auto moved = std::move(*compact); + CHECK(compact->payload_bytes() == 0 && compact->read(0)->material().value == 0); + CHECK(moved.read(4095) && *moved.read(4095) == input[4095]); + *compact = std::move(moved); + // Explicitly test the documented empty-void moved-from guarantee. + // NOLINTNEXTLINE(bugprone-use-after-move) + CHECK(moved.payload_bytes() == 0 && moved.read(0)->fill() == 0); + CHECK(*compact->read(0) == input[0]); + } + std::vector empty; + CHECK(refused(CompactCells::create(empty), ChunkError::invalid_cells)); + empty.assign(4097, cell(0, 0)); + CHECK(refused(CompactCells::create(empty), ChunkError::invalid_cells)); + empty.resize(4096, cell(0, 0)); + auto uniform = CompactCells::create(empty); + CHECK(uniform && uniform->layout() == CellLayout::uniform && uniform->payload_bytes() == 0); + // Distinct material identities must survive, even with identical fill. + for (std::uint32_t i = 0; i < 4096; ++i) { + empty[i] = cell(static_cast(1 + i % 3), 65535); + } + const auto materials = CompactCells::create(empty); + CHECK(materials && materials->layout() == CellLayout::palette); + for (std::uint32_t i = 0; i < 4096; ++i) { + CHECK(*materials->read(i) == empty[i]); + } +} +void bounded_store() { + const auto minimum = ChunkStore::minimum_bytes(2); + CHECK(minimum); + auto made = ChunkStore::create({73}, 2, *minimum + 32768); + CHECK(made); + auto& store = **made; + CHECK(store.size() == 0 && store.accounted_bytes() == *minimum); + CHECK(refused(store.view({}), ChunkError::missing)); + const auto a = store.load({-1, 0, -1}); + CHECK(a); + const auto first_bytes = store.accounted_bytes(); + const auto same = store.load({-1, 0, -1}); + CHECK(same && same->revision() == a->revision() && store.accounted_bytes() == first_bytes); + const auto b = store.load({65535, -65536, 65535}); + CHECK(b); + CHECK(store.size() == 2 && store.accounted_bytes() == first_bytes); // far uniform void + CHECK(refused(store.load({7, 8, 9}), ChunkError::capacity)); + for (std::uint32_t i = 0; i < 4096; ++i) { + const auto local = *local_from_ordinal(i, 16); + const auto expected = + base_sample({73}, {std::int64_t{-16} + local.x, local.y, std::int64_t{-16} + local.z}); + const auto actual = store.read(*a, local); + CHECK(expected && actual && *expected == *actual); + } + CHECK(refused(store.read(*a, {16, 0, 0}), ChunkError::invalid_local)); + CHECK(store.evict(*a)); + CHECK(refused(store.read(*a, {}), ChunkError::stale_view)); + CHECK(refused(store.evict(*a), ChunkError::stale_view)); + CHECK(refused(store.mark_dirty(*a), ChunkError::stale_view)); + const auto reloaded = store.load({-1, 0, -1}); + CHECK(reloaded); + CHECK(reloaded->revision() != a->revision()); + CHECK(refused(store.read(*a, {}), ChunkError::stale_view)); + CHECK(store.accounted_bytes() == first_bytes); + CHECK(*store.read(*reloaded, {0, 0, 0}) == *base_sample({73}, {-16, 0, -16})); + const auto dirty = store.mark_dirty(*reloaded); + CHECK(dirty); + CHECK(refused(store.read(*reloaded, {}), ChunkError::stale_view)); + CHECK(refused(store.evict(*dirty), ChunkError::dirty)); + CHECK(store.read(*dirty, {})); + const auto repeated = store.mark_dirty(*dirty); + CHECK(repeated && repeated->revision() == dirty->revision()); + CHECK(store.size() == 2 && store.accounted_bytes() == first_bytes); + auto other = ChunkStore::create({73}, 2, *minimum + 32768); + CHECK(other); + CHECK(refused((*other)->read(*dirty, {}), ChunkError::stale_view)); + CHECK(refused((*other)->evict(*dirty), ChunkError::stale_view)); + CHECK(refused((*other)->mark_dirty(*dirty), ChunkError::stale_view)); + // Dirty state here is only a test pin, no modified geometry is discarded. +} +void budgets_and_rejection() { + using E = ChunkError; + CHECK(refused(ChunkStore::minimum_bytes(0), E::invalid_config)); + CHECK(refused(ChunkStore::minimum_bytes(std::numeric_limits::max()), + E::invalid_config)); + const auto minimum = *ChunkStore::minimum_bytes(3); + CHECK(refused(ChunkStore::create({}, 3, minimum - 1), E::memory_budget)); + BaseDescriptor invalid{}; + invalid.generator_version = 2; + CHECK(refused(ChunkStore::create(invalid, 3, minimum), E::invalid_descriptor)); + auto created = ChunkStore::create({}, 3, minimum); + CHECK(created); + auto& store = **created; + const auto uniform = store.load({1000, -1000, 1000}); + CHECK(uniform); + CHECK(store.accounted_bytes() == minimum); + CHECK(refused(store.load({0, 0, 0}), E::memory_budget)); + CHECK(store.size() == 1 && store.accounted_bytes() == minimum && store.read(*uniform, {})); + CHECK(refused(store.view({0, 0, 0}), E::missing)); + const auto base = generate_base_chunk({}, {}); + CHECK(base); + const auto compact = CompactCells::create(*base); + CHECK(compact); + const auto needed = compact->payload_bytes(); + CHECK(needed > 0); + auto exact = ChunkStore::create({}, 3, minimum + needed); + CHECK(exact); + const auto at = (*exact)->load({}); + CHECK(at); + CHECK((*exact)->accounted_bytes() == minimum + needed); + CHECK(refused((*exact)->load({1, 0, 0}), E::memory_budget)); + CHECK((*exact)->evict(*at)); + CHECK((*exact)->accounted_bytes() == minimum); + CHECK((*exact)->load({1, 0, 0})); + constexpr auto low = std::numeric_limits::min(); + constexpr auto high = std::numeric_limits::max(); + for (const auto bad : std::array{low, high, -65537, 65536}) { + for (const auto addr : + {ChunkAddress{bad, 0, 0}, ChunkAddress{0, bad, 0}, ChunkAddress{0, 0, bad}}) { + CHECK(refused(store.load(addr), E::invalid_address)); + CHECK(refused(store.view(addr), E::invalid_address)); + } + } + CHECK(store.size() == 1 && store.accounted_bytes() == minimum); +} +} // namespace +int main() try { + compact_layouts(); + bounded_store(); + budgets_and_rejection(); + return 0; +} catch (const std::exception& e) { + std::fprintf(stderr, "%s\n", e.what()); + return 1; +} catch (...) { + return 1; +}