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
18.2 KB
Raw Blame
/**
 * The render protocol (task 2.8, design D7): edits are detected against the
 * stored base before a render, merged with the user winning, re-checked
 * before the replacement, conflict copies are ingested and removed, and
 * only changed bytes are written. Human edits become human records.
 */
import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
import * as fs from "node:fs";
import {
  existsSync,
  lstatSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  renameSync,
  statSync,
  symlinkSync,
  unlinkSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { join } from "node:path";

import type { StoreRecord } from "../../../src/core/store/envelope.ts";
import type { StoreHandle } from "../../../src/core/store/store-open.ts";
import { allRecords, catchUp } from "../../../src/core/view/catch-up.ts";
import { VIEW_RECOVER_DAYS } from "../../../src/core/view/constants.ts";
import { listReplacedVersions } from "../../../src/core/view/recover.ts";
import { runViewPass, type ViewPassReport } from "../../../src/core/view/render.ts";
import type { ReplaceHooks } from "../../../src/core/view/page-io.ts";
import { claimViewWriter } from "../../../src/core/view/writer.ts";
import { initStore } from "../../../src/core/store/store-init.ts";
import { openStore } from "../../../src/core/store/store-open.ts";
import { blobPath, partitionDir } from "../../../src/core/store/store-paths.ts";
import { makeMachines, type Machines } from "./fixtures/machines.ts";
import { seedLogEvent, seedPreference } from "./fixtures/seed.ts";

const MON = Date.UTC(2026, 10, 2, 9, 0, 0);
let clock = MON + 86_400_000 * 5;
const now = () => clock;

let m: Machines;
let a: StoreHandle;
beforeEach(() => {
  clock = MON + 86_400_000 * 5;
  m = makeMachines(["dev-a"]);
  a = m.open("dev-a");
  seedPreference(a, MON, "pref-a", { principle: "Rule A.", status: "confirmed", scope: "work" });
  seedPreference(a, MON + 1, "pref-b", {
    principle: "Rule B.",
    status: "confirmed",
    scope: "work",
  });
  seedLogEvent(a, MON + 2, "note", { text: "Did a thing." });
  claimViewWriter(a, { agent: "t", now });
  pass();
  pass();
});
afterEach(() => m.cleanup());

function pass(hooks?: ReplaceHooks, store: StoreHandle = a): ViewPassReport {
  clock += 1000;
  return runViewPass(store, {
    target: m.view(store.device),
    vault: null,
    agent: "t",
    now,
    ...(hooks !== undefined ? { hooks } : {}),
  });
}

/** Files under `dir` whose bytes contain `text`. */
function filesHolding(dir: string, text: string): string[] {
  if (!existsSync(dir)) return [];
  return readdirSync(dir, { recursive: true, encoding: "utf8" }).filter((name) => {
    const path = join(dir, name);
    return statSync(path).isFile() && readFileSync(path).includes(text);
  });
}

const about = () => join(m.view("dev-a"), "about-me.md");
const read = (path = about()) => readFileSync(path, "utf8");

function records(kind: string): StoreRecord[] {
  return allRecords(catchUp(a, now)).filter((r) => r.kind === kind);
}

function humanPreferenceSets(): Array<Record<string, unknown>> {
  return records("preference-set")
    .filter((r) => r.body["authority"] === "human")
    .map((r) => ({ preference: r.body["preference"], fields: r.body["fields"] }));
}

describe("render protocol", () => {
  test("an idle render changes no file's bytes or modification time, and writes no record", () => {
    const files = [about(), join(m.view("dev-a"), "decisions.md")];
    const old = new Date(MON);
    for (const f of files) utimesSync(f, old, old);
    const before = files.map((f) => [readFileSync(f, "utf8"), statSync(f).mtimeMs] as const);
    const count = allRecords(catchUp(a, now)).length;
    const report = pass();
    expect(report.status).toBe("rendered");
    expect(
      report.status === "rendered" &&
        report.pages.length > 0 &&
        report.pages.every((p) => p.status === "unchanged"),
    ).toBe(true);
    expect(files.map((f) => [readFileSync(f, "utf8"), statSync(f).mtimeMs] as const)).toEqual(
      before,
    );
    expect(allRecords(catchUp(a, now)).length).toBe(count);
  });

  test("a phone-style whole-file rewrite becomes human records, and the next render keeps it", () => {
    const original = read();
    const phone =
      // A byte-order mark, as some phone editors write.
      "\uFEFF" +
      original
        .replace("- Rule A.", "- Rule A, in my words.")
        .replace("- Rule B.\n", "- Rule B.\n- Also remember the milk.\n")
        .replaceAll("\n", "\r\n");
    writeFileSync(about(), phone);
    const report = pass();
    expect(
      report.status === "rendered" && report.pages.find((p) => p.page === "about-me.md"),
    ).toMatchObject({ ingested: 2 });
    expect(humanPreferenceSets()).toEqual([
      { preference: "pref-a", fields: { principle: "Rule A, in my words." } },
    ]);
    const additions = records("view-addition");
    expect(additions.map((r) => r.body)).toEqual([
      {
        authority: "human",
        page: "about-me.md",
        after: "pref:pref-b",
        text: "- Also remember the milk.",
      },
    ]);
    const after = read();
    expect(after).toContain("- Rule A, in my words.\n- Rule B.\n- Also remember the milk.\n");
    expect(after).not.toContain("\r");
    // Stable from here on: the next pass ingests nothing and writes nothing.
    const count = allRecords(catchUp(a, now)).length;
    pass();
    expect(read()).toBe(after);
    expect(allRecords(catchUp(a, now)).length).toBe(count);
  });

  test("an edit seen while its merge base has not synced is ingested once the base arrives", () => {
    const renders = records("view-render").filter((r) => r.body["page"] === "about-me.md");
    const base = blobPath(partitionDir(a.root, "shared"), renders.at(-1)!.body["base"] as string);
    const away = `${base}.away`;
    renameSync(base, away);
    writeFileSync(about(), read().replace("- Rule A.", "- Rule A, edited offline."));
    const pending = pass();
    expect(
      pending.status === "rendered" && pending.pages.find((p) => p.page === "about-me.md"),
    ).toMatchObject({ status: "base-pending" });
    renameSync(away, base);
    pass();
    expect(humanPreferenceSets()).toEqual([
      { preference: "pref-a", fields: { principle: "Rule A, edited offline." } },
    ]);
  });

  test("only an idle pass records that the writer is alive", () => {
    clock += 2 * 86_400_000;
    const before = records("view-pass").length;
    clock += 1000;
    runViewPass(a, { target: null, vault: null, agent: "t", now });
    expect(records("view-pass")).toHaveLength(before);
    pass();
    expect(records("view-pass")).toHaveLength(before + 1);
  });

  test("a page truncated by a sync tool retires nothing and is rendered back whole", () => {
    seedPreference(a, MON + 3, "pref-c", {
      principle: "Rule C.",
      status: "confirmed",
      scope: "work",
    });
    pass();
    pass();
    const whole = read();
    writeFileSync(about(), whole.split("\n").slice(0, 3).join("\n") + "\n");
    pass();
    expect(humanPreferenceSets()).toEqual([]);
    expect(read()).toBe(whole);
    // The truncated bytes are kept, recoverable.
    expect(records("view-replaced").length).toBeGreaterThan(0);
  });

  test("deleting a rule line retires the rule; deleting the page retires nothing", () => {
    writeFileSync(about(), read().replace("- Rule B.\n", ""));
    pass();
    expect(humanPreferenceSets()).toEqual([
      { preference: "pref-b", fields: { status: "retired" } },
    ]);
    expect(read()).not.toContain("Rule B.");
    // The retire is visible in the week's history, and the edit that made it is recoverable.
    expect(read(join(m.view("dev-a"), "history", "2026-W45.md"))).toContain(
      "- You retired a rule: Rule B.",
    );
    expect(listReplacedVersions(a, "about-me.md", now).map((v) => v.reason)).toEqual(["edit"]);
    unlinkSync(about());
    pass();
    expect(read()).toContain("- Rule A.");
    expect(humanPreferenceSets()).toHaveLength(1);
  });

  test("a history edit is kept as a correction by every later render", () => {
    const week = join(m.view("dev-a"), "history", "2026-W45.md");
    writeFileSync(week, read(week).replace("- Did a thing.", "- Did a thing, and it worked."));
    pass();
    expect(records("view-correction").map((r) => r.body["text"])).toEqual([
      "- Did a thing, and it worked.",
    ]);
    seedLogEvent(a, MON + 3, "note", { text: "Another thing." });
    pass();
    const text = read(week);
    expect(text).toContain("- Did a thing, and it worked.");
    expect(text).toContain("- Another thing.");
  });

  test("an agent change and a user edit of other lines merge, the user's line kept", () => {
    writeFileSync(about(), read().replace("- Rule A.", "- Rule A, my way."));
    seedPreference(a, clock + 10, "pref-b", { principle: "Rule B, revised." });
    clock += 100;
    pass();
    const text = read();
    expect(text).toContain("- Rule A, my way.");
    expect(text).toContain("- Rule B, revised.");
  });

  test("a racing edit with no conflict copy is recovered from the replaced bytes", () => {
    seedPreference(a, clock + 10, "pref-c", {
      principle: "Rule C.",
      status: "confirmed",
      scope: "work",
    });
    clock += 100;
    const racing = read().replace("- Rule A.", "- Rule A, edited on the phone.");
    let raced = false;
    const report = pass({
      beforeCapture: (path) => {
        if (path !== about() || raced) return;
        raced = true;
        writeFileSync(path, racing);
      },
    });
    expect(
      report.status === "rendered" && report.pages.find((p) => p.page === "about-me.md"),
    ).toMatchObject({ status: "written", ingested: 1 });
    expect(humanPreferenceSets()).toEqual([
      { preference: "pref-a", fields: { principle: "Rule A, edited on the phone." } },
    ]);
    const text = read();
    expect(text).toContain("- Rule A, edited on the phone.");
    expect(text).toContain("- Rule C.");
    expect(records("view-replaced").map((r) => r.body["reason"])).toEqual(["race"]);
  });

  test("a racing edit with a conflict copy is ingested and leaves no copy behind", () => {
    const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
    writeFileSync(copy, read().replace("- Rule B.", "- Rule B, from the phone."));
    pass();
    expect(existsSync(copy)).toBe(false);
    expect(readdirSync(m.view("dev-a")).filter((n) => n.includes("conflict"))).toEqual([]);
    expect(humanPreferenceSets()).toEqual([
      { preference: "pref-b", fields: { principle: "Rule B, from the phone." } },
    ]);
    expect(read()).toContain("- Rule B, from the phone.");
    expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
  });

  test("a conflict copy a sync tool writes again while the page renders is kept and ingested later", () => {
    const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
    writeFileSync(copy, read().replace("- Rule B.", "- Rule B, older from the phone."));
    const newer = join(m.view("dev-a"), "..", "newer.tmp");
    writeFileSync(newer, read().replace("- Rule B.", "- Rule B, newer from the phone."));
    const realOpen = fs.openSync;
    const realRename = fs.renameSync;
    let delivered = false;
    // The sync tool writes the copy again right after the writer first
    // touches it: once a read has closed the file (Windows refuses to
    // replace a file that is open), or right after a rename took it.
    const deliver = (): void => {
      if (delivered) return;
      delivered = true;
      realRename(newer, copy);
    };
    const realClose = fs.closeSync;
    let copyFd: number | null = null;
    const open = spyOn(fs, "openSync").mockImplementation(((p: fs.PathLike, ...rest: never[]) => {
      const fd = (realOpen as (...args: unknown[]) => number)(p, ...rest);
      if (String(p) === copy) copyFd = fd;
      return fd;
    }) as typeof fs.openSync);
    const close = spyOn(fs, "closeSync").mockImplementation(((fd: number) => {
      realClose(fd);
      if (fd === copyFd) {
        copyFd = null;
        deliver();
      }
    }) as typeof fs.closeSync);
    const rename = spyOn(fs, "renameSync").mockImplementation(((p: fs.PathLike, q: fs.PathLike) => {
      realRename(p, q);
      if (String(p) === copy) deliver();
    }) as typeof fs.renameSync);
    try {
      pass();
    } finally {
      open.mockRestore();
      close.mockRestore();
      rename.mockRestore();
    }
    expect(delivered).toBe(true);
    pass();
    expect(
      humanPreferenceSets().map((s) => (s["fields"] as Record<string, unknown>)["principle"]),
    ).toContain("Rule B, newer from the phone.");
    expect(existsSync(copy)).toBe(false);
  });

  test("a folder named like a conflict copy of a live page is refused and stays where it is", () => {
    const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
    mkdirSync(copy);
    writeFileSync(join(copy, "mine.txt"), "mine\n");
    const report = pass();
    expect(readFileSync(join(copy, "mine.txt"), "utf8")).toBe("mine\n");
    expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
    if (report.status !== "rendered") throw new Error(report.status);
    expect(report.pages.find((p) => p.page === "about-me.md")?.status).toBe("refused");
  });

  test.skipIf(process.platform === "win32")(
    "a symbolic link named like a conflict copy of a live page is never read or moved",
    () => {
      const outside = join(m.view("dev-a"), "..", "outside-secret.md");
      writeFileSync(outside, read().replace("- Rule B.", "- Rule B, outside secret."));
      const copy = join(m.view("dev-a"), "about-me.sync-conflict-20261106-120000-ABCDEFG.md");
      symlinkSync(outside, copy);
      pass();
      pass();
      expect(lstatSync(copy).isSymbolicLink()).toBe(true);
      expect(readdirSync(m.view("dev-a")).filter((n) => n.startsWith("."))).toEqual([]);
      expect(JSON.stringify(allRecords(catchUp(a, now)).map((r) => r.body))).not.toContain(
        "outside secret",
      );
    },
  );

  test("a private racing edit lands in private, and no shared file holds its text", () => {
    // A new rule makes the pass render, so the edit races the replace.
    seedPreference(a, clock + 10, "pref-c", {
      principle: "Rule C.",
      status: "confirmed",
      scope: "work",
    });
    clock += 100;
    const racing = read().replace("- Rule A.", "- Rule A <private>racing secret</private>");
    let raced = false;
    pass({
      beforeCapture: (path) => {
        if (path !== about() || raced) return;
        raced = true;
        writeFileSync(path, racing);
      },
    });
    expect(raced).toBe(true);
    const privateSets = (catchUp(a, now).records.get("private") ?? []).filter(
      (r) => r.kind === "preference-set" || r.kind === "view-replaced",
    );
    expect(privateSets.map((r) => [r.kind, r.body["reason"] ?? null])).toEqual([
      ["view-replaced", "race"],
      ["preference-set", null],
    ]);
    const shared = catchUp(a, now).records.get("shared") ?? [];
    expect(shared.filter((r) => r.kind === "view-replaced" && r.body["reason"] === "race")).toEqual(
      [],
    );
    expect(filesHolding(join(m.root("dev-a"), "private"), "racing secret")).not.toEqual([]);
    expect(filesHolding(join(m.root("dev-a"), "shared"), "racing secret")).toEqual([]);
    expect(read()).not.toContain("racing secret");
  });

  test("a conflict copy that is the writer's own older render is removed without an edit", () => {
    const copy = join(m.view("dev-a"), "about-me (conflicted copy 2026-11-06).md");
    writeFileSync(copy, read());
    pass();
    expect(existsSync(copy)).toBe(false);
    expect(humanPreferenceSets()).toEqual([]);
  });

  test("o2b view recover lists replaced versions with their text, newest first", () => {
    writeFileSync(about(), read().replace("- Rule A.", "- First edit."));
    pass();
    writeFileSync(about(), read().replace("- First edit.", "- Second edit."));
    pass();
    const versions = listReplacedVersions(a, "about-me.md", now);
    expect(versions.map((v) => v.reason)).toEqual(["edit", "edit"]);
    expect(versions[0]!.text).toContain("- Second edit.");
    expect(versions[1]!.text).toContain("- First edit.");
    // Both still listed inside the window; none once it has passed.
    const day = 86_400_000;
    const inside = listReplacedVersions(
      a,
      "about-me.md",
      () => clock + (VIEW_RECOVER_DAYS - 1) * day,
    );
    expect(inside).toHaveLength(2);
    const after = () => clock + (VIEW_RECOVER_DAYS + 1) * day;
    expect(listReplacedVersions(a, "about-me.md", after)).toEqual([]);
  });

  test("a private edit on a machine without the private partition is refused and left on disk", () => {
    const parent = m.parent;
    const root = join(parent, "server-store");
    initStore({ root, partitions: ["shared"] });
    const s = openStore({
      root,
      device: "srv",
      dirs: {
        platform: process.platform,
        home: join(parent, "home", "srv"),
        env: {
          XDG_STATE_HOME: join(parent, "state", "srv"),
          LOCALAPPDATA: join(parent, "state", "srv"),
        },
      },
    });
    seedPreference(s, MON, "pref-a", { principle: "Rule A.", status: "confirmed" });
    claimViewWriter(s, { agent: "t", now });
    pass(undefined, s);
    pass(undefined, s);
    const path = join(m.view("srv"), "about-me.md");
    const edited = read(path).replace("- Rule A.", "- Rule A <private>secret</private>");
    writeFileSync(path, edited);
    const report = pass(undefined, s);
    expect(
      report.status === "rendered" && report.pages.find((p) => p.page === "about-me.md"),
    ).toMatchObject({ status: "refused" });
    expect(read(path)).toBe(edited);
  });

  test("a private edit is stored in private, and the page keeps the rule's last shared version", () => {
    writeFileSync(about(), read().replace("- Rule A.", "- Rule A <private>secret</private>"));
    pass();
    const privateSets = (catchUp(a, now).records.get("private") ?? []).filter(
      (r) => r.kind === "preference-set" || r.kind === "view-replaced",
    );
    expect(privateSets.map((r) => r.kind)).toEqual(["view-replaced", "preference-set"]);
    expect(read()).not.toContain("secret");
    expect(read()).toContain("- Rule A.\n");
    // Stable: the next pass sees its own render and stores nothing more.
    const count = allRecords(catchUp(a, now)).length;
    pass();
    expect(allRecords(catchUp(a, now)).length).toBe(count);
  });
});