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
9.6 KB
Raw Blame
/**
 * `writePreferenceTxn` - the single chokepoint that wraps every
 * preference write. Acquires the sync lock, re-reads the current
 * file state, runs an expectations chain that can raise typed
 * `BrainCollisionError`, then mutates via `writeFrontmatterAtomic`.
 */

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

import { brainDirs, preferencePath } from "../../../src/core/brain/paths.ts";
import { parsePreference } from "../../../src/core/brain/preference.ts";
import {
  BrainCollisionError,
  BRAIN_COLLISION_KIND,
  noRevisionRewind,
  writePreferenceTxn,
  type WritePreferenceExpectation,
} from "../../../src/core/brain/preference-txn.ts";
import { acquireLockSync } from "../../../src/core/brain/sync-lockfile.ts";
import { BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";

let tmpRoot: string;
let vault: string;

beforeEach(() => {
  tmpRoot = mkdtempSync(join(tmpdir(), "osb-pref-txn-"));
  vault = tmpRoot;
  // Ensure Brain/preferences/ exists so the writer can drop the file.
  require("node:fs").mkdirSync(brainDirs(vault).preferences, {
    recursive: true,
  });
});

afterEach(() => {
  if (tmpRoot) rmSync(tmpRoot, { recursive: true, force: true });
});

const baseInput = (overrides: Record<string, unknown> = {}) => ({
  slug: "test-rule",
  topic: "test-topic",
  principle: "do the right thing in production code",
  created_at: "2026-05-26T12:00:00Z",
  unconfirmed_until: "2026-06-02T12:00:00Z",
  status: BRAIN_PREFERENCE_STATUS.unconfirmed,
  evidenced_by: [] as ReadonlyArray<string>,
  ...overrides,
});

describe("BRAIN_COLLISION_KIND", () => {
  test("exposes the four discriminant string values", () => {
    expect(BRAIN_COLLISION_KIND.staleUpdate).toBe("StaleUpdate");
    expect(BRAIN_COLLISION_KIND.unsafeShrink).toBe("UnsafeShrink");
    expect(BRAIN_COLLISION_KIND.sourceLock).toBe("SourceLock");
    expect(BRAIN_COLLISION_KIND.duplicateWrite).toBe("DuplicateWrite");
  });
});

describe("BrainCollisionError", () => {
  test("kind field is preserved on instances", () => {
    const err = new BrainCollisionError(BRAIN_COLLISION_KIND.staleUpdate, "test message");
    expect(err).toBeInstanceOf(Error);
    expect(err.kind).toBe("StaleUpdate");
    expect(err.name).toBe("BrainCollisionError");
    expect(err.message).toBe("test message");
  });
});

describe("writePreferenceTxn", () => {
  test("with empty expectations writes a preference identical to writePreference", () => {
    const result = writePreferenceTxn(vault, baseInput(), [], {});
    expect(result.id).toBe("pref-test-rule");
    expect(existsSync(result.path)).toBe(true);
    // Lock file must be cleaned up after the txn returns.
    expect(existsSync(result.path + ".lock")).toBe(false);
    const parsed = parsePreference(result.path);
    expect(parsed.principle).toBe("do the right thing in production code");
    expect(parsed.topic).toBe("test-topic");
  });

  test("raises BrainCollisionError(SourceLock) when the lock is already held", () => {
    const path = preferencePath(vault, "held-rule");
    const handle = acquireLockSync(path);
    try {
      let caught: unknown;
      try {
        writePreferenceTxn(vault, baseInput({ slug: "held-rule" }), [], {});
      } catch (err) {
        caught = err;
      }
      expect(caught).toBeInstanceOf(BrainCollisionError);
      expect((caught as BrainCollisionError).kind).toBe("SourceLock");
    } finally {
      handle.release();
    }
  });

  test("runs expectations chain in order; first failure short-circuits", () => {
    // First write to seed the on-disk state.
    writePreferenceTxn(vault, baseInput({ slug: "chain-rule" }), [], {});

    const calls: string[] = [];
    const ok: WritePreferenceExpectation = () => {
      calls.push("ok");
    };
    const fail: WritePreferenceExpectation = () => {
      calls.push("fail");
      throw new BrainCollisionError(BRAIN_COLLISION_KIND.staleUpdate, "deliberate failure");
    };
    const never: WritePreferenceExpectation = () => {
      calls.push("never");
    };

    let caught: unknown;
    try {
      writePreferenceTxn(
        vault,
        baseInput({
          slug: "chain-rule",
          principle: "updated principle text",
        }),
        [ok, fail, never],
        { overwrite: true },
      );
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(BrainCollisionError);
    expect((caught as BrainCollisionError).kind).toBe("StaleUpdate");
    expect(calls).toEqual(["ok", "fail"]); // `never` was not invoked
  });

  test("releases the lock even when an expectation throws", () => {
    writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {});
    const failingExpectation: WritePreferenceExpectation = () => {
      throw new BrainCollisionError(BRAIN_COLLISION_KIND.duplicateWrite, "blocked");
    };

    let caught: unknown;
    try {
      writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [failingExpectation], {
        overwrite: true,
      });
    } catch (err) {
      caught = err;
    }
    expect(caught).toBeInstanceOf(BrainCollisionError);

    // Lock must be released even though the write was aborted.
    const lockPath = preferencePath(vault, "release-rule") + ".lock";
    expect(existsSync(lockPath)).toBe(false);

    // A follow-up write with empty expectations must succeed.
    const ok = writePreferenceTxn(vault, baseInput({ slug: "release-rule" }), [], {
      overwrite: true,
    });
    expect(existsSync(ok.path)).toBe(true);
  });

  test("expectation receives the existing preference when overwriting", () => {
    writePreferenceTxn(
      vault,
      baseInput({ slug: "ctx-rule", principle: "original principle text" }),
      [],
      {},
    );

    const observed: { principle: string | null } = { principle: null };
    const inspect: WritePreferenceExpectation = (ctx) => {
      observed.principle = ctx.existing?.principle ?? null;
    };

    writePreferenceTxn(
      vault,
      baseInput({ slug: "ctx-rule", principle: "replacement principle text" }),
      [inspect],
      { overwrite: true },
    );
    expect(observed.principle).toBe("original principle text");
  });

  test("expectation context shows existing=null on first write", () => {
    const observed: { existing: unknown } = { existing: "unset" };
    const inspect: WritePreferenceExpectation = (ctx) => {
      observed.existing = ctx.existing;
    };
    writePreferenceTxn(vault, baseInput({ slug: "first-rule" }), [inspect], {});
    expect(observed.existing).toBeNull();
  });

  test("file bytes match what writePreference would have produced (no txn overhead)", () => {
    const result = writePreferenceTxn(
      vault,
      baseInput({ slug: "bytewise-rule", principle: "exact bytes please" }),
      [],
      {},
    );
    const text = readFileSync(result.path, "utf8");
    expect(text).toContain("principle: exact bytes please");
    expect(text).toContain("kind: brain-preference");
    expect(text).toContain("_status: unconfirmed");
  });
});

