Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
10.9 KB
Raw Blame
/**
 * Tests for `mergePreferences` — the §12 mutating writer.
 *
 * Fixtures are built via the canonical `writePreference` so the
 * on-disk shape stays in lockstep with production output. Guards
 * are tested by `expect.toThrow(BrainMergeError)` plus a `code`
 * check; the happy path is verified by reading the resulting files
 * back through `parsePreference`/`parseRetired`/`parseLogDay`.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { regenerateActiveQuiet } from "../../../src/core/brain/active.ts";
import { parseLogDay } from "../../../src/core/brain/log.ts";
import { BrainMergeError, mergePreferences } from "../../../src/core/brain/merge.ts";
import {
  parsePreference,
  parseRetired,
  writePreference,
  type WritePreferenceInput,
} from "../../../src/core/brain/preference.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
} from "../../../src/core/brain/types.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

let vault: string;
const NOW = new Date("2026-05-18T10:00:00Z");

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-merge-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
  mkdirSync(join(vault, "Brain", "log"), { recursive: true });
});
afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

function basePref(
  slug: string,
  overrides: Partial<WritePreferenceInput> = {},
): WritePreferenceInput {
  return {
    slug,
    topic: "commits",
    principle: `Principle for ${slug}`,
    created_at: "2026-05-01T00:00:00Z",
    unconfirmed_until: "2026-05-08T00:00:00Z",
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
    confirmed_at: "2026-05-02T00:00:00Z",
    applied_count: 1,
    violated_count: 0,
    last_evidence_at: "2026-05-02T00:00:00Z",
    confidence: BRAIN_CONFIDENCE.high,
    confidence_value: 0.8,
    pinned: false,
    ...overrides,
  };
}

describe("mergePreferences — guards", () => {
  test("rejects when keep id equals drop id", () => {
    writePreference(vault, basePref("a"));
    expect(() => mergePreferences(vault, "pref-a", "pref-a", { now: NOW })).toThrow(
      BrainMergeError,
    );
  });

  test("rejects when keep is missing", () => {
    writePreference(vault, basePref("b"));
    try {
      mergePreferences(vault, "pref-missing", "pref-b", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("keep-not-found");
    }
  });

  test("rejects when drop is missing", () => {
    writePreference(vault, basePref("a"));
    try {
      mergePreferences(vault, "pref-a", "pref-missing", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("drop-not-found");
    }
  });

  test("rejects mismatched topic", () => {
    writePreference(vault, basePref("a", { topic: "x" }));
    writePreference(vault, basePref("b", { topic: "y" }));
    try {
      mergePreferences(vault, "pref-a", "pref-b", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("topic-mismatch");
    }
  });

  test("rejects mismatched scope (string vs null)", () => {
    writePreference(vault, basePref("a", { scope: "writing" }));
    writePreference(vault, basePref("b"));
    try {
      mergePreferences(vault, "pref-a", "pref-b", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("scope-mismatch");
    }
  });

  test("rejects when drop is pinned and keep is not", () => {
    writePreference(vault, basePref("a"));
    writePreference(vault, basePref("b", { pinned: true }));
    try {
      mergePreferences(vault, "pref-a", "pref-b", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("pin-parity");
    }
  });

  test("rejects unconfirmed preferences", () => {
    writePreference(
      vault,
      basePref("a", {
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
      }),
    );
    writePreference(vault, basePref("b"));
    try {
      mergePreferences(vault, "pref-a", "pref-b", { now: NOW });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(BrainMergeError);
      expect((e as BrainMergeError).code).toBe("unsupported-status");
    }
  });

  test("accepts when both are pinned", () => {
    writePreference(vault, basePref("a", { pinned: true }));
    writePreference(vault, basePref("b", { pinned: true }));
    expect(() => mergePreferences(vault, "pref-a", "pref-b", { now: NOW })).not.toThrow();
  });
});

describe("mergePreferences — happy path", () => {
  test("merges counters, evidenced_by, last_evidence_at; retires drop with merged-into", () => {
    writePreference(
      vault,
      basePref("keep", {
        evidenced_by: ["[[sig-2026-05-01-keep]]", "[[sig-2026-05-02-shared]]"],
        applied_count: 5,
        violated_count: 1,
        last_evidence_at: "2026-05-10T00:00:00Z",
        principle: "Use imperative voice in commit subjects",
      }),
    );
    writePreference(
      vault,
      basePref("drop", {
        evidenced_by: ["[[sig-2026-05-02-shared]]", "[[sig-2026-05-03-drop]]"],
        applied_count: 4,
        violated_count: 0,
        last_evidence_at: "2026-05-12T00:00:00Z",
        principle: "Write commit subjects in imperative voice",
      }),
    );
    regenerateActiveQuiet(vault, { now: NOW });

    const plan = mergePreferences(vault, "pref-keep", "pref-drop", {
      now: NOW,
      agentName: "test-agent",
    });

    expect(plan.keep_id).toBe("pref-keep");
    expect(plan.drop_id).toBe("pref-drop");
    expect(plan.applied_sum).toBe(9);
    expect(plan.violated_sum).toBe(1);
    expect(plan.last_evidence_at).toBe("2026-05-12T00:00:00Z");
    expect(plan.merged_evidenced_by).toEqual([
      "[[sig-2026-05-01-keep]]",
      "[[sig-2026-05-02-shared]]",
      "[[sig-2026-05-03-drop]]",
    ]);

    // Keep is updated on disk.
    const keepPath = join(vault, "Brain", "preferences", "pref-keep.md");
    const keep = parsePreference(keepPath);
    expect(keep.applied_count).toBe(9);
    expect(keep.violated_count).toBe(1);
    expect(keep.last_evidence_at).toBe("2026-05-12T00:00:00Z");
    expect(keep.evidenced_by).toEqual([
      "[[sig-2026-05-01-keep]]",
      "[[sig-2026-05-02-shared]]",
      "[[sig-2026-05-03-drop]]",
    ]);
    // Principle and other identity fields stay on keep.
    expect(keep.principle).toBe("Use imperative voice in commit subjects");

    // Drop is gone from preferences/ and present in retired/ with the
    // merged-into reason and a superseded_by pointing at keep.
    const dropPrefPath = join(vault, "Brain", "preferences", "pref-drop.md");
    expect(existsSync(dropPrefPath)).toBe(false);
    const retiredPath = join(vault, "Brain", "retired", "ret-drop.md");
    const retired = parseRetired(retiredPath);
    expect(retired.retired_reason).toBe(BRAIN_RETIRED_REASON.mergedInto);
    expect(retired.superseded_by).toBeTruthy();
    expect(retired.superseded_by!).toContain("pref-keep");

    // Log carries a `merge` event with both wikilinks plus the
    // summary counters.
    const day = NOW.toISOString().slice(0, 10);
    const { entries } = parseLogDay(vault, day);
    const merges = entries.filter((e) => e.eventType === BRAIN_LOG_EVENT_KIND.merge);
    expect(merges.length).toBe(1);
    const body = merges[0]!.body;
    expect(String(body["keep"])).toContain("pref-keep");
    expect(String(body["drop"])).toContain("pref-drop");
    expect(String(body["applied_sum"])).toContain("9");
    expect(String(body["agent"])).toBe("test-agent");

    // active.md regenerated — drop is gone, keep is there.
    const activeContent = readFileSync(join(vault, "Brain", "active.md"), "utf8");
    expect(activeContent).toContain("pref-keep");
    expect(activeContent).not.toContain("pref-drop");
  });

  test("dryRun returns plan but writes nothing", () => {
    writePreference(vault, basePref("keep"));
    writePreference(vault, basePref("drop"));
    const before = readFileSync(join(vault, "Brain", "preferences", "pref-keep.md"), "utf8");
    const plan = mergePreferences(vault, "pref-keep", "pref-drop", {
      now: NOW,
      dryRun: true,
    });
    expect(plan.applied_sum).toBe(2);
    // Disk unchanged.
    expect(readFileSync(join(vault, "Brain", "preferences", "pref-keep.md"), "utf8")).toBe(before);
    expect(existsSync(join(vault, "Brain", "preferences", "pref-drop.md"))).toBe(true);
    expect(existsSync(join(vault, "Brain", "retired", "ret-drop.md"))).toBe(false);
  });

  test("preserves keep.pinned across merge", () => {
    writePreference(vault, basePref("keep", { pinned: true }));
    writePreference(vault, basePref("drop", { pinned: true }));
    mergePreferences(vault, "pref-keep", "pref-drop", { now: NOW });
    const keep = parsePreference(join(vault, "Brain", "preferences", "pref-keep.md"));
    expect(keep.pinned).toBe(true);
  });
});

describe("mergePreferences — legacy keep scope", () => {
  test("a keep record with a pre-v1.78.0 invalid scope still merges, tagging the slug", () => {
    const { path } = writePreference(vault, basePref("keep", { scope: "frontend" }));
    writeFileSync(
      path,
      readFileSync(path, "utf8")
        .replace("scope: frontend", "scope: front end")
        .replace("brain/scope/frontend", '"brain/scope/front end"'),
    );
    // Guard against a writer format change turning the edit into a no-op.
    const edited = readFileSync(path, "utf8");
    expect(edited).toContain("scope: front end");
    expect(edited).toContain('"brain/scope/front end"');
    // Merge requires matching scopes; the drop record carries the same legacy value.
    const { path: dropPath } = writePreference(vault, basePref("drop", { scope: "frontend" }));
    writeFileSync(
      dropPath,
      readFileSync(dropPath, "utf8")
        .replace("scope: frontend", "scope: front end")
        .replace("brain/scope/frontend", '"brain/scope/front end"'),
    );

    expect(() => mergePreferences(vault, "pref-keep", "pref-drop", { now: NOW })).not.toThrow();

    const raw = readFileSync(path, "utf8");
    expect(raw).toContain("brain/scope/front-end");
    expect(raw).not.toContain("brain/scope/front end");
    expect(parsePreference(path).scope).toBe("front end");
  });
});