feat: derive capable opportunity helpers

docs/ARCHITECTURE_OVERVIEW.md

@@ -43,7 +43,9 @@ would otherwise obscure that lifecycle:
 - `simulation/opportunities/VillageOpportunitySystem.gd` observes immutable
   event references plus current NPC/storage state, then owns the bounded shared
   open/resolved/invalidated lifecycle for the proven pantry-food and blocked-
-  work wood consumers without changing resources or assigning tasks;
+  work wood consumers. It also derives one ephemeral `OpportunityHelperResult`
+  from knowledge, directed relationships, inventory, action definitions, and
+  finite-resource state without changing resources or assigning tasks;
 - `simulation/persistence/` owns save-slot file safety;
 - `simulation/state/` owns versioned serialized record contracts;
 - `simulation/definitions/` owns stable IDs and immutable action/profession

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -731,13 +731,18 @@ Completed:
     player tree-harvest resolutions use real economy history; interested-party
     death and one-day staleness close the need cleanly. The compact UI explains
     the blocked action without reusing the pantry's hunger cue.
+28. Explainable capable helper: an open food or wood need now names one
+    deterministic informed and trusted villager plus the ordinary gather or
+    deposit action and real inventory/resource route that makes them capable.
+    The result is re-derived after restore and does not assign work or alter the
+    simulation.
 
 Next:
 
-1. Add the first read-only capable-helper query for an open need. Expose one
-   deterministic viable villager and the real knowledge, relationship, action,
-   inventory, and resource facts behind that result before allowing it to
-   affect autonomous selection, as sequenced in `LEARNING_ROADMAP.md`.
+1. Let the currently derived helper consume the query through ordinary
+   autonomous action selection, after urgent self-care and schedule precedence.
+   Re-query instead of persisting assignment, and keep acceptance/rewards out
+   of scope, as sequenced in `LEARNING_ROADMAP.md`.
 
 Do not start with GIS data, a full city, a large asset pack, or more NPC
 mechanics. The next proof is a beautiful stage for the systems that already

docs/ECONOMIC_EVENTS.md

@@ -99,6 +99,19 @@ opening; invalidation emits no event and stores the close tick and stable
 reason. Resolution or invalidation returns the trigger to normal bounded
 retention.
 
