class_name SpatialSubslotService
extends RefCounted

## Independent spatial occupancy for systems that may share a WorldService cell
## with a primary facility. Every layer cell owns exactly one slot per category.

signal entity_placed(entity_id: StringName, category: StringName, cells: Array[Vector3i])
signal entity_removed(entity_id: StringName, category: StringName, cells: Array[Vector3i])
signal entity_cells_replaced(
	entity_id: StringName,
	category: StringName,
	before_cells: Array[Vector3i],
	after_cells: Array[Vector3i]
)

const CommandResultType = preload("res://scripts/core/command_result.gd")

const SNAPSHOT_SCHEMA_VERSION := 1

const CATEGORY_ROUTE: StringName = &"ROUTE"
const CATEGORY_DECORATION: StringName = &"DECORATION"
const CATEGORY_UTILITY: StringName = &"UTILITY"
const CATEGORIES: Array[StringName] = [
	CATEGORY_ROUTE,
	CATEGORY_DECORATION,
	CATEGORY_UTILITY,
]

const LAYER_FRONT := 0
const LAYER_BACK := 1

const MAX_ENTITY_ID_LENGTH := 128
const MAX_ENTITIES := 4_096
const MAX_CELLS_PER_ENTITY := 256
const MAX_TOTAL_SLOTS := 65_536
const MAX_DIRTY_CELLS := 65_536
const MAX_COORDINATE_ABS := 100_000
const MAX_REVISION := 9_007_199_254_740_991
const MAX_SNAPSHOT_DEPTH := 8
const MAX_CONTAINER_ITEMS := 65_536

var revision := 0
var last_error := ""
var last_callback_report: Dictionary = {}

var _category_revisions: Dictionary = {
	CATEGORY_ROUTE: 0,
	CATEGORY_DECORATION: 0,
	CATEGORY_UTILITY: 0,
}
var _slots: Dictionary = {}
var _entity_cells: Dictionary = {}
var _entity_categories: Dictionary = {}
var _dirty_cells: Dictionary = {}
var _compatibility_validator := Callable()
var _mutation_active := false


## Optional read-only boundary for World-specific rules such as pass-through
## facilities. The callback receives one defensive payload and must return a
## strict `{ok: bool, reason?: StringName, details?: Dictionary}` response.
func configure_compatibility_validator(callback: Callable = Callable()) -> bool:
	if _mutation_active:
		last_error = "Spatial subslot mutation is already active."
		return false
	_compatibility_validator = callback
	last_callback_report = {}
	last_error = ""
	return true


func place(entity_id: Variant, category: Variant, cells: Variant) -> CommandResult:
	if _mutation_active:
		return _failure(CommandResultType.Code.TRANSACTION_CLOSED, "Spatial subslot mutation is already active.")
	_mutation_active = true
	var result := _place_internal(entity_id, category, cells)
	_mutation_active = false
	return result


func remove(entity_id: Variant) -> CommandResult:
	if _mutation_active:
		return _failure(CommandResultType.Code.TRANSACTION_CLOSED, "Spatial subslot mutation is already active.")
	_mutation_active = true
	var result := _remove_internal(entity_id)
	_mutation_active = false
	return result


func replace_entity_cells(entity_id: Variant, cells: Variant) -> CommandResult:
	if _mutation_active:
		return _failure(CommandResultType.Code.TRANSACTION_CLOSED, "Spatial subslot mutation is already active.")
	_mutation_active = true
	var result := _replace_internal(entity_id, cells)
	_mutation_active = false
	return result


func has_entity(entity_id: StringName) -> bool:
	return _entity_cells.has(entity_id)


func get_entity_category(entity_id: StringName) -> StringName:
	return StringName(_entity_categories.get(entity_id, &""))


func get_entity_cells(entity_id: StringName) -> Array[Vector3i]:
	var source: Variant = _entity_cells.get(entity_id, [])
	return _copy_cells(source) if source is Array else []


func get_entity_ids(category: Variant = null) -> Array[StringName]:
	var filter_category: StringName = &""
	if category != null:
		if not _category_is_valid(category):
			return []
		filter_category = StringName(category)
	var result: Array[StringName] = []
	for entity_id: StringName in _sorted_entity_ids(_entity_cells):
		if filter_category.is_empty() or _entity_categories[entity_id] == filter_category:
			result.append(entity_id)
	return result


func get_entities(category: Variant = null) -> Array[Dictionary]:
	var result: Array[Dictionary] = []
	for entity_id: StringName in get_entity_ids(category):
		result.append({
			&"entity_id": entity_id,
			&"category": _entity_categories[entity_id],
			&"cells": get_entity_cells(entity_id),
		})
	return result


