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.1 KB
Raw Blame
/**
 * Controlled-vocabulary labels (t_7a41f42d): the schema pack declares
 * label dimensions with allowed values; assignment is fail-closed
 * (unknown dimension or value rejected with the vocabulary in the
 * error), one value per dimension per note, stored as a sorted
 * `labels: [dim/value]` frontmatter array plus a canonical
 * `label` entity in the registry for clustering.
 */

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

import { listEntities } from "../../../src/core/brain/entities/registry.ts";
import {
  assignNoteLabel,
  LabelVocabularyError,
  labelToken,
  removeNoteLabel,
  validateLabelAssignment,
} from "../../../src/core/brain/labels.ts";
import { parseSchemaPack } from "../../../src/core/brain/schema-pack.ts";
import { parseFrontmatter } from "../../../src/core/vault.ts";

const PRIORITY_HIGH = "priority/high";

const PACK = parseSchemaPack(
  [
    "schema_version: 1",
    "schema:",
    "  labels:",
    "    - priority=low",
    "    - priority=high",
    "    - sensitivity=public",
    "    - sensitivity=private",
  ].join("\n") + "\n",
);

const EMPTY_PACK = parseSchemaPack("schema_version: 1\n");

const NOW = new Date("2026-06-04T10:00:00Z");

describe("validateLabelAssignment", () => {
  test("normalizes and accepts declared dimension/value pairs", () => {
    expect(validateLabelAssignment(PACK, " Priority ", "HIGH")).toEqual({
      dimension: "priority",
      value: "high",
      token: PRIORITY_HIGH,
    });
  });

  test("unknown dimension fails closed listing declared dimensions", () => {
    expect(() => validateLabelAssignment(PACK, "mood", "high")).toThrow(LabelVocabularyError);
    expect(() => validateLabelAssignment(PACK, "mood", "high")).toThrow(
      /mood.*declared dimensions: priority, sensitivity/,
    );
  });

  test("unknown value fails closed listing the allowed vocabulary", () => {
    expect(() => validateLabelAssignment(PACK, "priority", "urgent")).toThrow(
      /priority.*allowed values: low, high/,
    );
  });

  test("a pack without labels rejects every assignment", () => {
    expect(() => validateLabelAssignment(EMPTY_PACK, "priority", "high")).toThrow(
      /no label dimensions are declared/,
    );
  });

  test("labelToken renders the canonical dim/value form", () => {
    expect(labelToken("priority", "high")).toBe("priority/high");
  });
});

