feat: score resource discovery by comfort and safety

docs/LEARNING_ROADMAP.md

@@ -655,8 +655,9 @@ The practical next sequence is:
 1. Add a cinematic/debug toggle and repeatable simulation-garden demo reset.
 2. Expand resource discovery with many finite `ResourceNode` instances placed
    in meaningful foliage, animal-camp, berry, and village-stockpile contexts.
-   Score them by reachability, distance, safety, profession, and NPC comfort
-   range rather than reintroducing abstract resource zones.
+   The first distance/safety/comfort scoring pass exists; next, add more
+   authored resources and validate their navigation/reachability rather than
+   reintroducing abstract resource zones.
 3. Expand persistence only when schedules, player state, or a real save menu
    creates a concrete requirement.
 

docs/PROJECT_CONTEXT.md

@@ -312,7 +312,9 @@ that amount, and releases an NPC reservation if the source is depleted.
 Future resource expansion should add many finite `ResourceNode` instances rather
 than broad resource zones: trees in foliage clusters, berry patches, animal
 camps, and village stockpiles can be ranked by reachability, distance, safety,
-profession, and NPC comfort range.
+profession, and NPC comfort range. The current resolver already combines
+distance with resource `safety_risk`, `comfort_distance`, and
+`discovery_priority` metadata.
 
 ### Jajce scaffold
 

docs/RESOURCE_NODE_MIGRATION.md

@@ -542,11 +542,13 @@ compete for the same social/workstation site.
 **Exit:** temporary activity markers and task-to-marker mapping are deleted,
 not merely unused.
 
-**Status: complete for the marker-removal migration.** Future work should
-extend target scoring rather than reintroducing zones: resources can be spread
+**Status: complete for the marker-removal migration.** Follow-up work now
+extends target scoring rather than reintroducing zones: resources can be spread
 as many finite `ResourceNode` instances across foliage, animal camps, berry
 patches, and village stockpiles, then ranked by distance, reachability, safety,
-profession, and NPC comfort range.
+profession, and NPC comfort range. The first scoring pass stores
+`safety_risk`, `comfort_distance`, and `discovery_priority` on resource state
+and uses them when selecting NPC resource targets.
 
 ## Test scenarios
 

docs/SIMULATION_STATE_SCHEMA.md

@@ -74,8 +74,8 @@ duplicate IDs, and preserve deterministic ordering across save/restore. See
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the
 scene tree. Amount, reservation, enabled state, action/resource identity,
-yield, and usage permissions remain available and serializable while no
-ResourceNode is loaded.
+yield, usage permissions, and discovery metadata remain available and
+serializable while no ResourceNode is loaded.
 
 ResourceNode binds to a record by stable ID and provides presentation,
 interaction transforms, and active-world discoverability. Unloading a node does
@@ -83,9 +83,10 @@ not delete its record. Loading another node with the same stable ID rebinds to
 the existing record and cannot overwrite its amount or reservation with scene
 defaults.
 
-ResourceStateRecord v2 adds the definition facts needed while unloaded. Nested
-v1 resource records are migrated explicitly and hydrate their missing
-definition from a matching presentation node when one becomes available.
+ResourceStateRecord v3 adds `safety_risk`, `comfort_distance`, and
+`discovery_priority` so unloaded resources keep the same target-selection
+meaning after save/restore. Nested v1 and v2 resource records are migrated
+explicitly.
 
 ## Local quicksave boundary