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
10.1 KB
Raw Blame
/**
 * The reference grammar both rules ask through
 * (`src/core/brain/artifact-ref-view.ts`).
 *
 * `visible()` reads a reference that resolves to no artifact on disk as
 * "this row names nothing that could be hidden" and lets the row
 * through. That reading is only true for the spellings the resolver
 * would have FOUND had the artifact existed - so every spelling it
 * cannot resolve is a fail-open, on a rule whose whole posture is
 * fail-closed. These are the spellings.
 */

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

import { artifactRefView } from "../../../src/core/brain/artifact-ref-view.ts";
import { logEntryArtifactRefs } from "../../../src/core/brain/log.ts";
import type { BrainLogEntry } from "../../../src/core/brain/log.ts";

const HIDDEN_ID = "pref-hidden";
const HIDDEN_REL = `Brain/preferences/${HIDDEN_ID}.md`;

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-artifact-ref-"));
  mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
  writeFileSync(join(vault, HIDDEN_REL), "---\ntopic: hidden\n---\n\nthe rule\n");
});

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

/** A view that hides exactly the one page above, and nothing else. */
const hidingView = () => artifactRefView(vault, (rel) => rel !== HIDDEN_REL);

describe("reference spellings the rule must resolve", () => {
  const SPELLINGS: ReadonlyArray<{ readonly ref: string; readonly why: string }> = [
    { ref: HIDDEN_ID, why: "the bare id" },
    { ref: `[[${HIDDEN_ID}]]`, why: "the wikilink form" },
    { ref: HIDDEN_REL, why: "the vault-relative path" },
    { ref: `[[${HIDDEN_REL}]]`, why: "the path as a wikilink" },
    { ref: `[[${HIDDEN_ID}|the rule]]`, why: "an ALIASED wikilink" },
    { ref: `[[${HIDDEN_ID}#Raw]]`, why: "an ANCHORED wikilink" },
    { ref: `[[${HIDDEN_REL}|the rule]]`, why: "an aliased PATH wikilink" },
    { ref: `${HIDDEN_ID}|the rule`, why: "decoration with no brackets left on it" },
  ];

  for (const { ref, why } of SPELLINGS) {
    test(`${why} resolves to the hidden page and is withheld`, () => {
      expect(hidingView().visible(ref), why).toBe(false);
    });
  }

  test("a reference that genuinely names nothing still passes", () => {
    const view = hidingView();
    expect(view.visible("pref-never-existed")).toBe(true);
    expect(view.visible("[[pref-never-existed|alias]]")).toBe(true);
    expect(view.visible(null)).toBe(true);
    expect(view.visible(undefined)).toBe(true);
    expect(view.visible("")).toBe(true);
  });

  test("a row survives only when every reference it names survives", () => {
    const view = hidingView();
    expect(view.row("pref-other", HIDDEN_ID)).toBe(false);
    expect(view.row("pref-other", "pref-another")).toBe(true);
  });
});

describe("the vault path as the caller spelled it", () => {
  // A bare id is resolved to a file under the vault and then handed to the
  // rule as a vault-relative path. The vault a surface was configured with
  // is not always canonical; the relative path must not depend on that.
  const SPELLINGS: ReadonlyArray<{ readonly spell: () => string; readonly why: string }> = [
    { spell: () => `${vault}/`, why: "a trailing separator" },
    { spell: () => join(vault, "Brain") + "/..", why: "a `..` segment" },
    { spell: () => `${vault}/./`, why: "a `.` segment" },
  ];

  for (const { spell, why } of SPELLINGS) {
    test(`a bare id under a vault spelled with ${why} is still withheld`, () => {
      const view = artifactRefView(spell(), (rel) => rel !== HIDDEN_REL);
      expect(view.visible(HIDDEN_ID)).toBe(false);
    });
  }
});

describe("what a log entry offers the rule", () => {
  const entry = (body: Record<string, unknown>): BrainLogEntry =>
    ({
      timestamp: "2026-05-04T00:00:00Z",
      eventType: "apply-evidence",
      body,
    }) as unknown as BrainLogEntry;

  test("a key outside the old four-name list is still offered", () => {
    // `target`, `subject_a`, `successor`, `source_path` and the rest are
    // real writer keys in this tree; the enumeration that omitted them
    // made their rows unconditionally visible.
    for (const key of ["target", "subject_a", "successor", "predecessor", "source_path", "note"]) {
      expect(hidingView().keep([entry({ [key]: HIDDEN_ID })], logEntryArtifactRefs)).toEqual([]);
    }
  });

  test("an ARRAY-valued payload is flattened rather than dropped", () => {
    // `parseLogDay` produces an array whenever a key repeats or uses the
    // indented sub-bullet form, and a `typeof === "string"` test answered
    // `undefined` for exactly those.
    const rows = [entry({ path: ["notes/open.md", HIDDEN_ID] })];
    expect(hidingView().keep(rows, logEntryArtifactRefs)).toEqual([]);
  });

  test("a row naming nothing hidden is kept, so the widening is not blanket-denying", () => {
    const rows = [entry({ path: "notes/open.md", detail: "some prose about a rule" })];
    expect(hidingView().keep(rows, logEntryArtifactRefs)).toEqual(rows);
  });
});

