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
19.2 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";

import {
  parseSignal,
  resolveEffectiveScope,
  writeSignal,
  type WriteSignalInput,
} from "../../src/core/brain/signal.ts";
import { TagSyntaxError } from "../../src/core/brain/tag-syntax.ts";

let tmp: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-brain-signal-"));
  // A legacy tree: these tests pin the page layout of an unswitched
  // machine (a vault with no `Brain/` is store-only, task 2.10).
  mkdirSync(join(tmp, "Brain"), { recursive: true });
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

function baseInput(overrides: Partial<WriteSignalInput> = {}): WriteSignalInput {
  return {
    topic: "no-internal-abbrev",
    signal: "negative",
    agent: "claude",
    principle: "Do not use internal abbreviations in user-facing copy unless explained first",
    created_at: "2026-05-14T10:15:00Z",
    date: "2026-05-14",
    slug: "no-internal-abbrev",
    scope: "writing",
    source: ["[[Daily/2026.05.14]]", "[[blog-header-draft]]"],
    raw: "Sergey pointed out that OSB appeared as an abbreviation.",
    ...overrides,
  };
}

describe("writeSignal β€” required field validation", () => {
  // Test each required field independently. The contract is
  // `Error('signal missing field: <name>')` so a regression that
  // changes the message format would be caught here.
  const requiredFields: ReadonlyArray<keyof WriteSignalInput> = [
    "topic",
    "signal",
    "agent",
    "principle",
    "created_at",
    "date",
    "slug",
  ];
  for (const field of requiredFields) {
    test(`missing '${String(field)}' throws naming the field`, () => {
      const input = baseInput();
      // `as any`-equivalent without `any`: structurally remove the
      // field by composing a fresh object that omits it.
      const partial = { ...input } as Record<string, unknown>;
      delete partial[field as string];
      expect(() => writeSignal(tmp, partial as unknown as WriteSignalInput)).toThrow(
        new RegExp(`signal missing field: ${String(field)}`),
      );
    });
  }

  test("invalid signal value throws", () => {
    expect(() =>
      writeSignal(tmp, baseInput({ signal: "neutral" as unknown as "positive" })),
    ).toThrow(/must be 'positive' or 'negative'/);
  });
});

describe("writeSignal + parseSignal roundtrip", () => {
  test("parses every field that was written", () => {
    const result = writeSignal(tmp, baseInput());
    expect(result.id).toBe("sig-2026-05-14-no-internal-abbrev");
    const parsed = parseSignal(result.path);
    expect(parsed.kind).toBe("brain-signal");
    expect(parsed.id).toBe(result.id);
    expect(parsed.created_at).toBe("2026-05-14T10:15:00Z");
    expect(parsed.topic).toBe("no-internal-abbrev");
    expect(parsed.signal).toBe("negative");
    expect(parsed.agent).toBe("claude");
    expect(parsed.scope).toBe("writing");
    expect(parsed.principle).toContain("internal abbreviations");
    expect(parsed.tags).toContain("brain");
    expect(parsed.tags).toContain("brain/signal");
    expect(parsed.tags).toContain("brain/topic/no-internal-abbrev");
    expect(parsed.tags).toContain("brain/scope/writing");
    expect(parsed.source).toEqual(["[[Daily/2026.05.14]]", "[[blog-header-draft]]"]);
    expect(parsed.raw).toContain("Sergey pointed out");
  });

  test("byte-equal roundtrip: write β†’ parse β†’ write to a fresh slug β†’ identical bytes", () => {
    // Step 1: original write.
    const first = writeSignal(tmp, baseInput());
    const firstBytes = readFileSync(first.path, "utf8");

    // Step 2: parse what we wrote.
    const parsed = parseSignal(first.path);

    // Step 3: write to a second slug; same input, different filename
    // (so we can compare bytes without colliding on the first file).
    const second = writeSignal(
      tmp,
      baseInput({
        slug: "no-internal-abbrev-roundtrip",
      }),
    );
    const secondBytes = readFileSync(second.path, "utf8");

    // The two files differ only on the `id:` line and the filename
    // baked into the id; everything else must be byte-identical.
    const normalize = (s: string): string =>
      s
        .replace(/^id:.*$/m, "id: <ID>")
        .replace(/\bno-internal-abbrev-roundtrip\b/g, "no-internal-abbrev");
    expect(normalize(firstBytes)).toBe(normalize(secondBytes));

    // And the parsed source array survives untouched.
    expect(parsed.source).toEqual(["[[Daily/2026.05.14]]", "[[blog-header-draft]]"]);
  });
});

