hack_manifest.cc

Go to the documentation of this file.

#include "core/hack_manifest.h"
 
#include <algorithm>
#include <array>
#include <cctype>
#include <filesystem>
#include <fstream>
#include <iterator>
#include <limits>
#include <sstream>
#include <utility>
 
#include "absl/status/statusor.h"
#include "absl/strings/str_format.h"
#include "rom/snes.h"
#include "util/json.h"
#include "util/log.h"
#include "util/macro.h"
 
namespace yaze::core {
 
std::string AddressOwnershipToString(AddressOwnership ownership) {
  switch (ownership) {
    case AddressOwnership::kVanillaSafe:
      return "vanilla_safe";
    case AddressOwnership::kHookPatched:
      return "hook_patched";
    case AddressOwnership::kAsmOwned:
      return "asm_owned";
    case AddressOwnership::kShared:
      return "shared";
    case AddressOwnership::kAsmExpansion:
      return "asm_expansion";
    case AddressOwnership::kRam:
      return "ram";
    case AddressOwnership::kMirror:
      return "mirror";
  }
  return "unknown";
}
 
namespace {
 
absl::StatusOr<uint32_t> ParseHexAddress(const std::string& str) {
  try {
    if (str.size() >= 2 && str[0] == '0' && (str[1] == 'x' || str[1] == 'X')) {
      return static_cast<uint32_t>(std::stoul(str.substr(2), nullptr, 16));
    }
    return static_cast<uint32_t>(std::stoul(str, nullptr, 16));
  } catch (const std::exception& exc) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid hex address '%s': %s", str, exc.what()));
  }
}
 
absl::StatusOr<AddressOwnership> ParseOwnership(const std::string& str) {
  if (str == "vanilla_safe")
    return AddressOwnership::kVanillaSafe;
  if (str == "hook_patched")
    return AddressOwnership::kHookPatched;
  if (str == "asm_owned")
    return AddressOwnership::kAsmOwned;
  if (str == "shared")
    return AddressOwnership::kShared;
  if (str == "asm_expansion")
    return AddressOwnership::kAsmExpansion;
  if (str == "ram")
    return AddressOwnership::kRam;
  if (str == "mirror")
    return AddressOwnership::kMirror;
  return absl::InvalidArgumentError(
      absl::StrFormat("Unknown ownership string '%s'", str));
}
 
bool IsAsmOwned(AddressOwnership ownership) {
  switch (ownership) {
    case AddressOwnership::kHookPatched:
    case AddressOwnership::kAsmOwned:
    case AddressOwnership::kAsmExpansion:
    case AddressOwnership::kMirror:
      return true;
    case AddressOwnership::kVanillaSafe:
    case AddressOwnership::kShared:
    case AddressOwnership::kRam:
      return false;
  }
  return false;
}
 
uint32_t NormalizeSnesAddress(uint32_t address) {
  // Treat FastROM mirrors ($80-$FF) as equivalent to the canonical banks
  // ($00-$7F). The hack manifest is emitted from ASM `org $XXXXXX` directives
  // and typically uses canonical addresses.
  if (address >= 0x800000 && address <= 0xFFFFFF) {
    address &= 0x7FFFFF;
  }
  return address;
}
 
constexpr uint64_t kCanonicalLoRomSize = 0x400000;
 
const char* DungeonStreamTypeToString(DungeonStreamType stream) {
  switch (stream) {
    case DungeonStreamType::kObjects:
      return "objects";
    case DungeonStreamType::kSprites:
      return "sprites";
    case DungeonStreamType::kPotItems:
      return "pot_items";
  }
  return "unknown";
}
 
absl::StatusOr<uint32_t> ParseStrictHexValue(const Json& value,
                                             const std::string& field,
                                             uint32_t maximum) {
  if (!value.is_string()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s must be a hexadecimal string", field));
  }
 
  const std::string input = value.get<std::string>();
  size_t digits_begin = 0;
  if (!input.empty() && input.front() == '$') {
    digits_begin = 1;
  } else if (input.size() >= 2 && input[0] == '0' &&
             (input[1] == 'x' || input[1] == 'X')) {
    digits_begin = 2;
  }
  if (digits_begin == input.size()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s has no hexadecimal digits", field));
  }
  for (size_t index = digits_begin; index < input.size(); ++index) {
    if (!std::isxdigit(static_cast<unsigned char>(input[index]))) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s contains an invalid hexadecimal value '%s'", field, input));
    }
  }
 
  try {
    const uint64_t parsed =
        std::stoull(input.substr(digits_begin), nullptr, 16);
    if (parsed > maximum) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s value '%s' exceeds 0x%X", field, input, maximum));
    }
    return static_cast<uint32_t>(parsed);
  } catch (const std::exception& exc) {
    return absl::InvalidArgumentError(
        absl::StrFormat("Invalid hexadecimal value for %s ('%s'): %s", field,
                        input, exc.what()));
  }
}
 
absl::StatusOr<int> ParseManifestVersion(const Json& root) {
  if (!root.contains("manifest_version")) {
    return 0;
  }
 
  const Json& value = root["manifest_version"];
  uint64_t version = 0;
  if (value.is_number_unsigned()) {
    version = value.get<uint64_t>();
  } else if (value.is_number_integer()) {
    const int64_t signed_version = value.get<int64_t>();
    if (signed_version < 0) {
      return absl::InvalidArgumentError(
          "manifest_version must be a non-negative integer");
    }
    version = static_cast<uint64_t>(signed_version);
  } else {
    return absl::InvalidArgumentError(
        "manifest_version must be a non-negative integer");
  }
 
  if (version > static_cast<uint64_t>(std::numeric_limits<int>::max())) {
    return absl::InvalidArgumentError("manifest_version is too large");
  }
  return static_cast<int>(version);
}
 
absl::StatusOr<int> ParseBoundedNonnegativeInteger(const Json& value,
                                                   absl::string_view field,
                                                   uint64_t maximum) {
  uint64_t parsed = 0;
  if (value.is_number_unsigned()) {
    parsed = value.get<uint64_t>();
  } else if (value.is_number_integer()) {
    const int64_t signed_value = value.get<int64_t>();
    if (signed_value < 0) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s must be a non-negative integer", field));
    }
    parsed = static_cast<uint64_t>(signed_value);
  } else {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s must be a non-negative integer", field));
  }
  if (parsed > maximum ||
      parsed > static_cast<uint64_t>(std::numeric_limits<int>::max())) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s is too large", field));
  }
  return static_cast<int>(parsed);
}
 