func get_slot_entity(cell: Variant, category: Variant) -> StringName:
	if not _cell_is_valid(cell) or not _category_is_valid(category):
		return &""
	var cell_slots: Variant = _slots.get(cell, {})
	if not cell_slots is Dictionary:
		return &""
	return StringName(cell_slots.get(StringName(category), &""))


func get_cell_slots(cell: Variant) -> Dictionary:
	if not _cell_is_valid(cell):
		return {}
	var source: Variant = _slots.get(cell, {})
	if not source is Dictionary:
		return {}
	var result: Dictionary = {}
	for category: StringName in CATEGORIES:
		if source.has(category):
			result[category] = StringName(source[category])
	return result


func get_cells_for_category(category: Variant) -> Array[Vector3i]:
	if not _category_is_valid(category):
		return []
	var cell_set: Dictionary = {}
	var canonical_category := StringName(category)
	for entity_id: StringName in _sorted_entity_ids(_entity_cells):
		if _entity_categories[entity_id] != canonical_category:
			continue
		for cell: Vector3i in _entity_cells[entity_id]:
			cell_set[cell] = true
	return _sorted_cells(cell_set.keys())


## Canonical passable-cell input for a future PathService graph rebuild.
func get_route_cells() -> Array[Vector3i]:
	return get_cells_for_category(CATEGORY_ROUTE)


func get_revision_for_category(category: Variant) -> int:
	if not _category_is_valid(category):
		return -1
	return int(_category_revisions[StringName(category)])


func get_dirty_revision() -> int:
	return revision


func get_dirty_cells() -> Array[Vector3i]:
	return _sorted_cells(_dirty_cells.keys())


func consume_dirty_cells() -> Array[Vector3i]:
	if _mutation_active:
		last_error = "Dirty cells cannot be consumed during a spatial mutation."
		return []
	var result := get_dirty_cells()
	_dirty_cells.clear()
	last_error = ""
	return result


func get_last_callback_report() -> Dictionary:
	return last_callback_report.duplicate(true)


func create_snapshot() -> Dictionary:
	var entities: Array[Dictionary] = []
	for entity_id: StringName in _sorted_entity_ids(_entity_cells):
		entities.append({
			&"entity_id": String(entity_id),
			&"category": String(_entity_categories[entity_id]),
			&"cells": get_entity_cells(entity_id),
		})
	return {
		&"schema_version": SNAPSHOT_SCHEMA_VERSION,
		&"revision": revision,
		&"category_revisions": {
			&"ROUTE": int(_category_revisions[CATEGORY_ROUTE]),
			&"DECORATION": int(_category_revisions[CATEGORY_DECORATION]),
			&"UTILITY": int(_category_revisions[CATEGORY_UTILITY]),
		},
		&"dirty_cells": get_dirty_cells(),
		&"entities": entities,
	}


func restore_snapshot(snapshot: Dictionary) -> bool:
	if _mutation_active:
		last_error = "Spatial subslot mutation is already active."
		return false
	_mutation_active = true
	var parsed := _parse_snapshot(snapshot)
	if not bool(parsed.get(&"ok", false)):
		_mutation_active = false
		last_error = String(parsed.get(&"message", "Spatial subslot snapshot is invalid."))
		return false
	_slots = parsed[&"slots"]
	_entity_cells = parsed[&"entity_cells"]
	_entity_categories = parsed[&"entity_categories"]
	_dirty_cells = parsed[&"dirty_cells"]
	_category_revisions = parsed[&"category_revisions"]
	revision = int(parsed[&"revision"])
	_mutation_active = false
	last_callback_report = {}
	last_error = ""
	return true


