gamedev-the-steward/tests/simulation_state_serialization_test.gd

extends SceneTree

var failures: Array[String] = []


func _initialize() -> void:
	call_deferred("_run")


func _run() -> void:
	await _test_deterministic_continuation()
	await _test_resource_state_round_trip()
	_test_legacy_npc_migration()
	_test_legacy_resource_migration()
	_test_legacy_world_storage_migration()
	_test_previous_world_event_migration()
	_test_previous_world_relationship_migration()
	_test_previous_world_knowledge_migration()
	_test_previous_world_provenance_migration()
	_test_previous_world_retention_migration()
	_test_previous_world_opportunity_migration()
	_test_previous_world_animal_migration()
	_test_previous_world_routine_migration()
	_test_relationship_schema_rejection()
	_test_opportunity_schema_rejection()
	_test_animal_schema_rejection()
	_test_storage_schema_rejection()
	_test_schema_rejection()

	if failures.is_empty():
		print("[TEST] Simulation state serialization passed")
		quit(0)
		return

	for failure in failures:
		push_error("[TEST] " + failure)
	quit(1)


func _test_deterministic_continuation() -> void:
	var uninterrupted := _create_manager(91234)
	_advance_scenario(uninterrupted, 24)
	uninterrupted.clock.advance(0.5)
	_advance_scenario(uninterrupted, 24)
	var uninterrupted_checksum: String = uninterrupted.get_state_checksum()

	var before_save := _create_manager(91234)
	_advance_scenario(before_save, 24)
	before_save.clock.advance(0.5)
	var saved_json: String = before_save.serialize_state()

	var restored := _create_manager(1)
	_check(
		restored.restore_state_from_json(saved_json),
		"A valid versioned state should restore into a fresh manager"
	)
	_check(restored.tick_count == 24, "Tick count should survive restoration")
	_check(
		is_equal_approx(restored.clock.accumulator, 0.5),
		"Clock remainder should survive restoration"
	)
	_advance_scenario(restored, 24)
	var restored_checksum: String = restored.get_state_checksum()
	if restored_checksum != uninterrupted_checksum:
		print(
			"[TEST] uninterrupted=",
			uninterrupted.serialize_state(),
			"\n[TEST] restored=",
			restored.serialize_state()
		)
	_check(
		restored_checksum == uninterrupted_checksum,
		"Restored simulation should match uninterrupted deterministic continuation"
	)

	uninterrupted.free()
	before_save.free()
	restored.free()


func _test_resource_state_round_trip() -> void:
	var resource: ResourceNode = load("res://world/resource_nodes/ResourceNode.tscn").instantiate()
	resource.node_id = &"SerializationTestBerry"
	resource.initial_amount = 9.0
	resource.yield_per_action = 2.0
	root.add_child(resource)
	await process_frame

	var manager := _create_manager(77)
	_check(
		manager.register_resource_node(resource),
		"Resource presentation should bind to simulation authority"
	)
	var resource_state: ResourceStateRecord = manager.get_resource_state(resource.node_id)
	_check(resource_state.reserve(42), "Resource should accept the test reservation")
	resource_state.extract()
	var saved_json: String = manager.serialize_state()
	resource.free()

	_check(
		is_equal_approx(resource_state.get_amount_remaining(), 7.0),
		"Resource state should survive without its presentation node"
	)
	resource_state.extract(5.0)
	resource_state.release(42)
	resource_state.set_enabled(false)

	_check(
		manager.restore_state_from_json(saved_json),
		"Unloaded resource state should restore with the simulation record"
	)
	resource_state = manager.get_resource_state(&"SerializationTestBerry")
	_check(
		is_equal_approx(resource_state.get_amount_remaining(), 7.0),
		"Resource amount should round-trip"
	)
	_check(resource_state.get_reserved_by() == 42, "Resource reservation should round-trip")
	_check(resource_state.is_enabled(), "Resource enabled state should round-trip")

	var rebound: ResourceNode = load("res://world/resource_nodes/ResourceNode.tscn").instantiate()
	rebound.node_id = &"SerializationTestBerry"
	rebound.initial_amount = 999.0
	root.add_child(rebound)
	await process_frame
	_check(
		rebound.state == resource_state,
		"Reloaded presentation should bind to the existing authoritative record"
	)
	_check(
		is_equal_approx(rebound.get_amount_remaining(), 7.0),
		"Reloaded presentation must not overwrite authoritative amount"
	)

	manager.free()
	rebound.free()


func _test_schema_rejection() -> void:
	var unsupported := JSON.stringify(
		{"schema": SimulationStateRecord.SCHEMA_NAME, "schema_version": 999}
	)
	_check(
		SimulationStateRecord.from_json(unsupported) == null,
		"Unsupported schema versions should be rejected"
	)
	_check(SimulationStateRecord.from_json("[]") == null, "Non-record JSON should be rejected")

	var manager := _create_manager(41)
	var invalid_clock_data: Dictionary = manager.create_state_record().to_dictionary()
	invalid_clock_data["simulation"]["tick_interval"] = 0.0
	_check(
		SimulationStateRecord.from_dictionary(invalid_clock_data) == null,
		"Saved simulation clocks with a zero tick interval should be rejected"
	)
	manager.free()