absl::StatusOr<uint32_t> ParseLoRomAddress(const Json& object,
                                           const std::string& key,
                                           const std::string& path) {
  if (!object.contains(key)) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.%s is required", path, key));
  }
 
  uint32_t address = 0;
  ASSIGN_OR_RETURN(address, ParseStrictHexValue(object[key], path + "." + key,
                                                /*maximum=*/0xFFFFFF));
  address = NormalizeSnesAddress(address);
  const uint8_t bank = static_cast<uint8_t>((address >> 16) & 0xFF);
  if (bank == 0x7E || bank == 0x7F) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s.%s must not use SNES WRAM bank 0x%02X", path, key, bank));
  }
  if ((address & 0xFFFF) < 0x8000) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s.%s must be a mapped LoROM address (low word >= 0x8000)", path,
        key));
  }
  if (NormalizeSnesAddress(PcToSnes(SnesToPc(address))) != address) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s.%s is not convertible to a canonical LoROM address", path, key));
  }
  return address;
}
 
absl::StatusOr<uint32_t> ParsePointerCount(const Json& object,
                                           const std::string& path) {
  constexpr const char* kField = "pointer_count";
  constexpr uint32_t kMaxDungeonPointerCount = 296;
  if (!object.contains(kField)) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.%s is required", path, kField));
  }
 
  const Json& value = object[kField];
  uint64_t count = 0;
  if (value.is_number_unsigned()) {
    count = value.get<uint64_t>();
  } else if (value.is_number_integer()) {
    const int64_t signed_count = value.get<int64_t>();
    if (signed_count <= 0) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s.%s must be greater than zero", path, kField));
    }
    count = static_cast<uint64_t>(signed_count);
  } else {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.%s must be an integer", path, kField));
  }
 
  if (count == 0 || count > kMaxDungeonPointerCount) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s.%s must be in [1, %u]", path, kField, kMaxDungeonPointerCount));
  }
  return static_cast<uint32_t>(count);
}
 
absl::StatusOr<DungeonPointerEncoding> ParsePointerEncoding(
    const Json& object, const std::string& path) {
  constexpr const char* kField = "pointer_encoding";
  if (!object.contains(kField) || !object[kField].is_string()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.%s must be 'long24' or 'bank16'", path, kField));
  }
  const std::string value = object[kField].get<std::string>();
  if (value == "long24") {
    return DungeonPointerEncoding::kLong24;
  }
  if (value == "bank16") {
    return DungeonPointerEncoding::kBank16;
  }
  return absl::InvalidArgumentError(
      absl::StrFormat("%s.%s has unknown encoding '%s'", path, kField, value));
}
 
absl::StatusOr<DungeonWriteStrategy> ParseWriteStrategy(
    const Json& object, const std::string& path) {
  constexpr const char* kField = "strategy";
  if (!object.contains(kField) || !object[kField].is_string()) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s.%s must be 'copy_on_write' or 'repack_all'", path, kField));
  }
  const std::string value = object[kField].get<std::string>();
  if (value == "copy_on_write") {
    return DungeonWriteStrategy::kCopyOnWrite;
  }
  if (value == "repack_all") {
    return DungeonWriteStrategy::kRepackAll;
  }
  return absl::InvalidArgumentError(
      absl::StrFormat("%s.%s has unknown strategy '%s'", path, kField, value));
}
 
struct NamedPcRange {
  uint32_t start;
  uint32_t end;
  std::string name;
};
 
absl::Status ValidateDisjointRanges(std::vector<NamedPcRange> ranges,
                                    const std::string& description) {
  std::sort(ranges.begin(), ranges.end(),
            [](const NamedPcRange& lhs, const NamedPcRange& rhs) {
              return lhs.start < rhs.start ||
                     (lhs.start == rhs.start && lhs.end < rhs.end);
            });
  if (ranges.empty()) {
    return absl::OkStatus();
  }
 
  NamedPcRange active = ranges.front();
  for (size_t index = 1; index < ranges.size(); ++index) {
    const NamedPcRange& current = ranges[index];
    if (current.start < active.end) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s overlap: %s conflicts with %s", description,
                          current.name, active.name));
    }
    if (current.end > active.end) {
      active = current;
    }
  }
  return absl::OkStatus();
}
 
absl::StatusOr<std::vector<SnesAddressRange>> ParseAddressRanges(
    const Json& object, const std::string& key, const std::string& path) {
  const std::string field_path = path + "." + key;
  if (!object.contains(key) || !object[key].is_array() || object[key].empty()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s must be a non-empty array", field_path));
  }
 
  std::vector<SnesAddressRange> ranges;
  std::vector<NamedPcRange> pc_ranges;
  ranges.reserve(object[key].size());
  pc_ranges.reserve(object[key].size());
  size_t index = 0;
  for (const Json& range_json : object[key]) {
    const std::string range_path =
        absl::StrFormat("%s[%zu]", field_path, index);
    if (!range_json.is_object()) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s must be an object", range_path));
    }
 
    SnesAddressRange range;
    ASSIGN_OR_RETURN(range.start,
                     ParseLoRomAddress(range_json, "start", range_path));
    ASSIGN_OR_RETURN(range.end,
                     ParseLoRomAddress(range_json, "end", range_path));
    const uint32_t pc_start = SnesToPc(range.start);
    const uint32_t pc_end = SnesToPc(range.end);
    if (range.end <= range.start || pc_end <= pc_start) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s must be a non-empty half-open range with end > start",
          range_path));
    }
 
    ranges.push_back(range);
    pc_ranges.push_back({pc_start, pc_end, range_path});
    ++index;
  }
 
  RETURN_IF_ERROR(ValidateDisjointRanges(std::move(pc_ranges), field_path));
  std::sort(ranges.begin(), ranges.end(),
            [](const SnesAddressRange& lhs, const SnesAddressRange& rhs) {
              return lhs.start < rhs.start;
            });
  return ranges;
}
 
absl::StatusOr<std::vector<SnesAddressRange>> ParseEditorManagedRegions(
    const Json& root, int manifest_version) {
  constexpr const char* kSection = "editor_managed_regions";
  if (!root.contains(kSection)) {
    return std::vector<SnesAddressRange>{};
  }
  if (manifest_version < 3) {
    return absl::InvalidArgumentError(
        "editor_managed_regions requires manifest_version 3 or newer");
  }
 
  const Json& section = root[kSection];
  if (!section.is_object() || section.empty()) {
    return absl::InvalidArgumentError(
        "editor_managed_regions must be a non-empty object");
  }
  return ParseAddressRanges(section, "regions", kSection);
}
 
struct ParsedProtectedRegions {
  int total_hooks = 0;
  std::vector<ProtectedRegion> regions;
};
 
absl::StatusOr<uint32_t> ParseProtectedAddress(const Json& object,
                                               const std::string& key,
                                               const std::string& path,
                                               bool require_mapped_lorom) {
  if (require_mapped_lorom) {
    return ParseLoRomAddress(object, key, path);
  }
  if (!object.contains(key)) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.%s is required", path, key));
  }
 
  uint32_t address = 0;
  ASSIGN_OR_RETURN(address, ParseStrictHexValue(object[key], path + "." + key,
                                                /*maximum=*/0xFFFFFF));
  return NormalizeSnesAddress(address);
}
 
