feat(v0.4.0): vNext — closed-loop world model + settlement contract

Implements the vNext architecture from the research doc: demote the noisy
multi-rail planner in favour of a closed loop (world truth → invariant check)
plus a single utility-driven goal authority.

L1 services (fix no_drop / silent pathfinder hang first):
- InventoryLedger: diff-based "did I actually get it" verifier; acquire-food
  now confirms via ledger.gainedSince instead of the unreliable count/event.
- MotionService.gotoSafe: wall-clock timeout + progress watchdog +
  path_update(noPath/timeout) → structured {reached|stuck|timeout|nopath}.

L3 plan — unify the three competing rails (curriculum/manifesto/storyline):
- Settlement Contract: ordered M0–M9 milestones, each invariant-checked
  against an authoritative world view (early steps delegate to the proven
  curriculum; late game adds farming).
- InvariantChecker + predicate library; GoalManager selects the lowest unmet
  milestone via utility argmax (food-urgency preempts, DEPS-style).
- Wired into the scheduler: bot.js precomputes snapshot.contract; reflex.js
  consumes it in place of the storyline rail. Manifesto L0 still preempts.

Eval + robustness:
- Village Score (single 0..1 metric) on the snapshot + TUI "build" line.
- survive.dig-in skill + dusk_dig_in mode (exposed at night, no bed → cover).
- approach_block helper (GoalNear + lookAt, avoids GoalLookAtBlock #341).

+28 new tests (450 total green). LLM remains entirely off the tick path.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

runtime/goal/contract.js

@@ -0,0 +1,149 @@
+// Settlement Contract (L3) — the global goal as a typed, invariant-checked
+// chain of milestones (research §2). This replaces the two competing
+// progression rails (storyline quest + raw curriculum) with ONE ordered
+// contract whose "done" is a fact about the world, not a guess.
+//
+// Each milestone:
+//   id          stable string
+//   title       human label (TUI / diary)
+//   invariants  [{ id, describe, met(world) }]  — milestone is "met" iff all hold
+//   suggest     (world) -> { skillId, args? } | null   — next concrete action
+//   urgency?    (world) -> number   — utility boost so survival-critical
+//               milestones (food) can preempt a lower-indexed unmet milestone
+//
+// The early tech-tree milestones delegate `suggest` to the proven
+// deterministic curriculum (runtime/curriculum.js) so we reuse its careful
+// chop→craft→tool chain instead of duplicating it. The contract owns ordering,
+// invariant truth, observability and the late-game milestones curriculum lacks.
+
+import { nextMilestone as curriculumNext } from "../curriculum.js";
+import {
+	alive,
+	foodSecure,
+	bedSecured,
+	stoneTier,
+	locationExists,
+	hasItem,
+	has,
+	WOODEN_TOOLS,
+	totalMatching,
+} from "./invariants.js";
+
+// curriculum's plan for the current snapshot. Prefer the plan bot.js already
+// precomputed onto snapshot.curriculum (single source, no double-walk); fall
+// back to recomputing when it is absent (unit tests, late-game). Returns null
+// when curriculum is exhausted — the late-game contract takes over.
+function curriculumPlan(world) {
+	const pre = world.snapshot?.curriculum?.plan;
+	if (pre && pre.skillId) return pre;
+	try {
+		return curriculumNext(world.snapshot)?.plan ?? null;
+	} catch {
+		return null;
+	}
+}
+
+const FOOD_MOBS = new Set(["cow", "pig", "chicken", "sheep", "rabbit", "mooshroom"]);
+function hasVisibleFoodTarget(world) {
+	const passives = world.nearbyEntities?.passives ?? [];
+	if (passives.some((e) => FOOD_MOBS.has(e.name))) return true;
+	return (world.nearbyEntities?.droppedItems?.length ?? 0) > 0;
+}
+
+// Wooden tools acquired, OR already advanced to stone tier (monotonic: don't
+// regress to "go chop wood" after the bot burned its logs into tools).
+const woodenOrStoneTier = {
+	id: "tool_tier",
+	describe: "wooden tools (or already stone tier)",
+	met: (w) =>
+		WOODEN_TOOLS.every((n) => has(w.inventory, n)) ||
+		totalMatching(w.inventory, (k) => /^stone_(axe|pickaxe|sword)$/.test(k)) > 0,
+};
+
+// A wheat farm is established. We mark it via a `farm` location (set by the
+// farm skill) or by carrying harvested wheat as a fallback proxy.
+const farmEstablished = {
+	id: "farm",
+	describe: "a wheat farm location or harvested wheat",
+	met: (w) => !!w.locations?.farm || has(w.inventory, "wheat", 3),
+};
+
+export const SETTLEMENT_CONTRACT = Object.freeze([
+	{
+		id: "M0_alive",
+		title: "Stay alive",
+		invariants: [alive()],
+		suggest: () => null, // survival layer (modes/manifesto) owns HP emergencies
+	},
+	{
+		id: "M1_wood_tools",
+		title: "Wooden tools",
+		invariants: [woodenOrStoneTier],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M2_bed",
+		title: "A bed to skip the night",
+		invariants: [bedSecured()],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M3_stone_tools",
+		title: "Stone tools + furnace",
+		invariants: [stoneTier()],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M4_food_security",
+		title: "Secure food",
+		invariants: [foodSecure()],
+		// Direct suggest (NOT curriculum): when food urgency preempts a lower
+		// milestone, the strictly-ordered curriculum would still return the
+		// wood step. We want the food action now.
+		suggest: (w) => ({ skillId: hasVisibleFoodTarget(w) ? "survive.acquire-food" : "survive.scout-food" }),
+		// Starving preempts lower-indexed progression: go eat/hunt now.
+		urgency: (w) => (w.food < 8 ? 100 : w.food < 12 ? 20 : 0),
+	},
+	{
+		id: "M5_storage",
+		title: "A personal chest",
+		invariants: [locationExists("chest")],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M6_lighting",
+		title: "Torches for the perimeter",
+		invariants: [hasItem("torch", 4, "torch")],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M7_base_site",
+		title: "Pick a base site",
+		invariants: [locationExists("base")],
+		suggest: curriculumPlan,
+	},
+	{
+		id: "M8_shelter",
+		title: "Build a shelter",
+		invariants: [locationExists("shelter")],
+		suggest: curriculumPlan,
+	},
+	// ---- beyond the curriculum: late-game settlement work ----
+	{
+		id: "M9_farm",
+		title: "Start a wheat farm",
+		invariants: [farmEstablished],
+		suggest: (w) => {
+			// Deposit first if we're drowning in surplus and have a chest.
+			const distinct = Object.keys(w.inventory ?? {}).length;
+			if (distinct >= 30 && w.locations?.chest) return { skillId: "village.deposit-surplus" };
+			return { skillId: "farm.wheat" };
+		},
+	},
+]);
+
+export function listContractMilestones() {
+	return SETTLEMENT_CONTRACT.map((m) => ({ id: m.id, title: m.title }));
+}
+
+export const _internal = { woodenOrStoneTier, farmEstablished, curriculumPlan };