feat(v0.4.0): finish vNext plan — anti-loop, skill-graph, worldDelta diff, flee→motion

Completes the remaining v0.4.0 plan items and one fix motivated by a live in-game observation (flee hanging 30s against a persistent zombie). - flee → MotionService.gotoSafe: structured {stuck|timeout|nopath} in ~4s with a blind-retreat fallback, instead of the observed 30s pathfinder hang + 3 watchdog replans. Movements setup guarded so it is unit-testable. - QW5 anti-loop (runtime/anti-loop.js): same skill failing >=3x in 5min → 30min blacklist (reflex shouldSkip) + one-shot improvement_request (bot.js drainFired -> writeProposal). - 4.1 closed-loop worldDelta: runSkill snapshots inventory before execute and attaches the real delta (_invObserved) to every successful result; opt-in skill.expectGain asserts the claimed gain or returns world_unchanged. - 3.6 skill-graph (Plan4MC): declarative requires/produces for ~20 skills; prerequisitesMet/canRun/runnableFrontier; GoalManager annotates suggestions with blockedBy when prereqs are unmet. +22 tests (472 total green). Live smoke confirmed dig-in works and no new errors; flee loop is what this commit's flee migration addresses. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-28 11:20:52 +03:00
parent 2a6cc0cdb1
commit c963ab3ecb
13 changed files with 575 additions and 26 deletions
@@ -17,6 +17,7 @@

 import { SETTLEMENT_CONTRACT } from "./contract.js";
 import { checkInvariants, worldFromSnapshot } from "./invariants.js";
