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
13.8 KB
Raw Blame
/**
 * The destination-keyed write aggregate (actionable-now batch, A3 /
 * t_69fec179).
 *
 * Seeds go through `appendLogEvent` only - never hand-written logs - so
 * the fixtures stay in lockstep with production output. The exceptions
 * are hand-written shard lines on purpose: the unreadable-day torn line
 * is the warning path the reader exists to survive, and the sub-second
 * foreign line exercises a timestamp shape the writer never stamps.
 */

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

import { appendLogEvent } from "../../../../src/core/brain/log.ts";
import { listLogShardFiles } from "../../../../src/core/brain/log-jsonl.ts";
import {
  DEFAULT_WRITE_DESTINATION_WINDOW_DAYS,
  WRITE_DESTINATION_COVERAGE_NOTE,
  WRITE_DESTINATION_KIND,
  listWriteDestinations,
} from "../../../../src/core/brain/notes/write-destinations.ts";
import { BRAIN_LOG_EVENT_KIND } from "../../../../src/core/brain/types.ts";

let vault: string;
beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-write-destinations-"));
  // A legacy Brain/ tree: an unswitched machine (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));

interface NoteWriteSeed {
  readonly timestamp: string;
  readonly agent: string;
  readonly target: string;
  readonly deviceId?: string;
}

function seedNoteWrite(input: NoteWriteSeed): void {
  appendLogEvent(
    vault,
    {
      timestamp: input.timestamp,
      eventType: BRAIN_LOG_EVENT_KIND.noteWrite,
      agent: input.agent,
      body: {
        write_id: `nw_${input.timestamp.replace(/\D/g, "")}_${input.target}`,
        op: "update",
        target: input.target,
        hash_before: "a".repeat(64),
        hash_after: "b".repeat(64),
        bytes_before: "10",
        bytes_after: "20",
        agent: input.agent,
      },
    },
    { deviceId: input.deviceId ?? "" },
  );
}

interface WriteSessionSeed {
  readonly timestamp: string;
  readonly agent: string;
  readonly target: string;
  readonly deviceId?: string;
  /** Terminal status; defaults to `done` (the committed case). */
  readonly status?: "done" | "failed";
  /** The terminal-failure reason `auditTerminal` records for a failed session. */
  readonly reason?: string;
}

function seedWriteSession(input: WriteSessionSeed): void {
  const status = input.status ?? "done";
  appendLogEvent(
    vault,
    {
      timestamp: input.timestamp,
      eventType: BRAIN_LOG_EVENT_KIND.writeSession,
      agent: input.agent,
      body: {
        session_id: `ws_${input.timestamp.replace(/\D/g, "")}`,
        kind: "artifact",
        status,
        target: input.target,
        attempts: "1",
        review: "not-required",
        ...(status === "failed" && input.reason !== undefined ? { reason: input.reason } : {}),
      },
    },
    { deviceId: input.deviceId ?? "" },
  );
}

