Sapience: Living Villagers

# Sapience beta.356
## Changes since beta.355

### Careers and clothing

- Villagers now wear clothing that matches their settled Sapience career. Farmers, builders, defenders, miners, woodcutters, traders, and leaders use the closest matching outfit from Minecraft’s normal villager clothing.
- Clothing follows the villager’s saved career rather than nearby workstations. Temporary jobs no longer cause outfits to flicker between roles.
- Established career changes require the alternative role to remain justified for ten in-game minutes. The handover waits until the villager is no longer fighting, fleeing, sleeping, gathering, building, or crafting.
- New adult citizens can fill an established village need without waiting to leave a former career.
- Pending career changes retain their reason through save/load. Village need, trusted player opportunities, personal fit, and civic duty appear in `/villager` and ground the Chronicle entry and speech when the change happens.
- The five standard clothing badges now reflect practice in the corresponding Sapience skill. Mastery uses the existing skill threshold.
- Career clothing and badges are visual only. They do not create vanilla professions, trade offers, workstation claims, trading levels, or stat bonuses.
- Children retain neutral citizen clothing until adulthood.
- Resource packs can still replace the standard profession textures. Sapience respects replacement models rather than forcing fitted vanilla clothing over a body that removes those layers.

### Building-site searches

- Building surveys now process a fixed number of candidates per tick instead of searching large areas in one burst.
- Surveys retain a stable anchor and deterministic candidate order.
- Builders recheck the chosen footprint before changing the first block.
- Terrain suitability is now separate from temporary occupancy. A passing player or villager no longer permanently invalidates usable land.
- Builders wait for occupied placement cells to clear and abandon the attempt safely if they remain blocked.
- Changes in communal stock no longer split one home survey across several cursors. Each bounded scan finishes against its initial budget, while final admission checks the current bill.
- Failed searches can be reconsidered when actual available stock increases.

### Home costs and material gathering

- First-home projects now price the walls and foundation together before the initial material-gathering trip.
- Builders retain the exact building type, surveyed site, and complete bill during acquisition, then recheck that site before construction.
- The shared survey slot is released while the builder gathers materials.
- A rejected or changed site invalidates its old quote. Reloading replans the work without creating stock.
- Builders distinguish unsuitable land from a suitable lot that needs more foundation material.
- When neither existing two-bed home can be built with current stock, builders compare their complete costs and gather toward the cheaper legal option. Family homes retain preference on equal costs.
- Site comparisons now use the net imported foundation cost after safe excavation recovers usable blocks.
- Searches no longer stop early because a gross fill estimate appears to be the minimum. A later cut-and-fill site can still qualify with a lower real bill.
- Conservative cost pruning was corrected so it does not discard legal compact-home alternatives.
- Sand and gravel drops are not counted as guaranteed funding.
- Walking between an empty quarry and the village no longer renews a construction fund indefinitely.
- Real material acquisition and advancing block-break work count as progress. Idle routes, unchanged targets, and empty round trips do not.
- Exhausted material sources return their workers above ground.
- Directly claimed home funds now use the same retirement and deposit path as fallback projects. Carried materials remain accounted for.

### Construction and work continuity

- Cottage preparation preserves natural floor blocks that the blueprint intends to keep instead of digging them up and spending wall stock to replace them.
- Required doorstep cells still receive their proper preparation.
- Builders now distinguish open hillsides from underground work. Higher neighbouring ground alone no longer causes repeated surface-return attempts.
- Actual cover, registered mine access, and confined pits still require the appropriate return to the surface.
- Underground work uses the surrounding grade rather than the low height of the stair the worker just opened.
- Builders now find an exact, reachable position that clears their body from the pending placement cell.
- This replaces fractional step-aside destinations that navigation could consider reached without moving.
- Step-aside checks include the full body, a clearance margin, both bed halves where applicable, safe footing, hazards, collision, occupancy, and loaded terrain.
- The search remains bounded and deterministic. The existing cancellation limit is unchanged.
- Returning home at dusk ends the interrupted gathering shift instead of allowing stale mining work to reclaim the next plan.
- The between-plan building dispatcher now respects the same daylight boundary as the planner.
- Funded construction pauses at night without discarding the legitimate job or materials needed the next day.
- Slow pickaxe work can finish without being mistaken for a stalled source, provided actual break progress continues.

