movement.h

#pragma once
 
#include <tess/core/shape.h>
#include <tess/storage/chunk_meta.h>
#include <tess/storage/residency.h>
#include <tess/topology/movement_class.h>
#include <tess/topology/transition_model.h>
 
#include <cstddef>
#include <cstdint>
#include <optional>
#include <type_traits>
 
namespace tess {

enum class MovementStatus : std::uint8_t {
  Moved,
  InvalidFrom,
  InvalidTo,
  NotAdjacent,
  ImpassableFrom,
  ImpassableTo,
  Blocked,
  Occupied,
  Reserved,
  StaleContent,
  StaleTopology,
};
static_assert(sizeof(MovementStatus) == sizeof(std::uint8_t));

struct MovementVersionCheck {
  std::optional<ContentVersion> from_content_version;
  std::optional<ContentVersion> to_content_version;
  std::optional<TopologyVersion> from_topology_version;
  std::optional<TopologyVersion> to_topology_version;
};

struct MovementIntent {
  Coord3 from{};
  Coord3 to{};
  MovementVersionCheck versions{};
};

struct MovementResult {
  MovementStatus status = MovementStatus::Moved;
  Coord3 from{};
  Coord3 to{};
};

struct MovementFailureCounts {
  std::size_t invalid = 0;
  std::size_t impassable = 0;
  std::size_t blocked = 0;
  std::size_t occupied = 0;
  std::size_t reserved = 0;
  std::size_t stale_content = 0;
  std::size_t stale_topology = 0;
};

inline void record_movement_failure(MovementFailureCounts& counts,
                                    MovementStatus status) noexcept {
  switch (status) {
    case MovementStatus::Moved:
      return;
    case MovementStatus::InvalidFrom:
    case MovementStatus::InvalidTo:
    case MovementStatus::NotAdjacent:
      ++counts.invalid;
      return;
    case MovementStatus::ImpassableFrom:
    case MovementStatus::ImpassableTo:
      ++counts.impassable;
      return;
    case MovementStatus::Blocked:
      ++counts.blocked;
      return;
    case MovementStatus::Occupied:
      ++counts.occupied;
      return;
    case MovementStatus::Reserved:
      ++counts.reserved;
      return;
    case MovementStatus::StaleContent:
      ++counts.stale_content;
      return;
    case MovementStatus::StaleTopology:
      ++counts.stale_topology;
      return;
  }
}
 
// Transient failures describe a world state that can legitimately change
// under a routed agent (another agent passing through, a fresh wall, a
// stale content-version guard), so retrying may succeed. How to retry
// splits by cause. Occupancy and reservation failures should retry the
// retained step: path passability deliberately ignores both, so a fresh
// search returns the same route. The rest invalidate the route and need
// a new search before movement can resume. The remaining failures
// (invalid endpoints, non-adjacent steps) indicate a caller bug and are
// terminal.
[[nodiscard]] constexpr auto is_transient_movement_failure(
    MovementStatus status) noexcept -> bool {
  switch (status) {
    case MovementStatus::ImpassableFrom:
    case MovementStatus::ImpassableTo:
    case MovementStatus::Blocked:
    case MovementStatus::Occupied:
    case MovementStatus::Reserved:
    case MovementStatus::StaleContent:
    case MovementStatus::StaleTopology:
      return true;
    case MovementStatus::Moved:
    case MovementStatus::InvalidFrom:
    case MovementStatus::InvalidTo:
    case MovementStatus::NotAdjacent:
      return false;
  }
  return false;
}
 
namespace detail {
 
[[nodiscard]] inline auto movement_versions_match_meta(
    const ChunkMeta& from_meta, const ChunkMeta& to_meta,
    const MovementVersionCheck& versions) noexcept -> MovementStatus {
  if (versions.from_content_version.has_value() &&
      from_meta.content_version != *versions.from_content_version) {
    return MovementStatus::StaleContent;
  }
  if (versions.to_content_version.has_value() &&
      to_meta.content_version != *versions.to_content_version) {
    return MovementStatus::StaleContent;
  }
  if (versions.from_topology_version.has_value() &&
      from_meta.topology_version != *versions.from_topology_version) {
    return MovementStatus::StaleTopology;
  }
  if (versions.to_topology_version.has_value() &&
      to_meta.topology_version != *versions.to_topology_version) {
    return MovementStatus::StaleTopology;
  }
  return MovementStatus::Moved;
}
 
[[nodiscard]] constexpr auto has_version_expectations(
    const MovementVersionCheck& versions) noexcept -> bool {
  return versions.from_content_version.has_value() ||
         versions.to_content_version.has_value() ||
         versions.from_topology_version.has_value() ||
         versions.to_topology_version.has_value();
}
 
}  // namespace detail

template <typename World>
[[nodiscard]] auto movement_versions_match(const World& world,
                                           MovementIntent intent) noexcept
    -> MovementStatus {
  if constexpr (std::is_same_v<typename World::residency_type,
                               SparseResident>) {
    // A non-resident chunk has no content-version snapshot to compare against;
    // treat it as stale so the move is rejected rather than reading meta()
    // out of bounds. This holds even with no expectations set, so the
    // fast path below cannot change sparse semantics.
    const auto from = world.resolve(intent.from);
    const auto to = world.resolve(intent.to);
    if (!world.is_resident(from.chunk_key) ||
        !world.is_resident(to.chunk_key)) {
      return MovementStatus::StaleContent;
    }
    if (!detail::has_version_expectations(intent.versions)) {
      return MovementStatus::Moved;
    }
    return detail::movement_versions_match_meta(
        world.meta(from.chunk_key), world.meta(to.chunk_key), intent.versions);
  } else {
    // The movement-scheduler path submits intents with no content-version
    // expectations at all; resolving both endpoints and reading two metas
    // just to compare nothing is unnecessary per-step work.
    if (!detail::has_version_expectations(intent.versions)) {
      return MovementStatus::Moved;
    }
    const auto from = world.resolve(intent.from);
    const auto to = world.resolve(intent.to);
    return detail::movement_versions_match_meta(
        world.meta(from.chunk_key), world.meta(to.chunk_key), intent.versions);
  }
}
 
// `ClassOrTag` is the mover's movement class OR a raw passable tag (normalized
// exactly as in astar_path), so plan and commit share one vocabulary: every
// step A* accepted for a class passes validation for that same class. The
// from- and to-tiles may live on different pages; each is resolved and the
// class predicate evaluated on its own page.
 
namespace detail {
 
// Validation core: returns the resolved endpoints alongside the result so
// commit_movement_intent reuses them for its field writes and dirty marks
// instead of re-resolving the same coordinates 4-7x per committed step. This
// core is intentionally not noexcept: consumer
// providers are allowed to throw during enumeration, and validation must
// propagate that failure instead of terminating. Resolved tiles are meaningful
// only when result.status == Moved.
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag, typename Provider>
[[nodiscard]] auto validate_movement_intent_resolved(const World& world,
                                                     MovementIntent intent,
                                                     const Provider& provider) {
  using Class = movement::movement_class_of<ClassOrTag>;
  using Model = ResolvedTransitionModel<World, Class, Provider>;
  using Resolved = ResolvedTile<typename World::shape_type>;
  struct Validated {
    MovementResult result;
    Resolved from;
    Resolved to;
  };
  const auto fail = [&](MovementStatus status) {
    return Validated{MovementResult{status, intent.from, intent.to}, Resolved{},
                     Resolved{}};
  };
  const auto resolved_from = world.try_resolve(intent.from);
  if (!resolved_from.has_value()) {
    return fail(MovementStatus::InvalidFrom);
  }
  const auto resolved_to = world.try_resolve(intent.to);
  if (!resolved_to.has_value()) {
    return fail(MovementStatus::InvalidTo);
  }
  if constexpr (std::is_same_v<typename World::residency_type,
                               SparseResident>) {
    // try_resolve is containment-only, so an in-bounds but non-resident
    // endpoint passes the checks above. A non-resident chunk carries no data,
    // but this is a TRANSIENT condition -- the chunk may be rematerialized --
    // so return StaleContent (a transient failure, matching
    // movement_versions_match for the identical condition) rather than a
    // terminal InvalidFrom/InvalidTo. That routes the agent lifecycle to
    // re-plan against the now-changed residency instead of permanently
    // stranding it at Unreachable, and it still short-circuits before the
    // unchecked accessors below so we never read a non-resident slot out of
    // bounds. Ordinary LRU eviction of a chunk under a Following agent must
    // not read as a permanent caller bug.
    if (!world.is_resident(resolved_from->chunk_key) ||
        !world.is_resident(resolved_to->chunk_key)) {
      return fail(MovementStatus::StaleContent);
    }
  }
  const auto& from_page = world.chunk(resolved_from->chunk_key);
  const auto& to_page = world.chunk(resolved_to->chunk_key);
  if (!Class::passable(from_page, resolved_from->local_tile_id)) {
    return fail(MovementStatus::ImpassableFrom);
  }
  if (!Class::passable(to_page, resolved_to->local_tile_id)) {
    return fail(MovementStatus::ImpassableTo);
  }
  // Exact search rejects a zero-entry-cost goal before enumerating either
  // regular or provider transitions. The source was a valid search endpoint
  // when the route was planned; commit checks its passability above while a
  // zero-cost destination must invalidate this planned step.
  if (Class::entry_cost(to_page, resolved_to->local_tile_id) == 0) {
    return fail(MovementStatus::ImpassableTo);
  }
  auto transition_availability = TransitionAvailability::Blocked;
  auto is_candidate = Model::is_regular_candidate(intent.from, intent.to);
  if (is_candidate) {
    transition_availability =
        Model::regular_availability(world, intent.from, intent.to);
  }
  if constexpr (Model::has_special_transitions) {
    // A provider may deliberately add an edge parallel to a geometric
    // regular edge (a bridge across blocked diagonal clearance, for example).
    // A legal regular edge is the overwhelmingly common hot path and needs no
    // provider call. Otherwise enumerate both sources and accept the strongest
    // matching result: Legal beats MissingTopology, which beats Blocked.
    // This keeps commit aligned with the transition enumeration used by A*
    // without imposing provider overhead on ordinary legal movement.
    if (transition_availability != TransitionAvailability::Legal) {
      const auto model = Model{provider};
      model.for_each_forward(
          world, intent.from,
          detail::transition_index<typename World::shape_type>(intent.from),
          [&](auto probe) {
            if (probe.to != intent.to) {
              return;
            }
            is_candidate = true;
            if (probe.availability == TransitionAvailability::Legal) {
              transition_availability = TransitionAvailability::Legal;
            } else if (probe.availability ==
                           TransitionAvailability::MissingTopology &&
                       transition_availability !=
                           TransitionAvailability::Legal) {
              transition_availability = TransitionAvailability::MissingTopology;
            }
          });
    }
  }
  if (!is_candidate) {
    if constexpr (Model::has_special_transitions) {
      return fail(MovementStatus::StaleTopology);
    }
    return fail(MovementStatus::NotAdjacent);
  }
  if (transition_availability == TransitionAvailability::MissingTopology) {
    return fail(MovementStatus::StaleTopology);
  }
  if (transition_availability != TransitionAvailability::Legal) {
    return fail(MovementStatus::Blocked);
  }
  if (static_cast<bool>(
          to_page.template field<OccupancyTag>(resolved_to->local_tile_id))) {
    return fail(MovementStatus::Occupied);
  }
  if (static_cast<bool>(
          to_page.template field<ReservationTag>(resolved_to->local_tile_id))) {
    return fail(MovementStatus::Reserved);
  }
 
  // Residency (sparse) was checked above, so the meta reads are safe for
  // both world kinds; with no expectations the compares are skipped
  // entirely.
  if (detail::has_version_expectations(intent.versions)) {
    const auto version_status = detail::movement_versions_match_meta(
        world.meta(resolved_from->chunk_key),
        world.meta(resolved_to->chunk_key), intent.versions);
    if (version_status != MovementStatus::Moved) {
      return fail(version_status);
    }
  }
  return Validated{
      MovementResult{MovementStatus::Moved, intent.from, intent.to},
      *resolved_from, *resolved_to};
}
 
}  // namespace detail
 
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag>
[[nodiscard]] auto validate_movement_intent(const World& world,
                                            MovementIntent intent) noexcept
    -> MovementResult {
  return detail::validate_movement_intent_resolved<World, ClassOrTag,
                                                   OccupancyTag, ReservationTag,
                                                   AdjacentTransitions>(
             world, intent, AdjacentTransitions{})
      .result;
}
 
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag, typename Provider>
[[nodiscard]] auto validate_movement_intent(const World& world,
                                            MovementIntent intent,
                                            const Provider& provider)
    -> MovementResult {
  return detail::validate_movement_intent_resolved<
             World, ClassOrTag, OccupancyTag, ReservationTag, Provider>(
             world, intent, provider)
      .result;
}
 
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag>
[[nodiscard]] auto commit_movement_intent(World& world, MovementIntent intent,
                                          DirtyMask dirty_mask = {}) noexcept
    -> MovementResult {
  const auto validated = detail::validate_movement_intent_resolved<
      World, ClassOrTag, OccupancyTag, ReservationTag, AdjacentTransitions>(
      world, intent, AdjacentTransitions{});
  if (validated.result.status != MovementStatus::Moved) {
    return validated.result;
  }
 
  auto& from_page = world.chunk(validated.from.chunk_key);
  auto& to_page = world.chunk(validated.to.chunk_key);
  from_page.template field<OccupancyTag>(validated.from.local_tile_id) = false;
  to_page.template field<OccupancyTag>(validated.to.local_tile_id) = true;
  to_page.template field<ReservationTag>(validated.to.local_tile_id) = false;
  if (dirty_mask) {
    world.mark_dirty(validated.from.chunk_key, dirty_mask,
                     Box3{intent.from, Extent3{1, 1, 1}});
    world.mark_dirty(validated.to.chunk_key, dirty_mask,
                     Box3{intent.to, Extent3{1, 1, 1}});
  }
  return validated.result;
}
 
template <typename World, typename ClassOrTag, typename OccupancyTag,
          typename ReservationTag, typename Provider>
[[nodiscard]] auto commit_movement_intent(World& world, MovementIntent intent,
                                          DirtyMask dirty_mask,
                                          const Provider& provider)
    -> MovementResult {
  const auto validated =
      detail::validate_movement_intent_resolved<World, ClassOrTag, OccupancyTag,
                                                ReservationTag, Provider>(
          world, intent, provider);
  if (validated.result.status != MovementStatus::Moved) {
    return validated.result;
  }
 
  auto& from_page = world.chunk(validated.from.chunk_key);
  auto& to_page = world.chunk(validated.to.chunk_key);
  from_page.template field<OccupancyTag>(validated.from.local_tile_id) = false;
  to_page.template field<OccupancyTag>(validated.to.local_tile_id) = true;
  to_page.template field<ReservationTag>(validated.to.local_tile_id) = false;
  if (dirty_mask) {
    world.mark_dirty(validated.from.chunk_key, dirty_mask,
                     Box3{intent.from, Extent3{1, 1, 1}});
    world.mark_dirty(validated.to.chunk_key, dirty_mask,
                     Box3{intent.to, Extent3{1, 1, 1}});
  }
  return validated.result;
}
 
}  // namespace tess