func _test_storage_schema_rejection() -> void:
	var valid_storage := (
		StorageStateRecord
		. create(&"schema_test_storage", {String(SimulationIds.RESOURCE_FOOD): 1.0}, 2.0)
		. to_dictionary()
	)

	var negative_amount := valid_storage.duplicate(true)
	negative_amount["amounts"][String(SimulationIds.RESOURCE_FOOD)] = -1.0
	_check(
		StorageStateRecord.from_dictionary(negative_amount) == null,
		"Storage records should reject negative item amounts"
	)

	var non_finite_amount := valid_storage.duplicate(true)
	non_finite_amount["amounts"][String(SimulationIds.RESOURCE_FOOD)] = NAN
	_check(
		StorageStateRecord.from_dictionary(non_finite_amount) == null,
		"Storage records should reject non-finite item amounts"
	)

	var invalid_capacity := valid_storage.duplicate(true)
	invalid_capacity["capacity"] = -1.0
	_check(
		StorageStateRecord.from_dictionary(invalid_capacity) == null,
		"Storage records should reject negative capacity"
	)

	var over_capacity := valid_storage.duplicate(true)
	over_capacity["amounts"][String(SimulationIds.RESOURCE_FOOD)] = 3.0
	_check(
		StorageStateRecord.from_dictionary(over_capacity) == null,
		"Storage records should reject contents above capacity"
	)

	var empty_item_id := valid_storage.duplicate(true)
	empty_item_id["amounts"] = {"": 1.0}
	_check(
		StorageStateRecord.from_dictionary(empty_item_id) == null,
		"Storage records should reject empty item IDs"
	)

	var storage := StorageStateRecord.from_dictionary(valid_storage)
	_check(storage != null, "A valid bounded storage record should still parse")
	if storage != null:
		_check(
			storage.deposit(SimulationIds.RESOURCE_FOOD, NAN) == 0.0,
			"Storage deposits should reject non-finite requests"
		)
		_check(
			storage.withdraw(SimulationIds.RESOURCE_FOOD, INF) == 0.0,
			"Storage withdrawals should reject non-finite requests"
		)
		_check(
			is_equal_approx(storage.get_amount(SimulationIds.RESOURCE_FOOD), 1.0),
			"Rejected storage requests should not mutate authoritative stock"
		)

	var manager := _create_manager(42)
	var mismatched_food: Dictionary = manager.create_state_record().to_dictionary()
	mismatched_food["village"]["food"] = float(mismatched_food["village"]["food"]) + 1.0
	_check(
		SimulationStateRecord.from_dictionary(mismatched_food) == null,
		"World records should reject village food that disagrees with pantry authority"
	)
	var mismatched_wood: Dictionary = manager.create_state_record().to_dictionary()
	mismatched_wood["village"]["wood"] = float(mismatched_wood["village"]["wood"]) + 1.0
	_check(
		SimulationStateRecord.from_dictionary(mismatched_wood) == null,
		"World records should reject village wood that disagrees with woodpile authority"
	)
	manager.free()


func _test_legacy_resource_migration() -> void:
	var migrated := ResourceStateRecord.from_dictionary(
		{
			"schema_version": 1,
			"node_id": "legacy_tree",
			"amount_remaining": 6.0,
			"reserved_by": 12,
			"enabled": true
		}
	)
	_check(migrated != null, "ResourceStateRecord v1 should migrate explicitly")
	if migrated == null:
		return
	_check(
		migrated.data["schema_version"] == ResourceStateRecord.SCHEMA_VERSION,
		"Migrated resource state should use the current nested schema"
	)
	_check(
		is_equal_approx(migrated.get_amount_remaining(), 6.0) and migrated.get_reserved_by() == 12,
		"Resource migration should preserve mutable authority"
	)
	_check(
		(
			is_equal_approx(migrated.get_safety_risk(), 0.0)
			and is_equal_approx(migrated.get_comfort_distance(), 18.0)
		),
		"Resource migration should default discovery metadata"
	)


func _test_legacy_npc_migration() -> void:
	var npc := SimNPC.new(88, "LegacyNPC", SimulationIds.PROFESSION_FARMER, 5.0, 5.0)
	var legacy_data := NPCStateRecord.capture(npc).to_dictionary()
	legacy_data["schema_version"] = NPCStateRecord.LEGACY_SCHEMA_VERSION
	legacy_data.erase("travel_target_position")
	legacy_data.erase("has_travel_target")
	var migrated := NPCStateRecord.from_dictionary(legacy_data)
	_check(migrated != null, "NPCStateRecord v1 should migrate explicitly")
	if migrated == null:
		return
	_check(
		not bool(migrated.data["has_travel_target"]),
		"Legacy NPC migration should not invent an active travel target"
	)