### Mining and quarry work

- Mining now covers the complete physical job: prospecting, quarry stairs, reaching deposits, ore handoff, owned spoil, safe exit, and abandoned-shaft backfilling.
- Failed prospects must not leave an unaccounted open hole in the settlement.
- Narrow mine stairs admit one active worker at a time. Other workers yield and handle their needs instead of crowding the passage.
- Working miners retain their passage claim through swings and cooldowns. Interrupted claims expire, and old claims clear when mine records are restored or retired.
- Mine surveys follow the actual top-down clearing order. Stone behind forbidden sand or protected blocks no longer makes an unusable stair appear viable.
- Descending stairs check the entire swept head space, including the upper forward ceiling lip, before opening or entering the lower landing.
- The same safety checks can repair an older registered passage.
- Registered quarry stairs can clear their exact remaining soil headroom or prepared continuation landing when support and both head cells are safe.
- Suitable pickaxes can clear raw natural sandstone and red sandstone from those exact registered stair cells.
- These exceptions do not authorize unrestricted earthmoving or sandstone quarrying.
- Returning miners finish the cleared last stair before choosing another rock target. A nearby higher face can no longer pull them back above the quarry.

### Mine exits and underground recovery

- Home, food, and storage trips leave a registered mine through its known entrance before continuing across the surface.
- Depleted work faces no longer erase the known exit.
- Exit selection uses stable nearest-mouth ordering and does not take materials or a mining claim.
- Underground recovery retains its checked walk-out path while the villager makes physical headway instead of restarting emergency digging between route probes.
- A genuine five-second stall still releases a failed route.
- Rescue no longer ends halfway up a mine because the villager entered the initial six-block admission tolerance. The worker must reach the proved mouth and stand at surface level.
- A genuinely reached local surface can also resolve recovery when the old raised mouth has been flattened.
- Productive home-supply mining is recognized as legitimate work. A builder gathering stone for a committed home is no longer repeatedly interrupted by displaced-villager recovery.
- Idle or unrelated underground work still yields when recovery is needed.

### Terrain and structure protection

- Emergency digging preserves registered mine stair supports, including natural stone and ore carrying a communal tread.
- Emergency excavation checks adjacent water and lava before opening a dry wall.
- Home surveys and final construction admission reserve existing mine supports, swept headroom, and the surface exit step.
- The reservation includes the building’s foundation-preparation volume and remains valid for depleted registered mines.
- New homes can no longer seal an existing registered mine entrance.
- Emergency excavation recognizes crafted smooth and cut sandstone variants before a home finishes registration.
- Incomplete desert homes retain their wall protection. Raw natural sandstone remains available where the specific mining rules permit it.

### Farms and food

- Compact farms can establish on smaller usable patches without an oversized invisible margin rejecting the field.
- A completed farm must still be one coherent, planted field. Scattered farmland does not count as completed infrastructure.
- Farm admission checks unsupported sand and gravel before construction updates can collapse the field or its approach.
- Farmers wait through vanilla’s airborne no-query state instead of blacklisting a crop because a path request happened during a jump.
- Genuine route refusals and interrupted-route failures remain enforced.
- Critical hunger interrupts unrelated stale work when a real food route is available.
- Hungry villagers no longer resume old mining work ahead of food selection.
- Active fishing remains food work. Existing production and help fallbacks remain available when no food route exists.

### Shared storage and deliveries

- Storage ownership and expansion checks prevent several villagers noticing the same need from creating an unnecessary empty second chest.
- Storage-side path probes no longer disturb the carrier’s live navigation.
- Accepted approaches hand their exact target and first adjacent node to movement before reporting that travel has started.
- Chest approaches use actual dry standing height on uneven ground.
- If direct approaches fail, carriers can use bounded, checked intermediate legs that make real progress toward the chest.
- Unsafe, nonmoving, away-moving, tangent, or endpoint-mismatched legs remain rejected.
- A retained leg owns travel until arrival or a genuine stall rather than being discarded for another probe every few ticks.
- Initial route-queue waits remain protected.
- Once walking starts, later queued probes no longer renew the no-progress deadline. Actual body movement still counts.
- Transfers continue to require real physical reach and the existing access checks.

### Crafting and utility work