func validate_invariants() -> Dictionary:
	var errors: Array[String] = []
	if revision < 0 or revision > MAX_REVISION:
		errors.append("Revision is outside the supported range.")
	if not _dictionary_has_exact_keys(_category_revisions, CATEGORIES):
		errors.append("Category revision keys are not canonical.")
	else:
		var category_revisions_valid := true
		var latest_category_revision := 0
		for category: StringName in CATEGORIES:
			var raw_category_revision: Variant = _category_revisions[category]
			if typeof(raw_category_revision) != TYPE_INT \
					or int(raw_category_revision) < 0 \
					or int(raw_category_revision) > revision:
				errors.append("Category revision is invalid: %s" % category)
				category_revisions_valid = false
			else:
				latest_category_revision = max(latest_category_revision, int(raw_category_revision))
		if category_revisions_valid and revision > 0 and latest_category_revision != revision:
			errors.append("No category revision matches the global revision.")
	if _entity_cells.size() > MAX_ENTITIES or _slots.size() > MAX_TOTAL_SLOTS:
		errors.append("Spatial subslot capacity is exceeded.")
	if _entity_cells.size() != _entity_categories.size():
		errors.append("Entity cell/category maps differ in size.")
	var expected_slots: Dictionary = {}
	var total_slots := 0
	var valid_entity_ids: Array[StringName] = []
	for raw_entity_id: Variant in _entity_cells:
		if typeof(raw_entity_id) not in [TYPE_STRING, TYPE_STRING_NAME] \
				or not _stable_id_is_valid(raw_entity_id):
			errors.append("Entity cell map contains an invalid ID.")
			continue
		valid_entity_ids.append(StringName(raw_entity_id))
	valid_entity_ids.sort_custom(_name_less)
	for entity_id: StringName in valid_entity_ids:
		if not _stable_id_is_valid(entity_id) or not _entity_categories.has(entity_id):
			errors.append("Entity ID/category crosslink is invalid: %s" % entity_id)
			continue
		var category: Variant = _entity_categories[entity_id]
		var raw_cells: Variant = _entity_cells[entity_id]
		if not _category_is_valid(category) or not raw_cells is Array:
			errors.append("Entity category/cells are invalid: %s" % entity_id)
			continue
		var validation := _validate_cells(raw_cells)
		if not bool(validation[&"ok"]) or validation[&"cells"] != raw_cells:
			errors.append("Entity cells are invalid or unordered: %s" % entity_id)
			continue
		for cell: Vector3i in validation[&"cells"]:
			var cell_slots: Dictionary = expected_slots.get(cell, {})
			if cell_slots.has(category):
				errors.append("Two entities claim one category slot at %s." % cell)
			else:
				cell_slots[category] = entity_id
				expected_slots[cell] = cell_slots
				total_slots += 1
	if total_slots > MAX_TOTAL_SLOTS:
		errors.append("Total occupied subslots exceed the capacity.")
	if expected_slots != _slots:
		errors.append("Cell/entity/category crosslinks do not match.")
	if _dirty_cells.size() > MAX_DIRTY_CELLS:
		errors.append("Dirty-cell capacity is exceeded.")
	for raw_cell: Variant in _dirty_cells:
		if not _cell_is_valid(raw_cell) \
				or typeof(_dirty_cells[raw_cell]) != TYPE_BOOL \
				or not bool(_dirty_cells[raw_cell]):
			errors.append("Dirty cell is invalid.")
	return {&"ok": errors.is_empty(), &"errors": errors}


func _place_internal(entity_id_value: Variant, category_value: Variant, cells_value: Variant) -> CommandResult:
	var identity := _parse_identity(entity_id_value, category_value)
	if not bool(identity[&"ok"]):
		return _failure(CommandResultType.Code.INVALID_PAYLOAD, String(identity[&"message"]))
	var entity_id: StringName = identity[&"entity_id"]
	var category: StringName = identity[&"category"]
	if _entity_cells.has(entity_id):
		return _failure(CommandResultType.Code.DUPLICATE_COMMAND_ID, "Spatial entity ID already exists.")
	if _entity_cells.size() >= MAX_ENTITIES:
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial entity capacity is exhausted.")
	var cell_validation := _validate_cells(cells_value)
	if not bool(cell_validation[&"ok"]):
		return _failure(CommandResultType.Code.INVALID_PAYLOAD, String(cell_validation[&"message"]))
	var cells: Array[Vector3i] = cell_validation[&"cells"]
	var current_total := _total_occupied_slots()
	if current_total > MAX_TOTAL_SLOTS - cells.size():
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial subslot capacity is exhausted.")
	for cell: Vector3i in cells:
		var cell_slots: Dictionary = _slots.get(cell, {})
		if cell_slots.has(category):
			return _failure(
				CommandResultType.Code.VALIDATION_FAILED,
				"Spatial category slot is already occupied.",
				{&"cell": cell, &"category": category, &"occupant_id": cell_slots[category]}
			)
	if not _dirty_capacity_allows(cells):
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Dirty-cell capacity is exhausted.")
	if revision >= MAX_REVISION:
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial revision limit is exhausted.")
	var payload := _mutation_payload(&"PLACE", entity_id, category, [], cells)
	var boundary := _validate_external_boundary(payload)
	if not bool(boundary[&"ok"]):
		return _failure(
			CommandResultType.Code.TRANSACTION_APPLY_FAILED,
			String(boundary[&"message"]),
			boundary.get(&"details", {})
		)
	for cell: Vector3i in cells:
		var cell_slots: Dictionary = _slots.get(cell, {})
		cell_slots[category] = entity_id
		_slots[cell] = cell_slots
	_entity_cells[entity_id] = cells.duplicate()
	_entity_categories[entity_id] = category
	_mark_changed(category, cells)
	entity_placed.emit(entity_id, category, cells.duplicate())
	last_error = ""
	return _success({
		&"entity_id": entity_id,
		&"category": category,
		&"cells": cells.duplicate(),
		&"revision": revision,
		&"changed": true,
	})