absl::StatusOr<ParsedProtectedRegions> ParseProtectedRegions(
    const Json& root, int manifest_version) {
  ParsedProtectedRegions parsed;
  constexpr const char* kSection = "protected_regions";
  if (!root.contains(kSection)) {
    return parsed;
  }
 
  const Json& section = root[kSection];
  if (!section.is_object()) {
    return absl::InvalidArgumentError("protected_regions must be an object");
  }
  if (!section.contains("regions") || !section["regions"].is_array()) {
    return absl::InvalidArgumentError(
        "protected_regions.regions must be an array");
  }
 
  parsed.total_hooks = section.value("total_hooks", 0);
  parsed.regions.reserve(section["regions"].size());
  // Version 3 is the first schema that can exempt editor-managed ranges, so
  // its protected endpoints must be canonical mapped LoROM addresses. Legacy
  // manifests still require structurally valid ranges, but retain low-half
  // addresses emitted by older Oracle sources (for example $1E7F21).
  const bool require_mapped_lorom = manifest_version >= 3;
  size_t index = 0;
  for (const Json& region_json : section["regions"]) {
    const std::string path =
        absl::StrFormat("protected_regions.regions[%zu]", index);
    if (!region_json.is_object()) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s must be an object", path));
    }
 
    ProtectedRegion region;
    ASSIGN_OR_RETURN(region.start,
                     ParseProtectedAddress(region_json, "start", path,
                                           require_mapped_lorom));
    ASSIGN_OR_RETURN(region.end, ParseProtectedAddress(region_json, "end", path,
                                                       require_mapped_lorom));
    if (region.end <= region.start ||
        SnesToPc(region.end) <= SnesToPc(region.start)) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s must be a non-empty half-open range with end > start", path));
    }
 
    region.hook_count = region_json.value("hook_count", 0);
    region.module = region_json.value("module", "");
    parsed.regions.push_back(std::move(region));
    ++index;
  }
 
  // Unlike editor-managed and allocator ranges, protected hooks may overlap.
  // FindProtectedRegion() deliberately walks backward across all candidates.
  std::sort(parsed.regions.begin(), parsed.regions.end(),
            [](const ProtectedRegion& lhs, const ProtectedRegion& rhs) {
              return lhs.start < rhs.start;
            });
  return parsed;
}
 
bool PcRangeContains(const SnesAddressRange& outer,
                     const SnesAddressRange& inner) {
  return SnesToPc(outer.start) <= SnesToPc(inner.start) &&
         SnesToPc(inner.end) <= SnesToPc(outer.end);
}
 
absl::StatusOr<DungeonStreamLayout> ParseDungeonStreamLayout(
    DungeonStreamType stream, const Json& json) {
  const std::string path = absl::StrFormat("dungeon_stream_regions.%s",
                                           DungeonStreamTypeToString(stream));
  if (!json.is_object()) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s must be an object", path));
  }
 
  DungeonStreamLayout layout;
  ASSIGN_OR_RETURN(layout.pointer_table,
                   ParseLoRomAddress(json, "pointer_table", path));
  ASSIGN_OR_RETURN(layout.pointer_count, ParsePointerCount(json, path));
  ASSIGN_OR_RETURN(layout.pointer_encoding, ParsePointerEncoding(json, path));
  ASSIGN_OR_RETURN(layout.strategy, ParseWriteStrategy(json, path));
  ASSIGN_OR_RETURN(layout.data_regions,
                   ParseAddressRanges(json, "data_regions", path));
  ASSIGN_OR_RETURN(layout.allocation_regions,
                   ParseAddressRanges(json, "allocation_regions", path));
 
  if (layout.pointer_encoding == DungeonPointerEncoding::kBank16) {
    if (!json.contains("pointer_bank")) {
      return absl::InvalidArgumentError(
          absl::StrFormat("%s.pointer_bank is required for bank16", path));
    }
    uint32_t bank = 0;
    ASSIGN_OR_RETURN(
        bank, ParseStrictHexValue(json["pointer_bank"], path + ".pointer_bank",
                                  /*maximum=*/0xFF));
    if (bank >= 0x80) {
      bank &= 0x7F;
    }
    if (bank == 0x7E || bank == 0x7F) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s.pointer_bank must not use SNES WRAM bank 0x%02X", path, bank));
    }
    layout.pointer_bank = static_cast<uint8_t>(bank);
 
    const uint32_t bank_start_snes = (bank << 16) | 0x8000;
    const uint32_t bank_start_pc = SnesToPc(bank_start_snes);
    const uint64_t bank_end_pc = static_cast<uint64_t>(bank_start_pc) + 0x8000;
    for (const SnesAddressRange& range : layout.data_regions) {
      if (SnesToPc(range.start) < bank_start_pc ||
          SnesToPc(range.end) > bank_end_pc) {
        return absl::InvalidArgumentError(absl::StrFormat(
            "%s.data_regions must stay within pointer_bank 0x%02X for "
            "bank16 encoding",
            path, bank));
      }
    }
  } else if (json.contains("pointer_bank")) {
    return absl::InvalidArgumentError(
        absl::StrFormat("%s.pointer_bank is not allowed for long24", path));
  }
 
  for (const SnesAddressRange& allocation : layout.allocation_regions) {
    const bool contained =
        std::any_of(layout.data_regions.begin(), layout.data_regions.end(),
                    [&allocation](const SnesAddressRange& data) {
                      return PcRangeContains(data, allocation);
                    });
    if (!contained) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s allocation range [0x%06X, 0x%06X) is not fully contained in "
          "a data_region",
          path, allocation.start, allocation.end));
    }
  }
 
  const uint64_t pointer_width =
      layout.pointer_encoding == DungeonPointerEncoding::kLong24 ? 3 : 2;
  const uint64_t table_start_pc = SnesToPc(layout.pointer_table);
  const uint64_t table_size =
      pointer_width * static_cast<uint64_t>(layout.pointer_count);
  const uint64_t table_end_pc = table_start_pc + table_size;
  if (table_start_pc > kCanonicalLoRomSize ||
      table_end_pc > kCanonicalLoRomSize) {
    return absl::InvalidArgumentError(absl::StrFormat(
        "%s pointer table extends beyond canonical LoROM address space", path));
  }
  if (layout.pointer_encoding == DungeonPointerEncoding::kBank16) {
    const uint64_t runtime_table_end =
        static_cast<uint64_t>(layout.pointer_table & 0xFFFFu) + table_size;
    if (runtime_table_end > 0x10000u) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "%s bank16 pointer table crosses its runtime CPU bank", path));
    }
  }
 
  return layout;
}
 
