@bongos/core 1.17.0

package/tests/verify_task_guard.mjs

@@ -0,0 +1,64 @@
+// tests/verify_task_guard.mjs
+//
+// task 1053 (F): a verification task (kind='verify') must not be confirmed before
+// the verify actually ran — the #1027 trap (a hardware-verify sat at 'confirmed'
+// on a passing doc-grade, the verify never performed). The signal is the explicit
+// `kind`, NOT a title regex — a task ABOUT verify work (like task 1053 itself,
+// "guard premature-confirm of verify/hardware-verify tasks") must NOT be treated
+// as a verification task.
+//
+// Run:  node tests/verify_task_guard.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const tasks = require('../modules/lifecycle/routes/tasks.js');
+const { isVerifyTask } = tasks;
+const { VALID_KINDS, classifyTaskKind } = require('../modules/lifecycle/task-classifier.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}\n     ${err.message}`); }
+}
+
+test("'verify' is a valid, settable kind", () => {
+  assert.ok(VALID_KINDS.has('verify'));
+});
+
+test('isVerifyTask: true ONLY for kind="verify"', () => {
+  assert.equal(isVerifyTask({ kind: 'verify' }), true);
+});
+
+test('isVerifyTask: false for every other kind', () => {
+  for (const k of ['feature', 'bug', 'infra', 'refactor', 'spike', 'cleanup', 'decision', 'unclassified']) {
+    assert.equal(isVerifyTask({ kind: k }), false, `${k} must not be a verify task`);
+  }
+});
+
+test('isVerifyTask: false on missing/empty input (no crash)', () => {
+  assert.equal(isVerifyTask(null), false);
+  assert.equal(isVerifyTask(undefined), false);
+  assert.equal(isVerifyTask({}), false);
+});
+
+test('NO title-regex false positive: a task ABOUT verify work is not auto-classified verify', () => {
+  // task 1053's own title — must not classify to 'verify' (kind is opt-in only).
+  const r1 = classifyTaskKind('fix: guard premature-confirm of verify/hardware-verify tasks', '');
+  assert.notEqual(r1.kind, 'verify');
+  // A genuine hardware-verify task title also does not AUTO-classify to verify —
+  // the planner opts in explicitly (kind='verify' / KIND: verify tag).
+  const r2 = classifyTaskKind('ADR 0055: hardware-verify server-mediated publish end-to-end', '');
+  assert.notEqual(r2.kind, 'verify');
+});
+
+test('explicit KIND: verify tag classifies as verify (the opt-in path)', () => {
+  const r = classifyTaskKind('hardware-verify the box ship', 'KIND: verify\nRun it on a real box.');
+  assert.equal(r.kind, 'verify');
+});
+
+console.log('');
+console.log(`verify_task_guard: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/version_close.mjs

@@ -0,0 +1,76 @@
+// tests/version_close.mjs
+//
+// Pure-helper coverage for scripts/gds/version-close.js (the `/version-close`
+// tooling that archives a shipped version + opens the next). The derive*/build*
+// functions are pure string/path transforms with no DB or git dependency, but
+// had no unit test — so a regression in, say, the version-id increment regex
+// would only surface at close time on the droplet. These pin the happy path +
+// one edge for each.
+//
+// Run:  node tests/version_close.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const {
+  deriveNextVersionId,
+  deriveNextScopePath,
+  deriveShippedPath,
+  buildCommitMessage,
+} = require('../scripts/gds/version-close.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- deriveNextVersionId ---------------------------------------------------
+t('deriveNextVersionId: happy path — increments the trailing number', () => {
+  assert.equal(deriveNextVersionId('GDS-V3'), 'GDS-V4');
+  assert.equal(deriveNextVersionId('V1'), 'V2');
+  assert.equal(deriveNextVersionId('GDS-V9'), 'GDS-V10'); // no zero-pad, carries past 9
+});
+
+t('deriveNextVersionId: edge — null when there is no trailing V<number>', () => {
+  assert.equal(deriveNextVersionId('mainline'), null);
+  assert.equal(deriveNextVersionId('V'), null);       // V with no digits
+  assert.equal(deriveNextVersionId(''), null);
+});
+
+// ---- deriveShippedPath -----------------------------------------------------
+t('deriveShippedPath: happy path — appends -shipped before .md, keeping the dir', () => {
+  assert.equal(deriveShippedPath('limitations/pms-v2.md', 'PMS-V2'), 'limitations/pms-v2-shipped.md');
+});
+
+t('deriveShippedPath: edge — falls back to a versionId-derived name when no current path', () => {
+  assert.equal(deriveShippedPath(null, 'GDS-V4'), 'limitations/gds-v4-shipped.md');
+});
+
+// ---- deriveNextScopePath ---------------------------------------------------
+t('deriveNextScopePath: happy path — swaps the version number in the filename', () => {
+  assert.equal(deriveNextScopePath('limitations/pms-v2.md', 'PMS-V3'), 'limitations/pms-v3.md');
+});
+
+t('deriveNextScopePath: edge — lower-cases the version id when the name is not numbered', () => {
+  assert.equal(deriveNextScopePath('limitations/backlog.md', 'GDS-V4'), 'limitations/gds-v4.md');
+});
+
+// ---- buildCommitMessage ----------------------------------------------------
+t('buildCommitMessage: happy path — carry-over count appears in the body', () => {
+  const msg = buildCommitMessage({ versionId: 'GDS-V3', nextVersionId: 'GDS-V4', shippedCount: 12, carryCount: 3 });
+  assert.match(msg, /^pms: close GDS-V3, open GDS-V4\n/);
+  assert.match(msg, /12 shipped task\(s\)/);
+  assert.match(msg, /with 3 carry-over task\(s\)/);
+});
+
+t('buildCommitMessage: edge — clean close wording when nothing carries over', () => {
+  const msg = buildCommitMessage({ versionId: 'GDS-V3', nextVersionId: 'GDS-V4', shippedCount: 0, carryCount: 0 });
+  assert.match(msg, /\(clean close\)/);
+  assert.doesNotMatch(msg, /carry-over/);
+});
+
+console.log(`\nversion_close: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/versions_route.mjs

@@ -0,0 +1,93 @@
+// tests/versions_route.mjs
+//
+// Unit tests for the no-DB pieces of POST /versions — the version-create seed
+// primitive `bongos init` uses (task 1204 / R65, V4.R65). The SQL itself
+// (db.createVersion → versions + done_when_criteria, atomic) is verified against
+// a live Postgres the same way the other write paths are (see search_route.mjs
+// note); here we pin the validation contract + that the router builds.
+//
+// Run:  node tests/versions_route.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { validate } = require('../src/bongos/routes/_helpers.js');
+const buildVersionsRouter = require('../modules/lifecycle/routes/versions.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// The EXACT schema declared in versions.js → POST /versions validateOrRespond().
+// Keep in sync if the route's schema changes.
+const VERSIONS_POST_SCHEMA = {
+  id: { required: true, type: 'string', maxLength: 64, minLength: 1 },
+  name: { required: true, type: 'string', maxLength: 200, minLength: 1 },
+  status: { type: 'string', maxLength: 32 },
+  done_when: { type: 'string', maxLength: 8000 },
+  scope_doc_path: { type: 'string', maxLength: 256 },
+  criteria: { type: 'array', maxItems: 100 },
+};
+
+// ---- the router builds (smoke: imports auth/db/branding/_helpers cleanly) ----
+test('buildVersionsRouter is a factory that returns a router', () => {
+  assert.equal(typeof buildVersionsRouter, 'function');
+  const router = buildVersionsRouter();
+  assert.equal(typeof router, 'function'); // express.Router() is a function
+});
+
+// ---- GOOD shapes (what `bongos init` will send) must pass the guard ----
+test('INIT: minimal create (id + name only) passes', () => {
+  assert.equal(validate({ id: 'V1', name: 'Prove the loop' }, VERSIONS_POST_SCHEMA), null);
+});
+
+test('INIT: full create with criteria array passes', () => {
+  const body = {
+    id: 'V1',
+    name: 'V1 — Prove the loop',
+    status: 'building',
+    done_when: 'A task goes claim → grade → ship, with credits, on this instance.',
+    criteria: [
+      { criterion_id: 'first-loop', criterion_md: 'A task reaches shipped with credits.' },
+    ],
+  };
+  assert.equal(validate(body, VERSIONS_POST_SCHEMA), null);
+});
+
+test('INIT: unknown extra fields pass through (forward-compat)', () => {
+  assert.equal(validate({ id: 'V1', name: 'x', future_field: 42 }, VERSIONS_POST_SCHEMA), null);
+});
+
+// ---- BAD shapes must return a structured 400, never throw / 500 ----
+test('BAD: missing id → missing', () => {
+  const r = validate({ name: 'x' }, VERSIONS_POST_SCHEMA);
+  assert.ok(r);
+  assert.ok(r.details.some((d) => d.field === 'id' && d.reason === 'missing'));
+});
+
+test('BAD: missing name → missing', () => {
+  const r = validate({ id: 'V1' }, VERSIONS_POST_SCHEMA);
+  assert.ok(r);
+  assert.ok(r.details.some((d) => d.field === 'name' && d.reason === 'missing'));
+});
+
+test('BAD: oversize id → too_long', () => {
+  const r = validate({ id: 'v'.repeat(65), name: 'x' }, VERSIONS_POST_SCHEMA);
+  assert.ok(r);
+  assert.ok(r.details.some((d) => d.field === 'id' && d.reason === 'too_long'));
+});
+
+test('BAD: more than 100 criteria → too_many_items', () => {
+  const criteria = Array.from({ length: 101 }, (_, i) => ({ criterion_id: `c${i}`, criterion_md: 'x' }));
+  const r = validate({ id: 'V1', name: 'x', criteria }, VERSIONS_POST_SCHEMA);
+  assert.ok(r);
+  assert.ok(r.details.some((d) => d.field === 'criteria' && d.reason === 'too_many_items'));
+});
+
+console.log('');
+console.log(`Versions route tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/walkability.mjs

@@ -0,0 +1,188 @@
+// tests/walkability.mjs
+//
+// Verify the ground-object split's walkability semantics:
+//   - Ground SEA blocks (terrain-level).
+//   - Ground GRASS / SAND walkable on their own.
+//   - Object ROCK on grass blocks (object-level).
+//   - Object CONTAINER_PANEL_DOOR on sand blocks (object-level).
+//   - Both also blocks (object wins, same outcome).
+//   - Out-of-bounds blocks.
+//
+// Exercises the SERVER-side isBlocked() — that's the source of truth
+// for movement validation. Loads it via require() since the server
+// module is CJS.
+//
+// Run:  node tests/walkability.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const serverMap = require('../modules/game/world/map.js');
+const serverTerrain = require('../modules/game/world/terrain.js');
+
+const { isBlocked, INITIAL_MAP, WORLD_COLS, WORLD_ROWS } = serverMap;
+const { TERRAIN, OBJECT, isBlockingTerrain, isBlockingObject } = serverTerrain;
+
+let passed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (e) {
+    console.error(`  FAIL ${name}: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// ---------- helpers ------------------------------------------------------------
+
+// Find a sample cell of each kind in the actual INITIAL_MAP.
+function findCell(predicate) {
+  for (let y = 0; y < WORLD_ROWS; y++) {
+    for (let x = 0; x < WORLD_COLS; x++) {
+      if (predicate(INITIAL_MAP.ground[y][x], INITIAL_MAP.objects[y][x], x, y)) {
+        return { x, y };
+      }
+    }
+  }
+  return null;
+}
+
+const seaCell  = findCell((g, _o) => g === TERRAIN.SEA);
+const sandCell = findCell((g, o)  => g === TERRAIN.SAND && !o);
+const grassCell = findCell((g, o) => g === TERRAIN.GRASS && !o);
+const rockCell = findCell((_g, o) => o === OBJECT.ROCK);
+const doorCell = findCell((_g, o) => o === OBJECT.CONTAINER_PANEL_DOOR);
+const panelCell = findCell((_g, o) => o === OBJECT.CONTAINER_PANEL_TL);
+
+// ---------- registry shape ------------------------------------------------------
+
+test('TERRAIN + OBJECT enums export expected ids', () => {
+  assert.equal(TERRAIN.GRASS, 'grass');
+  assert.equal(TERRAIN.SAND,  'sand');
+  assert.equal(TERRAIN.SEA,   'sea');
+  assert.equal(OBJECT.ROCK,   'rock');
+  assert.equal(OBJECT.CONTAINER_PANEL_DOOR, 'container_panel_door');
+});
+
+test('isBlockingTerrain: SEA blocks; GRASS, SAND, MARBLE_PATH walkable', () => {
+  assert.equal(isBlockingTerrain(TERRAIN.SEA), true);
+  assert.equal(isBlockingTerrain(TERRAIN.GRASS), false);
+  assert.equal(isBlockingTerrain(TERRAIN.SAND), false);
+  assert.equal(isBlockingTerrain(TERRAIN.MARBLE_PATH), false);
+});
+
+test('isBlockingObject: ROCK + all 8 container panels block; null + PATH_MARBLE walkable', () => {
+  assert.equal(isBlockingObject(null), false);
+  assert.equal(isBlockingObject(undefined), false);
+  assert.equal(isBlockingObject(OBJECT.ROCK), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_TL), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_T1), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_T2), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_TR), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_DOOR), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_B1), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_B2), true);
+  assert.equal(isBlockingObject(OBJECT.CONTAINER_PANEL_BR), true);
+  // ADR 0013: paths are non-blocking objects (you walk on the path).
+  assert.equal(isBlockingObject(OBJECT.PATH_MARBLE), false);
+});
+
+// ---------- isBlocked over the actual INITIAL_MAP ------------------------------
+
+test('INITIAL_MAP contains the expected cell kinds', () => {
+  assert.ok(seaCell,   'no sea cell in INITIAL_MAP');
+  assert.ok(sandCell,  'no plain-sand cell in INITIAL_MAP');
+  assert.ok(grassCell, 'no plain-grass cell in INITIAL_MAP');
+  assert.ok(rockCell,  'no rock cell in INITIAL_MAP');
+  assert.ok(doorCell,  'no container-door cell in INITIAL_MAP');
+  assert.ok(panelCell, 'no container_panel_tl cell in INITIAL_MAP');
+});
+
+test('sea cells are blocked', () => {
+  assert.equal(isBlocked(seaCell.x, seaCell.y), true);
+});
+
+test('plain sand cells are walkable', () => {
+  assert.equal(isBlocked(sandCell.x, sandCell.y), false);
+});
+
+test('plain grass cells are walkable', () => {
+  assert.equal(isBlocked(grassCell.x, grassCell.y), false);
+});
+
+test('rock-on-grass cells are blocked (object wins)', () => {
+  // The ground at the rock cell is GRASS (walkable). The object is ROCK
+  // (blocking). isBlocked must return true.
+  assert.equal(INITIAL_MAP.ground[rockCell.y][rockCell.x], TERRAIN.GRASS);
+  assert.equal(INITIAL_MAP.objects[rockCell.y][rockCell.x], OBJECT.ROCK);
+  assert.equal(isBlocked(rockCell.x, rockCell.y), true);
+});
+
+test('container-door cells are blocked (object wins; ground is sand)', () => {
+  assert.equal(INITIAL_MAP.ground[doorCell.y][doorCell.x], TERRAIN.SAND);
+  assert.equal(INITIAL_MAP.objects[doorCell.y][doorCell.x], OBJECT.CONTAINER_PANEL_DOOR);
+  assert.equal(isBlocked(doorCell.x, doorCell.y), true);
+});
+
+test('all 8 container-panel cells share GROUND=sand and have an OBJECT', () => {
+  // Container is at anchor (13, 8), 2 rows x 4 cols.
+  for (let r = 0; r < 2; r++) {
+    for (let c = 0; c < 4; c++) {
+      const x = 13 + c, y = 8 + r;
+      assert.equal(INITIAL_MAP.ground[y][x], TERRAIN.SAND, `(${x},${y}) ground should be sand`);
+      assert.ok(INITIAL_MAP.objects[y][x], `(${x},${y}) object should not be null`);
+      assert.equal(isBlocked(x, y), true, `(${x},${y}) should be blocked`);
+    }
+  }
+});
+
+test('vendor cell (13, 9) ground=sand, object=container_panel_door, blocked', () => {
+  // Door MUST be at bottom-LEFT to preserve vendor placement.
+  assert.equal(INITIAL_MAP.ground[9][13], TERRAIN.SAND);
+  assert.equal(INITIAL_MAP.objects[9][13], OBJECT.CONTAINER_PANEL_DOOR);
+  assert.equal(isBlocked(13, 9), true);
+});
+
+test('cell south of vendor (13, 10) is walkable (path-as-object on sand)', () => {
+  // ADR 0013: marble path is now an OBJECT overlay over SAND ground.
+  // The player approaches the vendor from here (faces up + presses E),
+  // so the cell must remain walkable: sand is non-blocking ground +
+  // path_marble is a non-blocking object.
+  assert.equal(INITIAL_MAP.ground[10][13], TERRAIN.SAND);
+  assert.equal(INITIAL_MAP.objects[10][13], OBJECT.PATH_MARBLE);
+  assert.equal(isBlockingObject(OBJECT.PATH_MARBLE), false,
+               'PATH_MARBLE must be non-blocking (you walk on a path)');
+  assert.equal(isBlocked(13, 10), false);
+});
+
+test('marble path strip (rows 10-13, col 13) all walkable, all path-on-sand', () => {
+  // ADR 0013: the entire path strip is OBJECT.PATH_MARBLE over SAND.
+  // No cell should block; ground should be uniform sand.
+  for (let y = 10; y <= 13; y++) {
+    assert.equal(INITIAL_MAP.ground[y][13], TERRAIN.SAND,
+                 `(13,${y}) ground should be SAND under the path overlay`);
+    assert.equal(INITIAL_MAP.objects[y][13], OBJECT.PATH_MARBLE,
+                 `(13,${y}) object should be PATH_MARBLE`);
+    assert.equal(isBlocked(13, y), false,
+                 `(13,${y}) should be walkable (sand + non-blocking path)`);
+  }
+});
+
+test('out-of-bounds is blocked', () => {
+  assert.equal(isBlocked(-1, 0), true);
+  assert.equal(isBlocked(0, -1), true);
+  assert.equal(isBlocked(WORLD_COLS, 0), true);
+  assert.equal(isBlocked(0, WORLD_ROWS), true);
+});
+
+// ---------- summary -------------------------------------------------------------
+
+if (process.exitCode !== 1) {
+  console.log(`\n[walkability] OK — ${passed} tests passed`);
+} else {
+  console.error(`\n[walkability] FAIL — see output above`);
+  process.exit(1);
+}