- Utility work requires a reachable crafting table and the appropriate line of sight.
- Villagers approach the station and perform timed work.
- Exact inputs must be available.
- Input consumption and result creation commit together.
- Separately owned equipment is preserved.

### Flight and terrain escape

- Villagers can use a checked level diagonal when ordinary cardinal escape steps fail.
- Diagonal escapes require a safe side passage, dry footing, body clearance, safe drops, improved threat separation, and the existing village-distance limits.
- A validated emergency step receives bounded physical follow-through instead of waiting for a later steering request while a pursuer attacks.
- Badly wounded villagers retain their emergency pace while flight still physically owns the body, rather than slowing when the brief hit animation expires.
- Edge recovery moves toward checked support already touching the body instead of leaving a wounded villager waiting on navigation.
- A new checked edge correction starts its own pursuit observation. The abandoned route’s old no-progress debt cannot cancel it before it moves.
- Emergency bank searches resume through unvisited candidates instead of repeatedly exhausting their budget on the same rejected nearby paths.
- Last-resort climb routes reject approaches that close on the pursuer or enter another observed melee body.
- Checked arrow dodges can finish their knockback arc within a short bounded landing allowance when recent melee contact is absent.
- Grounded stalls, overshoots, and expiry still force reconsideration.
- An earlier arrow wound no longer makes every later pursuer count as an archer. Ranged height restrictions follow the tracked ranged threat.

### Danger and combat

- Civilian flight, defender duty, and cornered self-defense have clearer ownership.
- Civilians still avoid fights they cannot win. Assigned defenders retain their duty, and trapped residents can defend themselves within the existing bounded rules.
- Immediate fight-or-flight planning now uses the same physical danger boundary as execution.
- An inaccessible hostile appraisal can no longer recreate an escape that has already resolved.
- Broader sightings can still affect emotions without becoming impossible escape destinations.
- Healthy villagers without recent bodily damage can resolve an old, non-pressing sighting sooner.
- Actual wounds, pressing threats, unstable footing, and unfinished landings retain their safety checks.
- Swing cooldowns advance once per combat turn across approach, guarding, retreat, and attack.
- Closing distance no longer pauses recovery. Damage and cooldown limits are unchanged.
- Combat odds include the selected visible foe’s nearby battle group even when retreat moves it outside the old body-centred query.
- This prevents a defender from undercounting the same group and repeatedly re-entering a losing fight.
- The query stays inside the existing role-dependent perception envelope. It does not reveal arbitrary unseen enemies.

### Shelter entry

- A villager touching its exact front step can settle onto it during an already-owned shelter crossing without losing the checked interior destination.
- Checked diagonal contact with that same front step is accepted.
- Generic edge recovery no longer overwrites the interior route at an awkward door corner.
- Existing door ownership, topology, height, hostile-entry checks, and lease duration remain unchanged.

### Fire and lava recovery

- Gathering routes reject new contact-hazard exposure while retaining safe exits from an existing exposure.
- Routes cannot leave a hazard and then re-enter it.
- Open civic and bedless-rest anchors require dry, fire-buffered footing.
- Unhoused daytime returns use the appropriate buffered surface anchor. Finished homes retain their exact interior authority.
- Lava escape retains its checked swim-and-climb route instead of treating downward lava drag as an unrelated fall.
- Fire recovery can settle onto dry support already carrying part of the body when its centre still lies above lava.
- The bounded correction checks the complete movement sweep, collision, occupancy, and newly contacted hazard cells.
- Intermediate support does not count as a finished refuge. A checked route to buffered ground is still required.
- Applicable support centring happens before driving a lava route that would pull the body away from the bank it already touches.
- The supplemental lava-climb motor now requires actual vanilla lava immersion.
- Nearby lava detected by a broad contact probe no longer causes false upward movement from dry ground.
- Immersed villagers retain the checked lava movement. Dry-bank villagers use ordinary navigation and step-up behavior.
- These changes do not heal, extinguish, teleport, remove lava, or create escape platforms.

### Regression and test improvements

