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/services/inventory-ledger.js

@@ -0,0 +1,142 @@
+// InventoryLedger (L1 service) — diff-based "did I actually get it" verifier.
+//
+// The proximate cause of the live `no_drop` symptom (research §A.4, QW2): the
+// bot has no reliable signal that a pickup happened. mineflayer's
+// `playerCollect` event is unreliable (fires for the wrong entity when other
+// droppers tick nearby — mineflayer #1171) and item entities visually vanish
+// past ~16 blocks (Minecraft Wiki, Item entity). The only ground truth is the
+// inventory itself.
+//
+// This ledger snapshots `bot.inventory.items()` over time and answers two
+// questions deterministically:
+//   - count(name)               -> current count of an exact item
+//   - total(matcher)            -> sum of counts for items matching a predicate
+//   - gainedSince(baseline, m)  -> net positive gain of matching items vs a baseline
+//   - acquired(matcher, sinceTs)-> same, but baselined to a wall-clock timestamp
+//
+// Skills verify success with `const base = ledger.mark(); ...; ledger.update(bot);
+// const got = ledger.gainedSince(base, isFood)` instead of trusting events.
+//
+// Pure w.r.t. the runtime: it only reads inventory. update() is driven once
+// per tick from bot.js, and a skill may call update(bot) itself to force a
+// fresh read before checking a delta (independent of tick cadence).
+
+function itemsToCounts(items) {
+	const m = new Map();
+	for (const it of items ?? []) {
+		if (!it?.name) continue;
+		m.set(it.name, (m.get(it.name) ?? 0) + (it.count ?? 0));
+	}
+	return m;
+}
+
+function countsFromBot(bot) {
+	try {
+		return itemsToCounts(bot?.inventory?.items?.() ?? []);
+	} catch {
+		return new Map();
+	}
+}
+
+function matchFn(matcher) {
+	if (typeof matcher === "function") return matcher;
+	if (matcher instanceof RegExp) return (n) => matcher.test(n);
+	if (typeof matcher === "string") return (n) => n === matcher;
+	if (Array.isArray(matcher)) {
+		const set = new Set(matcher);
+		return (n) => set.has(n);
+	}
+	if (matcher instanceof Set) return (n) => matcher.has(n);
+	return () => true;
+}
+
+export function createInventoryLedger({ historyMs = 6 * 60_000, maxSnapshots = 240 } = {}) {
+	let history = []; // [{ ts, counts: Map<string,number> }], oldest→newest
+	let current = new Map();
+
+	// Record a snapshot now. Accepts a bot or a raw items array (for tests).
+	function update(botOrItems, now = Date.now()) {
+		current = Array.isArray(botOrItems) ? itemsToCounts(botOrItems) : countsFromBot(botOrItems);
+		history.push({ ts: now, counts: current });
+		const cutoff = now - historyMs;
+		while (history.length > 1 && (history[0].ts < cutoff || history.length > maxSnapshots)) {
+			history.shift();
+		}
+		return current;
+	}
+
+	function count(name) {
+		return current.get(name) ?? 0;
+	}
+
+	function total(matcher) {
+		const f = matchFn(matcher);
+		let sum = 0;
+		for (const [name, c] of current) if (f(name)) sum += c;
+		return sum;
+	}
+
+	// A baseline is just a frozen copy of the counts at a point in time.
+	function mark() {
+		return new Map(current);
+	}
+
+	function gainedSince(baseline, matcher) {
+		const f = matchFn(matcher);
+		const base = baseline ?? new Map();
+		let gained = 0;
+		for (const [name, c] of current) {
+			if (!f(name)) continue;
+			const before = base.get(name) ?? 0;
+			if (c > before) gained += c - before;
+		}
+		return gained;
+	}
+
+	// The newest recorded snapshot whose ts is <= sinceTs (i.e. the world as it
+	// was at that moment). Empty map if we have no history that old.
+	function baselineAt(sinceTs) {
+		let chosen = null;
+		for (const h of history) {
+			if (h.ts <= sinceTs) chosen = h;
+			else break;
+		}
+		return chosen ? new Map(chosen.counts) : new Map();
+	}
+
+	function acquired(matcher, sinceTs) {
+		return gainedSince(baselineAt(sinceTs), matcher);
+	}
+
+	// Full signed diff {name: change} vs the snapshot at sinceTs. Used for
+	// worldDelta validation and diary narration.
+	function delta(sinceTs) {
+		const base = baselineAt(sinceTs);
+		const out = {};
+		const names = new Set([...base.keys(), ...current.keys()]);
+		for (const name of names) {
+			const d = (current.get(name) ?? 0) - (base.get(name) ?? 0);
+			if (d !== 0) out[name] = d;
+		}
+		return out;
+	}
+
+	function snapshot() {
+		return new Map(current);
+	}
+
+	return {
+		update,
+		count,
+		total,
+		mark,
+		gainedSince,
+		acquired,
+		baselineAt,
+		delta,
+		snapshot,
+		_history: () => history,
+	};
+}
+
+export const _internal = { itemsToCounts, matchFn };