/**
 * `noRevisionRewind` (bank-bundle restore, unit E2). A restore replays a
 * record captured at some revision into a vault that has kept moving.
 * Without a gate the replay is decided by whichever write lands last,
 * which is the one thing a restore must never do to a rule the operator
 * has since edited.
 */
describe("noRevisionRewind", () => {
  test("allows a first write, whatever revision the incoming record carries", () => {
    expect(() =>
      writePreferenceTxn(vault, baseInput({ slug: "fresh-rule", revision: 5 }), [
        noRevisionRewind(5),
      ]),
    ).not.toThrow();
    expect(parsePreference(preferencePath(vault, "fresh-rule")).revision).toBe(5);
  });

  test("allows an incoming record that is ahead of the on-disk one", () => {
    writePreferenceTxn(vault, baseInput({ slug: "ahead-rule", revision: 2 }), []);
    writePreferenceTxn(
      vault,
      baseInput({ slug: "ahead-rule", revision: 8, principle: "the newer text of the rule" }),
      [noRevisionRewind(8)],
      { overwrite: true },
    );
    expect(parsePreference(preferencePath(vault, "ahead-rule")).revision).toBe(8);
  });

  test("refuses a rewind with the StaleUpdate discriminant", () => {
    writePreferenceTxn(vault, baseInput({ slug: "rewind-rule", revision: 9 }), []);
    let caught: unknown;
    try {
      writePreferenceTxn(
        vault,
        baseInput({ slug: "rewind-rule", revision: 4, principle: "an older text of the rule" }),
        [noRevisionRewind(4)],
        { overwrite: true },
      );
    } catch (exc) {
      caught = exc;
    }
    expect(caught).toBeInstanceOf(BrainCollisionError);
    expect((caught as BrainCollisionError).kind).toBe(BRAIN_COLLISION_KIND.staleUpdate);
    expect(parsePreference(preferencePath(vault, "rewind-rule")).principle).toBe(
      baseInput().principle as string,
    );
  });

  test("refuses divergent content at an equal revision", () => {
    writePreferenceTxn(vault, baseInput({ slug: "diverged-rule", revision: 3 }), []);
    expect(() =>
      writePreferenceTxn(
        vault,
        baseInput({ slug: "diverged-rule", revision: 3, principle: "a different text entirely" }),
        [noRevisionRewind(3)],
        { overwrite: true },
      ),
    ).toThrow(BrainCollisionError);
  });

  test("accepts an identical record at an equal revision (a replayed restore)", () => {
    writePreferenceTxn(vault, baseInput({ slug: "replay-rule", revision: 3 }), []);
    expect(() =>
      writePreferenceTxn(
        vault,
        baseInput({ slug: "replay-rule", revision: 3 }),
        [noRevisionRewind(3)],
        { overwrite: true },
      ),
    ).not.toThrow();
  });
});