describe("an extensionless vault-page spelling", () => {
  const HIDDEN_PAGE_REL = "Brain/notes/private";
  const OPEN_PAGE_REL = "Brain/notes/open";

  beforeEach(() => {
    mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
    writeFileSync(join(vault, `${HIDDEN_PAGE_REL}.md`), "---\ntopic: hidden\n---\n\nhidden\n");
    writeFileSync(join(vault, `${OPEN_PAGE_REL}.md`), "open page\n");
  });

  /** A view that hides exactly the hidden notes page above. */
  const hidingNotesPage = () => artifactRefView(vault, (rel) => rel !== `${HIDDEN_PAGE_REL}.md`);

  test("resolves to the same target as its .md form and is withheld", () => {
    // A gate that resolved only the .md form failed OPEN for the bare
    // wikilink shape - the conventional Obsidian spelling.
    const view = hidingNotesPage();
    expect(view.visible("[[Brain/notes/private]]")).toBe(false);
    expect(view.visible("Brain/notes/private")).toBe(false);
    expect(view.visible(`[[${HIDDEN_PAGE_REL}.md]]`)).toBe(false);
  });

  test("a readable page stays visible under the extensionless spelling", () => {
    expect(hidingNotesPage().visible("[[Brain/notes/open]]")).toBe(true);
  });

  test("the bare spelling wins when that file exists, as the write side resolves it", () => {
    // One extensionless file beside its .md twin: the bare candidate is
    // the page the reference names - the same first-existing rule the
    // ingest window resolver applies - so hiding one does not hide the
    // other.
    writeFileSync(join(vault, "Brain", "notes", "dual"), "bare twin\n");
    const view = artifactRefView(vault, (rel) => rel !== "Brain/notes/dual");
    expect(view.visible("[[Brain/notes/dual]]")).toBe(false);
    expect(view.visible("[[Brain/notes/dual.md]]")).toBe(true);
  });

  test("a spelling naming no page names nothing here, and stays visible", () => {
    // A convention like `Notes/<slug>-applied` in a log payload is not a
    // page: with neither candidate on disk the reference resolves to
    // nothing and the row keeps today's visibility, instead of inheriting
    // the verdict of the missing `.md` page it used to resolve to. The
    // rule therefore hides that twin too - the verdict the reference must
    // NOT inherit now that it names nothing.
    const view = artifactRefView(
      vault,
      (rel) => rel !== `${HIDDEN_PAGE_REL}.md` && rel !== "Brain/notes/never-written.md",
    );
    expect(view.visible("[[Brain/notes/never-written]]")).toBe(true);
    expect(view.visible("Brain/notes/never-written")).toBe(true);
  });

  test("a bare spelling naming a directory is never judged as a page", () => {
    // The bare candidate must be a regular file: a directory the rule
    // withholds (Brain/inbox, a convention folder) is not a page, and a
    // reference to it keeps today's visibility instead of dropping the
    // rows that carry it.
    mkdirSync(join(vault, "Brain", "notes", "shaped"), { recursive: true });
    const view = artifactRefView(
      vault,
      (rel) => rel !== `${HIDDEN_PAGE_REL}.md` && rel !== "Brain/notes/shaped",
    );
    expect(view.visible("[[Brain/notes/shaped]]")).toBe(true);
    expect(view.visible("Brain/notes/shaped")).toBe(true);
  });

  test("a bare id spelling is never read as a path", () => {
    // Ids keep the artifact-directory resolution: an extensionless id
    // that resolves to no artifact still names nothing.
    expect(hidingView().visible("pref-never-existed")).toBe(true);
  });
});

describe("a reference that leaves the vault", () => {
  test("is hidden without asking the rule, so nothing beside the vault is read", () => {
    const asked: string[] = [];
    const view = artifactRefView(vault, (rel) => {
      asked.push(rel);
      return true;
    });
    expect(view.visible("../outside.md")).toBe(false);
    expect(view.visible("[[../../outside.md]]")).toBe(false);
    expect(view.visible("Notes/../../outside.md")).toBe(false);
    expect(asked).toEqual([]);
    expect(view.visible("notes/inside.md")).toBe(true);
    expect(asked).toEqual(["notes/inside.md"]);
  });
});

describe("absolute and Windows spellings", () => {
  test("an absolute path to the hidden page is judged where it is, and withheld", () => {
    expect(hidingView().visible(join(vault, "Brain", "preferences", `${HIDDEN_ID}.md`))).toBe(
      false,
    );
    expect(hidingView().visible(`[[${join(vault, "Brain", "preferences", HIDDEN_ID)}]]`)).toBe(
      false,
    );
  });

  test("an absolute path outside the vault is hidden without asking the rule", () => {
    const asked: string[] = [];
    const view = artifactRefView(vault, (rel) => {
      asked.push(rel);
      return true;
    });
    expect(view.visible(join(vault, "..", "outside.md"))).toBe(false);
    expect(asked).toEqual([]);
  });

  test.skipIf(process.platform !== "win32")(
    "a backslash path is the path it spells on Windows, not a bare id",
    () => {
      expect(hidingView().visible(`Brain\\preferences\\${HIDDEN_ID}`)).toBe(false);
      expect(hidingView().visible(`Brain\\preferences\\${HIDDEN_ID}.md`)).toBe(false);
    },
  );
});