func _remove_internal(entity_id_value: Variant) -> CommandResult:
	if not _stable_id_is_valid(entity_id_value):
		return _failure(CommandResultType.Code.INVALID_PAYLOAD, "Spatial entity ID is invalid.")
	var entity_id := StringName(entity_id_value)
	if not _entity_cells.has(entity_id):
		return _failure(CommandResultType.Code.NOT_FOUND, "Spatial entity was not found.")
	var category: StringName = _entity_categories[entity_id]
	var cells := get_entity_cells(entity_id)
	if not _dirty_capacity_allows(cells):
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Dirty-cell capacity is exhausted.")
	if revision >= MAX_REVISION:
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial revision limit is exhausted.")
	var boundary := _validate_external_boundary(
		_mutation_payload(&"REMOVE", entity_id, category, cells, [])
	)
	if not bool(boundary[&"ok"]):
		return _failure(
			CommandResultType.Code.TRANSACTION_APPLY_FAILED,
			String(boundary[&"message"]),
			boundary.get(&"details", {})
		)
	for cell: Vector3i in cells:
		var cell_slots: Dictionary = _slots.get(cell, {})
		if cell_slots.get(category, &"") == entity_id:
			cell_slots.erase(category)
			if cell_slots.is_empty():
				_slots.erase(cell)
			else:
				_slots[cell] = cell_slots
	_entity_cells.erase(entity_id)
	_entity_categories.erase(entity_id)
	_mark_changed(category, cells)
	entity_removed.emit(entity_id, category, cells.duplicate())
	last_error = ""
	return _success({
		&"entity_id": entity_id,
		&"category": category,
		&"cells": cells,
		&"revision": revision,
		&"changed": true,
	})


func _replace_internal(entity_id_value: Variant, cells_value: Variant) -> CommandResult:
	if not _stable_id_is_valid(entity_id_value):
		return _failure(CommandResultType.Code.INVALID_PAYLOAD, "Spatial entity ID is invalid.")
	var entity_id := StringName(entity_id_value)
	if not _entity_cells.has(entity_id):
		return _failure(CommandResultType.Code.NOT_FOUND, "Spatial entity was not found.")
	var validation := _validate_cells(cells_value)
	if not bool(validation[&"ok"]):
		return _failure(CommandResultType.Code.INVALID_PAYLOAD, String(validation[&"message"]))
	var after_cells: Array[Vector3i] = validation[&"cells"]
	var before_cells := get_entity_cells(entity_id)
	var category: StringName = _entity_categories[entity_id]
	if before_cells == after_cells:
		last_error = ""
		return _success({
			&"entity_id": entity_id,
			&"category": category,
			&"cells": after_cells.duplicate(),
			&"revision": revision,
			&"changed": false,
		})
	var projected_total := _total_occupied_slots() - before_cells.size() + after_cells.size()
	if projected_total > MAX_TOTAL_SLOTS:
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial subslot capacity is exhausted.")
	for cell: Vector3i in after_cells:
		var occupant := get_slot_entity(cell, category)
		if not occupant.is_empty() and occupant != entity_id:
			return _failure(
				CommandResultType.Code.VALIDATION_FAILED,
				"Spatial category slot is already occupied.",
				{&"cell": cell, &"category": category, &"occupant_id": occupant}
			)
	var dirty_union: Dictionary = {}
	for cell: Vector3i in before_cells:
		dirty_union[cell] = true
	for cell: Vector3i in after_cells:
		dirty_union[cell] = true
	var dirty_cells := _sorted_cells(dirty_union.keys())
	if not _dirty_capacity_allows(dirty_cells):
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Dirty-cell capacity is exhausted.")
	if revision >= MAX_REVISION:
		return _failure(CommandResultType.Code.VALIDATION_FAILED, "Spatial revision limit is exhausted.")
	var boundary := _validate_external_boundary(
		_mutation_payload(&"REPLACE", entity_id, category, before_cells, after_cells)
	)
	if not bool(boundary[&"ok"]):
		return _failure(
			CommandResultType.Code.TRANSACTION_APPLY_FAILED,
			String(boundary[&"message"]),
			boundary.get(&"details", {})
		)
	for cell: Vector3i in before_cells:
		var cell_slots: Dictionary = _slots.get(cell, {})
		if cell_slots.get(category, &"") == entity_id:
			cell_slots.erase(category)
			if cell_slots.is_empty():
				_slots.erase(cell)
			else:
				_slots[cell] = cell_slots
	for cell: Vector3i in after_cells:
		var cell_slots: Dictionary = _slots.get(cell, {})
		cell_slots[category] = entity_id
		_slots[cell] = cell_slots
	_entity_cells[entity_id] = after_cells.duplicate()
	_mark_changed(category, dirty_cells)
	entity_cells_replaced.emit(
		entity_id,
		category,
		before_cells.duplicate(),
		after_cells.duplicate()
	)
	last_error = ""
	return _success({
		&"entity_id": entity_id,
		&"category": category,
		&"before_cells": before_cells,
		&"cells": after_cells.duplicate(),
		&"revision": revision,
		&"changed": true,
	})