func _test_legacy_world_storage_migration() -> void:
	var manager := _create_manager(55)
	var legacy_data: Dictionary = manager.create_state_record().to_dictionary()
	legacy_data["schema_version"] = SimulationStateRecord.LEGACY_SCHEMA_VERSION
	legacy_data.erase("storages")
	var legacy_food := StorageStateRecord.DEFAULT_CAPACITY + 25.0
	var legacy_wood := StorageStateRecord.DEFAULT_CAPACITY + 35.0
	legacy_data["village"]["food"] = legacy_food
	legacy_data["village"]["wood"] = legacy_wood
	var migrated := SimulationStateRecord.from_dictionary(legacy_data)
	_check(migrated != null, "World schema v1 should migrate authored storage")
	if migrated != null:
		var migrated_storages := {}
		for storage in migrated.storages:
			migrated_storages[storage.get_storage_id()] = storage
		var pantry: StorageStateRecord = migrated_storages.get(SimulationIds.STORAGE_VILLAGE_PANTRY)
		var woodpile: StorageStateRecord = migrated_storages.get(
			SimulationIds.STORAGE_VILLAGE_WOODPILE
		)
		_check(
			(
				pantry != null
				and woodpile != null
				and is_equal_approx(pantry.get_amount(SimulationIds.RESOURCE_FOOD), legacy_food)
				and is_equal_approx(woodpile.get_amount(SimulationIds.RESOURCE_WOOD), legacy_wood)
				and is_equal_approx(pantry.get_available_capacity(), 0.0)
				and is_equal_approx(woodpile.get_available_capacity(), 0.0)
			),
			"World migration should preserve legacy stock above the default storage capacity"
		)
	manager.free()


func _test_previous_world_event_migration() -> void:
	var manager := _create_manager(56)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.EVENT_LEGACY_SCHEMA_VERSION
	previous_data.erase("economic_events")
	previous_data["simulation"].erase("next_event_id")
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v2 should add an empty event stream")
	if migrated != null:
		_check(
			migrated.economic_events.is_empty() and int(migrated.simulation["next_event_id"]) == 0,
			"World v2 migration should initialize deterministic event identity"
		)
	manager.free()


func _test_previous_world_relationship_migration() -> void:
	var manager := _create_manager(57)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.RELATIONSHIP_LEGACY_SCHEMA_VERSION
	previous_data.erase("relationships")
	previous_data.erase("event_knowledge")
	for npc_data in previous_data["npcs"]:
		npc_data["schema_version"] = NPCStateRecord.RELATIONSHIP_LEGACY_SCHEMA_VERSION
		npc_data["familiarity"] = []
	previous_data["npcs"][0]["familiarity"] = [{"id": 1, "score": 0.75}]
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v3 should migrate NPC familiarity into relationships")
	if migrated != null:
		_check(
			(
				migrated.relationships.size() == 1
				and migrated.relationships[0].get_observer_id() == 0
				and migrated.relationships[0].get_subject_id() == 1
				and is_equal_approx(migrated.relationships[0].get_familiarity(), 0.75)
				and is_equal_approx(
					migrated.relationships[0].get_trust(), RelationshipStateRecord.NEUTRAL_TRUST
				)
			),
			"World v3 migration should preserve familiarity and initialize neutral trust"
		)
		_check(
			not migrated.npcs[0].data.has("familiarity"),
			"World v3 migration should remove obsolete NPC-local familiarity data"
		)
	manager.free()


func _test_previous_world_knowledge_migration() -> void:
	var manager := _create_manager(59)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.KNOWLEDGE_LEGACY_SCHEMA_VERSION
	previous_data.erase("event_knowledge")
	var deposit_event := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		1,
		SimulationIds.npc_inventory_id(1),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		2.0
	)
	previous_data["economic_events"] = [deposit_event.to_dictionary()]
	previous_data["simulation"]["next_event_id"] = 1
	previous_data["relationships"] = [
		RelationshipStateRecord.create(0, 1, 0.5, 0.65, 0).to_dictionary()
	]
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v4 should migrate causal facts into NPC knowledge")
	if migrated != null:
		_check(
			(
				migrated.event_knowledge.size() == 1
				and migrated.event_knowledge[0].get_knower_id() == 0
				and migrated.event_knowledge[0].get_event_id() == 0
				and (
					migrated.event_knowledge[0].get_acquisition_method()
					== SimulationIds.KNOWLEDGE_ACQUISITION_LEGACY
				)
			),
			"World v4 migration should preserve the fact implied by a relationship cause"
		)
	manager.free()


func _test_previous_world_provenance_migration() -> void:
	var manager := _create_manager(60)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.PROVENANCE_LEGACY_SCHEMA_VERSION
	var deposit_event := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		1,
		SimulationIds.npc_inventory_id(1),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		2.0
	)
	previous_data["economic_events"] = [deposit_event.to_dictionary()]
	previous_data["simulation"]["next_event_id"] = 1
	previous_data["event_knowledge"] = [
		{"schema_version": 1, "knower_id": 0, "event_id": 0},
		{"schema_version": 1, "knower_id": 1, "event_id": 0},
	]
	previous_data["relationships"] = [
		RelationshipStateRecord.create(0, 1, 0.5, 0.65, 0).to_dictionary()
	]
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v5 should add honest acquisition provenance")
	if migrated != null:
		var observer_record: KnownEventStateRecord
		var actor_record: KnownEventStateRecord
		for known_event in migrated.event_knowledge:
			if known_event.get_knower_id() == 0:
				observer_record = known_event
			elif known_event.get_knower_id() == 1:
				actor_record = known_event
		_check(
			(
				actor_record != null
				and (
					actor_record.get_acquisition_method()
					== SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED
				)
			),
			"World v5 migration can safely identify an actor's own completed fact"
		)
		_check(
			(
				observer_record != null
				and (
					observer_record.get_acquisition_method()
					== SimulationIds.KNOWLEDGE_ACQUISITION_LEGACY
				)
			),
			"World v5 migration must not invent witness or speaker provenance"
		)
	manager.free()


