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
20.5 KB
Raw Blame
/**
 * Topic planning in dream (task 3.4, spec `topics`): only the view writer
 * plans; it creates a topic from a cluster that recurs across sessions,
 * routes later records to it, lists every automatic action with its undo
 * command, honours the user's undo on every pass after, and only proposes
 * merges, splits and status decisions. A concurrent dream on two machines
 * and two planning processes on the view writer each leave exactly one
 * topic per cluster.
 */
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, readdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

import { appendRecord } from "../../../src/core/store/appender.ts";
import type { StorePartition } from "../../../src/core/store/constants.ts";
import { readPartition } from "../../../src/core/store/state-digest.ts";
import type { StoreHandle } from "../../../src/core/store/store-open.ts";
import { foldTopics } from "../../../src/core/topics/fold.ts";
import {
  runTopicPlanning,
  topicPlanLockTarget,
  type TopicPlanningReport,
} from "../../../src/core/topics/planning.ts";
import {
  claimSettled,
  claimViewWriter,
  readViewWriter,
  requestViewWriter,
} from "../../../src/core/view/writer.ts";
import { withLocalLock } from "../../../src/core/store/local-lock.ts";
import { makeMachines, type Machines } from "../view/fixtures/machines.ts";
import { seedTopicRecord } from "../view/fixtures/seed.ts";

const T0 = Date.UTC(2026, 10, 2, 9, 0, 0);
const DAY = 86_400_000;
let clock = T0;
const now = () => clock;

let m: Machines;
let a: StoreHandle;
beforeEach(() => {
  clock = T0;
  m = makeMachines(["dev-a", "dev-b"], "o2b-topics-plan-");
  a = m.open("dev-a");
  claimViewWriter(a, { agent: "t", now });
  // The render's first catch-up after the claim, which planning waits for.
  claimSettled(a, readViewWriter(a, now));
});
afterEach(() => m.cleanup());

let seq = 0;
function signal(
  text: string,
  meta: { project?: string; session?: string; on?: StoreHandle; partition?: StorePartition } = {},
): string {
  clock += 1000;
  seq += 1;
  return appendRecord(
    meta.on ?? a,
    {
      partition: meta.partition ?? "shared",
      stream: "events",
      kind: "signal",
      agent: "agent-1",
      body: {
        id: `sig-2026-11-02-s${seq}`,
        path: `Brain/inbox/s${seq}.md`,
        staged: false,
        frontmatter: {
          principle: text,
          project: meta.project ?? "o2b",
          ...(meta.session !== undefined ? { session: meta.session } : {}),
        },
        raw: null,
        raw_shape: "bare",
      },
    },
    { now },
  ).record.id;
}

/** Five records about one subject, from the sessions named. */
function cluster(sessions: ReadonlyArray<string>, on: StoreHandle = a): string[] {
  return sessions.map((session, i) =>
    signal(`Shard compaction keeps monthly shard files small ${i}`, { session, on }),
  );
}

/** How many planning children announced they are about to plan. */
function startedChildren(): number {
  return readdirSync(m.parent).filter((n) => n.startsWith("start.")).length;
}

/** Whether a topic-create of dev-a has landed in `shared`. */
function createdOnDisk(): boolean {
  return readPartition(join(m.root("dev-a"), "shared"))
    .flatMap((s) => s.records)
    .some((r) => r.kind === "topic-create");
}

function plan(store: StoreHandle = a): TopicPlanningReport {
  clock += 1000;
  return runTopicPlanning(store, { agent: "dream", now });
}

function planned(report: TopicPlanningReport) {
  if (report.status !== "planned") throw new Error(`not planned: ${report.status}`);
  return report;
}

function fold(device = "dev-a") {
  const records = (["shared", "private"] as const).flatMap((p) =>
    readPartition(join(m.root(device), p)).flatMap((s) => s.records),
  );
  return foldTopics(records);
}

