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
8.3 KB
Raw Blame
/**
 * The view writer role (task 2.7, design D7): the first machine takes it,
 * two simultaneous first claims leave one winner whose rival wrote no
 * page, a move waits for the old writer's release so no page is written
 * by both, a forced move renders at once and the old writer stops at its
 * first catch-up after it.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { join } from "node:path";

import { appendRecord } from "../../../src/core/store/appender.ts";
import { VIEW_RENDER_KIND } from "../../../src/core/view/constants.ts";
import { allRecords, catchUp } from "../../../src/core/view/catch-up.ts";
import { runViewPass } from "../../../src/core/view/render.ts";
import {
  claimViewWriter,
  readViewWriter,
  requestViewWriter,
} from "../../../src/core/view/writer.ts";
import { makeMachines, type Machines } from "./fixtures/machines.ts";
import type { StoreHandle } from "../../../src/core/store/store-open.ts";

const NOW = Date.UTC(2026, 10, 6, 12, 0, 0);
let clock = NOW;
const now = () => clock;
const agent = "view-test";

let m: Machines;
beforeEach(() => {
  clock = NOW;
  m = makeMachines(["dev-a", "dev-b"]);
});
afterEach(() => m.cleanup());

function pass(store: StoreHandle) {
  clock += 1000;
  return runViewPass(store, { target: m.view(store.device), vault: null, agent, now });
}

function pagesIn(device: string): string[] {
  return existsSync(m.view(device)) ? readdirSync(m.view(device)) : [];
}

function renderDevices(store: StoreHandle): string[] {
  return allRecords(catchUp(store, now))
    .filter((r) => r.kind === VIEW_RENDER_KIND)
    .map((r) => r.device);
}

describe("view writer role", () => {
  test("the first machine to initialise the store takes the role, once", () => {
    const a = m.open("dev-a");
    expect(claimViewWriter(a, { agent, now }).claimed).toBe(true);
    expect(readViewWriter(a, now)).toMatchObject({ writer: "dev-a", via: "claim" });
    m.sync();
    const b = m.open("dev-b");
    expect(claimViewWriter(b, { agent, now })).toEqual({ claimed: false, writer: "dev-a" });
  });

  test("a malformed claim does not keep a machine from claiming", () => {
    const a = m.open("dev-a");
    // An agent-authority claim: rejected by the fold, so nobody holds the role.
    appendRecord(a, {
      partition: "shared",
      stream: "settings",
      kind: "view-writer-claim",
      agent,
      body: { authority: "agent", device: "dev-a" },
    });
    expect(readViewWriter(a, now).writer).toBeNull();
    expect(claimViewWriter(a, { agent, now }).claimed).toBe(true);
    expect(readViewWriter(a, now).writer).toBe("dev-a");
  });

  test("a fresh claim waits one catch-up before its first render", () => {
    const a = m.open("dev-a");
    claimViewWriter(a, { agent, now });
    expect(pass(a).status).toBe("waiting-for-claim");
    expect(pagesIn("dev-a")).toEqual([]);
    expect(pass(a).status).toBe("rendered");
    expect(pagesIn("dev-a")).toContain("about-me.md");
  });

  test("two simultaneous first claims: the lowest clock wins and the loser writes no page", () => {
    const a = m.open("dev-a");
    const b = m.open("dev-b");
    claimViewWriter(b, { agent, now: () => NOW + 5 });
    claimViewWriter(a, { agent, now: () => NOW + 9 });
    // Each pass before the claims meet only waits.
    expect(pass(a).status).toBe("waiting-for-claim");
    expect(pass(b).status).toBe("waiting-for-claim");
    m.sync();
    expect(readViewWriter(a, now).writer).toBe("dev-b");
    expect(readViewWriter(b, now).writer).toBe("dev-b");
    expect(pass(a)).toEqual({ status: "not-writer", writer: "dev-b" });
    expect(pass(b).status).toBe("rendered");
    expect(pagesIn("dev-a")).toEqual([]);
    expect(pagesIn("dev-b")).toContain("about-me.md");
  });

  test("a move takes effect only after the old writer's release: no page is written by both", () => {
    const a = m.open("dev-a");
    claimViewWriter(a, { agent, now });
    pass(a);
    expect(pass(a).status).toBe("rendered");
    m.sync();
    const b = m.open("dev-b");
    const asked = requestViewWriter(b, { agent, now, force: false });
    expect(asked).toMatchObject({ status: "requested", previous: "dev-a" });
    // The request has not reached A: B is not the writer yet and renders nothing.
    expect(pass(b)).toEqual({ status: "not-writer", writer: "dev-a" });
    expect(pagesIn("dev-b")).toEqual([]);
    m.sync();
    // A sees the request at its catch-up and releases instead of rendering.
    const rendersBefore = renderDevices(a).filter((d) => d === "dev-a").length;
    expect(pass(a)).toEqual({ status: "released", to: "dev-b" });
    expect(pass(a)).toEqual({ status: "not-writer", writer: "dev-b" });
    expect(renderDevices(a).filter((d) => d === "dev-a").length).toBe(rendersBefore);
    // B still waits until the release reaches it.
    expect(pass(b)).toEqual({ status: "not-writer", writer: "dev-a" });
    m.sync();
    expect(pass(b).status).toBe("rendered");
    expect(pagesIn("dev-b")).toContain("about-me.md");
    m.sync();
    const order = allRecords(catchUp(b, now)).filter(
      (r) => r.kind === VIEW_RENDER_KIND || r.kind === "view-writer-released",
    );
    const releaseAt = order.findIndex((r) => r.kind === "view-writer-released");
    // The release is in the order, with renders on both sides of it.
    expect(releaseAt).toBeGreaterThan(0);
    expect(releaseAt).toBeLessThan(order.length - 1);
    // Every render before the release is A's, every one after it is B's.
    expect(order.slice(0, releaseAt).every((r) => r.device === "dev-a")).toBe(true);
    expect(order.slice(releaseAt + 1).every((r) => r.device === "dev-b")).toBe(true);
  });

  test("a forced move renders at once, warns, and the old writer stops at its next catch-up", () => {
    const a = m.open("dev-a");
    claimViewWriter(a, { agent, now });
    pass(a);
    pass(a);
    m.sync();
    const b = m.open("dev-b");
    const forced = requestViewWriter(b, { agent, now, force: true });
    expect(forced.status).toBe("forced");
    expect(forced.status === "forced" && forced.warning).toContain("may render the view once more");
    expect(pass(b).status).toBe("rendered");
    // A has not seen the move yet: it may render once more.
    expect(pass(a).status).toBe("rendered");
    m.sync();
    expect(pass(a)).toEqual({ status: "not-writer", writer: "dev-b" });
  });

  test("only a human request for the requesting device itself moves the role", () => {
    const a = m.open("dev-a");
    claimViewWriter(a, { agent, now });
    m.sync();
    const b = m.open("dev-b");
    for (const body of [
      { authority: "agent", device: "dev-b", force: true },
      { authority: "human", device: "dev-a", force: true },
    ]) {
      appendRecord(
        b,
        { partition: "shared", stream: "settings", kind: "view-writer-request", agent, body },
        { now },
      );
    }
    m.sync();
    const state = readViewWriter(a, now);
    expect(state.writer).toBe("dev-a");
    expect(state.rejected.map((r) => r.reason)).toEqual([
      "only the user moves the view writer role",
      "a device claims or requests the role only for itself",
    ]);
  });

  test("with no claim, a request takes the role at once", () => {
    const b = m.open("dev-b");
    expect(requestViewWriter(b, { agent, now, force: false })).toMatchObject({
      status: "taken",
      previous: null,
    });
    expect(pass(b).status).toBe("rendered");
  });
});

describe("a writer record read only in part", () => {
  test("a corrupt line in a settings shard stops the pass as an incomplete read", () => {
    const a = m.open("dev-a");
    claimViewWriter(a, { agent, now });
    expect(pass(a).status).toBe("waiting-for-claim");
    for (const value of ["en", "ru"]) {
      appendRecord(a, {
        partition: "shared",
        stream: "settings",
        kind: "setting-set",
        agent,
        body: { authority: "human", key: "view.language", value },
      });
    }
    const dir = join(a.root, "shared", "settings", "dev-a");
    const shard = join(dir, readdirSync(dir)[0]!);
    const lines = readFileSync(shard, "utf8").split("\n");
    // The middle record could have been a handover; it no longer verifies.
    lines[1] = lines[1]!.replace('"value":"en"', '"value":"de"');
    writeFileSync(shard, lines.join("\n"));
    expect(pass(a).status).toBe("incomplete-read");
    expect(pagesIn("dev-a")).toEqual([]);
  });
});