func _validate_external_boundary(payload: Dictionary) -> Dictionary:
	last_callback_report = {}
	if not _compatibility_validator.is_valid():
		return {&"ok": true, &"message": "", &"details": {}}
	var before := _capture_internal_state()
	var raw_response: Variant = _compatibility_validator.call(payload.duplicate(true))
	var tampered := not _internal_state_matches(before)
	if tampered:
		_restore_internal_state(before)
	var response_ok := false
	var response_reason: StringName = &""
	var response_details: Dictionary = {}
	var response_valid := raw_response is Dictionary
	if response_valid:
		var response: Dictionary = raw_response
		response_valid = _dictionary_has_only_keys(response, [&"ok", &"reason", &"details"])
		var raw_ok: Variant = response.get(&"ok", null)
		response_valid = response_valid and typeof(raw_ok) == TYPE_BOOL
		if response.has(&"reason"):
			response_valid = response_valid and typeof(response[&"reason"]) in [TYPE_STRING, TYPE_STRING_NAME]
		if response.has(&"details"):
			response_valid = response_valid \
				and response[&"details"] is Dictionary \
				and _variant_depth_is_valid(response[&"details"], 0)
		if response_valid:
			response_ok = bool(raw_ok)
			response_reason = StringName(response.get(&"reason", &""))
			response_details = (response.get(&"details", {}) as Dictionary).duplicate(true)
	last_callback_report = {
		&"ok": response_ok and not tampered,
		&"response_valid": response_valid,
		&"tampered": tampered,
		&"reason": response_reason,
		&"details": response_details.duplicate(true),
	}
	if tampered:
		return {
			&"ok": false,
			&"message": "Compatibility callback mutated SpatialSubslotService and was rolled back.",
			&"details": {&"reason": &"CALLBACK_TAMPERED", &"rollback_ok": true},
		}
	if not response_valid:
		return {
			&"ok": false,
			&"message": "Compatibility callback returned an invalid response.",
			&"details": {&"reason": &"INVALID_CALLBACK_RESPONSE", &"rollback_ok": true},
		}
	if not response_ok:
		return {
			&"ok": false,
			&"message": "Compatibility callback rejected the spatial mutation.",
			&"details": {
				&"reason": response_reason if not response_reason.is_empty() else &"COMPATIBILITY_REJECTED",
				&"callback_details": response_details,
				&"rollback_ok": true,
			},
		}
	return {&"ok": true, &"message": "", &"details": response_details}


func _capture_internal_state() -> Dictionary:
	return {
		&"mutation_active": _mutation_active,
		&"compatibility_validator": _compatibility_validator,
		&"revision": revision,
		&"category_revisions": _category_revisions.duplicate(true),
		&"slots": _slots.duplicate(true),
		&"entity_cells": _entity_cells.duplicate(true),
		&"entity_categories": _entity_categories.duplicate(true),
		&"dirty_cells": _dirty_cells.duplicate(true),
	}