describe("resolveEffectiveScope β€” precedence rule", () => {
  test("explicit non-empty scope wins over a default", () => {
    expect(resolveEffectiveScope("docs", "coding")).toBe("docs");
  });
  test("default applies when explicit is undefined", () => {
    expect(resolveEffectiveScope(undefined, "coding")).toBe("coding");
  });
  test("default applies when explicit is whitespace-only", () => {
    expect(resolveEffectiveScope("   ", "coding")).toBe("coding");
  });
  test("returns undefined when neither is set", () => {
    expect(resolveEffectiveScope(undefined, undefined)).toBeUndefined();
  });
  test("returns undefined when both are whitespace/empty", () => {
    expect(resolveEffectiveScope("  ", "")).toBeUndefined();
  });
  test("trims the chosen value", () => {
    expect(resolveEffectiveScope("  docs  ", undefined)).toBe("docs");
    expect(resolveEffectiveScope(undefined, "  coding ")).toBe("coding");
  });
});

describe("writeSignal β€” defaultScope option", () => {
  test("applies the default when no explicit scope is given", () => {
    const input = { ...baseInput({ slug: "default-scope" }) } as Record<string, unknown>;
    delete input["scope"];
    const r = writeSignal(tmp, input as unknown as WriteSignalInput, { defaultScope: "coding" });
    const parsed = parseSignal(r.path);
    expect(parsed.scope).toBe("coding");
    expect(parsed.tags).toContain("brain/scope/coding");
  });

  test("explicit scope overrides the default", () => {
    const r = writeSignal(tmp, baseInput({ slug: "explicit-wins", scope: "writing" }), {
      defaultScope: "coding",
    });
    const parsed = parseSignal(r.path);
    expect(parsed.scope).toBe("writing");
    expect(parsed.tags).toContain("brain/scope/writing");
    expect(parsed.tags).not.toContain("brain/scope/coding");
  });

  test("no default and no explicit scope omits the scope frontmatter (byte-identical)", () => {
    const noScope = { ...baseInput({ slug: "no-scope" }) } as Record<string, unknown>;
    delete noScope["scope"];
    const withDefault = writeSignal(tmp, noScope as unknown as WriteSignalInput, {});
    const text = readFileSync(withDefault.path, "utf8");
    expect(text).not.toContain("scope:");
    expect(text).not.toContain("brain/scope/");
    expect(parseSignal(withDefault.path).scope).toBeUndefined();
  });
});

describe("writeSignal β€” wikilink preservation", () => {
  test("wikilink strings in source[] survive parse β†’ write β†’ parse unchanged", () => {
    const input = baseInput({
      source: ["[[Daily/2026.05.14]]", "[[blog-header-draft]]"],
    });
    const first = writeSignal(tmp, input);
    const parsed = parseSignal(first.path);
    expect(parsed.source).toEqual(["[[Daily/2026.05.14]]", "[[blog-header-draft]]"]);

    // Write again to a different slug, then re-parse.
    const second = writeSignal(tmp, {
      ...input,
      slug: "wiki-roundtrip",
      source: [...parsed.source!],
    });
    const reparsed = parseSignal(second.path);
    expect(reparsed.source).toEqual(["[[Daily/2026.05.14]]", "[[blog-header-draft]]"]);
  });

  test("file body actually contains the wikilink literally", () => {
    const result = writeSignal(tmp, baseInput());
    const bytes = readFileSync(result.path, "utf8");
    expect(bytes).toContain("[[Daily/2026.05.14]]");
    expect(bytes).toContain("[[blog-header-draft]]");
  });
});