absl::StatusOr<std::unordered_map<DungeonStreamType, DungeonStreamLayout>>
ParseDungeonStreamLayouts(const Json& root) {
  std::unordered_map<DungeonStreamType, DungeonStreamLayout> layouts;
  if (!root.contains("dungeon_stream_regions")) {
    return layouts;
  }
 
  const Json& section = root["dungeon_stream_regions"];
  if (!section.is_object() || section.empty()) {
    return absl::InvalidArgumentError(
        "dungeon_stream_regions must be a non-empty object");
  }
 
  constexpr std::array<std::pair<const char*, DungeonStreamType>, 3> kStreams =
      {{{"objects", DungeonStreamType::kObjects},
        {"sprites", DungeonStreamType::kSprites},
        {"pot_items", DungeonStreamType::kPotItems}}};
  for (const auto& item : section.items()) {
    const auto& key = item.key();
    bool known = false;
    for (const auto& entry : kStreams) {
      if (key == entry.first) {
        known = true;
        break;
      }
    }
    if (!known) {
      return absl::InvalidArgumentError(absl::StrFormat(
          "dungeon_stream_regions contains unknown stream '%s'", key));
    }
  }
 
  std::vector<NamedPcRange> occupied_ranges;
  std::vector<NamedPcRange> allocation_ranges;
  for (const auto& [key, stream] : kStreams) {
    if (!section.contains(key)) {
      continue;
    }
 
    DungeonStreamLayout layout;
    ASSIGN_OR_RETURN(layout, ParseDungeonStreamLayout(stream, section[key]));
 
    const uint64_t pointer_width =
        layout.pointer_encoding == DungeonPointerEncoding::kLong24 ? 3 : 2;
    const uint64_t table_start_pc = SnesToPc(layout.pointer_table);
    const uint64_t table_end_pc =
        table_start_pc +
        pointer_width * static_cast<uint64_t>(layout.pointer_count);
    occupied_ranges.push_back({static_cast<uint32_t>(table_start_pc),
                               static_cast<uint32_t>(table_end_pc),
                               absl::StrFormat("%s.pointer_table", key)});
 
    for (size_t index = 0; index < layout.data_regions.size(); ++index) {
      const auto& range = layout.data_regions[index];
      occupied_ranges.push_back(
          {SnesToPc(range.start), SnesToPc(range.end),
           absl::StrFormat("%s.data_regions[%zu]", key, index)});
    }
    for (size_t index = 0; index < layout.allocation_regions.size(); ++index) {
      const auto& range = layout.allocation_regions[index];
      allocation_ranges.push_back(
          {SnesToPc(range.start), SnesToPc(range.end),
           absl::StrFormat("%s.allocation_regions[%zu]", key, index)});
    }
    layouts.emplace(stream, std::move(layout));
  }
 
  RETURN_IF_ERROR(ValidateDisjointRanges(std::move(occupied_ranges),
                                         "dungeon stream pointer/data ranges"));
  RETURN_IF_ERROR(ValidateDisjointRanges(std::move(allocation_ranges),
                                         "dungeon stream allocation ranges"));
  return layouts;
}
 
}  // namespace
 
void HackManifest::Reset() {
  loaded_ = false;
  manifest_version_ = 0;
  hack_name_.clear();
  total_hooks_ = 0;
  protected_regions_.clear();
  editor_managed_regions_.clear();
  owned_banks_.clear();
  room_tag_map_.clear();
  room_tags_.clear();
  feature_flag_map_.clear();
  feature_flags_.clear();
  sram_map_.clear();
  sram_variables_.clear();
  message_layout_ = MessageLayout{};
  dungeon_stream_layouts_.clear();
  build_pipeline_ = BuildPipeline{};
  project_registry_ = ProjectRegistry{};
  oracle_progression_state_.reset();
}
 
absl::Status HackManifest::LoadFromFile(const std::string& filepath) {
  std::ifstream file(filepath);
  if (!file.is_open()) {
    return absl::NotFoundError("Could not open manifest: " + filepath);
  }
  std::stringstream buffer;
  buffer << file.rdbuf();
  return LoadFromString(buffer.str());
}
 
