feat: define action completion costs

docs/ACTION_SYSTEM_ARCHITECTURE.md

@@ -23,8 +23,8 @@ SimulationManager tick
 - reads NPC and village state;
 - evaluates current utility scores;
 - consumes the NPC's deterministic decision RNG;
-- returns an action ID, optional urgent-duration override, branch reason, and
-  compared utility scores;
+- returns an action ID, optional urgent-duration override, branch reason,
+  compared utility scores, and definition-backed rejection reasons;
 - does not mutate targets, navigation, or visuals.
 
 ### ActionExecutionSystem
@@ -65,7 +65,9 @@ SimulationManager remains the orchestrator and event boundary. It owns
 simulation records, invokes the focused systems, stores selected actions and
 targets, and translates presentation callbacks into simulation transitions.
 It also publishes the latest `ActionSelectionResult` for presentation; the UI
-does not recompute decisions.
+does not recompute decisions. At completion it atomically pays any
+definition-backed stored-resource cost before applying the action effect. A
+late shortfall suppresses the effect and records a `task_blocked` fact.
 Further decomposition should follow measured pressure rather than splitting it
 into managers for their own sake.
 

docs/BUILD_IN_PUBLIC_PLAN.md

@@ -220,6 +220,12 @@ an asset catalog.
 
 Translate the desired animated-film warmth into an original style:
 
+Keep the gameplay camera as an elevated third-person/top-down player follow
+with gentle dead-zone lag. This supports the cozy farm-builder read and lets
+the player watch several villagers at once. Presentation presets may stage the
+same camera for repeatable captures, but should not replace gameplay with a
+free orbit or close over-the-shoulder view.
+
 | Element | Direction |
 | --- | --- |
 | Terrain | Broad painterly color regions and exaggerated silhouettes |
@@ -665,11 +671,10 @@ Completed:
 Next:
 
 1. Replace the remaining player capsule with a matching stylized presentation,
-   then revisit runtime camera framing so the waterfall and village action
-   remain readable in the same authored shot.
-2. Continue with the action precondition/material-cost contract and
-   relationship consequence work in `LEARNING_ROADMAP.md` before expanding
-   visual scope further.
+   while preserving the elevated top-down follow, gentle dead-zone lag, and
+   cozy farm-builder readability.
+2. Continue with the relationship consequence work in `LEARNING_ROADMAP.md`
+   before expanding visual scope further.
 
 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

@@ -20,6 +20,11 @@ Events are immutable facts about completed transfers. They do not perform the
 transaction and are not replayed to reconstruct current state. Resource,
 inventory, and storage records remain authoritative.
 
+An action whose definition-backed completion cost becomes unavailable records
+a zero-amount `task_blocked` narrative fact with the action and shortfall
+reason. This makes late contention inspectable without pretending that a
+transfer occurred.
+
 ## Persistence and determinism
 
 `SimulationStateRecord` schema v3 stores the ordered event stream and
@@ -47,7 +52,6 @@ NPC record, so unloading presentation does not lose the fact.
 
 The stream is currently kept in full for the small simulation garden. Before
 large populations or long-running worlds, add measured retention,
-archival/summary rules, and query indexes. Denied attempts, depletion,
-witnesses, secrecy, causal links, and memories belong in later event/history
-slices; they should extend this record family without making prose
-authoritative.
+archival/summary rules, and query indexes. General denied attempts, witnesses,
+secrecy, causal links, and memories belong in later event/history slices; they
+should extend this record family without making prose authoritative.

docs/LEARNING_ROADMAP.md

@@ -652,12 +652,11 @@ Completed after the architecture gate:
 
 The practical next sequence is:
 
-1. Move proven action preconditions and material costs into a reusable contract,
-   beginning with the patrol/study wood dependency, then expose unavailable
-   choices and interruption reasons in the NPC inspector.
-2. Grow the existing familiarity seed into one consequence-bearing relationship
+1. Grow the existing familiarity seed into one consequence-bearing relationship
    dimension, such as trust or obligation, driven by structured events rather
    than proximity alone.
+2. Use that dimension in one real choice or response, then expose the cause in
+   the NPC inspector before expanding the relationship graph.
 
 Recently completed:
 
@@ -706,6 +705,10 @@ Recently completed:
   wood deposits. Village wood syncs from storage. Economic events track all
   transfers. Patrol and study no longer produce benefits without paying their
   one-wood cost, and utility selection avoids those actions when wood is empty.
+- Action completion costs are definition-backed: patrol and study share one
+  stored-resource contract across selection and execution. The inspector shows
+  readable unavailable reasons, and a late shortfall creates a persisted
+  `task_blocked` fact without applying the work effect.
 - Structured event feed: EconomicEventRecord now supports narrative events
   (task started, NPC slept, NPC died) alongside economic transfers.
   Per-NPC event history with human-readable descriptions exposed in the

docs/SIMULATION_DEFINITIONS.md

@@ -20,15 +20,18 @@ Each executable action definition contains:
 - default duration;
 - optional preferred profession ID;
 - target type: resource, activity, or free movement;
-- resource action ID when the action targets a ResourceNode.
+- resource action ID when the action targets a ResourceNode;
+- optional completion-cost resource ID and amount.
 
-The current actions are gather food, gather wood, deposit food, withdraw food,
-patrol, study, eat, rest, and wander. Idle and dead are stable state sentinels,
-not executable action definitions.
+The current actions are gather food, gather wood, deposit food, deposit wood,
+withdraw food, patrol, study, eat, rest, sleep, and wander. Idle and dead are
+stable state sentinels, not executable action definitions.
 
 SimNPC reads default duration and preferred-profession metadata from these
 definitions. WorldViewManager reads target type and resource-action metadata
-instead of maintaining a separate gather-action map.
+instead of maintaining a separate gather-action map. ActionSelectionSystem and
+SimulationManager share the same completion-cost metadata, so patrol and study
+both require one stored wood without duplicating that rule.
 
 ## Current profession contract
 
@@ -49,6 +52,7 @@ The registry rejects:
 - non-positive action durations;
 - invalid target types;
 - resource actions without a resource-action ID;
+- incomplete, non-positive, or unknown completion-cost resources;
 - references to unknown professions or resource actions;
 - definition resources that fail to load.
 
@@ -59,10 +63,11 @@ round-tripping.
 ## Deliberate boundary
 
 Definitions currently own identity and the static metadata already proven by
-the prototype. They do not yet own:
+the prototype, including the patrol/study completion-cost contract. They do not
+yet own:
 
 - utility thresholds and consideration curves;
-- preconditions or costs;
+- general preconditions beyond stored-resource completion costs;
 - completion effects;
 - interruption and failure policy;
 - reservation strategy;