describe("extractRawSection (via parseSignal)", () => {
  test("multi-line raw block survives the roundtrip in full (regression on m-flag $)", () => {
    // With the regex `/^##\s+Raw\s*\n+([\s\S]*?)\s*$/m`, the `m` flag
    // makes `$` match end-of-line β€” the lazy `[\s\S]*?` capture was
    // truncated at the first newline. The fix drops the `m` flag so
    // `$` only matches end-of-string, letting the full multi-line raw
    // block flow into the capture group.
    const multiLine = [
      "First line of the raw quote.",
      "Second line continues the thought.",
      "",
      "Third line after a blank gap.",
    ].join("\n");
    const result = writeSignal(
      tmp,
      baseInput({
        slug: "multi-line-raw",
        raw: multiLine,
      }),
    );
    const parsed = parseSignal(result.path);
    expect(parsed.raw).toBe(multiLine);
  });

  test("missing or placeholder raw returns undefined", () => {
    // The "## Raw\n\n_(not provided)_" placeholder should always parse
    // back to `undefined` so the schema shape stays clean.
    const noRawInput = baseInput({ slug: "no-raw" });
    delete (noRawInput as { raw?: string }).raw;
    const result = writeSignal(tmp, noRawInput);
    const parsed = parseSignal(result.path);
    expect(parsed.raw).toBeUndefined();
  });
});

describe("writeSignal β€” slug collision allocator", () => {
  test("second write with the same slug receives a `-2` suffix", () => {
    const a = writeSignal(tmp, baseInput());
    expect(a.id).toBe("sig-2026-05-14-no-internal-abbrev");

    const b = writeSignal(tmp, baseInput());
    expect(b.id).toBe("sig-2026-05-14-no-internal-abbrev-2");
    expect(b.path).not.toBe(a.path);
  });

  test("third write with the same slug receives `-3`", () => {
    writeSignal(tmp, baseInput());
    writeSignal(tmp, baseInput());
    const c = writeSignal(tmp, baseInput());
    expect(c.id).toBe("sig-2026-05-14-no-internal-abbrev-3");
  });
});

/**
 * Plant a name that the read-only probe reads as free and the exclusive
 * create reads as taken: a dangling symlink. `existsSync` follows the
 * link and answers false; `link(2)` does not follow it and answers
 * EEXIST. That is byte-exactly what the loser of a concurrent write
 * observes - the winner's name is taken by the time the create runs -
 * with none of the timing dependence of actually racing two processes.
 */
function plantLostRace(target: string): void {
  mkdirSync(dirname(target), { recursive: true });
  symlinkSync(join(dirname(target), "never-created"), target);
}

describe("writeSignal β€” a lost race retries instead of dropping the event (#161)", () => {
  test("a name taken between the probe and the create lands on `-2`", () => {
    plantLostRace(join(tmp, "Brain", "inbox", "sig-2026-05-14-no-internal-abbrev.md"));

    const result = writeSignal(tmp, baseInput());

    expect(result.id).toBe("sig-2026-05-14-no-internal-abbrev-2");
    expect(existsSync(result.path)).toBe(true);
    expect(parseSignal(result.path).id).toBe("sig-2026-05-14-no-internal-abbrev-2");
  });

  test("exhausting the bound fails loudly and carries the collision as cause", () => {
    plantLostRace(join(tmp, "Brain", "inbox", "sig-2026-05-14-no-internal-abbrev.md"));

    let thrown: unknown;
    try {
      writeSignal(tmp, baseInput(), { maxSlugAttempts: 1 });
    } catch (err) {
      thrown = err;
    }
    expect((thrown as Error).message).toMatch(/could not find a free name after 1 attempts/);
    expect(((thrown as Error).cause as Error).message).toBe(
      "signal already exists: Brain/inbox/sig-2026-05-14-no-internal-abbrev.md",
    );
  });
});