absl::Status HackManifest::LoadFromString(const std::string& json_content) {
  Reset();
 
  Json root;
  try {
    root = Json::parse(json_content);
  } catch (const std::exception& exc) {
    return absl::InvalidArgumentError(
        std::string("Failed to parse manifest JSON: ") + exc.what());
  }
 
  if (!root.is_object()) {
    return absl::InvalidArgumentError("Hack manifest root must be an object");
  }
 
  ASSIGN_OR_RETURN(manifest_version_, ParseManifestVersion(root));
  hack_name_ = root.value("hack_name", "");
 
  std::vector<SnesAddressRange> editor_managed_regions;
  ASSIGN_OR_RETURN(editor_managed_regions,
                   ParseEditorManagedRegions(root, manifest_version_));
 
  std::unordered_map<DungeonStreamType, DungeonStreamLayout>
      dungeon_stream_layouts;
  ASSIGN_OR_RETURN(dungeon_stream_layouts, ParseDungeonStreamLayouts(root));
 
  ParsedProtectedRegions protected_regions;
  ASSIGN_OR_RETURN(protected_regions,
                   ParseProtectedRegions(root, manifest_version_));
 
  // Build pipeline
  if (root.contains("build_pipeline")) {
    auto& pipeline = root["build_pipeline"];
    build_pipeline_.dev_rom = pipeline.value("dev_rom", "");
    build_pipeline_.patched_rom = pipeline.value("patched_rom", "");
    build_pipeline_.assembler = pipeline.value("assembler", "");
    build_pipeline_.entry_point = pipeline.value("entry_point", "");
    build_pipeline_.build_script = pipeline.value("build_script", "");
  }
 
  // Owned banks
  if (root.contains("owned_banks") && root["owned_banks"].contains("banks")) {
    for (auto& bank_json : root["owned_banks"]["banks"]) {
      OwnedBank bank;
      uint32_t bank_u32 = 0;
      ASSIGN_OR_RETURN(bank_u32,
                       ParseHexAddress(bank_json.value("bank", "0x00")));
      bank.bank = static_cast<uint8_t>(bank_u32 & 0xFF);
      if (bank.bank >= 0x80) {
        bank.bank &= 0x7F;
      }
      ASSIGN_OR_RETURN(bank.bank_start, ParseHexAddress(bank_json.value(
                                            "bank_start", "0x000000")));
      ASSIGN_OR_RETURN(bank.bank_end, ParseHexAddress(bank_json.value(
                                          "bank_end", "0x000000")));
      bank.bank_start = NormalizeSnesAddress(bank.bank_start);
      bank.bank_end = NormalizeSnesAddress(bank.bank_end);
      ASSIGN_OR_RETURN(bank.ownership, ParseOwnership(bank_json.value(
                                           "ownership", "asm_owned")));
      bank.ownership_note = bank_json.value("ownership_note", "");
      owned_banks_[bank.bank] = bank;
    }
  }
 
  // Room tags
  if (root.contains("room_tags") && root["room_tags"].contains("tags")) {
    for (auto& tag_json : root["room_tags"]["tags"]) {
      RoomTagEntry tag;
      uint32_t tag_id_u32 = 0;
      ASSIGN_OR_RETURN(tag_id_u32,
                       ParseHexAddress(tag_json.value("tag_id", "0x00")));
      tag.tag_id = static_cast<uint8_t>(tag_id_u32 & 0xFF);
      ASSIGN_OR_RETURN(tag.address,
                       ParseHexAddress(tag_json.value("address", "0x000000")));
      tag.address = NormalizeSnesAddress(tag.address);
      tag.name = tag_json.value("name", "");
      tag.purpose = tag_json.value("purpose", "");
      tag.source = tag_json.value("source", "");
      tag.feature_flag = tag_json.value("feature_flag", "");
      tag.enabled = tag_json.value("enabled", true);
      room_tag_map_[tag.tag_id] = tag;
      room_tags_.push_back(tag);
    }
  }
 
  // Feature flags
  if (root.contains("feature_flags") &&
      root["feature_flags"].contains("flags")) {
    for (auto& flag_json : root["feature_flags"]["flags"]) {
      FeatureFlag flag;
      flag.name = flag_json.value("name", "");
      flag.value = flag_json.value("value", 0);
      flag.enabled = flag_json.value("enabled", false);
      flag.source = flag_json.value("source", "");
      feature_flag_map_[flag.name] = flag;
      feature_flags_.push_back(flag);
    }
  }
 
  // SRAM variables
  if (root.contains("sram") && root["sram"].contains("variables")) {
    for (auto& var_json : root["sram"]["variables"]) {
      SramVariable var;
      var.name = var_json.value("name", "");
      ASSIGN_OR_RETURN(var.address,
                       ParseHexAddress(var_json.value("address", "0x000000")));
      var.purpose = var_json.value("purpose", "");
      sram_map_[var.address] = var;
      sram_variables_.push_back(var);
    }
  }
 
  // Message layout
  if (root.contains("messages")) {
    auto& msg = root["messages"];
    if (!msg.is_object()) {
      return absl::InvalidArgumentError("messages must be an object");
    }
    if (msg.contains("hook_address") && msg["hook_address"].is_string()) {
      ASSIGN_OR_RETURN(message_layout_.hook_address,
                       ParseHexAddress(msg["hook_address"].get<std::string>()));
      message_layout_.hook_address =
          NormalizeSnesAddress(message_layout_.hook_address);
    }
    if (msg.contains("data_start")) {
      ASSIGN_OR_RETURN(message_layout_.data_start,
                       ParseHexAddress(msg.value("data_start", "0x000000")));
      message_layout_.data_start =
          NormalizeSnesAddress(message_layout_.data_start);
    }
    if (msg.contains("data_end")) {
      ASSIGN_OR_RETURN(message_layout_.data_end,
                       ParseHexAddress(msg.value("data_end", "0x000000")));
      message_layout_.data_end = NormalizeSnesAddress(message_layout_.data_end);
    }
    if (msg.contains("vanilla_count")) {
      ASSIGN_OR_RETURN(
          message_layout_.vanilla_count,
          ParseBoundedNonnegativeInteger(
              msg["vanilla_count"], "messages.vanilla_count",
              static_cast<uint64_t>(std::numeric_limits<int>::max())));
    } else {
      message_layout_.vanilla_count = 397;
    }
    if (msg.contains("expanded_range")) {
      auto& expanded = msg["expanded_range"];
      if (!expanded.is_object()) {
        return absl::InvalidArgumentError(
            "messages.expanded_range must be an object");
      }
      uint32_t first_id = 0;
      uint32_t last_id = 0;
      ASSIGN_OR_RETURN(first_id,
                       ParseHexAddress(expanded.value("first", "0x000")));
      ASSIGN_OR_RETURN(last_id,
                       ParseHexAddress(expanded.value("last", "0x000")));
      message_layout_.first_expanded_id =
          static_cast<uint16_t>(first_id & 0xFFFF);
      message_layout_.last_expanded_id =
          static_cast<uint16_t>(last_id & 0xFFFF);
      if (expanded.contains("count")) {
        constexpr uint64_t kMaximumExpandedMessageCount =
            static_cast<uint64_t>(std::numeric_limits<uint16_t>::max()) + 1;
        ASSIGN_OR_RETURN(message_layout_.expanded_count,
                         ParseBoundedNonnegativeInteger(
                             expanded["count"], "messages.expanded_range.count",
                             kMaximumExpandedMessageCount));
      } else {
        message_layout_.expanded_count = 0;
      }
    }
    if (msg.contains("source")) {
      const auto& source = msg["source"];
      if (!source.is_object()) {
        return absl::InvalidArgumentError("messages.source must be an object");
      }
      constexpr std::array<absl::string_view, 4> kSourceKeys = {
          "format", "version", "canonical_bundle_path",
          "generated_asm_include_path"};
      for (const auto& item : source.items()) {
        if (std::find(kSourceKeys.begin(), kSourceKeys.end(), item.key()) ==
            kSourceKeys.end()) {
          return absl::InvalidArgumentError(absl::StrFormat(
              "messages.source contains unknown field '%s'", item.key()));
        }
      }
      for (absl::string_view key : kSourceKeys) {
        if (!source.contains(key)) {
          return absl::InvalidArgumentError(
              absl::StrFormat("messages.source.%s is required", key));
        }
      }
      if (!source["format"].is_string() ||
          source["format"].get<std::string>() != "yaze-message-bundle") {
        return absl::InvalidArgumentError(
            "messages.source.format must be 'yaze-message-bundle'");
      }
      int source_version = 0;
      auto source_version_or = ParseBoundedNonnegativeInteger(
          source["version"], "messages.source.version",
          static_cast<uint64_t>(std::numeric_limits<int>::max()));
      if (!source_version_or.ok() || *source_version_or != 1) {
        return absl::InvalidArgumentError(
            "messages.source.version must be integer 1");
      }
      source_version = *source_version_or;
      if (!source["canonical_bundle_path"].is_string() ||
          source["canonical_bundle_path"].get<std::string>().empty()) {
        return absl::InvalidArgumentError(
            "messages.source.canonical_bundle_path must be a non-empty "
            "string");
      }
      if (!source["generated_asm_include_path"].is_string() ||
          source["generated_asm_include_path"].get<std::string>().empty()) {
        return absl::InvalidArgumentError(
            "messages.source.generated_asm_include_path must be a non-empty "
            "string");
      }
      message_layout_.source = MessageLayout::Source{
          .format = source["format"].get<std::string>(),
          .version = source_version,
          .canonical_bundle_path =
              source["canonical_bundle_path"].get<std::string>(),
          .generated_asm_include_path =
              source["generated_asm_include_path"].get<std::string>(),
      };
    }
  }
 
  total_hooks_ = protected_regions.total_hooks;
  protected_regions_ = std::move(protected_regions.regions);
  editor_managed_regions_ = std::move(editor_managed_regions);
  dungeon_stream_layouts_ = std::move(dungeon_stream_layouts);
  loaded_ = true;
  return absl::OkStatus();
}
 