func _internal_state_matches(capture: Dictionary) -> bool:
	return (
		_mutation_active == bool(capture[&"mutation_active"])
		and _compatibility_validator == capture[&"compatibility_validator"]
		and revision == int(capture[&"revision"])
		and _category_revisions == capture[&"category_revisions"]
		and _slots == capture[&"slots"]
		and _entity_cells == capture[&"entity_cells"]
		and _entity_categories == capture[&"entity_categories"]
		and _dirty_cells == capture[&"dirty_cells"]
	)


func _restore_internal_state(capture: Dictionary) -> void:
	_mutation_active = bool(capture[&"mutation_active"])
	_compatibility_validator = capture[&"compatibility_validator"]
	revision = int(capture[&"revision"])
	_category_revisions = (capture[&"category_revisions"] as Dictionary).duplicate(true)
	_slots = (capture[&"slots"] as Dictionary).duplicate(true)
	_entity_cells = (capture[&"entity_cells"] as Dictionary).duplicate(true)
	_entity_categories = (capture[&"entity_categories"] as Dictionary).duplicate(true)
	_dirty_cells = (capture[&"dirty_cells"] as Dictionary).duplicate(true)


func _mark_changed(category: StringName, cells: Array[Vector3i]) -> void:
	revision += 1
	_category_revisions[category] = revision
	for cell: Vector3i in cells:
		_dirty_cells[cell] = true


func _dirty_capacity_allows(cells: Array[Vector3i]) -> bool:
	var additional := 0
	for cell: Vector3i in cells:
		if not _dirty_cells.has(cell):
			additional += 1
	return _dirty_cells.size() <= MAX_DIRTY_CELLS - additional


func _total_occupied_slots() -> int:
	var total := 0
	for entity_id: StringName in _sorted_entity_ids(_entity_cells):
		var cells: Variant = _entity_cells[entity_id]
		if cells is Array:
			total += cells.size()
	return total


static func _mutation_payload(
	operation: StringName,
	entity_id: StringName,
	category: StringName,
	before_cells: Array[Vector3i],
	after_cells: Array[Vector3i]
) -> Dictionary:
	return {
		&"operation": operation,
		&"entity_id": entity_id,
		&"category": category,
		&"before_cells": before_cells.duplicate(),
		&"after_cells": after_cells.duplicate(),
	}