describe("writeSignal β€” sanitisation (Β§7)", () => {
  test("redacts secrets in principle / raw", () => {
    const r = writeSignal(
      tmp,
      baseInput({
        slug: "sec",
        principle: "do not put api_key=hunter2 anywhere",
        raw: 'config = {"client_secret": "shhh"}',
      }),
    );
    const round = parseSignal(r.path);
    expect(round.principle).toContain("***REDACTED***");
    expect(round.principle).not.toContain("hunter2");
    expect(round.raw).toContain("***REDACTED***");
    expect(round.raw).not.toContain("shhh");
  });

  test("a secret-bearing scope refuses at the tag gate, carrying the REDACTED value", () => {
    // t_11ee559f: a scope segment is refused unrewritten when it fails the
    // tag rule, so a spaced scope can no longer land a broken tag - even
    // one whose spaces surround a redacted credential. Sanitisation runs
    // first, so the refusal token carries the redacted value and the raw
    // secret reaches neither disk nor the error.
    let thrown: unknown;
    try {
      writeSignal(
        tmp,
        baseInput({
          slug: "sec-scope",
          scope: "writing token: abcd",
        }),
      );
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(TagSyntaxError);
    expect((thrown as TagSyntaxError).token).not.toContain("abcd");
    expect(existsSync(join(tmp, "Brain", "inbox", "sig-2026-05-14-sec-scope.md"))).toBe(false);
  });

  test("strips C0 controls and folds U+2028/U+2029 in principle", () => {
    // U+2028 = line separator. C0 byte 0x07 (BEL) should be stripped.
    const r = writeSignal(
      tmp,
      baseInput({
        slug: "ctrl",
        principle: "be\x07tidy line2",
      }),
    );
    const round = parseSignal(r.path);
    expect(round.principle).not.toContain("\x07");
    // singleLine collapses the folded LF to space.
    expect(round.principle).toBe("betidy line2");
  });

  test("caps principle at 512 chars", () => {
    const huge = "a".repeat(2000);
    const r = writeSignal(tmp, baseInput({ slug: "big", principle: huge }));
    const round = parseSignal(r.path);
    expect(round.principle.length).toBeLessThanOrEqual(512);
  });

  test("rejects when sanitisation strips principle down to empty", () => {
    expect(() => writeSignal(tmp, baseInput({ slug: "empty", principle: "\x00\x01\x07" }))).toThrow(
      /signal missing field: principle/,
    );
  });
});

// ── Β§9 / Β§16: source_type / dedup_hash / session_ref ─────────────────────────

describe("writeSignal β€” capture-extension fields (Β§9/Β§16)", () => {
  test("records source_type / dedup_hash / session_ref when provided", () => {
    const r = writeSignal(
      tmp,
      baseInput({
        slug: "ext-fields",
        source_type: "inline",
        dedup_hash: "deadbeef".repeat(8),
        session_ref: "Daily/2026-05-14.md#turn-7",
      }),
    );
    const raw = readFileSync(r.path, "utf8");
    expect(raw).toMatch(/^source_type: inline$/m);
    expect(raw).toMatch(
      /^dedup_hash: deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef$/m,
    );
    expect(raw).toMatch(/^session_ref: /m);
  });

  test("adds brain/source/<type> tag when source_type is 'inline'", () => {
    const r = writeSignal(tmp, baseInput({ slug: "inline-tag", source_type: "inline" }));
    const raw = readFileSync(r.path, "utf8");
    expect(raw).toMatch(/brain\/source\/inline/);
  });

  test("adds brain/source/<type> tag when source_type is 'session'", () => {
    const r = writeSignal(tmp, baseInput({ slug: "session-tag", source_type: "session" }));
    const raw = readFileSync(r.path, "utf8");
    expect(raw).toMatch(/brain\/source\/session/);
  });

  test("omits brain/source/* tag when source_type is 'live' (default)", () => {
    const r = writeSignal(tmp, baseInput({ slug: "live-default" }));
    const raw = readFileSync(r.path, "utf8");
    expect(raw).not.toMatch(/brain\/source\//);
  });

  test("parseSignal round-trips source_type / dedup_hash / session_ref", () => {
    const r = writeSignal(
      tmp,
      baseInput({
        slug: "roundtrip",
        source_type: "session",
        dedup_hash: "abc123",
        session_ref: "claude.jsonl#abc",
      }),
    );
    const parsed = parseSignal(r.path);
    expect(parsed.source_type).toBe("session");
    expect(parsed.dedup_hash).toBe("abc123");
    expect(parsed.session_ref).toBe("claude.jsonl#abc");
  });

  test("parseSignal returns undefined for capture-extension fields when absent (legacy file)", () => {
    const r = writeSignal(tmp, baseInput({ slug: "no-ext-fields" }));
    const parsed = parseSignal(r.path);
    expect(parsed.source_type).toBeUndefined();
    expect(parsed.dedup_hash).toBeUndefined();
    expect(parsed.session_ref).toBeUndefined();
  });

  test("rejects unknown source_type values", () => {
    expect(() =>
      writeSignal(
        tmp,
        baseInput({
          slug: "bad-source-type",
          source_type: "bogus" as unknown as "live",
        }),
      ),
    ).toThrow(/source_type/);
  });
});

// ── t_11ee559f: composed tags obey the one shared tag rule ───────────────────

describe("writeSignal β€” tag syntax (t_11ee559f)", () => {
  test("a spaced topic yields the slugified tag; the topic field stays as typed", () => {
    const r = writeSignal(tmp, baseInput({ topic: "foo bar", slug: "spaced-topic" }));
    const parsed = parseSignal(r.path);
    expect(parsed.topic).toBe("foo bar");
    expect(parsed.tags).toContain("brain/topic/foo-bar");
    const raw = readFileSync(r.path, "utf8");
    expect(raw).toContain("brain/topic/foo-bar");
    expect(raw).not.toContain("brain/topic/foo bar");
  });

  test("a topic that even slugified fails the rule refuses, naming the field", () => {
    let thrown: unknown;
    try {
      writeSignal(tmp, baseInput({ topic: "42", slug: "numeric-topic" }));
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(TagSyntaxError);
    expect((thrown as TagSyntaxError).field).toBe("topic");
  });

  test("a bad extraTags entry refuses, naming the field, and writes no file", () => {
    let thrown: unknown;
    try {
      writeSignal(tmp, baseInput({ extraTags: ["not a tag"] }));
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(TagSyntaxError);
    expect((thrown as TagSyntaxError).field).toBe("extraTags");
    expect(existsSync(join(tmp, "Brain", "inbox", "sig-2026-05-14-no-internal-abbrev.md"))).toBe(
      false,
    );
  });

  test("a scope segment is rejected unrewritten, naming the field", () => {
    expect(() => writeSignal(tmp, baseInput({ scope: "two words" }))).toThrow(TagSyntaxError);
  });

  test("a comma-separated scope composes one tag per segment; the field stays verbatim", () => {
    const r = writeSignal(tmp, baseInput({ scope: "alpha, beta" }));
    expect(parseSignal(r.path).scope).toBe("alpha, beta");
    expect(readFileSync(r.path, "utf8")).toContain(
      "tags: [brain, brain/signal, brain/topic/no-internal-abbrev, brain/scope/alpha, brain/scope/beta]",
    );
  });

  test("a failing segment of a comma-separated scope is refused, naming that segment", () => {
    let thrown: unknown;
    try {
      writeSignal(tmp, baseInput({ scope: "alpha,two words" }));
    } catch (err) {
      thrown = err;
    }
    expect(thrown).toBeInstanceOf(TagSyntaxError);
    expect((thrown as TagSyntaxError).field).toBe("scope");
    expect((thrown as TagSyntaxError).token).toBe("two words");
  });

  test("clean inputs keep the incumbent tags line byte-for-byte", () => {
    const r = writeSignal(tmp, baseInput());
    const raw = readFileSync(r.path, "utf8");
    expect(raw).toContain(
      "tags: [brain, brain/signal, brain/topic/no-internal-abbrev, brain/scope/writing]",
    );
  });
});