describe("assignNoteLabel / removeNoteLabel", () => {
  let vault: string;

  beforeEach(() => {
    vault = mkdtempSync(join(tmpdir(), "o2b-labels-"));
    // An unswitched vault: its Brain/ tree is the legacy layout under test.
    mkdirSync(join(vault, "Brain"), { recursive: true });
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(
      join(vault, "Notes", "rollout.md"),
      "---\ntitle: Rollout\n---\n\n# Rollout\n\nCanary first.\n",
    );
  });

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

  test("assignment writes a sorted labels array and preserves body and keys", () => {
    const result = assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "sensitivity",
      value: "private",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    expect(result.labels).toEqual(["sensitivity/private"]);
    const [fm, body] = parseFrontmatter(join(vault, "Notes", "rollout.md"));
    expect(fm["labels"]).toEqual(["priority/high", "sensitivity/private"]);
    expect(fm["title"]).toBe("Rollout");
    expect(body).toContain("Canary first.");
  });

  test("one value per dimension - reassignment replaces, idempotent repeat", () => {
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "low",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    const replaced = assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    expect(replaced.labels).toEqual(["priority/high"]);
    const again = assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    expect(again.labels).toEqual(["priority/high"]);
    expect(again.changed).toBe(false);
  });

  test("assignment registers a canonical label entity for clustering", () => {
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    const entities = listEntities(vault, { category: "label" });
    expect(entities).toHaveLength(1);
    expect(entities[0]!.name).toBe("priority/high");
  });

  test("invalid assignment never touches the file", () => {
    expect(() =>
      assignNoteLabel(vault, "Notes/rollout.md", {
        dimension: "priority",
        value: "urgent",
        pack: PACK,
        agent: "tester",
        now: NOW,
      }),
    ).toThrow(LabelVocabularyError);
    const [fm] = parseFrontmatter(join(vault, "Notes", "rollout.md"));
    expect(fm["labels"]).toBeUndefined();
  });

  test("a missing note fails with a clear error", () => {
    expect(() =>
      assignNoteLabel(vault, "Notes/ghost.md", {
        dimension: "priority",
        value: "high",
        pack: PACK,
        agent: "tester",
        now: NOW,
      }),
    ).toThrow(/does not exist/);
  });

  test("removal drops one dimension and reports whether it was present", () => {
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "sensitivity",
      value: "public",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    const removed = removeNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      pack: PACK,
    });
    expect(removed.removed).toBe(true);
    expect(removed.labels).toEqual(["sensitivity/public"]);
    const again = removeNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      pack: PACK,
    });
    expect(again.removed).toBe(false);
    const [fm] = parseFrontmatter(join(vault, "Notes", "rollout.md"));
    expect(fm["labels"]).toEqual(["sensitivity/public"]);
  });

  test("removing the last label drops the labels key entirely", () => {
    assignNoteLabel(vault, "Notes/rollout.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    removeNoteLabel(vault, "Notes/rollout.md", { dimension: "priority", pack: PACK });
    const [fm] = parseFrontmatter(join(vault, "Notes", "rollout.md"));
    expect(fm["labels"]).toBeUndefined();
  });

  test("path traversal outside the vault is refused", () => {
    expect(() =>
      assignNoteLabel(vault, "../outside.md", {
        dimension: "priority",
        value: "high",
        pack: PACK,
        agent: "tester",
        now: NOW,
      }),
    ).toThrow(/outside the vault/);
  });

  test("the write binding's own config is not writable through labels (t_sec_labels_governance)", () => {
    // A governance surface that could rewrite `Brain/_brain.yaml` would
    // not be governed: a label write over it would fail-closed the whole
    // caller-named write boundary until an operator repairs the file.
    mkdirSync(join(vault, "Brain"), { recursive: true });
    const configPath = join(vault, "Brain", "_brain.yaml");
    writeFileSync(configPath, "schema_version: 1\n", "utf8");
    expect(() =>
      assignNoteLabel(vault, "Brain/_brain.yaml", {
        dimension: "priority",
        value: "high",
        pack: PACK,
        agent: "tester",
        now: NOW,
      }),
    ).toThrow(/config/);
    expect(() =>
      removeNoteLabel(vault, "Brain/_brain.yaml", { dimension: "priority", pack: PACK }),
    ).toThrow(/config/);
    expect(readFileSync(configPath, "utf8")).toBe("schema_version: 1\n");
  });

  test("Brain machinery and non-note files are refused with no binding declared", () => {
    // Without a declared binding the only wall used to be the config's
    // name: a label write could rewrite the vault identity marker (and so
    // disable the identity guard) or the search provider registry.
    mkdirSync(join(vault, "Brain", "search"), { recursive: true });
    mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
    const targets: Record<string, string> = {
      "Brain/vault-id.json": '{"id":"v"}\n',
      "Brain/search/embedding-providers.json": "{}\n",
      "Brain/preferences/pref-x.md": "---\nid: pref-x\n---\nbody\n",
      "brain/preferences/pref-x.md": "",
      "_vault-map.yaml": "roles: {}\n",
    };
    for (const [rel, content] of Object.entries(targets)) {
      if (content !== "") writeFileSync(join(vault, rel), content, "utf8");
    }
    for (const rel of Object.keys(targets)) {
      const opts = { dimension: "priority", value: "high", pack: PACK, agent: "t", now: NOW };
      expect(() => assignNoteLabel(vault, rel, opts)).toThrow(
        /Brain machinery|not a Markdown note/,
      );
      expect(() => removeNoteLabel(vault, rel, { dimension: "priority", pack: PACK })).toThrow(
        /Brain machinery|not a Markdown note/,
      );
    }
    for (const [rel, content] of Object.entries(targets)) {
      if (content !== "") expect(readFileSync(join(vault, rel), "utf8")).toBe(content);
    }
    // The Brain page lanes hold notes, and stay labelable.
    mkdirSync(join(vault, "Brain", "sources"), { recursive: true });
    writeFileSync(join(vault, "Brain", "sources", "src-paper.md"), "---\ntitle: P\n---\nb\n");
    const ok = assignNoteLabel(vault, "Brain/sources/src-paper.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "t",
      now: NOW,
    });
    expect(ok.labels).toEqual(["priority/high"]);
  });

  // The binding matcher splits on `/`; the native `relative()` form on
  // Windows is backslash-separated, which refused every write there once
  // a binding was declared. Only Windows produces that form, so only
  // Windows can exercise it; the prefix test below covers it too there.
  test.skipIf(process.platform !== "win32")(
    "a backslash-spelled target inside a declared binding is admitted on Windows",
    () => {
      mkdirSync(join(vault, "Brain"), { recursive: true });
      writeFileSync(
        join(vault, "Brain", "_brain.yaml"),
        "schema_version: 1\nwrite_binding:\n  path_prefixes:\n    - Projects/Active\n",
        "utf8",
      );
      mkdirSync(join(vault, "Projects", "Active"), { recursive: true });
      writeFileSync(join(vault, "Projects", "Active", "plan.md"), "---\ntitle: P\n---\nb\n");
      const ok = assignNoteLabel(vault, "Projects\\Active\\plan.md", {
        dimension: "priority",
        value: "high",
        pack: PACK,
        agent: "t",
        now: NOW,
      });
      expect(ok.labels).toEqual(["priority/high"]);
    },
  );

  test.skipIf(process.platform === "win32")(
    "a vault note that is a symlink into Brain machinery is refused",
    () => {
      mkdirSync(join(vault, "Brain", "preferences"), { recursive: true });
      const pref = join(vault, "Brain", "preferences", "pref-x.md");
      writeFileSync(pref, "---\nid: pref-x\n---\nbody\n", "utf8");
      mkdirSync(join(vault, "Notes"), { recursive: true });
      symlinkSync(pref, join(vault, "Notes", "alias.md"));
      expect(() =>
        assignNoteLabel(vault, "Notes/alias.md", {
          dimension: "priority",
          value: "high",
          pack: PACK,
          agent: "t",
          now: NOW,
        }),
      ).toThrow(/resolves to Brain\/preferences\/pref-x\.md/);
      expect(readFileSync(pref, "utf8")).toBe("---\nid: pref-x\n---\nbody\n");
    },
  );

  test("a declared write binding refuses targets outside its prefixes", () => {
    mkdirSync(join(vault, "Notes"), { recursive: true });
    writeFileSync(
      join(vault, "Notes", "rollout.md"),
      "---\ntitle: Rollout\n---\n\nCanary first.\n",
      "utf8",
    );
    mkdirSync(join(vault, "Brain"), { recursive: true });
    writeFileSync(
      join(vault, "Brain", "_brain.yaml"),
      "schema_version: 1\nwrite_binding:\n  path_prefixes:\n    - Projects\n",
      "utf8",
    );
    expect(() =>
      assignNoteLabel(vault, "Notes/rollout.md", {
        dimension: "priority",
        value: "high",
        pack: PACK,
        agent: "tester",
        now: NOW,
      }),
    ).toThrow(/write binding/i);
    const [fm] = parseFrontmatter(join(vault, "Notes", "rollout.md"));
    expect(fm["labels"]).toBeUndefined();
    // Inside the declared prefix the same write succeeds.
    mkdirSync(join(vault, "Projects"), { recursive: true });
    writeFileSync(join(vault, "Projects", "plan.md"), "---\ntitle: Plan\n---\nbody\n", "utf8");
    const ok = assignNoteLabel(vault, "Projects/plan.md", {
      dimension: "priority",
      value: "high",
      pack: PACK,
      agent: "tester",
      now: NOW,
    });
    expect(ok.changed).toBe(true);
  });
});