@polderlabs/bizar 6.2.5 → 7.0.0

package/packages/sdk/tests/router-orchestrator.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * Tests for the router orchestrator (F-033).
+ *
+ * Verifies the precedence chain:
+ *   explicit > codemod > q-learning > bandit > default
+ *
+ * Plus the surfaced-tags contract:
+ *   [CODEMOD_AVAILABLE] <intent>
+ *   [TASK_MODEL_RECOMMENDATION] <tier>
+ *
+ * Plus persistence: saveTo() writes state files; loadFrom() rehydrates
+ * the same priors.
+ */
+
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  decideAgentWith,
+  getRouter,
+  ModelRouter,
+  QLearningRouter,
+  codemodTag,
+  tierTag,
+  DEFAULT_MODEL_STATE_PATH,
+  DEFAULT_Q_STATE_PATH,
+} from "../src/router/index.js";
+
+describe("decideAgentWith — precedence chain", () => {
+  test("explicit agent wins (when known)", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, {
+      task: "convert var to const",
+      explicitAgent: "odin",
+    });
+    expect(d.agent).toBe("odin");
+    expect(d.agentConfidence).toBe(1.0);
+    expect(d.codemodIntent).toBeNull();
+    // Explicit path still emits a [TASK_MODEL_RECOMMENDATION] tag.
+    expect(d.surfacedTags.some((t) => t.startsWith("[TASK_MODEL_RECOMMENDATION]"))).toBe(true);
+    expect(d.surfacedTags.some((t) => t.startsWith("[CODEMOD_AVAILABLE]"))).toBe(false);
+  });
+
+  test("codemod intent short-circuits before q-learning", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "convert var to const" });
+    expect(d.agent).toBe("heimdall");
+    expect(d.agentConfidence).toBe(1.0);
+    expect(d.codemodIntent).toBe("var-to-const");
+    expect(d.modelTier).toBe("flash");
+    // Both tags should be surfaced for a codemod hit.
+    expect(d.surfacedTags.some((t) => t.includes("CODEMOD_AVAILABLE"))).toBe(true);
+    expect(d.surfacedTags.some((t) => t.includes("TASK_MODEL_RECOMMENDATION"))).toBe(true);
+  });
+
+  test("non-codemod task routes via q-learning + bandit", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "design a database schema" });
+    expect(["odin", "frigg", "vor", "mimir", "heimdall", "thor", "tyr", "forseti"])
+      .toContain(d.agent);
+    expect(d.codemodIntent).toBeNull();
+    expect(["flash", "mid", "expensive"]).toContain(d.modelTier);
+    expect(d.surfacedTags.length).toBe(1);
+    expect(d.surfacedTags[0]).toMatch(/^\[TASK_MODEL_RECOMMENDATION\]/);
+  });
+
+  test("unknown explicit agent falls through to q-learning", () => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: "hello world", explicitAgent: "totally-unknown" });
+    expect(d.agent).not.toBe("totally-unknown");
+    expect(AGENT_SET.has(d.agent)).toBe(true);
+  });
+});
+
+const AGENT_SET = new Set(["odin", "frigg", "vor", "mimir", "heimdall", "thor", "tyr", "forseti"]);
+
+describe("tag formatters", () => {
+  test("codemodTag includes intent and confidence", () => {
+    const tag = codemodTag("var-to-const", 0.71);
+    expect(tag).toContain("[CODEMOD_AVAILABLE]");
+    expect(tag).toContain("var-to-const");
+    expect(tag).toMatch(/conf=0\.71/);
+  });
+
+  test("tierTag includes tier and confidence", () => {
+    const tag = tierTag({ tier: "flash", confidence: 0.42 });
+    expect(tag).toContain("[TASK_MODEL_RECOMMENDATION]");
+    expect(tag).toContain("flash");
+    expect(tag).toMatch(/conf=0\.42/);
+  });
+});
+
+describe("getRouter() — factory + persistence", () => {
+  test("with custom routers is in-memory only", () => {
+    const mr = new ModelRouter({ seed: 1 });
+    const qr = new QLearningRouter({ seed: 1 });
+    const bundle = getRouter({ modelRouter: mr, qRouter: qr });
+    expect(bundle.modelRouter).toBe(mr);
+    expect(bundle.qRouter).toBe(qr);
+    const d = bundle.decideAgent({ task: "convert var to const" });
+    expect(d.codemodIntent).toBe("var-to-const");
+  });
+
+  test("default state paths are .harness/router-state.{model,q}", () => {
+    expect(DEFAULT_MODEL_STATE_PATH).toBe(".harness/router-state.json");
+    expect(DEFAULT_Q_STATE_PATH).toBe(".harness/q-router-state.json");
+  });
+
+  test("saveTo writes the bundle pointer + per-router state files", () => {
+    const dir = mkdtempSync(join(tmpdir(), "bizar-router-"));
+    try {
+      const mr = new ModelRouter({ seed: 5 });
+      const qr = new QLearningRouter({ seed: 5 });
+      // Force the persistence files into a temp dir by manipulating
+      // the bundle basePath through saveTo's sibling files.
+      const bundle = getRouter({ modelRouter: mr, qRouter: qr });
+      // Override the cwd-derived basePath so the save lands in `dir`.
+      const basePath = join(dir, "router-state");
+      const modelPath = `${basePath}.model`;
+      const qPath = `${basePath}.q`;
+      mr.saveTo(modelPath);
+      qr.saveTo(qPath);
+      expect(existsSync(modelPath)).toBe(true);
+      expect(existsSync(qPath)).toBe(true);
+      const state = JSON.parse(readFileSync(modelPath, "utf-8"));
+      expect(state.version).toBe(1);
+      expect(state.priors.flash.alpha).toBe(2);
+    } finally {
+      // mkdtempSync + recursive rm
+      const { rmSync } = require("node:fs");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ModelRouter.loadFrom rehydrates priors", () => {
+    const dir = mkdtempSync(join(tmpdir(), "bizar-router-"));
+    try {
+      const fp = join(dir, "router.json");
+      const original = new ModelRouter({ seed: 42 });
+      original.recordOutcome("flash", true);
+      original.recordOutcome("flash", true);
+      original.saveTo(fp);
+
+      const loaded = ModelRouter.loadFrom(fp);
+      const priors = loaded.getPriors();
+      expect(priors.flash.alpha).toBeGreaterThan(2);
+    } finally {
+      const { rmSync } = require("node:fs");
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("decideAgent — codemod short-circuit covers all three intents", () => {
+  test.each([
+    ["convert var to const", "var-to-const"],
+    ["remove console.log calls", "remove-console"],
+    ["add logging to the handler", "add-logging"],
+  ])("codemod surface for: %s", (prompt, expected) => {
+    const mr = new ModelRouter({ seed: 42 });
+    const qr = new QLearningRouter({ seed: 42 });
+    const d = decideAgentWith(mr, qr, { task: prompt });
+    expect(d.codemodIntent).toBe(expected);
+    expect(d.agent).toBe("heimdall");
+  });
+});

package/packages/sdk/tests/router.test.mjs

@@ -0,0 +1,91 @@
+/**
+ * Tests for codemod intent detection (F-033).
+ *
+ * 5+ positive prompts per deterministic intent (var-to-const,
+ * remove-console, add-logging) plus 5+ negatives that should NOT
+ * be codemod-eligible (the caller falls through to the bandit).
+ */
+
+import { describe, test, expect } from "vitest";
+import { detectCodemodIntent } from "../src/router/codemod-intent.js";
+
+describe("detectCodemodIntent — var-to-const", () => {
+  test("matches canonical phrasing", () => {
+    const hit = detectCodemodIntent("convert var to const");
+    expect(hit).not.toBeNull();
+    expect(hit?.intent).toBe("var-to-const");
+    expect(hit?.confidence).toBeGreaterThan(0);
+  });
+
+  test.each([
+    "change var to const in this file",
+    "replace var with const",
+    "use const instead of var",
+    "var to const for all declarations",
+    "convert var declarations to const",
+    "change var declarations to const everywhere",
+  ])("matches var-to-const phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("var-to-const");
+  });
+});
+
+describe("detectCodemodIntent — remove-console", () => {
+  test.each([
+    "remove console.log calls",
+    "delete console statements",
+    "strip console logs",
+    "clean up console",
+    "remove all debug logs",
+    "remove console.log statements everywhere",
+  ])("matches remove-console phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("remove-console");
+  });
+});
+
+describe("detectCodemodIntent — add-logging", () => {
+  test.each([
+    "add logging to the handler",
+    "add console.log statements",
+    "add debug logs to the module",
+    "log this function for diagnostics",
+    "add trace logging",
+    "instrument with logs",
+  ])("matches add-logging phrasing: %s", (prompt) => {
+    const hit = detectCodemodIntent(prompt);
+    expect(hit?.intent).toBe("add-logging");
+  });
+});
+
+describe("detectCodemodIntent — negatives", () => {
+  test.each([
+    "design a database schema for inventory",
+    "implement OAuth2 PKCE flow with refresh-token rotation",
+    "debug a memory leak in the cache",
+    "explain what this function does",
+    "refactor the http client to use async await",
+    "add type annotations to the API",
+    "wrap the parser in try/catch",
+  ])("rejects non-codemod prompt: %s", (prompt) => {
+    expect(detectCodemodIntent(prompt)).toBeNull();
+  });
+
+  test("returns null for empty input", () => {
+    expect(detectCodemodIntent("")).toBeNull();
+  });
+
+  test("returns null for non-string input", () => {
+    expect(detectCodemodIntent(null)).toBeNull();
+    expect(detectCodemodIntent(undefined)).toBeNull();
+    expect(detectCodemodIntent(42)).toBeNull();
+  });
+});
+
+describe("detectCodemodIntent — confidence ordering", () => {
+  test("multi-match returns the highest-confidence intent", () => {
+    const hit = detectCodemodIntent("convert var to const, replace var with const, change var declarations to const");
+    expect(hit?.intent).toBe("var-to-const");
+    expect(hit?.confidence).toBeGreaterThan(0.4);
+  });
+});

package/packages/sdk/tests/sdk.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * SDK smoke tests — exercise the public surface.
+ *
+ * Run via:  npm run test:sdk
+ *          (or: node --test packages/sdk/tests/sdk.test.mjs)
+ *
+ * Uses vitest. The suite covers:
+ *   - dist artefacts present after build:sdk
+ *   - package.json exports map
+ *   - SDK module surfaces (memory, fingerprint, dangerous-patterns, mcp)
+ *   - dangerous-pattern behaviour (rm -rf / denied)
+ *   - fingerprint stability
+ *   - frontmatter round-trip
+ */
+
+import { describe, test, expect } from "vitest";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = fileURLToPath(new URL(".", import.meta.url));
+const distDir = join(here, "..", "dist");
+const pkgPath = join(here, "..", "package.json");
+
+describe("SDK build", () => {
+  test("all dist artefacts present", () => {
+    for (const f of [
+      "index.js", "index.d.ts",
+      "dangerous-patterns.js", "dangerous-patterns.d.ts",
+      "fingerprint.js", "fingerprint.d.ts",
+      "memory/index.js", "memory/index.d.ts",
+      "mcp/server.js", "mcp/server.d.ts",
+      "mcp/bin.js", "mcp/bin.d.ts",
+      // v6.4.0 — F-033 Self-Learning (codemod + bandit + distillation).
+      "router/codemod-intent.js", "router/codemod-intent.d.ts",
+      "router/model-router.js", "router/model-router.d.ts",
+      "router/q-learning-router.js", "router/q-learning-router.d.ts",
+      "router/memory-distillation.js", "router/memory-distillation.d.ts",
+    ]) {
+      expect(existsSync(join(distDir, f))).toBe(true);
+    }
+  });
+
+  test("package.json exports map declares memory, mcp, dangerous-patterns", async () => {
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+    expect(pkg.name).toBe("@polderlabs/bizar-sdk");
+    expect(pkg.exports["."]).toBeTruthy();
+    expect(pkg.exports["./memory"]).toBeTruthy();
+    expect(pkg.exports["./mcp"]).toBeTruthy();
+    expect(pkg.exports["./dangerous-patterns"]).toBeTruthy();
+  });
+});
+
+describe("SDK module surface", () => {
+  test("dangerous-patterns module exports the expected API", async () => {
+    const mod = await import("../dist/dangerous-patterns.js");
+    expect(typeof mod.checkDangerous).toBe("function");
+    expect(typeof mod.listDangerousPatterns).toBe("function");
+    expect(typeof mod.getDangerousPatternStats).toBe("function");
+  });
+
+  test("fingerprint module exports a function", async () => {
+    const mod = await import("../dist/fingerprint.js");
+    expect(typeof mod.fingerprint).toBe("function");
+  });
+
+  test("memory module exports vault helpers", async () => {
+    const mod = await import("../dist/memory/index.js");
+    expect(typeof mod.readNote).toBe("function");
+    expect(typeof mod.writeNote).toBe("function");
+    expect(typeof mod.listNotes).toBe("function");
+    expect(typeof mod.searchNotes).toBe("function");
+    expect(typeof mod.parseFrontmatter).toBe("function");
+    expect(typeof mod.serializeFrontmatter).toBe("function");
+    expect(typeof mod.resolveVaultRoot).toBe("function");
+    expect(typeof mod.DEFAULT_MEMORY_VAULT).toBe("string");
+  });
+
+  test("MCP server module exposes ≥20 BIZAR_TOOLS (13 core + 4 swarm + 3 self-learning)", async () => {
+    const mod = await import("../dist/mcp/server.js");
+    expect(Array.isArray(mod.BIZAR_TOOLS)).toBe(true);
+    expect(mod.BIZAR_TOOLS.length).toBeGreaterThanOrEqual(20);
+    expect(typeof mod.createBizarMcpServer).toBe("function");
+    expect(typeof mod.createBizarMcpServerConfig).toBe("function");
+    expect(typeof mod.defineTool).toBe("function");
+    expect(typeof mod.getBizarMcpToolSummary).toBe("function");
+
+    const expectedNames = new Set([
+      "memory_read", "memory_write", "memory_list", "memory_search",
+      "plan_action", "open_kb",
+      "loop_list", "loop_status", "loop_start", "loop_stop",
+      "graph_query", "graph_path", "danger_check",
+      // F-032 — Swarm coordination.
+      "agent_spawn", "agent_list", "agent_terminate", "swarm_init",
+      // F-033 — Self-learning.
+      "model_route", "agent_route", "memory_distill",
+    ]);
+    const have = new Set(mod.BIZAR_TOOLS.map((t) => t.name));
+    for (const n of expectedNames) {
+      expect(have.has(n)).toBe(true);
+    }
+  });
+
+  test("F-033 router modules export the expected API", async () => {
+    const cm = await import("../dist/router/codemod-intent.js");
+    expect(typeof cm.detectCodemodIntent).toBe("function");
+
+    const mr = await import("../dist/router/model-router.js");
+    expect(typeof mr.ModelRouter).toBe("function");
+
+    const ql = await import("../dist/router/q-learning-router.js");
+    expect(typeof ql.QLearningRouter).toBe("function");
+    expect(Array.isArray(ql.AGENT_ACTIONS)).toBe(true);
+
+    const ds = await import("../dist/router/memory-distillation.js");
+    expect(typeof ds.runDistillation).toBe("function");
+  });
+});
+
+describe("dangerous-patterns behaviour", () => {
+  test("denies rm -rf /", async () => {
+    const { checkDangerous } = await import("../dist/dangerous-patterns.js");
+    const result = checkDangerous("rm -rf /");
+    expect(result.decision).toBe("deny");
+    expect(typeof result.reason).toBe("string");
+    expect(result.reason.length).toBeGreaterThan(0);
+  });
+
+  test("allows echo", async () => {
+    const { checkDangerous } = await import("../dist/dangerous-patterns.js");
+    const result = checkDangerous("echo hello world");
+    expect(result.decision).toBe("allow");
+  });
+});
+
+describe("fingerprint stability", () => {
+  test("same input produces same fingerprint", async () => {
+    const { fingerprint } = await import("../dist/fingerprint.js");
+    const a = fingerprint("Bash", { command: "ls -la /tmp" });
+    const b = fingerprint("Bash", { command: "ls -la /tmp" });
+    expect(a).toBe(b);
+    expect(typeof a).toBe("string");
+    expect(a.length).toBeGreaterThanOrEqual(16);
+  });
+
+  test("different tools produce different fingerprints", async () => {
+    const { fingerprint } = await import("../dist/fingerprint.js");
+    const a = fingerprint("Bash", { command: "ls" });
+    const b = fingerprint("Edit", { command: "ls" });
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("frontmatter round-trip", () => {
+  test("parses simple values", async () => {
+    const { parseFrontmatter } = await import("../dist/memory/index.js");
+    const md = "---\ntitle: Test\ncount: 3\n---\nHello world";
+    const parsed = parseFrontmatter(md);
+    expect(parsed.frontmatter.title).toBe("Test");
+    expect(parsed.frontmatter.count).toBe("3");
+    expect(parsed.body.trim()).toBe("Hello world");
+  });
+
+  test("serialize + parse preserves array form", async () => {
+    const { parseFrontmatter, serializeFrontmatter } = await import("../dist/memory/index.js");
+    const md = serializeFrontmatter({ title: "Test", tags: ["a", "b"] }, "\nbody");
+    expect(md.startsWith("---")).toBe(true);
+    const parsed = parseFrontmatter(md);
+    expect(parsed.frontmatter.title).toBe("Test");
+    expect(md.includes("tags: [a, b]")).toBe(true);
+  });
+});

package/packages/sdk/tests/swarm-topology.test.ts

@@ -0,0 +1,258 @@
+/**
+ * swarm-topology.test.ts — unit tests for the swarm topology registry.
+ *
+ * F-032 — covers initSwarm, maxAgents clamping, topology enum, the
+ * lazy default swarm, recordAgentInSwarm, decommissionSwarm, and
+ * optional JSON persistence.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  SwarmTopologyRegistry,
+  swarmTopologyRegistry,
+  initSwarm,
+  getSwarm,
+  listSwarms,
+  recordAgentInSwarm,
+  decommissionSwarm,
+  SWARM_TOPOLOGIES,
+  DEFAULT_TOPOLOGY,
+  DEFAULT_MAX_AGENTS,
+  DEFAULT_SWARM_ID,
+  type SwarmTopology,
+} from "../src/swarm-topology.js";
+
+describe("SwarmTopologyRegistry — class API", () => {
+  let reg: SwarmTopologyRegistry;
+
+  beforeEach(() => {
+    reg = new SwarmTopologyRegistry();
+  });
+
+  test("initSwarm creates a swarm with defaults when no args", () => {
+    const r = reg.initSwarm();
+    expect(r.topology).toBe(DEFAULT_TOPOLOGY);
+    expect(r.maxAgents).toBe(DEFAULT_MAX_AGENTS);
+    expect(r.swarmId).toMatch(/^swarm-\d+$/);
+    expect(typeof r.createdAt).toBe("string");
+  });
+
+  test("initSwarm accepts a custom swarmId", () => {
+    const r = reg.initSwarm({ swarmId: "alpha" });
+    expect(r.swarmId).toBe("alpha");
+    expect(reg.getSwarm("alpha")).toBeDefined();
+  });
+
+  test("initSwarm rejects duplicate swarmId", () => {
+    reg.initSwarm({ swarmId: "dup" });
+    expect(() => reg.initSwarm({ swarmId: "dup" })).toThrow(/already exists/);
+  });
+
+  test("topology enum is enforced — falls back to default for unknown", () => {
+    const r = reg.initSwarm({ topology: "unknown" as unknown as SwarmTopology });
+    expect(r.topology).toBe(DEFAULT_TOPOLOGY);
+  });
+
+  test("each valid topology is accepted", () => {
+    for (const topo of SWARM_TOPOLOGIES) {
+      const r = reg.initSwarm({ topology: topo });
+      expect(r.topology).toBe(topo);
+    }
+  });
+
+  test("maxAgents is clamped to [1, 1000]", () => {
+    const lo = reg.initSwarm({ maxAgents: -5 });
+    expect(lo.maxAgents).toBe(1);
+    const hi = reg.initSwarm({ maxAgents: 9999 });
+    expect(hi.maxAgents).toBe(1000);
+    const mid = reg.initSwarm({ maxAgents: 50 });
+    expect(mid.maxAgents).toBe(50);
+  });
+
+  test("maxAgents defaults to 15", () => {
+    const r = reg.initSwarm();
+    expect(r.maxAgents).toBe(15);
+  });
+
+  test("non-numeric maxAgents falls back to default", () => {
+    const r = reg.initSwarm({ maxAgents: NaN });
+    expect(r.maxAgents).toBe(15);
+    const r2 = reg.initSwarm({ maxAgents: "50" as unknown as number });
+    expect(r2.maxAgents).toBe(15);
+  });
+
+  test("metadata is round-tripped", () => {
+    const r = reg.initSwarm({ metadata: { owner: "F-032", region: "us" } });
+    expect(reg.getSwarm(r.swarmId)?.metadata).toEqual({ owner: "F-032", region: "us" });
+  });
+
+  test("the 'default' swarm is seeded lazily on first initSwarm call", () => {
+    expect(reg.getSwarm(DEFAULT_SWARM_ID)).toBeUndefined();
+    reg.initSwarm({ swarmId: "after" });
+    const def = reg.getSwarm(DEFAULT_SWARM_ID);
+    expect(def).toBeDefined();
+    expect(def?.topology).toBe(DEFAULT_TOPOLOGY);
+    expect(def?.maxAgents).toBe(DEFAULT_MAX_AGENTS);
+  });
+
+  test("listSwarms includes the default swarm after first initSwarm", () => {
+    reg.initSwarm({ swarmId: "x" });
+    const all = reg.listSwarms();
+    expect(all.map((s) => s.swarmId).sort()).toEqual([DEFAULT_SWARM_ID, "x"].sort());
+  });
+
+  test("getSwarm on missing id returns undefined", () => {
+    expect(reg.getSwarm("nope")).toBeUndefined();
+  });
+
+  test("recordAgentInSwarm appends agentIds and dedupes", () => {
+    const r = reg.initSwarm({ swarmId: "team", maxAgents: 3 });
+    recordAgentInSwarmOn(reg, "team", "a1");
+    recordAgentInSwarmOn(reg, "team", "a2");
+    recordAgentInSwarmOn(reg, "team", "a1"); // dedupe
+    const swarm = reg.getSwarm("team");
+    expect(swarm?.agentIds).toEqual(["a1", "a2"]);
+  });
+
+  test("recordAgentInSwarm refuses beyond maxAgents", () => {
+    const r = reg.initSwarm({ swarmId: "small", maxAgents: 2 });
+    recordAgentInSwarmOn(reg, "small", "a1");
+    recordAgentInSwarmOn(reg, "small", "a2");
+    expect(() => recordAgentInSwarmOn(reg, "small", "a3")).toThrow(/maxAgents/);
+  });
+
+  test("recordAgentInSwarm throws on missing swarm", () => {
+    expect(() => recordAgentInSwarmOn(reg, "ghost", "a1")).toThrow(/not found/);
+  });
+
+  test("decommissionSwarm marks the swarm and refuses further recordAgentInSwarm", () => {
+    reg.initSwarm({ swarmId: "doomed" });
+    reg.decommissionSwarm("doomed");
+    expect(reg.getSwarm("doomed")?.decommissionedAt).toBeDefined();
+    expect(() => recordAgentInSwarmOn(reg, "doomed", "a1")).toThrow(/decommissioned/);
+  });
+
+  test("decommissionSwarm refuses the default swarm", () => {
+    reg.initSwarm({ swarmId: "trigger" });
+    expect(() => reg.decommissionSwarm(DEFAULT_SWARM_ID)).toThrow(/default/);
+  });
+
+  test("decommissionSwarm throws on missing swarm", () => {
+    expect(() => reg.decommissionSwarm("ghost")).toThrow(/not found/);
+  });
+
+  test("reset() drops everything including the lazy default seed flag", () => {
+    reg.initSwarm({ swarmId: "x" });
+    expect(reg.listSwarms().length).toBeGreaterThan(0);
+    reg.reset();
+    expect(reg.listSwarms().length).toBe(0);
+    expect(reg.getSwarm(DEFAULT_SWARM_ID)).toBeUndefined();
+  });
+});
+
+// Helper — bypass module-level helper to operate on a per-test registry.
+function recordAgentInSwarmOn(
+  reg: SwarmTopologyRegistry,
+  swarmId: string,
+  agentId: string,
+) {
+  return reg.recordAgentInSwarm(swarmId, agentId);
+}
+
+describe("SwarmTopologyRegistry — module-level helpers", () => {
+  test("initSwarm helper shares state with swarmTopologyRegistry", () => {
+    const r = initSwarm({ swarmId: "shared" });
+    expect(swarmTopologyRegistry.getSwarm(r.swarmId)).toBeDefined();
+    expect(getSwarm(r.swarmId)?.swarmId).toBe("shared");
+    expect(listSwarms().some((s) => s.swarmId === "shared")).toBe(true);
+    // cleanup
+    swarmTopologyRegistry.decommissionSwarm("shared");
+  });
+
+  test("recordAgentInSwarm helper reflects in swarmTopologyRegistry", () => {
+    const r = initSwarm({ swarmId: "record-helper" });
+    recordAgentInSwarm(r.swarmId, "agent-x");
+    expect(swarmTopologyRegistry.getSwarm(r.swarmId)?.agentIds).toContain("agent-x");
+    swarmTopologyRegistry.decommissionSwarm(r.swarmId);
+  });
+
+  test("decommissionSwarm helper reflects in swarmTopologyRegistry", () => {
+    const r = initSwarm({ swarmId: "decomm-helper" });
+    decommissionSwarm(r.swarmId);
+    expect(swarmTopologyRegistry.getSwarm(r.swarmId)?.decommissionedAt).toBeDefined();
+  });
+});
+
+describe("SwarmTopologyRegistry — persistence", () => {
+  let dir: string;
+  let persistPath: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "swarm-topology-"));
+    persistPath = join(dir, "topology.json");
+  });
+
+  afterEach(() => {
+    if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("a fresh registry with persistPath starts empty when file is missing", () => {
+    const reg = new SwarmTopologyRegistry({ persistPath });
+    expect(reg.listSwarms()).toEqual([]);
+  });
+
+  test("initSwarm writes a snapshot to disk after each call", () => {
+    const reg = new SwarmTopologyRegistry({ persistPath });
+    reg.initSwarm({ swarmId: "alpha", topology: "mesh" });
+    expect(existsSync(persistPath)).toBe(true);
+    const stored = JSON.parse(readFileSync(persistPath, "utf-8")) as {
+      swarms: Array<{ swarmId: string; topology: string }>;
+    };
+    expect(stored.swarms.some((s) => s.swarmId === "alpha" && s.topology === "mesh")).toBe(true);
+  });
+
+  test("a new registry reading the same path picks up persisted swarms", () => {
+    const reg1 = new SwarmTopologyRegistry({ persistPath });
+    reg1.initSwarm({ swarmId: "persisted", topology: "adaptive", maxAgents: 25 });
+    expect(reg1.listSwarms().some((s) => s.swarmId === "persisted")).toBe(true);
+
+    const reg2 = new SwarmTopologyRegistry({ persistPath });
+    const got = reg2.getSwarm("persisted");
+    expect(got?.topology).toBe("adaptive");
+    expect(got?.maxAgents).toBe(25);
+  });
+
+  test("setPersistPath switches the persistence target at runtime", () => {
+    const reg = new SwarmTopologyRegistry();
+    reg.setPersistPath(persistPath);
+    reg.initSwarm({ swarmId: "first" });
+    expect(existsSync(persistPath)).toBe(true);
+
+    const other = join(dir, "topology-other.json");
+    reg.setPersistPath(other);
+    reg.initSwarm({ swarmId: "second" });
+    expect(existsSync(other)).toBe(true);
+  });
+
+  test("a corrupt persistence file does not crash the registry", () => {
+    require("node:fs").writeFileSync(persistPath, "{not json", "utf-8");
+    const reg = new SwarmTopologyRegistry({ persistPath });
+    expect(reg.listSwarms()).toEqual([]);
+    reg.initSwarm({ swarmId: "recovered" });
+    expect(reg.getSwarm("recovered")).toBeDefined();
+  });
+
+  test("decommissionSwarm writes decommissionedAt to the persisted file", () => {
+    const reg = new SwarmTopologyRegistry({ persistPath });
+    reg.initSwarm({ swarmId: "doomed" });
+    reg.decommissionSwarm("doomed");
+    const stored = JSON.parse(readFileSync(persistPath, "utf-8")) as {
+      swarms: Array<{ swarmId: string; decommissionedAt?: string }>;
+    };
+    const row = stored.swarms.find((s) => s.swarmId === "doomed");
+    expect(row?.decommissionedAt).toBeDefined();
+  });
+});