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
16.3 KB
Raw Blame
/**
 * Per-partition state digests over explicit cuts (task 1.7): publishers
 * converge on one cut, an injected fold difference is reported, an
 * offline device is silent and not divergent, a machine without the
 * private partition raises no false alarm, and retired devices leave the
 * roster.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { appendFileSync, cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { dirname, join } from "node:path";

import { appendRecord } from "../../../src/core/store/appender.ts";
import type { StorePartition } from "../../../src/core/store/constants.ts";
import type { RecordBody } from "../../../src/core/store/envelope.ts";
import { checkStateDigests } from "../../../src/core/store/state-digest-check.ts";
import { compareDigests } from "../../../src/core/store/state-digest-compare.ts";
import {
  buildDigestBody,
  computeCut,
  publishStateDigest,
  readPartition,
} from "../../../src/core/store/state-digest.ts";
import { openStore, type StoreHandle } from "../../../src/core/store/store-open.ts";
import { partitionDir } from "../../../src/core/store/store-paths.ts";
import { makeTempStore, type TempStore } from "./fixtures/temp-store.ts";

const DAY = 24 * 60 * 60 * 1000;
const NOW = Date.UTC(2026, 10, 6, 12, 0, 0);
const at = (ms: number) => () => ms;

function write(
  store: StoreHandle,
  ms: number,
  kind: string,
  body: RecordBody,
  partition: StorePartition = "shared",
  stream: "events" | "settings" = "events",
) {
  return appendRecord(store, { partition, stream, kind, agent: "agent-1", body }, { now: at(ms) });
}

function seedPreferences(
  a: StoreHandle,
  b: StoreHandle,
  ms: number,
  partition: StorePartition = "shared",
) {
  write(
    a,
    ms,
    "preference-set",
    { authority: "agent", preference: "p1", fields: { principle: "tabs" } },
    partition,
  );
  write(b, ms + 1, "preference-evidence", { preference: "p1", result: "applied" }, partition);
  write(b, ms + 2, "pinned-set", { authority: "agent", content: "task" }, partition);
}

function silentDevices(report: ReturnType<typeof checkStateDigests>): string[] {
  return report.findings.flatMap((f) => (f.kind === "silent" ? [f.device] : []));
}

describe("state digests", () => {
  let tmp: TempStore;
  beforeEach(() => {
    tmp = makeTempStore("osb-store-digest-");
  });
  afterEach(() => tmp.cleanup());

  test("two publishers converge on one identical cut, and their digests agree", () => {
    const a = tmp.open("dev-a");
    const b = tmp.open("dev-b");
    seedPreferences(a, b, NOW - 60_000);
    const fromA = publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) });
    const fromB = publishStateDigest(b, { partition: "shared", agent: "doctor", now: at(NOW + 5) });
    expect(fromA.published && fromB.published).toBe(true);
    // B read A's digest before publishing; the digests stream is not in the cut.
    expect(fromB.body.cut).toEqual(fromA.body.cut);
    expect(fromB.body.cut_hash).toBe(fromA.body.cut_hash);
    expect(fromB.body.folds).toEqual(fromA.body.folds);
    expect(fromA.body.cut.map((e) => e.shard)).toEqual([
      "events/dev-a/2026-11.jsonl",
      "events/dev-b/2026-11.jsonl",
    ]);

    const report = checkStateDigests(a, { now: at(NOW + 10) });
    const shared = report.partitions.find((p) => p.partition === "shared")!;
    expect(shared.comparedCuts).toEqual([
      { cutHash: fromA.body.cut_hash, devices: ["dev-a", "dev-b"] },
    ]);
    expect(report.findings).toEqual([]);
  });

  test("an unchanged state is not republished within the interval, and is after it", () => {
    const a = tmp.open("dev-a");
    write(a, NOW - 1000, "pinned-set", { authority: "human", content: "x" });
    expect(
      publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) }).published,
    ).toBe(true);
    const again = publishStateDigest(a, {
      partition: "shared",
      agent: "doctor",
      now: at(NOW + 1000),
    });
    expect(again).toMatchObject({ published: false, reason: "unchanged" });
    const later = publishStateDigest(a, {
      partition: "shared",
      agent: "doctor",
      now: at(NOW + 2 * DAY),
    });
    expect(later.published).toBe(true);
    if (later.published) expect(later.body.cut_hash).toBe(again.body.cut_hash);
  });

  test("an injected fold difference over the same cut is reported with both devices and the fold", () => {
    const a = tmp.open("dev-a");
    const b = tmp.open("dev-b");
    seedPreferences(a, b, NOW - 60_000);
    const good = publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) });
    // dev-b runs a release whose preference fold differs: same cut, other hash.
    const wrong = { ...good.body, folds: { ...good.body.folds, preferences: "0".repeat(64) } };
    const bad = appendRecord(
      b,
      {
        partition: "shared",
        stream: "digests",
        kind: "state-digest",
        agent: "doctor",
        body: wrong,
      },
      { now: at(NOW + 5) },
    );

    for (const machine of [a, b]) {
      const report = checkStateDigests(machine, { now: at(NOW + 10) });
      expect(report.findings).toEqual([
        {
          kind: "divergent",
          partition: "shared",
          fold: "preferences",
          cutHash: good.body.cut_hash,
          devices: [
            {
              device: "dev-a",
              hash: good.body.folds.preferences,
              digest: good.published ? good.append.record.id : "",
            },
            { device: "dev-b", hash: "0".repeat(64), digest: bad.record.id },
          ],
        },
      ]);
    }
  });

  test("a topic fold difference is reported; an older release's digest without topics is not compared on it", () => {
    const a = tmp.open("dev-a");
    const b = tmp.open("dev-b");
    const c = tmp.open("dev-c");
    seedPreferences(a, b, NOW - 60_000);
    appendRecord(
      a,
      {
        partition: "shared",
        stream: "topics",
        kind: "topic-create",
        agent: "agent-1",
        topic: "01KA0000000000000000000000",
        body: { authority: "human", title: "Store", scope: "project:o2b" },
      },
      { now: at(NOW - 30_000) },
    );
    const good = publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) });
    const digest = (store: StoreHandle, body: RecordBody, ms: number) =>
      appendRecord(
        store,
        { partition: "shared", stream: "digests", kind: "state-digest", agent: "doctor", body },
        { now: at(ms) },
      );
    const { topics: _dropped, ...older } = good.body.folds;
    digest(c, { ...good.body, folds: older }, NOW + 3);
    const bad = digest(
      b,
      { ...good.body, folds: { ...good.body.folds, topics: "0".repeat(64) } },
      NOW + 5,
    );
    const report = checkStateDigests(a, { now: at(NOW + 10) });
    expect(report.findings.filter((f) => f.kind === "divergent")).toEqual([
      {
        kind: "divergent",
        partition: "shared",
        fold: "topics",
        cutHash: good.body.cut_hash,
        devices: [
          {
            device: "dev-a",
            hash: good.body.folds.topics!,
            digest: good.published ? good.append.record.id : "",
          },
          { device: "dev-b", hash: "0".repeat(64), digest: bad.record.id },
        ],
      },
    ]);
  });

  test("an offline device is reported as silent, never as divergent, and does not stall the others", () => {
    const a = tmp.open("dev-a");
    const b = tmp.open("dev-b");
    const laptop = tmp.open("laptop");
    // The laptop wrote and published two weeks ago, then went offline.
    write(laptop, NOW - 14 * DAY, "pinned-set", { authority: "agent", content: "old" });
    publishStateDigest(laptop, {
      partition: "shared",
      agent: "doctor",
      now: at(NOW - 14 * DAY + 10),
    });
    seedPreferences(a, b, NOW - 60_000);
    publishStateDigest(a, { partition: "shared", agent: "doctor", now: at(NOW) });
    publishStateDigest(b, { partition: "shared", agent: "doctor", now: at(NOW + 5) });

    const report = checkStateDigests(a, { now: at(NOW + 10) });
    const shared = report.partitions.find((p) => p.partition === "shared")!;
    expect(shared.roster.devices.map((d) => d.device)).toEqual(["dev-a", "dev-b", "laptop"]);
    expect(shared.comparedCuts.map((c) => c.devices)).toEqual([["dev-a", "dev-b"]]);
    expect(report.findings).toEqual([
      {
        kind: "silent",
        partition: "shared",
        device: "laptop",
        lastDigestMs: NOW - 14 * DAY + 10,
        lastRecordMs: NOW - 14 * DAY + 10,
      },
    ]);
  });

  test("a machine without the private partition raises no false alarm on either side", () => {
    const a = tmp.open("dev-a");
    const b = tmp.open("dev-b");
    seedPreferences(a, b, NOW - 60_000);
    seedPreferences(a, b, NOW - 30_000, "private");
    // The server syncs only shared: its store root holds no private folder.
    const serverRoot = join(tmp.parent, "server-store");
    cpSync(join(tmp.root, "shared"), join(serverRoot, "shared"), { recursive: true });
    const server = openStore({ root: serverRoot, device: "server", dirs: tmp.dirs("server") });
    expect([...server.partitions]).toEqual(["shared"]);

    for (const laptop of [a, b]) {
      publishStateDigest(laptop, { partition: "shared", agent: "doctor", now: at(NOW) });
      publishStateDigest(laptop, { partition: "private", agent: "doctor", now: at(NOW) });
    }
    // The laptops' shared digests reach the server; the server publishes its own.
    cpSync(join(tmp.root, "shared", "digests"), join(serverRoot, "shared", "digests"), {
      recursive: true,
    });
    const fromServer = publishStateDigest(server, {
      partition: "shared",
      agent: "doctor",
      now: at(NOW + 5),
    });
    cpSync(join(serverRoot, "shared", "digests"), join(tmp.root, "shared", "digests"), {
      recursive: true,
    });

    const onServer = checkStateDigests(server, { now: at(NOW + 10) });
    expect(onServer.skipped).toEqual(["private"]);
    expect(onServer.partitions.map((p) => p.partition)).toEqual(["shared"]);
    expect(onServer.partitions[0]!.comparedCuts).toEqual([
      { cutHash: fromServer.body.cut_hash, devices: ["dev-a", "dev-b", "server"] },
    ]);
    expect(onServer.findings).toEqual([]);

    const onLaptop = checkStateDigests(a, { now: at(NOW + 10) });
    const priv = onLaptop.partitions.find((p) => p.partition === "private")!;
    expect(priv.roster.devices.map((d) => d.device)).toEqual(["dev-a", "dev-b"]);
    expect(onLaptop.findings).toEqual([]);
  });

  test("a human device-retire record takes a device off the roster; an agent one does not", () => {
    const a = tmp.open("dev-a");
    const old = tmp.open("old-pc");
    write(old, NOW - 20 * DAY, "pinned-set", { authority: "agent", content: "x" });
    write(
      a,
      NOW - 1000,
      "device-retire",
      { authority: "agent", device: "old-pc" },
      "shared",
      "settings",
    );
    expect(silentDevices(checkStateDigests(a, { now: at(NOW) }))).toContain("old-pc");

    write(
      a,
      NOW - 500,
      "device-retire",
      { authority: "human", device: "old-pc" },
      "shared",
      "settings",
    );
    const report = checkStateDigests(a, { now: at(NOW) });
    const shared = report.partitions.find((p) => p.partition === "shared")!;
    expect(shared.roster.retired).toEqual(["old-pc"]);
    expect(silentDevices(report)).not.toContain("old-pc");

    // The retired id writes again after its retire record: back on the roster.
    write(old, NOW + 100, "pinned-set", { authority: "agent", content: "back" });
    const back = checkStateDigests(a, { now: at(NOW + 200) }).partitions.find(
      (p) => p.partition === "shared",
    )!;
    expect(back.roster.devices.map((d) => d.device)).toContain("old-pc");
  });

  test("devices outside the 30-day window are not on the roster; new devices get a grace period", () => {
    const a = tmp.open("dev-a");
    const gone = tmp.open("gone");
    write(gone, NOW - 40 * DAY, "pinned-set", { authority: "agent", content: "x" });
    write(a, NOW - 2 * DAY, "pinned-set", { authority: "agent", content: "y" });
    const report = checkStateDigests(a, { now: at(NOW) });
    const shared = report.partitions.find((p) => p.partition === "shared")!;
    expect(shared.roster.devices.map((d) => d.device)).toEqual(["dev-a"]);
    expect(report.findings).toEqual([]);
  });

  test("a torn tail is not part of the cut, and a pending blob is counted in it", () => {
    const a = tmp.open("dev-a");
    const first = write(a, NOW, "pinned-set", { authority: "agent", content: "x" });
    appendFileSync(first.path, '{"v":1,"id":"01K');
    const big = write(a, NOW + 1, "pinned-set", {
      authority: "agent",
      content: "y".repeat(20_000),
    });
    expect(big.spilled).toBe(true);
    const withBlob = computeCut(readPartition(partitionDir(tmp.root, "shared")));
    expect(withBlob).toEqual([{ shard: first.rel, count: 2, last: big.record.id, pending: 0 }]);

    // A machine that has the shard but not yet the blob has a different cut.
    const other = join(tmp.parent, "other");
    cpSync(join(tmp.root, "shared", "events"), join(other, "events"), { recursive: true });
    const shards = readPartition(other);
    expect(computeCut(shards)).toEqual([
      { shard: first.rel, count: 2, last: big.record.id, pending: 1 },
    ]);
    expect(buildDigestBody("shared", shards).cut_hash).not.toBe(
      buildDigestBody("shared", readPartition(partitionDir(tmp.root, "shared"))).cut_hash,
    );
  });

  test("machines that receive shards in different orders, some cut mid-line, reach one digest", () => {
    const writers = ["dev-a", "dev-b", "dev-c"].map((device) => tmp.open(device));
    writers.forEach((store, i) => {
      for (let n = 0; n < 5; n++) {
        const ms = NOW - 10_000 + n * 7 + i;
        write(store, ms, "preference-set", {
          authority: n % 2 === 0 ? "agent" : "model",
          preference: `p${n % 2}`,
          fields: { principle: `${store.device}-${n}` },
        });
        write(store, ms + 1, "pinned-set", { authority: "agent", content: `${store.device}-${n}` });
      }
    });
    const source = readPartition(partitionDir(tmp.root, "shared"));
    const deliver = (machine: string, order: number[], cutFirst: boolean) => {
      const root = join(tmp.parent, machine);
      for (const index of order) {
        const shard = source[index]!;
        const target = join(root, ...shard.rel.split("/"));
        mkdirSync(dirname(target), { recursive: true });
        const bytes = readFileSync(join(partitionDir(tmp.root, "shared"), ...shard.rel.split("/")));
        // A sync tool still copying: the file ends mid-record first.
        if (cutFirst) writeFileSync(target, bytes.subarray(0, Math.floor(bytes.length * 0.6)));
      }
      const early = buildDigestBody("shared", readPartition(root));
      for (const index of order) {
        const shard = source[index]!;
        cpSync(
          join(partitionDir(tmp.root, "shared"), ...shard.rel.split("/")),
          join(root, ...shard.rel.split("/")),
        );
      }
      return { early, final: buildDigestBody("shared", readPartition(root)) };
    };
    const one = deliver("machine-1", [0, 1, 2], true);
    const two = deliver("machine-2", [2, 0, 1], false);
    // Machine 2 had nothing before its copy: an empty cut, not a partial one.
    expect(two.early.cut).toEqual([]);
    const reference = buildDigestBody("shared", source);
    expect(one.early.cut_hash).not.toBe(reference.cut_hash);
    expect(one.final).toEqual(reference);
    expect(two.final).toEqual(reference);
  });

  test("digests of another partition and malformed digests are ignored", () => {
    const a = tmp.open("dev-a");
    write(a, NOW, "pinned-set", { authority: "agent", content: "x" });
    const body = publishStateDigest(a, {
      partition: "shared",
      agent: "doctor",
      now: at(NOW + 1),
    }).body;
    const records = readPartition(partitionDir(tmp.root, "shared")).flatMap((s) => s.all);
    const foreign = {
      ...records.at(-1)!,
      id: "01KZZZZZZZZZZZZZZZZZZZZZZZ",
      device: "dev-b",
      body: { ...body, partition: "private" },
    };
    const broken = {
      ...records.at(-1)!,
      id: "01KZZZZZZZZZZZZZZZZZZZZZZY",
      device: "dev-c",
      body: { partition: "shared" },
    };
    const result = compareDigests({
      partition: "shared",
      records: [...records, foreign, broken],
      retireRecords: [],
      nowMs: NOW + 2,
    });
    expect(result.comparedCuts).toEqual([]);
    expect(result.findings).toEqual([]);
  });
});