+For an open need, the same system can derive one capable helper without
+assigning work. A candidate must know the exact trigger and have a familiar
+directed relationship with at least 0.6 trust toward the interested villager.
+Enough carried inventory produces the matching deposit route; otherwise a
+matching enabled, NPC-usable, sufficiently stocked and available finite
+ResourceNode state produces the gather route. Ranking is deterministic and
+prefers ready inventory, trust, profession fit, familiarity, then stable NPC
+ID. The returned opportunity/trigger/helper/action/resource, inventory source
+or available finite-source count, and reason are an ephemeral query result. It
+does not select an exact gather target; that remains with `ActiveWorldAdapter`
+and `ActionTargetResolver`. No event, reservation, RNG draw, task mutation, or
+serialized assignment is created.
+
 The food-loop regression verifies this chain:
 
 ```text
@@ -123,7 +136,9 @@ The village summary also shows one compact active need with its real target
 progress and interested villager; only that villager's inspector retains its
 open/closed detail and names the exact supplier for a resolution. The empty-bowl
 world cue remains specific to the pantry shortage rather than representing a
-wood need as hunger.
+wood need as hunger. The active summary additionally names the currently
+derived helper, supply action, trust fact, and inventory or finite-source route,
+or states that no informed trusted villager is currently able to supply it.
 
 ## Deliberate limits
 
@@ -136,5 +151,6 @@ hearing, personalized reinforcement/decay, multi-hop rumours, secrecy, false
 beliefs, and multi-event causal graphs belong in later event/history slices.
 They should extend this record family without making prose authoritative or
 recomputing old evidence from current positions.
-The current opportunity family is likewise a bounded two-consumer projection,
-not a generic quest, reward, acceptance, dialogue, or capable-helper framework.
+The current opportunity family is likewise a bounded two-consumer projection
+with one read-only helper query, not a generic quest, reward, acceptance,
+dialogue, helper assignment, or capable-helper framework.

docs/LEARNING_ROADMAP.md

@@ -775,11 +775,28 @@ The second bounded Milestone 7 consumer is complete:
 - the two proven consumers now share `VillageOpportunitySystem` and the common
   lifecycle fields, while their evidence and care rules remain explicit.
 
-Milestone 7 is not complete. The immediate next slice is a bounded
-capable-helper query for an open need: derive one viable helper from existing
-knowledge, relationship, action, inventory, and resource facts and expose the
-reason for that result. Keep it read-only first; only a later proven slice
-should let opportunity awareness influence autonomous task selection.
+The first bounded capable-helper query is complete:
+
+- an open need derives at most one living helper who knows its exact trigger,
+  has an existing familiar directed relationship with at least 0.6 trust toward
+  the interested villager, and is not that villager;
+- the helper must either carry enough matching inventory to reach the target or
+  have a matching enabled, NPC-usable, sufficiently stocked finite resource
+  that is not reserved by someone else;
+- ready inventory wins first, followed by higher trust, matching gather
+  profession, familiarity, and lowest stable NPC ID;
+- `OpportunityHelperResult` exposes the exact opportunity, trigger, helper,
+  action, inventory source or finite-source count, resource, relationship
+  values, and concise reason without mutating RNG, tasks, reservations,
+  resources, or persisted state;
+- food and wood scenarios re-derive the same result after restore, and the
+  village summary explains the current helper route from real simulation facts.
+
+Milestone 7 is not complete. The immediate next slice is one bounded autonomous
+consumer of this query: let the currently derived helper choose the reported
+gather/deposit action through ordinary selection while preserving urgent
+self-care and schedule precedence. Re-query rather than persisting assignment,
+and do not add quest acceptance or reward state.
 
 Recently completed:
 

docs/PROJECT_CONTEXT.md

@@ -618,8 +618,9 @@ These are expected prototype constraints, not necessarily isolated bugs:
 - The bounded opportunity family supports one open `restock_empty_pantry` or
   `supply_missing_wood` need from exact known evidence. Both have exact NPC and
   player supply resolutions; the wood need also closes deterministically on
-  interested-party death or one-day staleness. There is still no capable-helper
-  assignment, acceptance, rewards, free-form dialogue, or quest log.
+  interested-party death or one-day staleness. One read-only query derives and
+  explains a capable helper, but there is still no helper assignment,
+  acceptance, rewards, free-form dialogue, or quest log.
 - The reason inspector exposes current decisions, utility rejections, one exact
   relationship cause, and a compact person-history view that distinguishes
   importance-ranked retained memories from objective personal actions.
@@ -902,10 +903,18 @@ v9 and nested opportunity schema v2 preserve open, resolved, and invalidated
 history. The two consumers now share `VillageOpportunitySystem`, while their
 evidence and care rules remain explicit.
 
-Milestone 7 remains in progress. The immediate next slice is a read-only,
-deterministic capable-helper query for an open need, derived from existing
-knowledge, relationship, action, inventory, and resource facts before it is
-allowed to influence autonomous task selection.
+The first capable-helper query is complete. An open food or wood need now
+derives one living informed villager with a familiar trusted directed tie and a
+real inventory-deposit or finite-resource gather route. Inventory readiness,
+trust, profession fit, familiarity, finite-source availability, and stable IDs
+produce one deterministic result. The village summary explains that result;
+save/load re-derives it, and querying changes no task, reservation, RNG stream,
+resource, event, or checksum.
+
+Milestone 7 remains in progress. The immediate next slice is one bounded
+autonomous consumer: allow the currently derived helper to choose its reported
+ordinary supply action after urgent self-care and schedule rules, without
+persisted assignment, quest acceptance, or reward state.
 
 The remaining simulation-garden target still aims for:
 

docs/SIMULATION_STATE_SCHEMA.md

@@ -196,6 +196,12 @@ lasting during deterministic memory maintenance. Resolution or invalidation
 releases that fact back to the normal bounded-retention rules; neither deletes
 objective event or opportunity history.
 
+`OpportunityHelperResult` is deliberately absent from this schema. It is
+re-derived from the open opportunity plus current NPC knowledge, directed
+relationship, inventory, action-definition, storage-capacity, and finite-
+resource records. Save/restore regressions require the same helper/action/route
+result and an unchanged checksum before and after querying.
+
 ## Resource authority
 
 `SimulationManager` owns `ResourceStateRecord` instances independently of the
@@ -212,7 +218,9 @@ defaults.
 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.
+explicitly. Current-schema parsing also canonicalizes numeric, boolean, and ID
+variants so a freshly registered finite source retains a byte-stable checksum
+after a JSON round trip.
 
 ## Local quicksave boundary