static func _parse_snapshot(snapshot: Dictionary) -> Dictionary:
	if not _variant_depth_is_valid(snapshot, 0):
		return {&"ok": false, &"message": "Snapshot depth or container capacity is exceeded."}
	if not _dictionary_has_exact_keys(snapshot, [
		&"schema_version", &"revision", &"category_revisions", &"dirty_cells", &"entities",
	]):
		return {&"ok": false, &"message": "Snapshot top-level fields are not canonical."}
	if typeof(snapshot[&"schema_version"]) != TYPE_INT \
			or int(snapshot[&"schema_version"]) != SNAPSHOT_SCHEMA_VERSION:
		return {&"ok": false, &"message": "Unsupported SpatialSubslotService snapshot version."}
	if typeof(snapshot[&"revision"]) != TYPE_INT:
		return {&"ok": false, &"message": "Snapshot revision must be an integer."}
	var next_revision := int(snapshot[&"revision"])
	if next_revision < 0 or next_revision > MAX_REVISION:
		return {&"ok": false, &"message": "Snapshot revision is outside the supported range."}
	if not snapshot[&"category_revisions"] is Dictionary \
			or not _dictionary_has_exact_keys(snapshot[&"category_revisions"], CATEGORIES):
		return {&"ok": false, &"message": "Snapshot category revisions are malformed."}
	var next_category_revisions: Dictionary = {}
	var latest_category_revision := 0
	for category: StringName in CATEGORIES:
		var raw_category_revision: Variant = snapshot[&"category_revisions"][category]
		if typeof(raw_category_revision) != TYPE_INT \
				or int(raw_category_revision) < 0 \
				or int(raw_category_revision) > next_revision:
			return {&"ok": false, &"message": "Snapshot category revision is invalid."}
		next_category_revisions[category] = int(raw_category_revision)
		latest_category_revision = max(latest_category_revision, int(raw_category_revision))
	if next_revision > 0 and latest_category_revision != next_revision:
		return {&"ok": false, &"message": "Snapshot has no category at the global revision."}

	if not snapshot[&"entities"] is Array or snapshot[&"entities"].size() > MAX_ENTITIES:
		return {&"ok": false, &"message": "Snapshot entity collection is malformed or too large."}
	var next_slots: Dictionary = {}
	var next_entity_cells: Dictionary = {}
	var next_entity_categories: Dictionary = {}
	var total_slots := 0
	var previous_entity_id := ""
	for raw_entity: Variant in snapshot[&"entities"]:
		if not raw_entity is Dictionary or not _dictionary_has_exact_keys(raw_entity, [
			&"entity_id", &"category", &"cells",
		]):
			return {&"ok": false, &"message": "Snapshot entity entry is malformed."}
		if typeof(raw_entity[&"entity_id"]) not in [TYPE_STRING, TYPE_STRING_NAME]:
			return {&"ok": false, &"message": "Snapshot entity ID must be a string."}
		var entity_id := StringName(raw_entity[&"entity_id"])
		var entity_text := String(entity_id)
		if not _stable_id_is_valid(entity_id) \
				or (not previous_entity_id.is_empty() and entity_text <= previous_entity_id):
			return {&"ok": false, &"message": "Snapshot entity IDs are invalid, duplicated, or unordered."}
		if not _category_is_valid(raw_entity[&"category"]):
			return {&"ok": false, &"message": "Snapshot entity category is invalid."}
		var category := StringName(raw_entity[&"category"])
		var cells_validation := _validate_cells(raw_entity[&"cells"])
		if not bool(cells_validation[&"ok"]):
			return {&"ok": false, &"message": String(cells_validation[&"message"])}
		var cells: Array[Vector3i] = cells_validation[&"cells"]
		if raw_entity[&"cells"] != cells:
			return {&"ok": false, &"message": "Snapshot entity cells are not canonically ordered."}
		if total_slots > MAX_TOTAL_SLOTS - cells.size():
			return {&"ok": false, &"message": "Snapshot occupied subslot capacity is exceeded."}
		for cell: Vector3i in cells:
			var cell_slots: Dictionary = next_slots.get(cell, {})
			if cell_slots.has(category):
				return {&"ok": false, &"message": "Snapshot contains a duplicate category slot."}
			cell_slots[category] = entity_id
			next_slots[cell] = cell_slots
		next_entity_cells[entity_id] = cells
		next_entity_categories[entity_id] = category
		total_slots += cells.size()
		previous_entity_id = entity_text

	if not snapshot[&"dirty_cells"] is Array or snapshot[&"dirty_cells"].size() > MAX_DIRTY_CELLS:
		return {&"ok": false, &"message": "Snapshot dirty-cell collection is malformed or too large."}
	var next_dirty: Dictionary = {}
	var previous_dirty: Variant = null
	for raw_cell: Variant in snapshot[&"dirty_cells"]:
		if not _cell_is_valid(raw_cell) or next_dirty.has(raw_cell):
			return {&"ok": false, &"message": "Snapshot dirty cell is invalid or duplicated."}
		var cell: Vector3i = raw_cell
		if previous_dirty is Vector3i and not _cell_less(previous_dirty, cell):
			return {&"ok": false, &"message": "Snapshot dirty cells are not canonically ordered."}
		next_dirty[cell] = true
		previous_dirty = cell
	if next_revision == 0 and (not next_entity_cells.is_empty() or not next_dirty.is_empty()):
		return {&"ok": false, &"message": "Zero revision cannot own entities or dirty cells."}
	for category: StringName in CATEGORIES:
		if int(next_category_revisions[category]) == 0:
			for entity_id: StringName in _sorted_entity_ids(next_entity_cells):
				if next_entity_categories[entity_id] == category:
					return {&"ok": false, &"message": "Occupied category must have a positive revision."}
	return {
		&"ok": true,
		&"revision": next_revision,
		&"category_revisions": next_category_revisions,
		&"slots": next_slots,
		&"entity_cells": next_entity_cells,
		&"entity_categories": next_entity_categories,
		&"dirty_cells": next_dirty,
	}


static func _parse_identity(entity_id_value: Variant, category_value: Variant) -> Dictionary:
	if not _stable_id_is_valid(entity_id_value):
		return {&"ok": false, &"message": "Spatial entity ID is invalid."}
	if not _category_is_valid(category_value):
		return {&"ok": false, &"message": "Spatial category is invalid."}
	return {
		&"ok": true,
		&"entity_id": StringName(entity_id_value),
		&"category": StringName(category_value),
	}