runtime/services/inventory-ledger.test.js

@@ -0,0 +1,84 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { createInventoryLedger, _internal } from "./inventory-ledger.js";
+
+function items(spec) {
+	return Object.entries(spec).map(([name, count]) => ({ name, count }));
+}
+
+function fakeBot(spec) {
+	return { inventory: { items: () => items(spec) } };
+}
+
+test("count + total reflect the latest snapshot", () => {
+	const led = createInventoryLedger();
+	led.update(fakeBot({ raw_chicken: 2, oak_log: 5, cobblestone: 12 }));
+	assert.equal(led.count("raw_chicken"), 2);
+	assert.equal(led.count("missing"), 0);
+	assert.equal(led.total(/_log$/), 5);
+	assert.equal(led.total((n) => n === "cobblestone" || n === "oak_log"), 17);
+});
+
+test("gainedSince counts only positive deltas of matching items", () => {
+	const led = createInventoryLedger();
+	led.update(fakeBot({ raw_chicken: 0, feather: 1 }));
+	const base = led.mark();
+	led.update(fakeBot({ raw_chicken: 2, feather: 3 }));
+	// food matcher: raw_chicken only
+	assert.equal(led.gainedSince(base, "raw_chicken"), 2);
+	// regex over both
+	assert.equal(led.gainedSince(base, /raw_chicken|feather/), 4);
+	// a drop must not register as a gain
+	led.update(fakeBot({ raw_chicken: 1, feather: 3 }));
+	assert.equal(led.gainedSince(base, "raw_chicken"), 1);
+});
+
+test("acquired baselines to a wall-clock timestamp via history", () => {
+	const led = createInventoryLedger();
+	led.update(fakeBot({ raw_chicken: 0 }), 1000);
+	led.update(fakeBot({ raw_chicken: 1 }), 2000);
+	const t = 2500;
+	led.update(fakeBot({ raw_chicken: 3 }), 3000);
+	// since t=2500 the baseline is the snapshot at ts=2000 (count 1) → gained 2
+	assert.equal(led.acquired("raw_chicken", t), 2);
+	// since the very beginning → gained 3
+	assert.equal(led.acquired("raw_chicken", 0), 3);
+});
+
+test("delta returns the signed diff vs a timestamp", () => {
+	const led = createInventoryLedger();
+	led.update(fakeBot({ oak_log: 5, dirt: 2 }), 1000);
+	led.update(fakeBot({ oak_log: 8, cobblestone: 4 }), 2000);
+	const d = led.delta(1000);
+	assert.equal(d.oak_log, 3);
+	assert.equal(d.cobblestone, 4);
+	assert.equal(d.dirt, -2);
+});
+
+test("history is pruned by age and cap", () => {
+	const led = createInventoryLedger({ historyMs: 1000, maxSnapshots: 100 });
+	led.update(fakeBot({ a: 1 }), 0);
+	led.update(fakeBot({ a: 1 }), 500);
+	led.update(fakeBot({ a: 1 }), 2000); // cutoff = 2000-1000=1000 → drops ts 0 and 500
+	const hist = led._history();
+	assert.equal(hist.length, 1);
+	assert.equal(hist[0].ts, 2000);
+});
+
+test("matchFn supports string, regex, array, set, fn", () => {
+	const { matchFn } = _internal;
+	assert.equal(matchFn("a")("a"), true);
+	assert.equal(matchFn("a")("b"), false);
+	assert.equal(matchFn(/x/)("axb"), true);
+	assert.equal(matchFn(["a", "b"])("b"), true);
+	assert.equal(matchFn(new Set(["c"]))("c"), true);
+	assert.equal(matchFn((n) => n.length === 3)("abc"), true);
+	assert.equal(matchFn(undefined)("anything"), true);
+});
+
+test("update accepts a raw items array (test convenience)", () => {
+	const led = createInventoryLedger();
+	led.update(items({ stick: 4 }));
+	assert.equal(led.count("stick"), 4);
+});