AddressOwnership HackManifest::ClassifyAddress(uint32_t address) const {
  if (!loaded_)
    return AddressOwnership::kVanillaSafe;
 
  address = NormalizeSnesAddress(address);
 
  // Explicit hooks always win, including hooks that overlap an exact
  // editor-managed exemption inside an ASM-owned bank.
  if (IsProtected(address)) {
    return AddressOwnership::kHookPatched;
  }
 
  if (IsEditorManaged(address)) {
    return AddressOwnership::kVanillaSafe;
  }
 
  const uint8_t bank = static_cast<uint8_t>((address >> 16) & 0xFF);
  const auto bank_it = owned_banks_.find(bank);
  if (bank_it != owned_banks_.end()) {
    return bank_it->second.ownership;
  }
 
  return AddressOwnership::kVanillaSafe;
}
 
bool HackManifest::IsWriteOverwritten(uint32_t address) const {
  const AddressOwnership ownership = ClassifyAddress(address);
  return ownership == AddressOwnership::kHookPatched ||
         ownership == AddressOwnership::kAsmOwned ||
         ownership == AddressOwnership::kAsmExpansion;
}
 
const ProtectedRegion* HackManifest::FindProtectedRegion(
    uint32_t address) const {
  address = NormalizeSnesAddress(address);
 
  // Start with the last possible region, then walk backwards so nested or
  // overlapping protected regions cannot hide an earlier containing hook.
  const auto upper = std::upper_bound(
      protected_regions_.begin(), protected_regions_.end(), address,
      [](uint32_t addr, const ProtectedRegion& region) {
        return addr < region.start;
      });
 
  for (auto iter = std::make_reverse_iterator(upper);
       iter != protected_regions_.rend(); ++iter) {
    if (address >= iter->start && address < iter->end) {
      return &*iter;
    }
  }
  return nullptr;
}
 
bool HackManifest::IsProtected(uint32_t address) const {
  return FindProtectedRegion(address) != nullptr;
}
 
bool HackManifest::IsEditorManaged(uint32_t address) const {
  address = NormalizeSnesAddress(address);
  const auto upper = std::upper_bound(
      editor_managed_regions_.begin(), editor_managed_regions_.end(), address,
      [](uint32_t addr, const SnesAddressRange& region) {
        return addr < region.start;
      });
  if (upper == editor_managed_regions_.begin()) {
    return false;
  }
  const SnesAddressRange& region = *std::prev(upper);
  return region.start <= address && address < region.end;
}
 
std::optional<AddressOwnership> HackManifest::GetBankOwnership(
    uint8_t bank) const {
  if (bank >= 0x80) {
    bank &= 0x7F;
  }
  auto iter = owned_banks_.find(bank);
  if (iter == owned_banks_.end())
    return std::nullopt;
  return iter->second.ownership;
}
 
std::string HackManifest::GetRoomTagLabel(uint8_t tag_id) const {
  auto iter = room_tag_map_.find(tag_id);
  if (iter == room_tag_map_.end())
    return "";
  return iter->second.name;
}
 
std::optional<RoomTagEntry> HackManifest::GetRoomTag(uint8_t tag_id) const {
  auto iter = room_tag_map_.find(tag_id);
  if (iter == room_tag_map_.end())
    return std::nullopt;
  return iter->second;
}
 
bool HackManifest::IsFeatureEnabled(const std::string& flag_name) const {
  auto iter = feature_flag_map_.find(flag_name);
  if (iter == feature_flag_map_.end())
    return false;
  return iter->second.enabled;
}
 
std::vector<WriteConflict> HackManifest::AnalyzeWriteRanges(
    const std::vector<std::pair<uint32_t, uint32_t>>& ranges) const {
  std::vector<WriteConflict> conflicts;
  if (!loaded_) {
    return conflicts;
  }
 
  for (const auto& range : ranges) {
    const uint32_t start = NormalizeSnesAddress(range.first);
    const uint32_t end = NormalizeSnesAddress(range.second);
    if (end <= start) {
      continue;
    }
 
    // Classify one segment at a time. Every possible ownership transition is
    // a boundary: bank edges, exact editor-managed edges, and hook edges.
    // This prevents a partially exempt write from bypassing an owned neighbor.
    std::vector<uint32_t> boundaries = {start, end};
    const uint64_t first_bank_boundary =
        (static_cast<uint64_t>(start) & 0xFF0000u) + 0x010000u;
    for (uint64_t boundary = first_bank_boundary; boundary < end;
         boundary += 0x010000u) {
      boundaries.push_back(static_cast<uint32_t>(boundary));
    }
    auto add_range_boundaries = [start, end, &boundaries](const auto& regions) {
      for (const auto& region : regions) {
        if (region.start < end && start < region.end) {
          boundaries.push_back(std::max(start, region.start));
          boundaries.push_back(std::min(end, region.end));
        }
      }
    };
    add_range_boundaries(editor_managed_regions_);
    add_range_boundaries(protected_regions_);
 
    std::sort(boundaries.begin(), boundaries.end());
    boundaries.erase(std::unique(boundaries.begin(), boundaries.end()),
                     boundaries.end());
 
    bool previous_was_conflict = false;
    AddressOwnership previous_ownership = AddressOwnership::kVanillaSafe;
    std::string previous_module;
    for (size_t index = 0; index + 1 < boundaries.size(); ++index) {
      const uint32_t segment_start = boundaries[index];
      if (segment_start >= boundaries[index + 1]) {
        continue;
      }
 
      const AddressOwnership ownership = ClassifyAddress(segment_start);
      if (!IsAsmOwned(ownership)) {
        previous_was_conflict = false;
        continue;
      }
 
      std::string module;
      if (ownership == AddressOwnership::kHookPatched) {
        if (const ProtectedRegion* protected_region =
                FindProtectedRegion(segment_start);
            protected_region != nullptr) {
          module = protected_region->module;
        }
      } else {
        const uint8_t bank = static_cast<uint8_t>((segment_start >> 16) & 0xFF);
        if (const auto bank_it = owned_banks_.find(bank);
            bank_it != owned_banks_.end()) {
          module = bank_it->second.ownership_note;
        }
      }
 
      if (!previous_was_conflict || ownership != previous_ownership ||
          module != previous_module) {
        conflicts.push_back({segment_start, ownership, module});
      }
      previous_was_conflict = true;
      previous_ownership = ownership;
      previous_module = std::move(module);
    }
  }
 
  return conflicts;
}
 