static func _validate_cells(value: Variant) -> Dictionary:
	if not value is Array:
		return {&"ok": false, &"message": "Spatial cells must be an Array.", &"cells": []}
	if value.is_empty() or value.size() > MAX_CELLS_PER_ENTITY:
		return {
			&"ok": false,
			&"message": "Spatial cells must be non-empty and within the per-entity limit.",
			&"cells": [],
		}
	var seen: Dictionary = {}
	var cells: Array[Vector3i] = []
	for raw_cell: Variant in value:
		if not _cell_is_valid(raw_cell):
			return {&"ok": false, &"message": "Spatial cell type, coordinate, or layer is invalid.", &"cells": []}
		var cell: Vector3i = raw_cell
		if seen.has(cell):
			return {&"ok": false, &"message": "Spatial cells contain a duplicate.", &"cells": []}
		seen[cell] = true
		cells.append(cell)
	cells.sort_custom(_cell_less)
	return {&"ok": true, &"message": "", &"cells": cells}


static func _stable_id_is_valid(value: Variant) -> bool:
	if typeof(value) not in [TYPE_STRING, TYPE_STRING_NAME]:
		return false
	var text := String(value)
	if text.is_empty() or text.length() > MAX_ENTITY_ID_LENGTH:
		return false
	for index: int in range(text.length()):
		var code := text.unicode_at(index)
		var allowed := (
			code >= 48 and code <= 57
			or code >= 65 and code <= 90
			or code >= 97 and code <= 122
			or code in [45, 46, 58, 64, 95]
		)
		if not allowed:
			return false
	return true


static func _category_is_valid(value: Variant) -> bool:
	return typeof(value) in [TYPE_STRING, TYPE_STRING_NAME] and CATEGORIES.has(StringName(value))


static func _cell_is_valid(value: Variant) -> bool:
	if not value is Vector3i:
		return false
	var cell: Vector3i = value
	return (
		cell.z in [LAYER_FRONT, LAYER_BACK]
		and cell.x >= -MAX_COORDINATE_ABS
		and cell.x <= MAX_COORDINATE_ABS
		and cell.y >= -MAX_COORDINATE_ABS
		and cell.y <= MAX_COORDINATE_ABS
	)


static func _sorted_entity_ids(source: Dictionary) -> Array[StringName]:
	var result: Array[StringName] = []
	for raw_entity_id: Variant in source:
		result.append(StringName(raw_entity_id))
	result.sort_custom(_name_less)
	return result


static func _copy_cells(source: Array) -> Array[Vector3i]:
	var result: Array[Vector3i] = []
	for raw_cell: Variant in source:
		if raw_cell is Vector3i:
			result.append(raw_cell)
	result.sort_custom(_cell_less)
	return result


static func _sorted_cells(source: Variant) -> Array[Vector3i]:
	var result: Array[Vector3i] = []
	if not source is Array:
		return result
	for raw_cell: Variant in source:
		if raw_cell is Vector3i:
			result.append(raw_cell)
	result.sort_custom(_cell_less)
	return result


static func _cell_less(left: Vector3i, right: Vector3i) -> bool:
	if left.y != right.y:
		return left.y < right.y
	if left.x != right.x:
		return left.x < right.x
	return left.z < right.z


static func _name_less(left: StringName, right: StringName) -> bool:
	return String(left) < String(right)


static func _dictionary_has_exact_keys(source: Dictionary, expected: Array) -> bool:
	if source.size() != expected.size():
		return false
	for key: Variant in expected:
		if not source.has(key):
			return false
	return true


static func _dictionary_has_only_keys(source: Dictionary, allowed: Array) -> bool:
	for key: Variant in source:
		if typeof(key) not in [TYPE_STRING, TYPE_STRING_NAME] or not allowed.has(StringName(key)):
			return false
	return source.has(&"ok") or source.has("ok")


static func _variant_depth_is_valid(value: Variant, depth: int) -> bool:
	if depth > MAX_SNAPSHOT_DEPTH:
		return false
	if value is Array:
		if value.size() > MAX_CONTAINER_ITEMS:
			return false
		for child: Variant in value:
			if not _variant_depth_is_valid(child, depth + 1):
				return false
	elif value is Dictionary:
		if value.size() > MAX_CONTAINER_ITEMS:
			return false
		for key: Variant in value:
			if not _variant_depth_is_valid(key, depth + 1) \
					or not _variant_depth_is_valid(value[key], depth + 1):
				return false
	elif typeof(value) in [TYPE_OBJECT, TYPE_CALLABLE, TYPE_SIGNAL, TYPE_RID]:
		return false
	return true


func _success(details: Dictionary = {}) -> CommandResult:
	last_error = ""
	return CommandResultType.succeeded(0, details)


func _failure(code: CommandResult.Code, message: String, details: Dictionary = {}) -> CommandResult:
	last_error = message
	return CommandResultType.failed(code, 0, message, details)