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.3 KB
Raw Blame
/**
 * Tests for `src/core/brain/export.ts` (§28).
 *
 * Two surfaces under test:
 *   - `exportPreferencesJson` — schema, row count, field set,
 *     deterministic ordering.
 *   - `exportPreferencesLlmsTxt` — llmstxt.org H1 + summary + per-
 *     status H2 sections, bullet shape, empty-section omission.
 */

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

import {
  BRAIN_EXPORT_SCHEMA_VERSION,
  collectExportRows,
  collectPreferenceRows,
  exportPreferencesJson,
  exportPreferencesLlmsTxt,
  exportPreferencesLlmsTxtDetailed,
  PreferenceParseError,
  type PreferenceDenyKey,
} from "../../../src/core/brain/export.ts";
import {
  PRIVACY_DENY_MARKER_VALUES,
  PRIVACY_MARKER_KEYS,
} from "../../../src/core/graph/privacy-markers.ts";
import { REMOTE_DENY_VISIBILITY_TOKEN } from "../../../src/core/graph/visibility.ts";
import {
  moveToRetired,
  writePreference,
  type WritePreferenceInput,
} from "../../../src/core/brain/preference.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_PREFERENCE_STATUS,
  BRAIN_RETIRED_REASON,
} from "../../../src/core/brain/types.ts";

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-export-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  mkdirSync(join(vault, "Brain", "retired"), { recursive: true });
  mkdirSync(join(vault, "Brain", "inbox"), { recursive: true });
  mkdirSync(join(vault, "Brain", "log"), { recursive: true });
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));

function basePref(
  slug: string,
  overrides: Partial<WritePreferenceInput> = {},
): WritePreferenceInput {
  return {
    slug,
    topic: slug,
    principle: `Principle for ${slug}`,
    created_at: "2026-05-01T00:00:00Z",
    unconfirmed_until: "2026-05-08T00:00:00Z",
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
    confirmed_at: "2026-05-02T00:00:00Z",
    applied_count: 1,
    violated_count: 0,
    last_evidence_at: "2026-05-03T00:00:00Z",
    confidence: BRAIN_CONFIDENCE.medium,
    confidence_value: 0.5,
    pinned: false,
    ...overrides,
  };
}

describe("exportPreferencesJson", () => {
  test("empty preferences/ → empty array, valid envelope", () => {
    const out = exportPreferencesJson(vault);
    expect(out.schema).toBe(BRAIN_EXPORT_SCHEMA_VERSION);
    expect(out.vault_basename.length).toBeGreaterThan(0);
    expect(out.generated_at).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/);
    expect(out.preferences).toEqual([]);
  });

  test("mixed-status preferences are all included, retired/signal are excluded", () => {
    writePreference(vault, basePref("alpha", { status: BRAIN_PREFERENCE_STATUS.confirmed }));
    writePreference(
      vault,
      basePref("beta", {
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
      }),
    );
    writePreference(
      vault,
      basePref("gamma", {
        status: BRAIN_PREFERENCE_STATUS.quarantine,
        applied_count: 2,
        violated_count: 3,
      }),
    );
    // A retired pref + a stray signal must not leak into the export.
    writePreference(vault, basePref("dead"));
    moveToRetired(
      vault,
      join(vault, "Brain", "preferences", "pref-dead.md"),
      BRAIN_RETIRED_REASON.staleNoEvidence,
      { now: new Date("2026-05-10T00:00:00Z"), retired_by: "[[Brain/log/2026-05-10]]" },
    );
    writeFileSync(
      join(vault, "Brain", "inbox", "sig-2026-05-04-thing.md"),
      "---\nkind: brain-signal\n---\nbody\n",
    );

    const out = exportPreferencesJson(vault);
    expect(out.preferences.map((p) => p.id)).toEqual(["pref-alpha", "pref-beta", "pref-gamma"]);
  });

  test("row carries the canonical field set", () => {
    writePreference(vault, basePref("alpha", { scope: "writing", pinned: true }));
    const out = exportPreferencesJson(vault);
    const r = out.preferences[0]!;
    expect(r.id).toBe("pref-alpha");
    expect(r.topic).toBe("alpha");
    expect(r.scope).toBe("writing");
    expect(r.status).toBe("confirmed");
    expect(r.principle).toBe("Principle for alpha");
    expect(r.applied_count).toBe(1);
    expect(r.violated_count).toBe(0);
    expect(r.confidence).toBe(BRAIN_CONFIDENCE.medium);
    expect(r.confidence_value).toBe(0.5);
    expect(r.pinned).toBe(true);
    expect(r.last_evidence_at).toBe("2026-05-03T00:00:00Z");
    expect(r.created_at).toBe("2026-05-01T00:00:00Z");
    expect(r.confirmed_at).toBe("2026-05-02T00:00:00Z");
    // `writePreference` derives a default tag set; the export
    // surfaces whatever made it onto disk verbatim.
    expect(Array.isArray(r.tags)).toBe(true);
    expect(r.tags).toContain("brain/preference");
  });

  test("pref without scope → scope: null in the row", () => {
    writePreference(vault, basePref("no-scope"));
    const out = exportPreferencesJson(vault);
    expect(out.preferences[0]!.scope).toBeNull();
  });

  test("row.body carries the markdown sections after the frontmatter", () => {
    writePreference(vault, basePref("with-body"));
    const out = exportPreferencesJson(vault);
    const r = out.preferences[0]!;
    expect(typeof r.body).toBe("string");
    // `writePreference` emits the `## Origin` section listing the
    // evidenced_by wikilinks as part of the standard skeleton.
    // The row must surface that body verbatim so a downstream
    // consumer can re-emit the rule with its origin trail.
    expect(r.body).toContain("## Origin");
    expect(r.body).toContain("[[sig-2026-05-01-with-body]]");
  });

  test("output ordering is stable by id", () => {
    writePreference(vault, basePref("zeta"));
    writePreference(vault, basePref("alpha"));
    writePreference(vault, basePref("mu"));
    const out = exportPreferencesJson(vault);
    expect(out.preferences.map((p) => p.id)).toEqual(["pref-alpha", "pref-mu", "pref-zeta"]);
  });
});