func _test_previous_world_retention_migration() -> void:
	var manager := _create_manager(61)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.RETENTION_LEGACY_SCHEMA_VERSION
	previous_data["simulation"]["tick_count"] = 50
	var deposit_event := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		0,
		SimulationIds.npc_inventory_id(0),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		2.0
	)
	previous_data["economic_events"] = [deposit_event.to_dictionary()]
	previous_data["simulation"]["next_event_id"] = 1
	var actor_knowledge := (
		KnownEventStateRecord
		. create(0, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
		. to_dictionary()
	)
	var witness_knowledge := (
		KnownEventStateRecord
		. create(2, 0, SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED)
		. to_dictionary()
	)
	var communicated_knowledge := (
		KnownEventStateRecord
		. create(
			1,
			0,
			SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED,
			2,
			0,
			SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
		)
		. to_dictionary()
	)
	for old_record in [actor_knowledge, witness_knowledge, communicated_knowledge]:
		old_record["schema_version"] = 2
		old_record.erase("acquired_tick")
		old_record.erase("source_acquisition_method")
	previous_data["event_knowledge"] = [communicated_knowledge, actor_knowledge, witness_knowledge]
	previous_data["relationships"] = []
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v6 should add deterministic retention metadata")
	if migrated != null:
		var records_by_knower := {}
		for record in migrated.event_knowledge:
			records_by_knower[record.get_knower_id()] = record
		var migrated_actor := records_by_knower.get(0) as KnownEventStateRecord
		var migrated_listener := records_by_knower.get(1) as KnownEventStateRecord
		_check(
			migrated_actor != null and migrated_actor.get_acquired_tick() == 0,
			"Direct v6 knowledge should retain the objective event tick"
		)
		_check(
			(
				migrated_listener != null
				and migrated_listener.get_acquired_tick() == 50
				and (
					migrated_listener.get_source_acquisition_method()
					== SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
				)
			),
			"Communicated v6 knowledge should receive a fresh lease and source snapshot"
		)
	manager.free()


func _test_previous_world_opportunity_migration() -> void:
	var manager := _create_manager(62)
	var previous_data: Dictionary = manager.create_state_record().to_dictionary()
	previous_data["schema_version"] = SimulationStateRecord.PREVIOUS_SCHEMA_VERSION
	previous_data.erase("opportunities")
	previous_data["simulation"].erase("next_opportunity_id")
	var migrated := SimulationStateRecord.from_dictionary(previous_data)
	_check(migrated != null, "World schema v7 should add an empty opportunity stream")
	if migrated != null:
		_check(
			(
				migrated.opportunities.is_empty()
				and int(migrated.simulation["next_opportunity_id"]) == 0
			),
			"World v7 migration should initialize deterministic opportunity identity"
		)
	var v8_data: Dictionary = _build_opportunity_world(manager, false)
	v8_data["schema_version"] = SimulationStateRecord.OPPORTUNITY_LEGACY_SCHEMA_VERSION
	var legacy_opportunity: Dictionary = v8_data["opportunities"][0]
	legacy_opportunity["schema_version"] = OpportunityStateRecord.LEGACY_SCHEMA_VERSION
	legacy_opportunity.erase("closed_tick")
	legacy_opportunity.erase("invalidation_reason")
	for event_data in v8_data["economic_events"]:
		event_data["schema_version"] = EconomicEventRecord.POSITION_LEGACY_SCHEMA_VERSION
		event_data.erase("action_id")
		event_data.erase("required_amount")
	var migrated_v8 := SimulationStateRecord.from_dictionary(v8_data)
	_check(migrated_v8 != null, "World schema v8 should preserve its pantry opportunity history")
	if migrated_v8 != null:
		_check(
			(
				migrated_v8.opportunities.size() == 1
				and migrated_v8.opportunities[0].get_status() == OpportunityStateRecord.STATUS_OPEN
				and migrated_v8.opportunities[0].get_closed_tick() == -1
			),
			"World v8 migration should normalize the nested opportunity lifecycle fields"
		)
	manager.free()


func _test_previous_world_animal_migration() -> void:
	var manager := _create_manager(63)
	var v9_data: Dictionary = _build_opportunity_world(manager, false)
	v9_data["schema_version"] = SimulationStateRecord.ANIMAL_LEGACY_SCHEMA_VERSION
	v9_data.erase("animals")
	var migrated := SimulationStateRecord.from_dictionary(v9_data)
	_check(migrated != null, "World schema v9 should add an empty animal stream")
	if migrated != null:
		_check(
			migrated.animals.is_empty() and migrated.opportunities.size() == 1,
			"World v9 migration should preserve opportunity history while adding animals"
		)
	manager.free()


func _test_previous_world_routine_migration() -> void:
	var manager := _create_manager(65)
	var v10_data: Dictionary = manager.create_state_record().to_dictionary()
	v10_data["schema_version"] = SimulationStateRecord.ROUTINE_LEGACY_SCHEMA_VERSION
	v10_data["animals"] = [
		{
			"schema_version": AnimalStateRecord.LEGACY_SCHEMA_VERSION,
			"animal_id": "legacy_goat",
			"display_name": "Legacy",
			"species_id": String(SimulationIds.SPECIES_GOAT),
			"position": [-4.0, 0.0, -11.5],
			"hunger": 40.0,
			"last_fed_tick": AnimalStateRecord.NEVER_FED_TICK,
			"reserved_by": -1,
			"enabled": true,
			"can_npcs_feed": true,
			"can_player_feed": true,
		}
	]
	var migrated := SimulationStateRecord.from_dictionary(v10_data)
	_check(migrated != null, "World schema v10 should preserve and upgrade animal records")
	if migrated != null:
		var animal := migrated.animals[0]
		_check(
			(
				animal.get_animal_id() == &"legacy_goat"
				and animal.get_routine_site_id().is_empty()
				and not animal.has_active_travel_target()
				and animal.get_next_routine_tick() == 0
			),
			"World v10 migration should add deterministic idle routine defaults"
		)
	manager.free()


func _test_animal_schema_rejection() -> void:
	var manager := _create_manager(64)
	var missing_animals: Dictionary = manager.create_state_record().to_dictionary()
	missing_animals.erase("animals")
	_check(
		SimulationStateRecord.from_dictionary(missing_animals) == null,
		"Current world records should require the authoritative animal array"
	)
	var invalid_position := (
		AnimalStateRecord
		. from_dictionary(
			{
				"schema_version": AnimalStateRecord.SCHEMA_VERSION,
				"animal_id": "invalid_goat",
				"display_name": "Invalid",
				"species_id": String(SimulationIds.SPECIES_GOAT),
				"position": [NAN, 0.0, 0.0],
				"hunger": 70.0,
				"last_fed_tick": AnimalStateRecord.NEVER_FED_TICK,
				"reserved_by": -1,
				"enabled": true,
				"can_npcs_feed": true,
				"can_player_feed": true,
				"routine_site_id": "",
				"travel_target_site_id": "",
				"travel_target_position": [0.0, 0.0, 0.0],
				"has_travel_target": false,
				"next_routine_tick": 0,
			}
		)
	)
	_check(invalid_position == null, "Animal records should reject non-finite positions")
	manager.free()


func _test_relationship_schema_rejection() -> void:
	var manager := _create_manager(58)
	var missing_cause_data: Dictionary = manager.create_state_record().to_dictionary()
	missing_cause_data["relationships"] = [
		RelationshipStateRecord.create(0, 1, 0.5, 0.65, 999).to_dictionary()
	]
	_check(
		SimulationStateRecord.from_dictionary(missing_cause_data) == null,
		"Relationship causes must reference an event in the same world record"
	)

	var duplicate_pair_data: Dictionary = manager.create_state_record().to_dictionary()
	var relationship_data := RelationshipStateRecord.create(0, 1, 0.5).to_dictionary()
	duplicate_pair_data["relationships"] = [relationship_data, relationship_data.duplicate(true)]
	_check(
		SimulationStateRecord.from_dictionary(duplicate_pair_data) == null,
		"World state should reject duplicate directed relationship pairs"
	)

	var unknown_knowledge_data: Dictionary = manager.create_state_record().to_dictionary()
	unknown_knowledge_data["event_knowledge"] = [
		KnownEventStateRecord.create(0, 999).to_dictionary()
	]
	_check(
		SimulationStateRecord.from_dictionary(unknown_knowledge_data) == null,
		"Known-event records must reference an event in the same world record"
	)
	var duplicate_knowledge_data: Dictionary = manager.create_state_record().to_dictionary()
	var event := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		0,
		SimulationIds.npc_inventory_id(0),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		1.0
	)
	duplicate_knowledge_data["economic_events"] = [event.to_dictionary()]
	duplicate_knowledge_data["simulation"]["next_event_id"] = 1
	var known_event_data := KnownEventStateRecord.create(0, 0).to_dictionary()
	duplicate_knowledge_data["event_knowledge"] = [
		known_event_data, known_event_data.duplicate(true)
	]
	_check(
		SimulationStateRecord.from_dictionary(duplicate_knowledge_data) == null,
		"World state should reject duplicate NPC knowledge pairs"
	)

	var wrong_subject_cause_data: Dictionary = manager.create_state_record().to_dictionary()
	var unrelated_deposit := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		2,
		SimulationIds.npc_inventory_id(2),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		1.0
	)
	wrong_subject_cause_data["economic_events"] = [unrelated_deposit.to_dictionary()]
	wrong_subject_cause_data["simulation"]["next_event_id"] = 1
	wrong_subject_cause_data["event_knowledge"] = [
		KnownEventStateRecord.create(0, 0).to_dictionary()
	]
	wrong_subject_cause_data["relationships"] = [
		RelationshipStateRecord.create(0, 1, 0.5, 0.65, 0).to_dictionary()
	]
	_check(
		SimulationStateRecord.from_dictionary(wrong_subject_cause_data) == null,
		"A trust cause must be a known food deposit performed by the relationship subject"
	)

	var nonpositive_cause_data: Dictionary = manager.create_state_record().to_dictionary()
	var nonpositive_deposit := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		1,
		SimulationIds.npc_inventory_id(1),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		0.0
	)
	nonpositive_cause_data["economic_events"] = [nonpositive_deposit.to_dictionary()]
	nonpositive_cause_data["simulation"]["next_event_id"] = 1
	nonpositive_cause_data["event_knowledge"] = [KnownEventStateRecord.create(0, 0).to_dictionary()]
	nonpositive_cause_data["relationships"] = [
		RelationshipStateRecord.create(0, 1, 0.5, 0.65, 0).to_dictionary()
	]
	_check(
		SimulationStateRecord.from_dictionary(nonpositive_cause_data) == null,
		"A trust cause must describe a successful positive food deposit"
	)

	var provenance_event := EconomicEventRecord.create(
		0,
		SimulationIds.EVENT_STORAGE_DEPOSITED,
		0,
		0,
		SimulationIds.npc_inventory_id(0),
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.RESOURCE_FOOD,
		1.0
	)
	var historical_source_data: Dictionary = manager.create_state_record().to_dictionary()
	historical_source_data["economic_events"] = [provenance_event.to_dictionary()]
	historical_source_data["simulation"]["next_event_id"] = 1
	historical_source_data["event_knowledge"] = [
		(
			KnownEventStateRecord
			. create(
				1,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED,
				2,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
			)
			. to_dictionary()
		)
	]
	_check(
		SimulationStateRecord.from_dictionary(historical_source_data) != null,
		"A listener's provenance should remain valid after the direct source forgets"
	)

	var unknown_source_data: Dictionary = historical_source_data.duplicate(true)
	unknown_source_data["event_knowledge"][0]["source_npc_id"] = 999
	_check(
		SimulationStateRecord.from_dictionary(unknown_source_data) == null,
		"Communicated knowledge must reference an existing historical source"
	)

	var wrong_actor_data: Dictionary = manager.create_state_record().to_dictionary()
	wrong_actor_data["economic_events"] = [provenance_event.to_dictionary()]
	wrong_actor_data["simulation"]["next_event_id"] = 1
	wrong_actor_data["event_knowledge"] = [
		(
			KnownEventStateRecord
			. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
			. to_dictionary()
		)
	]
	_check(
		SimulationStateRecord.from_dictionary(wrong_actor_data) == null,
		"Performed provenance must belong to the event actor"
	)

	var relayed_source_data: Dictionary = manager.create_state_record().to_dictionary()
	relayed_source_data["economic_events"] = [provenance_event.to_dictionary()]
	relayed_source_data["simulation"]["next_event_id"] = 1
	relayed_source_data["event_knowledge"] = [
		(
			KnownEventStateRecord
			. create(
				1,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED,
				2,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED
			)
			. to_dictionary()
		),
		(
			KnownEventStateRecord
			. create(
				2,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED,
				0,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED
			)
			. to_dictionary()
		),
		(
			KnownEventStateRecord
			. create(0, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
			. to_dictionary()
		),
	]
	_check(
		SimulationStateRecord.from_dictionary(relayed_source_data) == null,
		"Communicated facts must not form a second relay hop in this phase"
	)
	var reacquired_source_data: Dictionary = relayed_source_data.duplicate(true)
	reacquired_source_data["event_knowledge"][0]["source_acquisition_method"] = String(
		SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
	)
	_check(
		SimulationStateRecord.from_dictionary(reacquired_source_data) != null,
		"Historical direct provenance should survive a source reacquiring the fact differently"
	)

	var order_independent_data: Dictionary = manager.create_state_record().to_dictionary()
	order_independent_data["economic_events"] = [provenance_event.to_dictionary()]
	order_independent_data["simulation"]["next_event_id"] = 1
	order_independent_data["event_knowledge"] = [
		(
			KnownEventStateRecord
			. create(
				1,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_COMMUNICATED,
				2,
				0,
				SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED
			)
			. to_dictionary()
		),
		(
			KnownEventStateRecord
			. create(0, 0, SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED)
			. to_dictionary()
		),
		(
			KnownEventStateRecord
			. create(2, 0, SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED)
			. to_dictionary()
		),
	]
	_check(
		SimulationStateRecord.from_dictionary(order_independent_data) != null,
		"Provenance validation should not depend on knowledge array ordering"
	)

	var invalid_direct_time_data: Dictionary = manager.create_state_record().to_dictionary()
	invalid_direct_time_data["simulation"]["tick_count"] = 2
	invalid_direct_time_data["economic_events"] = [provenance_event.to_dictionary()]
	invalid_direct_time_data["simulation"]["next_event_id"] = 1
	invalid_direct_time_data["event_knowledge"] = [
		(
			KnownEventStateRecord
			. create(1, 0, SimulationIds.KNOWLEDGE_ACQUISITION_WITNESSED, -1, 1)
			. to_dictionary()
		)
	]
	_check(
		SimulationStateRecord.from_dictionary(invalid_direct_time_data) == null,
		"Direct witness acquisition must use the immutable objective event tick"
	)
	manager.free()


func _test_opportunity_schema_rejection() -> void:
	var manager := _create_manager(63)
	var valid_open := _build_opportunity_world(manager, false)
	_check(
		SimulationStateRecord.from_dictionary(valid_open) != null,
		"A known empty-pantry trigger should accept one open restock opportunity"
	)

	var missing_knowledge := valid_open.duplicate(true)
	missing_knowledge["event_knowledge"] = []
	_check(
		SimulationStateRecord.from_dictionary(missing_knowledge) == null,
		"An open opportunity should require its interested NPC to know the trigger"
	)
	var knowledge_acquired_too_late := valid_open.duplicate(true)
	knowledge_acquired_too_late["event_knowledge"][0]["acquisition_method"] = String(
		SimulationIds.KNOWLEDGE_ACQUISITION_LEGACY
	)
	knowledge_acquired_too_late["event_knowledge"][0]["acquired_tick"] = 3
	_check(
		SimulationStateRecord.from_dictionary(knowledge_acquired_too_late) == null,
		"An open opportunity cannot predate the interested NPC's knowledge"
	)
	var already_supplied := valid_open.duplicate(true)
	for storage_data in already_supplied["storages"]:
		if StringName(storage_data["storage_id"]) == SimulationIds.STORAGE_VILLAGE_PANTRY:
			storage_data["amounts"][String(SimulationIds.RESOURCE_FOOD)] = 1.0
	already_supplied["village"]["food"] = 1.0
	_check(
		SimulationStateRecord.from_dictionary(already_supplied) == null,
		"An open pantry need should reject a save whose target is already supplied"
	)

	var duplicate_id := valid_open.duplicate(true)
	var second_opportunity: Dictionary = duplicate_id["opportunities"][0].duplicate(true)
	second_opportunity["trigger_event_id"] = 1
	duplicate_id["economic_events"].append(_create_pantry_withdrawal_event(1, 3, 1).to_dictionary())
	duplicate_id["event_knowledge"].append(
		(
			KnownEventStateRecord
			. create(
				1,
				1,
				SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED,
				KnownEventStateRecord.NO_SOURCE_NPC_ID,
				3
			)
			. to_dictionary()
		)
	)
	duplicate_id["opportunities"].append(second_opportunity)
	duplicate_id["simulation"]["next_event_id"] = 2
	duplicate_id["simulation"]["next_opportunity_id"] = 2
	_check(
		SimulationStateRecord.from_dictionary(duplicate_id) == null,
		"Opportunity IDs should be unique"
	)
	var multiple_open := duplicate_id.duplicate(true)
	multiple_open["opportunities"][1]["opportunity_id"] = 1
	_check(
		SimulationStateRecord.from_dictionary(multiple_open) == null,
		"The bounded pantry slice should restore at most one open opportunity"
	)

	var duplicate_trigger := valid_open.duplicate(true)
	var repeated_trigger: Dictionary = duplicate_trigger["opportunities"][0].duplicate(true)
	repeated_trigger["opportunity_id"] = 1
	duplicate_trigger["opportunities"].append(repeated_trigger)
	duplicate_trigger["simulation"]["next_opportunity_id"] = 2
	_check(
		SimulationStateRecord.from_dictionary(duplicate_trigger) == null,
		"One objective trigger should not create duplicate opportunity records"
	)

	var colliding_next_id := valid_open.duplicate(true)
	colliding_next_id["simulation"]["next_opportunity_id"] = 0
	_check(
		SimulationStateRecord.from_dictionary(colliding_next_id) == null,
		"The next opportunity ID should remain above restored history"
	)

	var unknown_interested_npc := valid_open.duplicate(true)
	unknown_interested_npc["opportunities"][0]["interested_npc_id"] = 999
	_check(
		SimulationStateRecord.from_dictionary(unknown_interested_npc) == null,
		"Opportunities should reference an existing interested NPC"
	)

	var future_creation := valid_open.duplicate(true)
	future_creation["opportunities"][0]["created_tick"] = 11
	_check(
		SimulationStateRecord.from_dictionary(future_creation) == null,
		"Opportunity creation cannot occur after the saved simulation tick"
	)

	var before_trigger := valid_open.duplicate(true)
	before_trigger["opportunities"][0]["created_tick"] = 1
	_check(
		SimulationStateRecord.from_dictionary(before_trigger) == null,
		"Opportunity creation cannot predate its trigger event"
	)

	var invalid_trigger := valid_open.duplicate(true)
	invalid_trigger["economic_events"][0]["destination_id"] = "unrelated_inventory"
	_check(
		SimulationStateRecord.from_dictionary(invalid_trigger) == null,
		"A restock opportunity trigger should be a real NPC pantry withdrawal"
	)

	var player_trigger := valid_open.duplicate(true)
	player_trigger["economic_events"][0]["actor_id"] = -1
	player_trigger["economic_events"][0]["destination_id"] = "player_inventory"
	_check(
		SimulationStateRecord.from_dictionary(player_trigger) == null,
		"Player extraction or consumption should not masquerade as an informed NPC trigger"
	)

	var valid_resolved := _build_opportunity_world(manager, true)
	_check(
		SimulationStateRecord.from_dictionary(valid_resolved) != null,
		"A later NPC pantry deposit should resolve an opportunity without retained knowledge"
	)

	var player_resolved := _build_opportunity_world(manager, true)
	player_resolved["economic_events"][1] = (
		EconomicEventRecord
		. create(
			1,
			SimulationIds.EVENT_RESOURCE_EXTRACTED,
			3,
			-1,
			&"schema_test_berry",
			SimulationIds.STORAGE_VILLAGE_PANTRY,
			SimulationIds.RESOURCE_FOOD,
			1.0
		)
		. to_dictionary()
	)
	player_resolved["resources"].append(
		_create_player_food_resource_state(&"schema_test_berry").to_dictionary()
	)
	_check(
		SimulationStateRecord.from_dictionary(player_resolved) != null,
		"A later player resource extraction into the pantry should be a valid resolution"
	)
	var unknown_player_source := player_resolved.duplicate(true)
	unknown_player_source["economic_events"][1]["source_id"] = "missing_berry"
	_check(
		SimulationStateRecord.from_dictionary(unknown_player_source) == null,
		"A player resolution should reference a real player-usable food resource"
	)

	var invalid_resolution := valid_resolved.duplicate(true)
	invalid_resolution["economic_events"][1]["destination_id"] = "somewhere_else"
	_check(
		SimulationStateRecord.from_dictionary(invalid_resolution) == null,
		"Resolution events should actually supply food to the opportunity target"
	)

	var mismatched_resolution_tick := valid_resolved.duplicate(true)
	mismatched_resolution_tick["opportunities"][0]["resolved_tick"] = 4
	_check(
		SimulationStateRecord.from_dictionary(mismatched_resolution_tick) == null,
		"Resolved opportunity ticks should match the referenced resolution event"
	)
	manager.free()


func _build_opportunity_world(manager: Node, resolved: bool) -> Dictionary:
	var world: Dictionary = manager.create_state_record().to_dictionary()
	world["simulation"]["tick_count"] = 10
	world["village"]["food"] = 1.0 if resolved else 0.0
	for storage_data in world["storages"]:
		if StringName(storage_data["storage_id"]) == SimulationIds.STORAGE_VILLAGE_PANTRY:
			storage_data["amounts"][String(SimulationIds.RESOURCE_FOOD)] = (
				1.0 if resolved else 0.0
			)
	world["economic_events"] = [_create_pantry_withdrawal_event(0, 2, 0).to_dictionary()]
	world["simulation"]["next_event_id"] = 1
	var opportunity := OpportunityStateRecord.create(0, 2, 0, 0)
	if resolved:
		world["economic_events"].append(
			(
				EconomicEventRecord
				. create(
					1,
					SimulationIds.EVENT_STORAGE_DEPOSITED,
					3,
					1,
					SimulationIds.npc_inventory_id(1),
					SimulationIds.STORAGE_VILLAGE_PANTRY,
					SimulationIds.RESOURCE_FOOD,
					1.0
				)
				. to_dictionary()
			)
		)
		world["simulation"]["next_event_id"] = 2
		opportunity.resolve(1, 3)
		world["event_knowledge"] = []
	else:
		world["event_knowledge"] = [
			(
				KnownEventStateRecord
				. create(
					0,
					0,
					SimulationIds.KNOWLEDGE_ACQUISITION_PERFORMED,
					KnownEventStateRecord.NO_SOURCE_NPC_ID,
					2
				)
				. to_dictionary()
			)
		]
	world["opportunities"] = [opportunity.to_dictionary()]
	world["simulation"]["next_opportunity_id"] = 1
	return world


func _create_pantry_withdrawal_event(
	event_id: int, tick: int, actor_id: int
) -> EconomicEventRecord:
	return EconomicEventRecord.create(
		event_id,
		SimulationIds.EVENT_STORAGE_WITHDRAWN,
		tick,
		actor_id,
		SimulationIds.STORAGE_VILLAGE_PANTRY,
		SimulationIds.npc_inventory_id(actor_id),
		SimulationIds.RESOURCE_FOOD,
		1.0
	)


func _create_player_food_resource_state(node_id: StringName) -> ResourceStateRecord:
	var resource_node := ResourceNode.new()
	resource_node.node_id = node_id
	resource_node.action_id = SimulationIds.ACTION_GATHER_FOOD
	resource_node.resource_id = SimulationIds.RESOURCE_FOOD
	resource_node.can_player_use = true
	var resource_state := ResourceStateRecord.create_from_node(resource_node)
	resource_node.free()
	return resource_state


func _create_manager(seed_value: int) -> Node:
	var manager: Node = load("res://simulation/SimulationManager.gd").new()
	manager.simulation_seed = seed_value
	manager.debug_logs = false
	root.add_child(manager)
	manager.set_process(false)
	return manager


func _advance_scenario(manager: Node, steps: int) -> void:
	for step in steps:
		manager.simulate_tick()
		for npc in manager.npcs:
			manager.get_wander_offset(npc.id)
			if npc.task_state == SimNPC.TASK_STATE_TRAVELING:
				manager.notify_npc_arrived(npc.id)


func _check(condition: bool, message: String) -> void:
	if not condition:
		failures.append(message)