package/tests/wandering_prefs.mjs

@@ -0,0 +1,176 @@
+// tests/wandering_prefs.mjs
+//
+// Unit smoke for src/bongos/wandering-prefs.js (task 1268) — the per-builder
+// "wandering" knob. Covers the pure resolution: rank defaults, the rank ceiling
+// clamp (Xenos hard-locked, Thetes capped, Metic+ free), validate/apply, and the
+// describeForApi shape. DB plumbing is exercised by routes/me.js + the prod smoke;
+// here we cover the logic without touching pg.
+//
+// Run:  node tests/wandering_prefs.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const w = require('../modules/builder-settings/wandering-prefs.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log('wandering-prefs constants:');
+
+t('LEVELS has the four named levels in low→high order', () => {
+  assert.deepEqual(w.LEVELS, ['locked', 'focused', 'balanced', 'exploratory']);
+});
+
+t('every LEVEL has meta (with matching index) + a contract', () => {
+  for (let i = 0; i < w.LEVELS.length; i++) {
+    const key = w.LEVELS[i];
+    assert.ok(w.LEVEL_META[key], `meta for ${key}`);
+    assert.equal(w.LEVEL_META[key].n, i, `meta.n for ${key} === index`);
+    assert.equal(typeof w.contractFor(i), 'string');
+    assert.ok(w.contractFor(i).length > 0, `contract for ${key} non-empty`);
+  }
+});
+
+t('every rank with a default has a max, and default <= max', () => {
+  for (const rank of Object.keys(w.RANK_DEFAULT)) {
+    assert.ok(rank in w.RANK_MAX, `max for ${rank}`);
+    assert.ok(w.RANK_DEFAULT[rank] <= w.RANK_MAX[rank], `default<=max for ${rank}`);
+  }
+});
+
+console.log('\nrank defaults (the trust ladder):');
+
+t('defaults ride the ladder: xenos0 thetes1 metic2 archon3', () => {
+  assert.equal(w.effectiveLevel({}, 'xenos'), 0);
+  assert.equal(w.effectiveLevel({}, 'thetes'), 1);
+  assert.equal(w.effectiveLevel({}, 'metic'), 2);
+  assert.equal(w.effectiveLevel({}, 'archon'), 3);
+});
+
+t('unknown / absent rank falls back to the Locked floor', () => {
+  assert.equal(w.effectiveLevel({}, 'helot'), 0);
+  assert.equal(w.effectiveLevel({}, undefined), 0);
+  assert.equal(w.effectiveLevel({ wandering: 3 }, 'helot'), 0);
+});
+
+console.log('\nthe rank ceiling clamp (the load-bearing rule):');
+
+t('Xenos is hard-clamped to Locked regardless of stored override', () => {
+  for (const lvl of [1, 2, 3]) assert.equal(w.effectiveLevel({ wandering: lvl }, 'xenos'), 0);
+});
+
+t('Thetes is capped at Focused — may dial DOWN to Locked, never UP', () => {
+  assert.equal(w.effectiveLevel({ wandering: 0 }, 'thetes'), 0, 'down to Locked ok');
+  assert.equal(w.effectiveLevel({ wandering: 1 }, 'thetes'), 1, 'stay at Focused');
+  assert.equal(w.effectiveLevel({ wandering: 2 }, 'thetes'), 1, 'Balanced clamps to Focused');
+  assert.equal(w.effectiveLevel({ wandering: 3 }, 'thetes'), 1, 'Exploratory clamps to Focused');
+});
+
+t('Metic may set any level (rank is a starting default, not a ceiling)', () => {
+  assert.equal(w.effectiveLevel({ wandering: 0 }, 'metic'), 0);
+  assert.equal(w.effectiveLevel({ wandering: 3 }, 'metic'), 3);
+});
+
+t('Archon may set any level (incl. dialing down)', () => {
+  assert.equal(w.effectiveLevel({ wandering: 0 }, 'archon'), 0);
+  assert.equal(w.effectiveLevel({ wandering: 3 }, 'archon'), 3);
+});
+
+t('maxLevelForRank: xenos0 thetes1 metic3 archon3; unknown0', () => {
+  assert.equal(w.maxLevelForRank('xenos'), 0);
+  assert.equal(w.maxLevelForRank('thetes'), 1);
+  assert.equal(w.maxLevelForRank('metic'), 3);
+  assert.equal(w.maxLevelForRank('archon'), 3);
+  assert.equal(w.maxLevelForRank('nobody'), 0);
+});
+
+console.log('\ninject gating (only constraining levels are emitted):');
+
+t('shouldInject true for Locked/Focused, false for Balanced/Exploratory', () => {
+  assert.equal(w.shouldInject(0), true);
+  assert.equal(w.shouldInject(1), true);
+  assert.equal(w.shouldInject(2), false);
+  assert.equal(w.shouldInject(3), false);
+});
+
+console.log('\nvalidation:');
+
+t('validatePatch accepts an empty body', () => {
+  const r = w.validatePatch({});
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.patch, {});
+});
+
+t('validatePatch rejects non-object bodies', () => {
+  for (const bad of [null, undefined, 'x', 7, [1]]) {
+    assert.equal(w.validatePatch(bad).ok, false, `reject ${JSON.stringify(bad)}`);
+  }
+});
+
+t('validatePatch accepts a valid level and the null clear-sentinel', () => {
+  assert.equal(w.validatePatch({ wandering: 2 }).ok, true);
+  const cleared = w.validatePatch({ wandering: null });
+  assert.equal(cleared.ok, true);
+  assert.equal(cleared.patch.wandering, null);
+});
+
+t('validatePatch rejects out-of-range / non-integer levels', () => {
+  for (const bad of [-1, 4, 1.5, '1', true]) {
+    const r = w.validatePatch({ wandering: bad });
+    assert.equal(r.ok, false, `reject level ${JSON.stringify(bad)}`);
+  }
+});
+
+t('validatePatch rejects unknown keys', () => {
+  const r = w.validatePatch({ verbosity: 1 });
+  assert.equal(r.ok, false);
+  assert.equal(r.errors[0].error, 'unknown_key');
+});
+
+t('validatePatch enforces the rank cap via opts.maxLevel', () => {
+  const r = w.validatePatch({ wandering: 3 }, { maxLevel: 1 });
+  assert.equal(r.ok, false);
+  assert.equal(r.errors[0].error, 'above_rank_cap');
+  assert.equal(w.validatePatch({ wandering: 1 }, { maxLevel: 1 }).ok, true);
+});
+
+console.log('\npatch apply:');
+
+t('applyPatch sets, clears (null), and leaves other keys alone', () => {
+  assert.equal(w.applyPatch({}, { wandering: 2 }).wandering, 2);
+  assert.ok(!('wandering' in w.applyPatch({ wandering: 2 }, { wandering: null })));
+  const next = w.applyPatch({ verbosity: 5 }, { wandering: 1 });
+  assert.equal(next.verbosity, 5, 'other behavior keys untouched');
+  assert.equal(next.wandering, 1);
+});
+
+console.log('\ndescribeForApi (the /me + UI payload):');
+
+t('describeForApi reflects override vs effective + per-rank allowed set', () => {
+  const d = w.describeForApi({ wandering: 3 }, 'thetes');
+  assert.equal(d.override_level, 3);
+  assert.equal(d.effective_level, 1, 'thetes clamps 3→1');
+  assert.equal(d.max_level, 1);
+  assert.equal(d.effective_key, 'focused');
+  assert.equal(d.levels.length, 4);
+  assert.equal(d.levels.filter((l) => l.allowed).length, 2, 'thetes may pick Locked + Focused');
+  assert.equal(d.inject, true, 'focused is a constraining (injected) level');
+});
+
+t('describeForApi for an unset metic = rank default, all levels allowed', () => {
+  const d = w.describeForApi({}, 'metic');
+  assert.equal(d.override_level, null);
+  assert.equal(d.effective_level, 2);
+  assert.equal(d.default_level, 2);
+  assert.equal(d.levels.filter((l) => l.allowed).length, 4);
+  assert.equal(d.inject, false, 'balanced is permissive — not injected');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);