runtime/services/motion.js

@@ -0,0 +1,160 @@
+// MotionService (L1 service) — gotoSafe(): pathfinding that cannot hang silently.
+//
+// mineflayer-pathfinder has three documented failure modes that leak into the
+// planner as "false success / silent hang" (research §B):
+//   - #222: obstructed by an unbreakable block → bot stops, NO error, NO
+//     goal_reached / path_update / path_reset event. goto() never settles.
+//   - #273: AStar returns a partial path → monitorMovements returns early.
+//   - #341: GoalLookAtBlock raycasts collision boxes only → never "reached".
+//
+// gotoSafe wraps bot.pathfinder.goto with three independent kill-switches and
+// returns a STRUCTURED result the caller can branch on instead of awaiting a
+// promise that may never resolve:
+//   { ok: true,  code: "reached",  movedBlocks }
+//   { ok: false, code: "stuck",    movedBlocks }   // progress watchdog
+//   { ok: false, code: "timeout",  movedBlocks }   // wall-clock OR pf compute
+//   { ok: false, code: "nopath",   movedBlocks }   // path_update status noPath
+//   { ok: false, code: "goal_changed" | "error", movedBlocks }
+//
+// On any non-reached outcome it calls bot.pathfinder.stop() so the caller is
+// free to fall back (blind walk, dig-in, relocate) without two controllers
+// fighting over the same goal.
+
+import pathfinderPkg from "mineflayer-pathfinder";
+const { pathfinder } = pathfinderPkg;
+
+import { info, warn } from "../log.js";
+
+function hdist(a, b) {
+	if (!a || !b) return Number.POSITIVE_INFINITY;
+	return Math.hypot((a.x ?? 0) - (b.x ?? 0), (a.z ?? 0) - (b.z ?? 0));
+}
+
+function clonePos(p) {
+	return p ? { x: p.x, y: p.y, z: p.z } : null;
+}
+
+function round1(n) {
+	return Number.isFinite(n) ? Math.round(n * 10) / 10 : 0;
+}
+
+// Classify a goto() rejection into a stable code.
+export function classifyGotoError(err) {
+	const msg = (err?.message ?? String(err ?? "")).toLowerCase();
+	if (msg.includes("goalchanged") || msg.includes("goal was changed")) return "goal_changed";
+	if (msg.includes("took too long") || msg.includes("timed out") || msg.includes("timeout")) return "timeout";
+	if (msg.includes("no path") || msg.includes("nopath")) return "nopath";
+	return "error";
+}
+
+function ensurePathfinder(bot) {
+	// A real bot needs the plugin loaded once; a fake bot in tests already
+	// carries a stub `pathfinder`, so we only load when it is absent.
+	if (bot?.pathfinder) return;
+	try {
+		bot.loadPlugin(pathfinder);
+	} catch (e) {
+		warn("motion", `loadPlugin failed: ${e?.message ?? e}`);
+	}
+}
+
+export function createMotionService(bot, defaults = {}) {
+	if (!bot) throw new Error("motion: bot required");
+	ensurePathfinder(bot);
+
+	async function gotoSafe(goal, opts = {}) {
+		const timeoutMs = opts.timeoutMs ?? defaults.timeoutMs ?? 30_000;
+		const stuckWindowMs = opts.stuckWindowMs ?? defaults.stuckWindowMs ?? 8_000;
+		const stuckDelta = opts.stuckDelta ?? defaults.stuckDelta ?? 1.0;
+		const pollMs = opts.pollMs ?? defaults.pollMs ?? 1_000;
+		const graceMs = opts.graceMs ?? defaults.graceMs ?? 1_500;
+		const label = opts.label ?? "gotoSafe";
+
+		const startPos = clonePos(bot.entity?.position);
+		let lastProgressPos = startPos;
+		let lastProgressAt = Date.now();
+		const startedAt = lastProgressAt;
+
+		let settled = false;
+		let outcome = null;
+		let watchTimer = null;
+		let wallTimer = null;
+		let onPathUpdate = null;
+
+		const movedSoFar = () => hdist(startPos, bot.entity?.position);
+
+		function cleanup() {
+			if (watchTimer) { clearInterval(watchTimer); watchTimer = null; }
+			if (wallTimer) { clearTimeout(wallTimer); wallTimer = null; }
+			if (onPathUpdate) {
+				try { bot.removeListener?.("path_update", onPathUpdate); } catch {}
+				onPathUpdate = null;
+			}
+		}
+
+		function finalize(result) {
+			if (settled) return outcome;
+			settled = true;
+			outcome = { ...result, movedBlocks: round1(movedSoFar()) };
+			if (!result.ok) {
+				try { bot.pathfinder?.stop?.(); } catch {}
+			}
+			cleanup();
+			return outcome;
+		}
+
+		const gotoP = Promise.resolve()
+			.then(() => bot.pathfinder.goto(goal))
+			.then(
+				() => finalize({ ok: true, code: "reached", detail: null }),
+				(err) => finalize({ ok: false, code: classifyGotoError(err), detail: err?.message ?? String(err) }),
+			);
+
+		const earlyExit = new Promise((resolve) => {
+			onPathUpdate = (res) => {
+				const status = res?.status;
+				if (status === "noPath") {
+					resolve(finalize({ ok: false, code: "nopath", detail: "pathfinder: noPath" }));
+				} else if (status === "timeout") {
+					resolve(finalize({ ok: false, code: "timeout", detail: "pathfinder: compute timeout" }));
+				}
+			};
+			try { bot.on?.("path_update", onPathUpdate); } catch {}
+
+			watchTimer = setInterval(() => {
+				if (settled) return;
+				const now = Date.now();
+				if (now - startedAt < graceMs) return;
+				const here = bot.entity?.position;
+				if (hdist(lastProgressPos, here) >= stuckDelta) {
+					lastProgressPos = clonePos(here);
+					lastProgressAt = now;
+					return;
+				}
+				if (now - lastProgressAt >= stuckWindowMs) {
+					resolve(finalize({
+						ok: false,
+						code: "stuck",
+						detail: `no progress for ${Math.round((now - lastProgressAt) / 1000)}s`,
+					}));
+				}
+			}, pollMs);
+		});
+
+		const wallClock = new Promise((resolve) => {
+			wallTimer = setTimeout(() => {
+				resolve(finalize({ ok: false, code: "timeout", detail: `${label} wall-clock ${timeoutMs}ms` }));
+			}, timeoutMs);
+		});
+
+		const result = await Promise.race([gotoP, earlyExit, wallClock]);
+		if (!result.ok && result.code !== "goal_changed") {
+			info("motion", `${label} → ${result.code} (moved ${result.movedBlocks}b)`);
+		}
+		return result;
+	}
+
+	return { gotoSafe };
+}
+
+export const _internal = { hdist, classifyGotoError, clonePos, round1 };

