Files
dingoandClaude Opus 5.5 feca07f791 Implement M9.4 revision-tagged microscopic environment rendering
Add SDL-free owned EnvironmentPresentation copied from M6.3 views (no
store pointers or validation tokens), a single-slot EnvironmentLayer that
rejects foreign/regressed updates and reports none/current/stale against
observed authority watermarks, and a bounded camera projection with
explicit missing, not-requested, present-zero, undefined-moisture and
stale encodings (at most 2313 clipped rectangles, reused buffer).

The engineering app renders a local in-memory fixture authority with
configurable refresh cadence and layer selection. ADR-0080 records the
decision; validation evidence and limits are in VALIDATION.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 17:45:53 -04:00

103 lines
4.3 KiB
C++

#pragma once
#include "evo/world/environment.hpp"
#include <array>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <optional>
#include <span>
#include <vector>
namespace evo::client {
inline constexpr std::size_t max_environment_cells = world::max_environment_footprint;
// Authority revision a presentation was copied from. Not a capability or session grant.
struct EnvironmentRevision {
world::WorldIdentity identity;
std::uint64_t tick{}, field_revision{};
auto operator<=>(const EnvironmentRevision&) const = default;
};
enum class FieldPresence : std::uint8_t { not_requested, missing, present };
// Copied presentation values for one habitat in the selected Z slice. Public aggregates
// are unvalidated input; EnvironmentPresentation::create validates them.
struct EnvironmentCell {
world::VoxelAddress voxel;
std::uint64_t chunk_revision{};
world::HabitatBox habitat{};
world::CubicMicrometres volume{};
world::MaterialId substrate, terrain_material;
std::uint16_t terrain_fill{};
std::array<FieldPresence, world::field_count> presence{};
// Femtograms for mass fields, picojoules for energy fields; zero unless present.
std::array<std::uint64_t, world::field_count> quantity{};
world::MoistureStatus moisture_status{world::MoistureStatus::not_requested};
world::WaterSaturation moisture{}; // Meaningful only when moisture_status is available.
};
enum class ViewError : std::uint8_t {
invalid_view,
empty_slice,
too_many_cells,
foreign_world,
regressed
};
// Immutable owned copy; never retains world stores, chunk tokens or native handles.
class EnvironmentPresentation {
public:
[[nodiscard]] static std::expected<EnvironmentPresentation, ViewError>
create(EnvironmentRevision revision, std::uint32_t requested_mask, std::int64_t slice_z,
std::span<const EnvironmentCell> cells);
[[nodiscard]] EnvironmentRevision revision() const noexcept {
return revision_;
}
[[nodiscard]] std::uint32_t requested_mask() const noexcept {
return mask_;
}
[[nodiscard]] std::int64_t slice_z() const noexcept {
return slice_z_;
}
// Strictly ordered by voxel (x, then y), all at slice_z.
[[nodiscard]] std::span<const EnvironmentCell> cells() const noexcept {
return cells_;
}
private:
EnvironmentPresentation(EnvironmentRevision revision, std::uint32_t mask, std::int64_t z,
std::span<const EnvironmentCell> cells)
: revision_{revision}, mask_{mask}, slice_z_{z}, cells_(cells.begin(), cells.end()) {}
EnvironmentRevision revision_;
std::uint32_t mask_;
std::int64_t slice_z_;
std::vector<EnvironmentCell> cells_;
};
// Copies the samples at slice_z from a local M6.3 view. Reads only; the view's
// validation tokens and store identities are not copied.
[[nodiscard]] std::expected<EnvironmentPresentation, ViewError>
present_environment(const world::EnvironmentView& view, std::int64_t slice_z);
enum class Freshness : std::uint8_t { none, current, stale };
// Latest accepted presentation plus the newest authority revision observed.
// Bounded to one presentation; no history or update queue.
class EnvironmentLayer {
public:
// Rejects a different world/frame or any regression of tick, field revision or a
// shared voxel's chunk revision. Equal revisions are accepted (e.g. a new footprint).
[[nodiscard]] std::expected<void, ViewError> accept(EnvironmentPresentation next);
// Records that the authority has reached `latest` (also before any presentation);
// the presentation is stale while it differs from the newest observed revision.
// A different world/frame or a regressed revision rejects without mutation.
[[nodiscard]] std::expected<void, ViewError> observe(EnvironmentRevision latest);
// Host evidence (e.g. failed local validation) that the presentation is out of date.
void mark_stale() noexcept;
// Required after restore/reconnect to a different authority lineage.
void reset() noexcept;
[[nodiscard]] const EnvironmentPresentation* current() const noexcept {
return current_ ? &*current_ : nullptr;
}
[[nodiscard]] Freshness freshness() const noexcept;
private:
std::optional<EnvironmentPresentation> current_;
std::optional<EnvironmentRevision> latest_;
bool stale_{};
};
} // namespace evo::client