describe("exportPreferencesLlmsTxt", () => {
  test("empty preferences → H1 + summary only, no H2 sections", () => {
    const txt = exportPreferencesLlmsTxt(vault);
    expect(txt).toContain("# ");
    expect(txt).toContain("Brain preferences");
    expect(txt).toContain("Auto-generated");
    expect(txt).not.toContain("## Confirmed");
    expect(txt).not.toContain("## Unconfirmed");
    expect(txt).not.toContain("## Quarantine");
  });

  test("mixed statuses render in fixed Confirmed → Unconfirmed → Quarantine order", () => {
    writePreference(vault, basePref("alpha", { status: BRAIN_PREFERENCE_STATUS.confirmed }));
    writePreference(
      vault,
      basePref("beta", {
        status: BRAIN_PREFERENCE_STATUS.unconfirmed,
        confirmed_at: null,
      }),
    );
    writePreference(vault, basePref("gamma", { status: BRAIN_PREFERENCE_STATUS.quarantine }));
    const txt = exportPreferencesLlmsTxt(vault);
    const idxConfirmed = txt.indexOf("## Confirmed");
    const idxUnconfirmed = txt.indexOf("## Unconfirmed");
    const idxQuarantine = txt.indexOf("## Quarantine");
    expect(idxConfirmed).toBeGreaterThanOrEqual(0);
    expect(idxUnconfirmed).toBeGreaterThan(idxConfirmed);
    expect(idxQuarantine).toBeGreaterThan(idxUnconfirmed);
  });

  test("only-confirmed vault → only the Confirmed section", () => {
    writePreference(vault, basePref("solo"));
    const txt = exportPreferencesLlmsTxt(vault);
    expect(txt).toContain("## Confirmed");
    expect(txt).not.toContain("## Unconfirmed");
    expect(txt).not.toContain("## Quarantine");
  });

  test("bullet shape matches `- <id> (topic: X[, scope: Y]): <principle>`", () => {
    writePreference(vault, basePref("scoped", { scope: "writing" }));
    writePreference(vault, basePref("unscoped"));
    const txt = exportPreferencesLlmsTxt(vault);
    expect(txt).toContain("- pref-scoped (topic: scoped, scope: writing): Principle for scoped");
    expect(txt).toContain("- pref-unscoped (topic: unscoped): Principle for unscoped");
  });
});