runtime/services/motion.test.js

@@ -0,0 +1,92 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+
+import { createMotionService, classifyGotoError, _internal } from "./motion.js";
+
+function makeBot({ goto, startPos = { x: 0, y: 64, z: 0 } }) {
+	const em = new EventEmitter();
+	const bot = {
+		entity: { position: { ...startPos } },
+		pathfinder: {
+			goto,
+			_stopped: false,
+			stop() { this._stopped = true; },
+		},
+		on: (...a) => em.on(...a),
+		removeListener: (...a) => em.removeListener(...a),
+		emit: (...a) => em.emit(...a),
+		loadPlugin() {},
+	};
+	return bot;
+}
+
+const NEVER = () => new Promise(() => {});
+
+test("reached: goto resolves → ok/reached, pathfinder not stopped", async () => {
+	const bot = makeBot({ goto: () => Promise.resolve() });
+	const m = createMotionService(bot);
+	const r = await m.gotoSafe({}, { timeoutMs: 1000, stuckWindowMs: 1000, pollMs: 20, graceMs: 0 });
+	assert.equal(r.ok, true);
+	assert.equal(r.code, "reached");
+	assert.equal(bot.pathfinder._stopped, false);
+});
+
+test("stuck: goto hangs with no movement → stuck, pathfinder stopped", async () => {
+	const bot = makeBot({ goto: NEVER });
+	const m = createMotionService(bot);
+	const r = await m.gotoSafe({}, { timeoutMs: 5000, stuckWindowMs: 60, pollMs: 10, graceMs: 0, stuckDelta: 1 });
+	assert.equal(r.ok, false);
+	assert.equal(r.code, "stuck");
+	assert.equal(bot.pathfinder._stopped, true);
+});
+
+test("nopath: path_update status noPath → nopath", async () => {
+	const bot = makeBot({ goto: NEVER });
+	const m = createMotionService(bot);
+	const p = m.gotoSafe({}, { timeoutMs: 5000, stuckWindowMs: 5000, pollMs: 1000, graceMs: 5000 });
+	setTimeout(() => bot.emit("path_update", { status: "noPath" }), 20);
+	const r = await p;
+	assert.equal(r.code, "nopath");
+	assert.equal(bot.pathfinder._stopped, true);
+});
+
+test("timeout: goto hangs, wall-clock fires before watchdog", async () => {
+	const bot = makeBot({ goto: NEVER });
+	const m = createMotionService(bot);
+	const r = await m.gotoSafe({}, { timeoutMs: 40, stuckWindowMs: 10000, pollMs: 1000, graceMs: 10000 });
+	assert.equal(r.code, "timeout");
+});
+
+test("goal_changed: goto rejection is classified, not treated as reached", async () => {
+	const bot = makeBot({
+		goto: () => Promise.reject(new Error("GoalChanged: The goal was changed before it could be completed")),
+	});
+	const m = createMotionService(bot);
+	const r = await m.gotoSafe({}, { timeoutMs: 1000, stuckWindowMs: 1000, pollMs: 50, graceMs: 1000 });
+	assert.equal(r.ok, false);
+	assert.equal(r.code, "goal_changed");
+});
+
+test("progress resets the stuck window", async () => {
+	const bot = makeBot({ goto: NEVER });
+	const m = createMotionService(bot);
+	// Move the bot forward steadily so the watchdog never trips before timeout.
+	const mover = setInterval(() => { bot.entity.position.x += 5; }, 15);
+	const r = await m.gotoSafe({}, { timeoutMs: 120, stuckWindowMs: 80, pollMs: 10, graceMs: 0, stuckDelta: 1 });
+	clearInterval(mover);
+	// It kept moving, so it should hit the wall-clock timeout, not "stuck".
+	assert.equal(r.code, "timeout");
+	assert.ok(r.movedBlocks > 0, `expected movedBlocks>0, got ${r.movedBlocks}`);
+});
+
+test("classifyGotoError maps messages to stable codes", () => {
+	assert.equal(classifyGotoError(new Error("GoalChanged")), "goal_changed");
+	assert.equal(classifyGotoError(new Error("Took too long to compute path")), "timeout");
+	assert.equal(classifyGotoError(new Error("No path to the goal!")), "nopath");
+	assert.equal(classifyGotoError(new Error("something else")), "error");
+});
+
+test("hdist is horizontal only", () => {
+	assert.equal(_internal.hdist({ x: 0, y: 0, z: 0 }, { x: 3, y: 100, z: 4 }), 5);
+});