std::vector<WriteConflict> HackManifest::AnalyzePcWriteRanges(
    const std::vector<std::pair<uint32_t, uint32_t>>& pc_ranges) const {
  if (!loaded_) {
    return {};
  }
 
  std::vector<std::pair<uint32_t, uint32_t>> snes_ranges;
  snes_ranges.reserve(pc_ranges.size());
 
  for (const auto& range : pc_ranges) {
    uint32_t pc_start = range.first;
    const uint32_t pc_end = range.second;
    if (pc_end <= pc_start) {
      continue;
    }
 
    // Split at LoROM bank boundaries (0x8000 bytes per bank segment in PC
    // space). PcToSnes() is linear within these segments.
    while (pc_start < pc_end) {
      const uint32_t next_boundary = (pc_start & ~0x7FFFu) + 0x8000u;
      const uint32_t seg_end = std::min(pc_end, next_boundary);
      const uint32_t seg_len = seg_end - pc_start;
      const uint32_t snes_start = PcToSnes(pc_start);
      const uint32_t snes_end = snes_start + seg_len;
      snes_ranges.emplace_back(snes_start, snes_end);
      pc_start = seg_end;
    }
  }
 
  return AnalyzeWriteRanges(snes_ranges);
}
 
std::string HackManifest::GetSramVariableName(uint32_t address) const {
  auto iter = sram_map_.find(address);
  if (iter == sram_map_.end())
    return "";
  return iter->second.name;
}
 
bool HackManifest::IsExpandedMessage(uint16_t message_id) const {
  return message_id >= message_layout_.first_expanded_id &&
         message_id <= message_layout_.last_expanded_id;
}
 
const DungeonStreamLayout* HackManifest::GetDungeonStreamLayout(
    DungeonStreamType stream) const {
  const auto iter = dungeon_stream_layouts_.find(stream);
  return iter == dungeon_stream_layouts_.end() ? nullptr : &iter->second;
}
 
// ============================================================================
// Project Registry Loading
// ============================================================================
 