+import { prerequisitesMet } from "./skill-graph.js";

 export function createGoalManager({ contract = SETTLEMENT_CONTRACT } = {}) {
 	// Evaluate every milestone; returns the per-milestone invariant status plus
@@ -57,6 +58,14 @@ export function createGoalManager({ contract = SETTLEMENT_CONTRACT } = {}) {
 			suggestedSkill = null;
 		}

+		// Annotate the suggestion with skill-graph prerequisite status (Plan4MC).
+		// Observability + a guard surface: if prereqs are unmet the curriculum
+		// chain should already be steering toward them, but we expose the gap.
+		if (suggestedSkill?.skillId) {
+			const pre = prerequisitesMet(suggestedSkill.skillId, world);
+			if (!pre.ok) suggestedSkill = { ...suggestedSkill, blockedBy: pre.missing };
+		}
+
 		const reason = current.urgency > 0 && current.index > unmet[0].index
 			? `urgent:${current.id}(${current.urgency}) preempts ${unmet[0].id}`
 			: `lowest unmet: ${current.id}`;
@@ -0,0 +1,89 @@
+// Skill dependency graph (Plan4MC-style, research §C). A static, declarative
+// model of "what does this skill need, what does it produce". The contract
+// already SEQUENCES the early game via the curriculum, so this graph is the
+// queryable prerequisite layer on top: the GoalManager annotates each suggested
+// skill with whether its prerequisites currently hold (surfaced for the TUI and
+// as a guard against suggesting a skill that physically cannot succeed here).
+//
+// Requirement kinds:
+//   { item: <semantic-group|exact>, min }   — need N of an item / group
+//   { tool: "pickaxe" | "axe" | "sword" }     — need any tier of that tool
+// Semantic groups: logs (*_log/_stem), planks (*_planks), sticks, cobblestone,
+// wool (*_wool), coal, bed (*_bed). Anything else is matched as an exact name.
+
+import { totalMatching, has } from "./invariants.js";
+
+const GROUP = {
+	logs: (k) => k.endsWith("_log") || k.endsWith("_stem"),
+	planks: (k) => k.endsWith("_planks"),
+	wool: (k) => k.endsWith("_wool"),
+	cobblestone: (k) => k === "cobblestone" || k === "cobbled_deepslate",
+	coal: (k) => k === "coal" || k === "charcoal",
+};
+
+const TOOL = {
+	pickaxe: (k) => k.endsWith("_pickaxe"),
+	axe: (k) => k.endsWith("_axe") && !k.endsWith("_pickaxe"),
+	sword: (k) => k.endsWith("_sword"),
+};
+
+export const SKILL_GRAPH = Object.freeze({
+	"gather.logs": { requires: [], produces: ["logs"] },
+	"gather.wool": { requires: [], produces: ["wool"] },
+	"gather.stone": { requires: [{ tool: "pickaxe" }], produces: ["cobblestone"] },
+	"craft.planks": { requires: [{ item: "logs", min: 1 }], produces: ["planks"] },
+	"craft.sticks": { requires: [{ item: "planks", min: 2 }], produces: ["stick"] },
+	"craft.wooden-axe": { requires: [{ item: "planks", min: 3 }, { item: "stick", min: 2 }], produces: ["wooden_axe"] },
+	"craft.wooden-pickaxe": { requires: [{ item: "planks", min: 3 }, { item: "stick", min: 2 }], produces: ["wooden_pickaxe"] },
+	"craft.wooden-sword": { requires: [{ item: "planks", min: 2 }, { item: "stick", min: 1 }], produces: ["wooden_sword"] },
+	"craft.stone-axe": { requires: [{ item: "cobblestone", min: 3 }, { item: "stick", min: 2 }], produces: ["stone_axe"] },
+	"craft.stone-pickaxe": { requires: [{ item: "cobblestone", min: 3 }, { item: "stick", min: 2 }], produces: ["stone_pickaxe"] },
+	"craft.stone-sword": { requires: [{ item: "cobblestone", min: 2 }, { item: "stick", min: 1 }], produces: ["stone_sword"] },
+	"craft.furnace": { requires: [{ item: "cobblestone", min: 8 }], produces: ["furnace"] },
+	"craft.chest": { requires: [{ item: "planks", min: 8 }], produces: ["chest"] },
+	"craft.torch": { requires: [{ item: "coal", min: 1 }, { item: "stick", min: 1 }], produces: ["torch"] },
+	"craft.bed": { requires: [{ item: "wool", min: 3 }, { item: "planks", min: 3 }], produces: ["bed"] },
+	"village.choose-base": { requires: [], produces: ["loc:base"] },
+	"village.build-shelter": { requires: [{ item: "planks", min: 1 }], produces: ["loc:shelter"] },
+	"village.place-chest": { requires: [{ item: "chest", min: 1 }], produces: ["loc:chest"] },
+	"farm.wheat": { requires: [], produces: [] },
+});
+
+function itemCount(inv, name) {
+	const g = GROUP[name];
+	return g ? totalMatching(inv, g) : (inv?.[name] ?? 0);
+}
+
+function hasTool(inv, kind) {
+	const t = TOOL[kind];
+	if (!t) return false;
+	return Object.keys(inv ?? {}).some((k) => t(k) && (inv[k] ?? 0) > 0);
+}
+
+// { ok, missing: [{ item|tool, min, have }] } for a skill given the world.
+export function prerequisitesMet(skillId, world) {
+	const node = SKILL_GRAPH[skillId];
+	if (!node) return { ok: true, missing: [], known: false };
+	const inv = world?.inventory ?? {};
+	const missing = [];
+	for (const req of node.requires) {
+		if (req.tool) {
+			if (!hasTool(inv, req.tool)) missing.push({ tool: req.tool });
+		} else if (req.item) {
+			const have = itemCount(inv, req.item);
+			if (have < (req.min ?? 1)) missing.push({ item: req.item, min: req.min ?? 1, have });
+		}
+	}
+	return { ok: missing.length === 0, missing, known: true };
+}
+
+export function canRun(skillId, world) {
+	return prerequisitesMet(skillId, world).ok;
+}
+
+// All skills whose prerequisites currently hold (Plan4MC "frontier").
+export function runnableFrontier(world) {
+	return Object.keys(SKILL_GRAPH).filter((id) => canRun(id, world));
+}
+
+export const _internal = { GROUP, TOOL, itemCount, hasTool, has };
@@ -0,0 +1,56 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { prerequisitesMet, canRun, runnableFrontier, _internal } from "./skill-graph.js";
+
+function world(inv = {}) {
+	return { inventory: inv };
+}
+
+test("gather.logs needs nothing", () => {
+	assert.equal(canRun("gather.logs", world()), true);
+});
+
+test("gather.stone needs a pickaxe (any tier)", () => {
+	assert.equal(canRun("gather.stone", world({})), false);
+	assert.equal(canRun("gather.stone", world({ wooden_pickaxe: 1 })), true);
+	assert.equal(canRun("gather.stone", world({ stone_pickaxe: 1 })), true);
+});
+
+test("craft.planks needs a log (semantic group)", () => {
+	assert.equal(canRun("craft.planks", world({})), false);
+	assert.equal(canRun("craft.planks", world({ birch_log: 1 })), true);
+	assert.equal(canRun("craft.planks", world({ mangrove_stem: 2 })), true);
+});
+
+test("craft.furnace needs 8 cobblestone", () => {
+	assert.equal(canRun("craft.furnace", world({ cobblestone: 7 })), false);
+	assert.equal(canRun("craft.furnace", world({ cobblestone: 8 })), true);
+	assert.equal(canRun("craft.furnace", world({ cobbled_deepslate: 8 })), true);
+});
+
+test("prerequisitesMet reports the missing requirement detail", () => {
+	const r = prerequisitesMet("craft.wooden-pickaxe", world({ stick: 2 }));
+	assert.equal(r.ok, false);
+	assert.deepEqual(r.missing, [{ item: "planks", min: 3, have: 0 }]);
+});
+
+test("unknown skill is treated as runnable (known:false)", () => {
+	const r = prerequisitesMet("explore.far", world());
+	assert.equal(r.ok, true);
+	assert.equal(r.known, false);
+});
+
+test("axe matcher excludes pickaxe", () => {
+	assert.equal(_internal.TOOL.axe("wooden_axe"), true);
+	assert.equal(_internal.TOOL.axe("wooden_pickaxe"), false);
+	assert.equal(_internal.TOOL.pickaxe("stone_pickaxe"), true);
+});
+
+test("runnableFrontier grows as inventory fills", () => {
+	const empty = runnableFrontier(world());
+	const stocked = runnableFrontier(world({ oak_planks: 8, stick: 4, cobblestone: 8, wooden_pickaxe: 1 }));
+	assert.ok(stocked.length > empty.length);
+	assert.ok(stocked.includes("gather.stone"));
+	assert.ok(stocked.includes("craft.furnace"));
+});