describe("listWriteDestinations", () => {
  test("folds both kinds into one row per destination with agents, devices and kinds", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "alpha", target: "Notes/One.md" });
    seedNoteWrite({ timestamp: "2026-03-04T02:00:00Z", agent: "beta", target: "Notes/One.md" });
    seedWriteSession({
      timestamp: "2026-03-05T03:00:00Z",
      agent: "alpha",
      target: "Notes/One.md",
      deviceId: "laptop",
    });

    const result = listWriteDestinations(vault, {
      until: "2026-03-05",
      now: new Date("2026-03-05T12:00:00Z"),
    });
    expect(result.warnings).toEqual([]);
    expect(result.destinations).toHaveLength(1);
    const row = result.destinations[0]!;
    expect(row.target).toBe("Notes/One.md");
    expect(row.kinds).toEqual([
      WRITE_DESTINATION_KIND.noteWrite,
      WRITE_DESTINATION_KIND.writeSession,
    ]);
    expect(row.note_writes).toBe(2);
    expect(row.write_sessions).toBe(1);
    expect([...row.agents]).toEqual(["alpha", "beta"]);
    expect([...row.devices]).toEqual(["", "laptop"]);
    expect(row.last_write).toBe("2026-03-05T03:00:00Z");
  });

  test("a destination touched only by a write-session audit still appears, honestly", () => {
    seedWriteSession({
      timestamp: "2026-03-04T01:00:00Z",
      agent: "alpha",
      target: "Reports/Q1.md",
    });
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations).toHaveLength(1);
    const row = result.destinations[0]!;
    expect(row.target).toBe("Reports/Q1.md");
    expect(row.kinds).toEqual([WRITE_DESTINATION_KIND.writeSession]);
    expect(row.note_writes).toBe(0);
    expect(row.write_sessions).toBe(1);
  });

  test("a failed write-session audit is not a write; only done sessions count", () => {
    // `auditTerminal` emits a failed row for a session that died before
    // anything landed (abandoned / retry-cap / expired): no bytes moved,
    // so the aggregate must not claim a write.
    seedWriteSession({
      timestamp: "2026-03-04T01:00:00Z",
      agent: "alpha",
      target: "Notes/One.md",
      status: "failed",
      reason: "abandoned",
    });
    seedWriteSession({
      timestamp: "2026-03-04T02:00:00Z",
      agent: "alpha",
      target: "Notes/One.md",
    });
    seedWriteSession({
      timestamp: "2026-03-04T03:00:00Z",
      agent: "alpha",
      target: "Notes/Ghost.md",
      status: "failed",
      reason: "retry-cap",
    });
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["Notes/One.md"]);
    const row = result.destinations[0]!;
    expect(row.write_sessions).toBe(1);
    expect(row.writes).toBe(1);
    expect(row.last_write).toBe("2026-03-04T02:00:00Z");
  });

  test("events of neither recorded kind never create a row, and the note says so", () => {
    appendLogEvent(
      vault,
      {
        timestamp: "2026-03-04T01:00:00Z",
        eventType: BRAIN_LOG_EVENT_KIND.note,
        agent: "alpha",
        body: { text: "a milestone" },
      },
      { deviceId: "" },
    );
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations).toEqual([]);
    // The coverage note states the honesty contract rather than implying
    // the aggregate is complete.
    expect(result.coverage_note).toBe(WRITE_DESTINATION_COVERAGE_NOTE);
    expect(result.coverage_note.length).toBeGreaterThan(40);
  });

  test("an until-only query anchors the default window on until, not on the present", () => {
    seedNoteWrite({ timestamp: "2026-02-25T01:00:00Z", agent: "a", target: "Ancient.md" });
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "Old.md" });
    // No `now` at all: the wall clock is years past the seeded day, so a
    // now-anchored default would answer a clean, wrong empty.
    const result = listWriteDestinations(vault, { until: "2026-03-04" });
    // The until day itself is the seventh day of the default window.
    expect(result.window).toEqual({
      since: "2026-02-26T00:00:00Z",
      until: "2026-03-04T23:59:59.999Z",
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["Old.md"]);
  });

  test("a given now does not drag an until-only window back to the present", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "Old.md" });
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2031-01-01T00:00:00Z"),
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["Old.md"]);
  });

  test("the default window covers seven days and since/until narrow the walk", () => {
    expect(DEFAULT_WRITE_DESTINATION_WINDOW_DAYS).toBe(7);
    seedNoteWrite({ timestamp: "2026-03-01T01:00:00Z", agent: "a", target: "Old.md" });
    seedNoteWrite({ timestamp: "2026-03-10T01:00:00Z", agent: "a", target: "New.md" });
    // `now` pins the walk: 2026-03-10 minus 6 days reaches 2026-03-04, so
    // the March 1 write is outside the default window.
    const result = listWriteDestinations(vault, {
      until: "2026-03-10",
      now: new Date("2026-03-10T12:00:00Z"),
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["New.md"]);
    const narrowed = listWriteDestinations(vault, {
      since: "2026-03-01",
      until: "2026-03-01",
    });
    expect(narrowed.destinations.map((d) => d.target)).toEqual(["Old.md"]);
  });

  test("an unreadable day yields a warning and not an empty group", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md" });
    // A torn line on the SAME day: the parseable rows survive and the
    // warning rides out beside them.
    const shards = listLogShardFiles(vault);
    expect(shards.length).toBeGreaterThan(0);
    appendFileSync(shards[0]!.path, "not-json\n");
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.warnings.length).toBeGreaterThan(0);
    expect(result.destinations.map((d) => d.target)).toEqual(["One.md"]);
  });

  test("rows order by target and equal-second seeds keep their order inside a row", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "beta", target: "Zed.md" });
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "alpha", target: "Zed.md" });
    seedNoteWrite({ timestamp: "2026-03-04T02:00:00Z", agent: "a", target: "Aye.md" });
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["Aye.md", "Zed.md"]);
    expect([...result.destinations[1]!.agents]).toEqual(["beta", "alpha"]);
  });

  test("last_write orders by instant when a sub-second foreign line meets a whole-second one", () => {
    // The JSONL reader admits foreign sub-second timestamps the writer
    // never stamps, and a plain string compare orders `…56.789Z` before
    // `…56Z` - the exact reason `log-window.ts` compares instants. The
    // hand-written shard line is the second fixture exception: a foreign
    // line is by definition not production output.
    seedNoteWrite({ timestamp: "2026-03-04T12:34:56Z", agent: "a", target: "Same.md" });
    const shards = listLogShardFiles(vault);
    expect(shards.length).toBeGreaterThan(0);
    appendFileSync(
      shards[0]!.path,
      `${JSON.stringify({
        ts: "2026-03-04T12:34:56.789Z",
        kind: "note-write",
        payload: { target: "Same.md", agent: "foreign" },
      })}\n`,
      "utf8",
    );
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations).toHaveLength(1);
    expect(result.destinations[0]!.note_writes).toBe(2);
    expect(result.destinations[0]!.last_write).toBe("2026-03-04T12:34:56.789Z");
  });

  test("filters by agent, device and exact path", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md" });
    seedNoteWrite({
      timestamp: "2026-03-04T02:00:00Z",
      agent: "b",
      target: "One.md",
      deviceId: "laptop",
    });
    seedNoteWrite({ timestamp: "2026-03-04T03:00:00Z", agent: "a", target: "Two.md" });
    seedWriteSession({
      timestamp: "2026-03-04T04:00:00Z",
      agent: "b",
      target: "Three.md",
      deviceId: "laptop",
    });

    const byAgent = listWriteDestinations(vault, {
      agent: "a",
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(byAgent.destinations.map((d) => d.target)).toEqual(["One.md", "Two.md"]);
    const byAgentRow = byAgent.destinations[0]!;
    // The kinds field only names the kinds the FILTERED events contributed.
    expect(byAgentRow.kinds).toEqual([WRITE_DESTINATION_KIND.noteWrite]);

    const byDevice = listWriteDestinations(vault, {
      device: "laptop",
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(byDevice.destinations.map((d) => d.target)).toEqual(["One.md", "Three.md"]);

    const byPath = listWriteDestinations(vault, {
      path: "Three.md",
      until: "2026-03-04",
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(byPath.destinations).toHaveLength(1);
    expect(byPath.destinations[0]!.write_sessions).toBe(1);
  });

  test("limit truncates and total_matched reports the pre-truncation count", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "A.md" });
    seedNoteWrite({ timestamp: "2026-03-04T02:00:00Z", agent: "a", target: "B.md" });
    seedNoteWrite({ timestamp: "2026-03-04T03:00:00Z", agent: "a", target: "C.md" });
    const result = listWriteDestinations(vault, {
      until: "2026-03-04",
      limit: 2,
      now: new Date("2026-03-04T12:00:00Z"),
    });
    expect(result.destinations.map((d) => d.target)).toEqual(["A.md", "B.md"]);
    expect(result.total_matched).toBe(3);
    expect(result.limit).toBe(2);
  });

  test("a query writes nothing to the vault", () => {
    seedNoteWrite({ timestamp: "2026-03-04T01:00:00Z", agent: "a", target: "One.md" });
    const fingerprint = (): string =>
      readdirSync(vault, { withFileTypes: true })
        .map((e) => {
          const abs = join(vault, e.name);
          return e.isDirectory()
            ? `d:${e.name}:${readdirSync(abs).toSorted().join(",")}`
            : `f:${e.name}:${readFileSync(abs, "utf8")}`;
        })
        .toSorted()
        .join("\n");
    const before = fingerprint();
    listWriteDestinations(vault, { until: "2026-03-04", now: new Date("2026-03-04T12:00:00Z") });
    expect(fingerprint()).toBe(before);
  });
});