absl::Status HackManifest::LoadProjectRegistry(const std::string& code_folder) {
  namespace fs = std::filesystem;
 
  project_registry_ = ProjectRegistry{};
  fs::path base(code_folder);
 
  // Look for data files in Docs/Dev/Planning/ (generated output location)
  fs::path planning = base / "Docs" / "Dev" / "Planning";
 
  // ── Load dungeons.json ──────────────────────────────────────────────────
  fs::path dungeons_path = planning / "dungeons.json";
  if (fs::exists(dungeons_path)) {
    std::ifstream file(dungeons_path);
    if (file.is_open()) {
      std::stringstream buffer;
      buffer << file.rdbuf();
      try {
        Json root = Json::parse(buffer.str());
        if (root.contains("dungeons") && root["dungeons"].is_array()) {
          for (const auto& dj : root["dungeons"]) {
            DungeonEntry entry;
            entry.id = dj.value("id", "");
            entry.name = dj.value("name", "");
            entry.vanilla_name = dj.value("vanilla_name", "");
 
            // Rooms
            if (dj.contains("rooms") && dj["rooms"].is_array()) {
              for (const auto& rj : dj["rooms"]) {
                DungeonRoom room;
                std::string id_str = rj.value("id", "0x00");
                auto parsed = ParseHexAddress(id_str);
                room.id = parsed.ok() ? static_cast<int>(*parsed) : 0;
                room.name = rj.value("name", "");
                room.floor = rj.value("floor", "");
                room.has_grid_position =
                    rj.contains("grid_row") && rj.contains("grid_col");
                room.grid_row = rj.value("grid_row", 0);
                room.grid_col = rj.value("grid_col", 0);
                room.type = rj.value("type", "normal");
                room.palette = rj.value("palette", 0);
                room.blockset = rj.value("blockset", 0);
                room.spriteset = rj.value("spriteset", 0);
                room.tag1 = static_cast<uint8_t>(rj.value("tag1", 0));
                room.tag2 = static_cast<uint8_t>(rj.value("tag2", 0));
                entry.rooms.push_back(std::move(room));
              }
            }
 
            // Stairs
            if (dj.contains("stairs") && dj["stairs"].is_array()) {
              for (const auto& sj : dj["stairs"]) {
                DungeonConnection conn;
                std::string from_str = sj.value("from", "0x00");
                std::string to_str = sj.value("to", "0x00");
                auto from_parsed = ParseHexAddress(from_str);
                auto to_parsed = ParseHexAddress(to_str);
                conn.from_room =
                    from_parsed.ok() ? static_cast<int>(*from_parsed) : 0;
                conn.to_room =
                    to_parsed.ok() ? static_cast<int>(*to_parsed) : 0;
                conn.label = sj.value("label", "");
                entry.stairs.push_back(std::move(conn));
              }
            }
 
            // Holewarps
            if (dj.contains("holewarps") && dj["holewarps"].is_array()) {
              for (const auto& hj : dj["holewarps"]) {
                DungeonConnection conn;
                std::string from_str = hj.value("from", "0x00");
                std::string to_str = hj.value("to", "0x00");
                auto from_parsed = ParseHexAddress(from_str);
                auto to_parsed = ParseHexAddress(to_str);
                conn.from_room =
                    from_parsed.ok() ? static_cast<int>(*from_parsed) : 0;
                conn.to_room =
                    to_parsed.ok() ? static_cast<int>(*to_parsed) : 0;
                conn.label = hj.value("label", "");
                entry.holewarps.push_back(std::move(conn));
              }
            }
 
            // Doors
            if (dj.contains("doors") && dj["doors"].is_array()) {
              for (const auto& doorj : dj["doors"]) {
                DungeonConnection conn;
                std::string from_str = doorj.value("from", "0x00");
                std::string to_str = doorj.value("to", "0x00");
                auto from_parsed = ParseHexAddress(from_str);
                auto to_parsed = ParseHexAddress(to_str);
                conn.from_room =
                    from_parsed.ok() ? static_cast<int>(*from_parsed) : 0;
                conn.to_room =
                    to_parsed.ok() ? static_cast<int>(*to_parsed) : 0;
                conn.label = doorj.value("label", "");
                conn.direction = doorj.value("direction", "");
                entry.doors.push_back(std::move(conn));
              }
            }
 
            project_registry_.dungeons.push_back(std::move(entry));
          }
        }
      } catch (const std::exception& exc) {
        LOG_WARN("HackManifest", "Failed to parse dungeons.json: %s",
                 exc.what());
      }
    }
  }
 
  // ── Load overworld.json ─────────────────────────────────────────────────
  fs::path overworld_path = planning / "overworld.json";
  if (fs::exists(overworld_path)) {
    std::ifstream file(overworld_path);
    if (file.is_open()) {
      std::stringstream buffer;
      buffer << file.rdbuf();
      try {
        Json root = Json::parse(buffer.str());
        if (root.contains("areas") && root["areas"].is_array()) {
          for (const auto& aj : root["areas"]) {
            OverworldArea area;
            std::string id_str = aj.value("area_id", "0x00");
            auto parsed = ParseHexAddress(id_str);
            area.area_id = parsed.ok() ? static_cast<int>(*parsed) : 0;
            area.name = aj.value("name", "");
            area.world = aj.value("world", "");
            area.grid_row = aj.value("grid_row", 0);
            area.grid_col = aj.value("grid_col", 0);
            project_registry_.overworld_areas.push_back(std::move(area));
          }
        }
      } catch (const std::exception& exc) {
        LOG_WARN("HackManifest", "Failed to parse overworld.json: %s",
                 exc.what());
      }
    }
  }
 
  // ── Load resource labels ────────────────────────────────────────────────
  // Priority 1: Unified oracle_resource_labels.json (all types)
  // Priority 2: Legacy oracle_room_labels.json (room type only)
  fs::path unified_path = planning / "oracle_resource_labels.json";
  fs::path legacy_path = planning / "oracle_room_labels.json";
 
  auto normalize_label_id = [](const std::string& raw) -> std::string {
    // Project resource_labels keys are decimal strings (std::to_string(id)).
    // Support either decimal ("57") or explicit hex ("0x39") here.
    std::string s = raw;
    while (!s.empty() && std::isspace(static_cast<unsigned char>(s.front()))) {
      s.erase(s.begin());
    }
    while (!s.empty() && std::isspace(static_cast<unsigned char>(s.back()))) {
      s.pop_back();
    }
    if (s.empty()) {
      return raw;
    }
 
    int base = 10;
    if (s.size() >= 2 && s[0] == '0' && (s[1] == 'x' || s[1] == 'X')) {
      base = 16;
      s = s.substr(2);
      if (s.empty()) {
        return raw;
      }
    }
 
    try {
      size_t idx = 0;
      const unsigned long value = std::stoul(s, &idx, base);
      if (idx != s.size()) {
        return raw;
      }
      if (value > static_cast<unsigned long>(std::numeric_limits<int>::max())) {
        return raw;
      }
      return std::to_string(static_cast<int>(value));
    } catch (...) {
      return raw;
    }
  };
 
  if (fs::exists(unified_path)) {
    std::ifstream file(unified_path);
    if (file.is_open()) {
      std::stringstream buffer;
      buffer << file.rdbuf();
      try {
        Json root = Json::parse(buffer.str());
        // Parse all type sections (room, sprite, item, entrance, etc.)
        const std::vector<std::string> label_types = {
            "room", "sprite", "item", "entrance", "overworld_map", "music"};
        for (const auto& type_key : label_types) {
          if (root.contains(type_key) && root[type_key].is_object()) {
            for (const auto& [key, value] : root[type_key].items()) {
              if (value.is_string()) {
                const std::string normalized_key = normalize_label_id(key);
                project_registry_
                    .all_resource_labels[type_key][normalized_key] =
                    value.get<std::string>();
              }
            }
          }
        }
      } catch (const std::exception& exc) {
        LOG_WARN("HackManifest",
                 "Failed to parse oracle_resource_labels.json: %s", exc.what());
      }
    }
  } else if (fs::exists(legacy_path)) {
    // Backward compat: load room-only labels from legacy file
    std::ifstream file(legacy_path);
    if (file.is_open()) {
      std::stringstream buffer;
      buffer << file.rdbuf();
      try {
        Json root = Json::parse(buffer.str());
        if (root.contains("resource_labels") &&
            root["resource_labels"].contains("room")) {
          for (const auto& [key, value] :
               root["resource_labels"]["room"].items()) {
            const std::string normalized_key = normalize_label_id(key);
            project_registry_.all_resource_labels["room"][normalized_key] =
                value.get<std::string>();
          }
        }
      } catch (const std::exception& exc) {
        LOG_WARN("HackManifest", "Failed to parse oracle_room_labels.json: %s",
                 exc.what());
      }
    }
  }
 
  // `dungeons.json` is the canonical Oracle room/dungeon structure. Mirror its
  // room names into the generic resource-label registry so opening an Oracle
  // project can populate YazeProject::resource_labels and serialize those names
  // into the project file. This intentionally runs after oracle_*_labels.json
  // so stale generated label bundles cannot mask the current dungeon registry.
  size_t dungeon_room_labels = 0;
  for (const auto& dungeon : project_registry_.dungeons) {
    for (const auto& room : dungeon.rooms) {
      if (room.id >= 0 && !room.name.empty()) {
        project_registry_.all_resource_labels["room"][std::to_string(room.id)] =
            room.name;
        ++dungeon_room_labels;
      }
    }
  }
  if (dungeon_room_labels > 0) {
    LOG_DEBUG("HackManifest",
              "Mirrored %zu dungeon room names into project resource labels",
              dungeon_room_labels);
  }
 
  // ── Load story events ──────────────────────────────────────────────────
  fs::path story_events_path = planning / "story_events.json";
  if (fs::exists(story_events_path)) {
    auto story_status =
        project_registry_.story_events.LoadFromJson(story_events_path.string());
    if (story_status.ok()) {
      project_registry_.story_events.AutoLayout();
      if (oracle_progression_state_.has_value()) {
        project_registry_.story_events.UpdateStatus(*oracle_progression_state_);
      } else {
        // Default to an initial "no progress" state so the graph renders with
        // sensible locked/available coloring even before live SRAM is wired up.
        project_registry_.story_events.UpdateStatus(/*crystal_bitfield=*/0,
                                                    /*game_state=*/0);
      }
      LOG_DEBUG("HackManifest", "Loaded story events: %zu nodes, %zu edges",
                project_registry_.story_events.nodes().size(),
                project_registry_.story_events.edges().size());
    } else {
      LOG_WARN("HackManifest", "Failed to load story_events.json: %s",
               std::string(story_status.message()).c_str());
    }
  }
 
  size_t total_labels = 0;
  for (const auto& [type, labels] : project_registry_.all_resource_labels) {
    total_labels += labels.size();
  }
 
  if (!project_registry_.dungeons.empty() ||
      !project_registry_.overworld_areas.empty() || total_labels > 0) {
    LOG_DEBUG("HackManifest",
              "Loaded project registry: %zu dungeons, %zu overworld areas, "
              "%zu resource labels (%zu types)",
              project_registry_.dungeons.size(),
              project_registry_.overworld_areas.size(), total_labels,
              project_registry_.all_resource_labels.size());
  }
 
  return absl::OkStatus();
}
 
void HackManifest::SetOracleProgressionState(
    const OracleProgressionState& state) {
  oracle_progression_state_ = state;
  if (project_registry_.story_events.loaded()) {
    project_registry_.story_events.UpdateStatus(state);
  }
}
 
void HackManifest::ClearOracleProgressionState() {
  oracle_progression_state_.reset();
  if (project_registry_.story_events.loaded()) {
    project_registry_.story_events.UpdateStatus(/*crystal_bitfield=*/0,
                                                /*game_state=*/0);
  }
}
 
}  // namespace yaze::core