describe("topic planning", () => {
  test("a cluster from two sessions becomes one topic, listed with its undo command", () => {
    const members = cluster(["s1", "s1", "s1", "s2", "s2"]);
    const report = planned(plan());
    expect(report.created).toHaveLength(1);
    const created = report.created[0]!;
    expect(created.title).toBe("Shard compaction keeps");
    expect(created.members).toBe(5);
    expect(created.undo).toBe(`o2b topic undo ${created.record}`);
    const state = fold();
    const topic = state.topics.get(created.topic)!;
    expect(topic.goal).toBe("Shard compaction keeps monthly shard files small 0");
    expect(topic.scope).toBe("project:o2b");
    expect(members.map((id) => state.assignments.get(id))).toEqual(
      members.map(() => created.topic),
    );
    // A second pass finds nothing left to do.
    expect(planned(plan()).created).toEqual([]);
  });

  test("a cluster written without word spaces still becomes a topic, its title cut to fit", () => {
    const longA = "シャードの圧縮".repeat(18);
    const longB = "毎月の小さなファイル".repeat(12);
    const members = ["s1", "s1", "s2", "s2", "s2"].map((session, i) =>
      signal(`${longA}、${longB}、${i}`, { session }),
    );
    const created = planned(plan()).created[0]!;
    const state = fold();
    const topic = state.topics.get(created.topic)!;
    // The record check counts UTF-16 code units: so does the clamp.
    expect(topic.title.length).toBeLessThanOrEqual(200);
    expect(members.map((id) => state.assignments.get(id))).toEqual(
      members.map(() => created.topic),
    );
  });

  test("a cluster in astral-plane characters becomes a topic, its title cut on a whole character", () => {
    // CJK Extension B: two UTF-16 code units per character.
    const longA = "𠀀𠀁𠀂𠀃𠀄𠀅".repeat(30);
    const longB = "𠁀𠁁𠁂𠁃𠁄".repeat(30);
    const members = ["s1", "s1", "s2", "s2", "s2"].map((session, i) =>
      signal(`${longA}、${longB}、${i}`, { session }),
    );
    const report = planned(plan());
    expect(report.created).toHaveLength(1);
    const created = report.created[0]!;
    const state = fold();
    const topic = state.topics.get(created.topic)!;
    expect(topic.title.length).toBeLessThanOrEqual(200);
    expect(topic.title.length).toBeGreaterThanOrEqual(199);
    // No lone surrogate: every character is whole.
    expect(/[\uD800-\uDFFF]/u.test(topic.title)).toBe(false);
    expect(members.map((id) => state.assignments.get(id))).toEqual(
      members.map(() => created.topic),
    );
  });

  test("a private item's words never route a shared record to a topic", () => {
    const id = "01KA0000000000000000000000";
    seedTopicRecord(a, (clock += 1000), "topic-create", id, {
      title: "Unrelated",
      scope: "project:o2b",
    });
    seedTopicRecord(
      a,
      (clock += 1000),
      "decision",
      id,
      { text: "Clinic appointment rescheduling paperwork" },
      { partition: "private" },
    );
    const record = signal("Clinic appointment rescheduling paperwork again", { session: "s9" });
    expect(planned(plan()).routed.map((r) => r.record)).not.toContain(record);
  });

  test("a route taken back from a topic merged away is not taken to the topic it merged into", () => {
    const from = "01KA0000000000000000000007";
    const into = "01KA0000000000000000000008";
    const words = "Clinic appointment rescheduling paperwork";
    seedTopicRecord(a, (clock += 1000), "topic-create", from, {
      title: words,
      scope: "project:o2b",
    });
    seedTopicRecord(a, (clock += 1000), "topic-create", into, {
      title: words,
      scope: "project:o2b",
    });
    const record = signal(`${words} again`, { session: "s9" });
    seedTopicRecord(a, (clock += 1000), "merge", from, { into }, { authority: "human" });
    const assign = seedTopicRecord(a, (clock += 1000), "assign", from, { record });
    seedTopicRecord(a, (clock += 1000), "undo", from, { record: assign }, { authority: "human" });
    expect(planned(plan()).routed.map((r) => r.record)).not.toContain(record);
  });

  test("a private record is routed to a private topic by its private title", () => {
    const id = "01KA0000000000000000000009";
    seedTopicRecord(
      a,
      (clock += 1000),
      "topic-create",
      id,
      { title: "Clinic appointment rescheduling paperwork", scope: "project:o2b" },
      { partition: "private" },
    );
    const record = signal("Clinic appointment rescheduling paperwork again", {
      session: "s9",
      partition: "private",
    });
    const routed = planned(plan()).routed.filter((r) => r.record === record);
    expect(routed.map((r) => r.topic)).toEqual([id]);
    // The assign lands in `private`, beside the record and the topic.
    const assigns = readPartition(join(m.root("dev-a"), "private"))
      .flatMap((s) => s.records)
      .filter((r) => r.kind === "assign" && r.body["record"] === record);
    expect(assigns).toHaveLength(1);
  });

  test("a private title, description or goal never routes a shared record to a topic", () => {
    const words = "Clinic appointment rescheduling paperwork";
    const fields = [
      ["topic-rename", { title: words }],
      ["topic-rename", { description: words }],
      ["topic-goal", { goal: words }],
    ] as const;
    const records: string[] = [];
    for (const [i, [kind, body]] of fields.entries()) {
      const id = `01KA000000000000000000000${i}`;
      seedTopicRecord(a, (clock += 1000), "topic-create", id, {
        title: `Unrelated ${i}`,
        scope: "project:o2b",
      });
      seedTopicRecord(a, (clock += 1000), kind, id, body, { partition: "private" });
      records.push(signal(`${words} again ${i}`, { session: `s${9 + i}` }));
    }
    const routed = planned(plan()).routed.map((r) => r.record);
    expect(routed.filter((r) => records.includes(r))).toEqual([]);
    // The same words in a shared field do route.
    seedTopicRecord(a, (clock += 1000), "topic-goal", "01KA0000000000000000000000", {
      goal: `${words} shared`,
    });
    const late = signal(`${words} shared later`, { session: "s20" });
    expect(planned(plan()).routed.map((r) => r.record)).toContain(late);
  });

  test("a log event whose type names an Object property is not a candidate and breaks nothing", () => {
    appendRecord(
      a,
      {
        partition: "shared",
        stream: "log",
        kind: "log-event",
        agent: "legacy",
        body: {
          timestamp: new Date(clock).toISOString(),
          event_type: "constructor",
          body: { text: "x" },
        },
      },
      { now },
    );
    expect(plan().status).toBe("planned");
  });

  test("one busy session makes no topic until the subject recurs in another session", () => {
    cluster(["s1", "s1", "s1", "s1", "s1", "s1"]);
    expect(planned(plan()).created).toEqual([]);
    signal("Shard compaction keeps monthly shard files small again", { session: "s2" });
    expect(planned(plan()).created).toHaveLength(1);
  });

  test("a later record is routed to the topic; an undone route is never taken again", () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    const topic = planned(plan()).created[0]!.topic;
    const late = signal("Shard compaction should run monthly on each device", { session: "s3" });
    const report = planned(plan());
    expect(report.routed.map((r) => [r.record, r.topic])).toEqual([[late, topic]]);
    seedTopicRecord(
      a,
      (clock += 1000),
      "undo",
      topic,
      { record: report.routed[0]!.assign },
      {
        authority: "human",
      },
    );
    expect(fold().assignments.has(late)).toBe(false);
    expect(planned(plan()).routed).toEqual([]);
    expect(fold().assignments.has(late)).toBe(false);
  });

  test("an agent's undo of an automatic route (as brain_topic writes it) blocks the route too", () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    const topic = planned(plan()).created[0]!.topic;
    const late = signal("Shard compaction should run monthly on each device", { session: "s3" });
    const route = planned(plan()).routed[0]!;
    seedTopicRecord(
      a,
      (clock += 1000),
      "undo",
      topic,
      { record: route.assign },
      { authority: "agent" },
    );
    expect(planned(plan()).routed).toEqual([]);
    expect(fold().assignments.has(late)).toBe(false);
  });

  test("an undone topic is gone and is not created again from the same records", () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    const created = planned(plan()).created[0]!;
    seedTopicRecord(
      a,
      (clock += 1000),
      "undo",
      created.topic,
      { record: created.record },
      {
        authority: "human",
      },
    );
    expect(fold().topics.size).toBe(0);
    expect(planned(plan()).created).toEqual([]);
    expect(fold().topics.size).toBe(0);
  });

  test("a cluster with a private record becomes a private topic", () => {
    cluster(["s1", "s1", "s2", "s2"]);
    signal("Shard compaction keeps monthly shard files small too", {
      session: "s2",
      partition: "private",
    });
    const created = planned(plan()).created[0]!;
    const topicRecords = readPartition(join(m.root("dev-a"), "private"))
      .filter((s) => s.stream === "topics")
      .flatMap((s) => s.records);
    expect(topicRecords.some((r) => r.kind === "topic-create" && r.topic === created.topic)).toBe(
      true,
    );
    const sharedTopicRecords = readPartition(join(m.root("dev-a"), "shared"))
      .filter((s) => s.stream === "topics")
      .flatMap((s) => s.records);
    expect(sharedTopicRecords.filter((r) => r.topic === created.topic)).toEqual([]);
    expect(topicRecords.filter((r) => r.kind === "assign")).toHaveLength(5);
  });

  test("a shared record that carries a <private> region makes its cluster's topic private", () => {
    cluster(["s1", "s1", "s2", "s2"]);
    signal("Shard compaction keeps monthly shard <private>files of Dr. X</private> small", {
      session: "s2",
    });
    const created = planned(plan()).created[0]!;
    const shared = readPartition(join(m.root("dev-a"), "shared"))
      .filter((s) => s.stream === "topics")
      .flatMap((s) => s.records);
    expect(shared.filter((r) => r.topic === created.topic)).toEqual([]);
  });

  test("two topics that look the same are proposed for a merge and both stay as they are", () => {
    const one = "01KA0000000000000000000000";
    const two = "01KA0000000000000000000001";
    for (const id of [one, two]) {
      seedTopicRecord(a, (clock += 1000), "topic-create", id, {
        title: "Shard compaction policy",
        scope: "project:o2b",
        goal: "Monthly shard compaction",
      });
    }
    const report = planned(plan());
    expect(report.merges.map((p) => p.topics)).toEqual([[one, two]]);
    const state = fold();
    expect([state.topics.get(one)!.mergedInto, state.topics.get(two)!.mergedInto]).toEqual([
      null,
      null,
    ]);
  });

  test("a quiet active topic is offered for a status decision; its status does not change", () => {
    const id = "01KA0000000000000000000000";
    seedTopicRecord(a, clock, "topic-create", id, { title: "Old work", scope: "project:o2b" });
    clock += 31 * DAY;
    const report = planned(plan());
    expect(report.quiet).toEqual([{ topic: id, days: 31 }]);
    expect(fold().topics.get(id)!.status).toBe("active");
  });

  test("a topic whose records fall into two clusters is proposed for a split", () => {
    const id = "01KA0000000000000000000000";
    seedTopicRecord(a, (clock += 1000), "topic-create", id, {
      title: "Mixed",
      scope: "project:o2b",
    });
    const records = [
      ...cluster(["s1", "s1", "s2", "s2", "s2"]),
      ...["s3", "s3", "s4", "s4", "s4"].map((session, i) =>
        signal(`Phone views render markdown pages offline ${i}`, { session }),
      ),
    ];
    for (const record of records) {
      seedTopicRecord(a, (clock += 1000), "assign", id, { record }, { authority: "human" });
    }
    const report = planned(plan());
    expect(report.splits.map((s) => [s.topic, s.groups.map((g) => g.length)])).toEqual([
      [id, [5, 5]],
    ]);
    expect(report.created).toEqual([]);
  });

  test("dream on two machines at once: only the view writer creates, and one topic exists", () => {
    const b = m.open("dev-b");
    cluster(["s1", "s1", "s2", "s2", "s2"], b);
    m.sync();
    const onB = plan(b);
    expect(onB).toEqual({ status: "not-writer", writer: "dev-a" });
    expect(planned(plan()).created).toHaveLength(1);
    m.sync();
    expect(plan(b)).toEqual({ status: "not-writer", writer: "dev-a" });
    expect(fold("dev-b").topics.size).toBe(1);
    expect(fold("dev-a").topics.size).toBe(1);
  });

  test("planning waits for the claim to settle, and hands the role over on a request", () => {
    const fresh = makeMachines(["dev-c", "dev-d"], "o2b-topics-plan-gate-");
    try {
      const c = fresh.open("dev-c");
      claimViewWriter(c, { agent: "t", now });
      cluster(["s1", "s1", "s2", "s2", "s2"], c);
      expect(plan(c)).toEqual({ status: "waiting-for-claim" });
      fresh.sync();
      const d = fresh.open("dev-d");
      requestViewWriter(d, { agent: "t", now, force: false });
      fresh.sync();
      expect(plan(c)).toEqual({ status: "released", to: "dev-d" });
      const records = (["shared", "private"] as const).flatMap((p) =>
        readPartition(join(fresh.root("dev-c"), p)).flatMap((s) => s.records),
      );
      expect(foldTopics(records).topics.size).toBe(0);
    } finally {
      fresh.cleanup();
    }
  });

  test("a writer move that arrives while the pass holds the planning lock stops it before it plans", () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    m.sync();
    const b = m.open("dev-b");
    const lock = `${topicPlanLockTarget(a)}.lock`;
    let moved = false;
    clock += 1000;
    const report = runTopicPlanning(a, {
      agent: "dream",
      // The first clock reading under the lock comes after the gate read
      // the settings: the move lands between that read and the plan's.
      now: () => {
        if (!moved && existsSync(lock)) {
          moved = true;
          requestViewWriter(b, { agent: "t", now, force: true });
          m.deliver("dev-b", "dev-a");
        }
        return clock;
      },
    });
    expect(moved).toBe(true);
    expect(report).toEqual({ status: "not-writer", writer: "dev-b" });
    expect(fold().topics.size).toBe(0);
  });

  test("a write that fails after a topic was created still lists the topic with its undo command", () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    clock += 1000;
    const report = runTopicPlanning(a, {
      agent: "dream",
      // A clock that fails once the create has landed: the first assign fails.
      now: () => {
        if (createdOnDisk()) throw new Error("clock unavailable");
        return clock;
      },
    });
    expect(report.status).toBe("error");
    if (report.status !== "error") return;
    expect(report.error).toBe("clock unavailable");
    expect(report.created.map((c) => [c.members, c.undo])).toEqual([
      [0, `o2b topic undo ${report.created[0]!.record}`],
    ]);
    expect(fold().topics.size).toBe(1);
  });

  test("two planning processes on the view writer wait for the lock and leave one topic per cluster", async () => {
    cluster(["s1", "s1", "s2", "s2", "s2"]);
    ["s3", "s3", "s4", "s4", "s4"].forEach((session, i) =>
      signal(`Phone views render markdown pages offline ${i}`, { session }),
    );
    const start = join(m.parent, "start");
    const children = [0, 1].map(() =>
      Bun.spawn(
        [
          process.execPath,
          join(import.meta.dir, "fixtures", "plan-child.ts"),
          m.root("dev-a"),
          "dev-a",
          m.parent,
          start,
        ],
        {
          stdin: "ignore",
          stdout: "pipe",
          stderr: "pipe",
          // Shorter than the time the lock is held: planning must wait longer.
          env: { ...process.env, OPEN_SECOND_BRAIN_LOCK_WAIT_MS: "200" },
        },
      ),
    );
    // Hold the planning lock while both children start, so both must wait on it.
    let released = 0;
    withLocalLock(topicPlanLockTarget(a), () => {
      writeFileSync(start, "");
      // Release only once both children are about to plan, so both meet the held lock.
      const deadline = Date.now() + 20_000;
      while (startedChildren() < 2 && Date.now() < deadline) Bun.sleepSync(10);
      expect(startedChildren()).toBe(2);
      Bun.sleepSync(300);
      released = Date.now();
    });
    const outs = await Promise.all(children.map((c) => new Response(c.stdout).text()));
    await Promise.all(children.map((c) => c.exited));
    const results = outs.map(
      (o) => JSON.parse(o) as { report?: { status: string; created: unknown[] }; end: number },
    );
    for (const result of results) {
      expect(result.report?.status).toBe("planned");
      expect(result.end).toBeGreaterThanOrEqual(released);
    }
    expect(results.flatMap((r) => r.report!.created)).toHaveLength(2);
    expect(fold().topics.size).toBe(2);
  });
});