- Motion checks keep legitimate work-phase handoffs separate instead of stitching them into false twitch windows.
- Movement uses three-dimensional distance so real quarry climbing is not labelled stationary pacing.
- Original failing playtest traces remain regression cases. Genuine flat-ground oscillation still fails.
- Stationary-hop detection requires actual upward movement evidence. Constant-height grounded-flag changes with falling velocity no longer count as jumps.
- Genuine rising and jumping cases remain detected with the existing thresholds.
- Construction proof recognizes a newly started shell completed through a repair handoff only when its exact type, origin, and full integrity match.
- Repairs to old homes, incomplete structures, farm work, mismatched origins, and duplicate events do not receive new-home credit.
- Woodcut tests wait for the exact villager’s brain attachment before pinning a target.
- Natural-world startup freezes at the intended tick boundary before delayed readiness bookkeeping can advance the world.
- A dedicated lava-bank regression reproduces the saved failure’s collision and lava arrangement.
- The bank test requires a real support-centering event, a checked route, safe arrival, and stable footing afterward.
- Lava remains present during the observed escape, with no healing, teleporting, or terrain assistance.
- Failed worlds and diagnostic evidence were retained alongside the final passing results.
- Designed-failure canaries verify that broken behavior reaches the final failure verdict.

### Release verification

- All 1,463 Java tests passed: 1,222 fast tests and 241 registry-backed tests.
- Two fresh deterministic boots produced byte-identical results and matched the reviewed full semantic and persistence fingerprint.
- One-day survival completed three homes, six beds, and 17 planted crops.
- Generated-world survival retained all 24 villagers, with two structures, three crops, 17 peak sleepers, and 57 peak hostiles.
- The generated-world run ended without unresolved acute recovery at dawn.
- A 40-frame rendered visual sweep passed, along with conversation and reload checks, five-family vernacular rendering, and equipment views.
- Functional behavior, transformations, interrupted-work continuity, and save/load checks passed.
- Population stress retained all 250 original villagers. The measured local megacrowd peak was 11 ms per server tick; this is a test result, not a hardware-independent guarantee.
- Hostile-flood, churn, simulation-distance, dimension, void, and water checks passed.
- The seven-simulated-day soak covered 169,200 game ticks and retained all 24 villagers with no founder deaths.
- That soak ended with four homes, eight beds, 19 crops, and 15 peak sleepers, with no final deep non-miner, deep need-pin, or failed deep escape pause.
- The focused lava-bank test reached safety in 25 ticks against its 40-tick requirement, retained full health, and passed all 20 stable ticks.
- Owned-door checks passed at all three tested loaded simulation tiers.
- The losing-fight retreat regression passed 8/8.
- A separate cramped-world case completed a paid 47-block family cottage with all 24 founders alive.
- The complete release certificate passed coverage, regression-history, receipt, ledger, and final artifact-identity checks.

### Source and license

- Sapience’s source code is now licensed under MIT.
- The license, mod metadata, distribution documentation, and source archive use the same terms.
- The release source snapshot contains 800 files, including the source, resources, build files, tests, documentation, and test tooling.
- Private runtime configuration, saves, EULA acceptance, caches, generated build files, and reference decompositions are excluded.
- Archive integrity, file inventory, safe paths, file hashes, and known credential patterns were checked.
- A clean extraction outside the development checkout built successfully with Java 21.
- All 1,463 tests passed again with zero failures, errors, or skips.
- The rebuilt JAR was byte-for-byte identical to the certified release.

### Requirements and known limits

- Fabric on Minecraft 1.21.1.
- Java 21 and Fabric API required.
- Tested with Fabric Loader 0.16.9 and Fabric API 0.116.13+1.21.1.
- Install the same Sapience JAR and Fabric API on the server and connecting clients.
- This JAR does not target other Minecraft versions, NeoForge, or Sinytra Connector.
- Back up important worlds before updating. Sapience changes villager AI and can modify terrain.
- Vanilla trading is still replaced. Right-click greets a villager; sneak-right-click with an item offers a gift. Player-facing trading is not included.
- Some fire-adjacent terrain can still leave villagers waiting for a safe route. Recovery from every generated terrain trap is not guaranteed.
- The long soak covers seven simulated Minecraft days, not a real-time week. Detailed CSV recording reached its 64 MiB cap; final-state and gate checks continued.
- Arbitrary modpacks, other operating systems, and a real multiplayer session were not certified by this test run.
- Sapience continues to run locally through deterministic game logic. No language model, account, API key, or cloud service is required.