describe("collector privacy denial reporting", () => {
  /**
   * Stamp one extra frontmatter line onto a written preference file.
   * The informal markers (`access:` and siblings) have no write-input
   * field - they are hand-added user-tier lines - so the test adds one
   * the same way an operator does.
   */
  function stampMarker(slug: string, line: string): void {
    const abs = join(vault, "Brain", "preferences", `pref-${slug}.md`);
    writeFileSync(abs, readFileSync(abs, "utf8").replace(/^---\n/, `---\n${line}\n`));
  }

  test("every informal marker key times deny value denies, and rows stay complete", () => {
    // One unmarked control row plus one file per marker key x deny value.
    // Denial is a report BESIDE the rows: the collector's `rows` stay
    // complete because the import-side topic maps must keep seeing every
    // rule, marker or not.
    writePreference(vault, basePref("open"));
    const marked: string[] = [];
    for (const key of PRIVACY_MARKER_KEYS) {
      for (const value of PRIVACY_DENY_MARKER_VALUES) {
        const slug = `marked-${key}-${value}`;
        writePreference(vault, basePref(slug));
        stampMarker(slug, `${key}: ${value}`);
        marked.push(`pref-${slug}`);
      }
    }

    const out = collectPreferenceRows(vault);
    expect(out.rows).toHaveLength(1 + marked.length);
    expect(out.rows.map((r) => r.id)).toContain("pref-open");
    // Sorted by id, like the rows: the denial list rides byte-deterministic
    // surfaces (the json envelope's omitted, the bundle's preferences_omitted).
    expect(out.denied.map((d) => d.id)).toEqual(marked.toSorted());
    // The reason stays the "visibility" class for machine readers; the key
    // names the frontmatter key whose value actually denied the row.
    const expectedKeys = new Map<string, PreferenceDenyKey>(
      marked.map((id) => [id, id.replace("pref-marked-", "").split("-")[0] as PreferenceDenyKey]),
    );
    for (const d of out.denied) {
      expect(d.reason).toBe("visibility");
      // Every denied id is asserted above to come from `marked`, so the
      // expected key is always present.
      expect(d.denied_by).toBe(expectedKeys.get(d.id)!);
    }
  });

  test("visibility: private denies the row", () => {
    writePreference(vault, basePref("reserved", { visibility: [REMOTE_DENY_VISIBILITY_TOKEN] }));
    writePreference(vault, basePref("open"));

    const out = collectPreferenceRows(vault);
    expect(out.denied).toEqual([
      { id: "pref-reserved", reason: "visibility", denied_by: "visibility" },
    ]);
    // Denied rows ride beside the kept ones, never inside them.
    expect(out.rows.map((r) => r.id).toSorted()).toEqual(["pref-open", "pref-reserved"]);
  });

  test("a vault without reservations denies nothing", () => {
    writePreference(vault, basePref("plain"));

    const out = collectPreferenceRows(vault);
    expect(out.denied).toEqual([]);
    expect(out.rows).toHaveLength(1);
  });

  test("parse refusals behave exactly as before denial reporting", () => {
    writePreference(vault, basePref("good"));
    writeFileSync(join(vault, "Brain", "preferences", "pref-broken.md"), "no frontmatter here\n");

    const scan = collectPreferenceRows(vault);
    expect(scan.failures.map((f) => f.path)).toEqual(["Brain/preferences/pref-broken.md"]);
    expect(scan.denied).toEqual([]);
    expect(() => collectExportRows(vault)).toThrow(PreferenceParseError);
  });
});

describe("shared-lane omission reporting", () => {
  function stampMarker(slug: string, line: string): void {
    const abs = join(vault, "Brain", "preferences", `pref-${slug}.md`);
    writeFileSync(abs, readFileSync(abs, "utf8").replace(/^---\n/, `---\n${line}\n`));
  }

  test("a reserved preference leaves the json envelope and is named in omitted", () => {
    writePreference(vault, basePref("open"));
    writePreference(vault, basePref("reserved"));
    stampMarker("reserved", "access: private");

    const out = exportPreferencesJson(vault);
    expect(out.preferences.map((p) => p.id)).toEqual(["pref-open"]);
    expect(out.omitted).toEqual([
      { id: "pref-reserved", reason: "visibility", denied_by: "access" },
    ]);
    // The envelope's version is additive, not a bump: a consumer written
    // against the field-less envelope keeps working.
    expect(out.schema).toBe(BRAIN_EXPORT_SCHEMA_VERSION);
  });

  test("omitted is absent when nothing is denied", () => {
    writePreference(vault, basePref("plain"));

    const out = exportPreferencesJson(vault);
    expect("omitted" in out).toBe(false);
  });

  test("the llms-txt detailed variant leaves the reserved row out of the text and names it", () => {
    writePreference(vault, basePref("open", { scope: "writing" }));
    writePreference(vault, basePref("reserved"));
    stampMarker("reserved", "confidentiality: secret");

    const detail = exportPreferencesLlmsTxtDetailed(vault);
    expect(detail.text).toContain("- pref-open (topic: open, scope: writing): Principle for open");
    expect(detail.text).not.toContain("pref-reserved");
    expect(detail.text).not.toContain("Principle for reserved");
    expect(detail.omitted).toEqual([
      { id: "pref-reserved", reason: "visibility", denied_by: "confidentiality" },
    ]);
    // The stable string signature delegates to the detailed one, so the
    // two never disagree about what the document contains.
    expect(exportPreferencesLlmsTxt(vault)).toBe(detail.text);
  });
});