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

import {
  computeSchemaPackDigest,
  SCHEMA_MUTATION_AUDIT_ACTION,
  SCHEMA_MUTATION_AUDIT_DIR,
  SCHEMA_PACK_DIGEST_FIELD,
} from "../../../src/core/brain/schema-integrity.ts";
import {
  applySchemaMutations,
  previewSchemaMutations,
  type SchemaMutation,
} from "../../../src/core/brain/schema-mutate.ts";
import { loadSchemaPack } from "../../../src/core/brain/schema-pack.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

/** Schema tokens used by the cases below. */
const DECISION = "decision";
const RESEARCH = "research";
const RESEARCH_NOTE = "research-note";
const SUPPORTS = "supports";
const CREDENTIAL_NOTE = "credential-note";
const UNDECLARED = "undeclared";

let vault: string;

/**
 * Epoch seconds stamped onto `_brain.yaml` before a preview, far enough in
 * the past that ANY write during the preview would move the modification
 * time to now. Without this the assertion would be satisfied by a coarse
 * filesystem timestamp rather than by the preview keeping its hands off.
 */
const PAST_MTIME_SECONDS = Date.UTC(2020, 0, 1) / 1000;

function configPathFor(root: string): string {
  return join(root, "Brain", "_brain.yaml");
}

interface ConfigSnapshot {
  /** Base64 of the raw file, so the comparison is over bytes, not text. */
  readonly bytes: string;
  readonly mtimeMs: number;
}

/** Freeze `_brain.yaml`'s observable state so a later write is detectable. */
function snapshotConfig(root: string): ConfigSnapshot {
  const path = configPathFor(root);
  utimesSync(path, PAST_MTIME_SECONDS, PAST_MTIME_SECONDS);
  return { bytes: readFileSync(path).toString("base64"), mtimeMs: statSync(path).mtimeMs };
}

function expectConfigUntouched(root: string, snapshot: ConfigSnapshot): void {
  const path = configPathFor(root);
  expect(readFileSync(path).toString("base64")).toBe(snapshot.bytes);
  expect(statSync(path).mtimeMs).toBe(snapshot.mtimeMs);
}

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-schema-mutate-"));
  mkdirSync(join(vault, "Brain"), { recursive: true });
  writeFileSync(
    join(vault, "Brain", "_brain.yaml"),
    [
      "schema_version: 1",
      "primary_agent: tester",
      "schema:",
      "  preference_types: [research]",
      "  signal_types: [observation]",
      "  page_types: [paper]",
      "  log_event_kinds: [milestone]",
    ].join("\n") + "\n",
    "utf8",
  );
});

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

describe("applySchemaMutations", () => {
  test("applies all schema mutation primitives through one atomic batch", async () => {
    const mutations: SchemaMutation[] = [
      { op: "add_type", category: "preference_types", token: DECISION },
      {
        op: "update_type",
        category: "preference_types",
        token: RESEARCH,
        new_token: RESEARCH_NOTE,
      },
      { op: "add_alias", token: DECISION, alias: "choice" },
      { op: "remove_alias", token: DECISION, alias: "choice" },
      { op: "add_prefix", prefix: "pref", token: DECISION },
      { op: "remove_prefix", prefix: "pref" },
      { op: "add_link_type", token: SUPPORTS },
      { op: "remove_link_type", token: SUPPORTS },
      { op: "set_extractable", token: DECISION, enabled: true },
      { op: "set_extractable", token: DECISION, enabled: false },
      { op: "set_expert_routing", token: DECISION, expert: "schema-author" },
      { op: "set_expert_routing", token: DECISION, expert: null },
      { op: "remove_type", category: "preference_types", token: DECISION },
    ];

    const result = await applySchemaMutations(vault, mutations, {
      actor: "tester",
      now: new Date("2026-05-30T12:00:00.000Z"),
    });

    expect(result.applied).toBe(13);
    const pack = loadSchemaPack(vault);
    expect(pack.declarations.preference_types).toEqual(["research-note"]);
    expect(pack.aliases).toEqual({});
    expect(pack.prefixes).toEqual({});
    expect(pack.link_types).toEqual([]);
    expect(pack.extractable).toEqual([]);
    expect(pack.expert_routing).toEqual({});
    expect(result.audit_path.endsWith("2026-W22.jsonl")).toBe(true);
  });

  test("rejects invalid batches before touching _brain.yaml", async () => {
    const configPath = join(vault, "Brain", "_brain.yaml");
    const before = readFileSync(configPath, "utf8");

    await expect(
      applySchemaMutations(
        vault,
        [{ op: "add_type", category: "preference_types", token: "123bad" }],
        { actor: "tester" },
      ),
    ).rejects.toThrow("schema.preference_types");

    expect(readFileSync(configPath, "utf8")).toBe(before);
  });

  test("rejects update_type when the source token is missing", async () => {
    await expect(
      applySchemaMutations(
        vault,
        [
          {
            op: "update_type",
            category: "preference_types",
            token: "missing",
            new_token: "renamed",
          },
        ],
        { actor: "tester" },
      ),
    ).rejects.toThrow("schema.preference_types: missing is not declared");
  });

  test("rejects multi-line expert routing values before rendering", async () => {
    await expect(
      applySchemaMutations(
        vault,
        [
          {
            op: "set_expert_routing",
            token: RESEARCH,
            expert: "schema-author\nother",
          },
        ],
        { actor: "tester" },
      ),
    ).rejects.toThrow("expert must be a single line");
  });

  test("writes redacted mutation audit records", async () => {
    const result = await applySchemaMutations(
      vault,
      [{ op: "add_type", category: "signal_types", token: CREDENTIAL_NOTE }],
      {
        actor: "tester",
        now: new Date("2026-05-30T12:00:00.000Z"),
        reason: "api_key=secret-value",
      },
    );

    const audit = readFileSync(result.audit_path, "utf8");
    expect(audit).toContain("schema_apply_mutations");
    expect(audit).toContain("***REDACTED***");
    expect(audit).not.toContain("secret-value");
  });

  test("records the resulting pack digest into the audit record it writes", async () => {
    const result = await applySchemaMutations(
      vault,
      [{ op: "add_type", category: "preference_types", token: DECISION }],
      { actor: "tester", now: new Date("2026-05-30T12:00:00.000Z") },
    );

    // The record said which mutations were requested and nothing about the
    // pack they produced, so no later read had an expectation to compare
    // the file against.
    const record = JSON.parse(readFileSync(result.audit_path, "utf8").trim()) as {
      action: string;
      details: Record<string, unknown>;
    };
    expect(record.action).toBe(SCHEMA_MUTATION_AUDIT_ACTION);
    expect(record.details[SCHEMA_PACK_DIGEST_FIELD]).toBe(result.pack_digest);
    expect(result.pack_digest).toBe(computeSchemaPackDigest(result.pack));
    expect(result.pack_digest).toBe(computeSchemaPackDigest(loadSchemaPack(vault)));
  });

  test("writes its audit shard under the shared audit-directory constant", async () => {
    const result = await applySchemaMutations(
      vault,
      [{ op: "add_type", category: "preference_types", token: DECISION }],
      { actor: "tester" },
    );

    expect(
      result.audit_path.startsWith(join(vault, "Brain", "log", SCHEMA_MUTATION_AUDIT_DIR)),
    ).toBe(true);
  });
});

describe("previewSchemaMutations", () => {
  test("returns the pack that would result and the diff from the current one", () => {
    const snapshot = snapshotConfig(vault);

    const preview = previewSchemaMutations(vault, [
      { op: "add_type", category: "preference_types", token: DECISION },
      { op: "add_alias", token: DECISION, alias: "choice" },
      { op: "set_expert_routing", token: DECISION, expert: "schema-author" },
    ]);

    expect(preview.dry_run).toBe(true);
    expect(preview.would_apply).toBe(3);
    expect(preview.pack.declarations.preference_types).toEqual(["research", "decision"]);
    expect(preview.diff).toEqual([
      { path: "aliases.decision", before: null, after: "choice" },
      { path: "declarations.preference_types", before: null, after: "decision" },
      { path: "expert_routing.decision", before: null, after: "schema-author" },
    ]);

    expectConfigUntouched(vault, snapshot);
    expect(loadSchemaPack(vault).declarations.preference_types).toEqual(["research"]);
  });

  test("reports a scalar leaf whose value changed as a before/after pair", async () => {
    await applySchemaMutations(
      vault,
      [{ op: "set_expert_routing", token: RESEARCH, expert: "first-expert" }],
      { actor: "tester" },
    );
    const snapshot = snapshotConfig(vault);

    const preview = previewSchemaMutations(vault, [
      { op: "set_expert_routing", token: RESEARCH, expert: "second-expert" },
    ]);

    expect(preview.diff).toEqual([
      { path: "expert_routing.research", before: "first-expert", after: "second-expert" },
    ]);
    expectConfigUntouched(vault, snapshot);
  });

  test("reports a rename as one removed and one added declaration member", () => {
    const preview = previewSchemaMutations(vault, [
      {
        op: "update_type",
        category: "preference_types",
        token: RESEARCH,
        new_token: RESEARCH_NOTE,
      },
    ]);

    expect(preview.diff).toEqual([
      { path: "declarations.preference_types", before: "research", after: null },
      { path: "declarations.preference_types", before: null, after: "research-note" },
    ]);
  });

  test("returns an empty diff for a batch that would change nothing", () => {
    const preview = previewSchemaMutations(vault, [
      { op: "add_type", category: "preference_types", token: RESEARCH },
    ]);

    expect(preview.would_apply).toBe(1);
    expect(preview.diff).toEqual([]);
  });

  test("previews against a vault with no _brain.yaml without creating one", () => {
    const configPath = configPathFor(vault);
    rmSync(configPath);

    const preview = previewSchemaMutations(vault, [
      { op: "add_type", category: "preference_types", token: DECISION },
    ]);

    expect(preview.diff).toEqual([
      { path: "declarations.preference_types", before: null, after: "decision" },
    ]);
    // Absent must stay absent: a preview creates nothing, not even the file
    // the apply path would materialise from its default.
    expect(existsSync(configPath)).toBe(false);
  });

  const REJECTED_BATCHES: ReadonlyArray<{
    readonly name: string;
    readonly mutations: ReadonlyArray<SchemaMutation>;
    readonly message: string;
  }> = [
    {
      name: "a malformed token",
      mutations: [{ op: "add_type", category: "preference_types", token: "123bad" }],
      message:
        "schema.preference_types: must start with a letter and contain only letters, numbers, underscores, or hyphens",
    },
    {
      name: "a prefix pointing at an undeclared token",
      mutations: [{ op: "add_prefix", prefix: "pref", token: UNDECLARED }],
      message: "schema.prefixes.pref: token is not declared",
    },
    {
      name: "a rename of a token that is not declared",
      mutations: [
        {
          op: "update_type",
          category: "preference_types",
          token: "missing",
          new_token: "renamed",
        },
      ],
      message: "schema.preference_types: missing is not declared",
    },
  ];

  for (const rejected of REJECTED_BATCHES) {
    test(`preview of ${rejected.name} raises exactly what an apply raises, without writing`, async () => {
      const snapshot = snapshotConfig(vault);

      let previewMessage = "";
      try {
        previewSchemaMutations(vault, rejected.mutations);
      } catch (err) {
        previewMessage = (err as Error).message;
      }
      expectConfigUntouched(vault, snapshot);

      let applyMessage = "";
      try {
        await applySchemaMutations(vault, rejected.mutations, { actor: "tester" });
      } catch (err) {
        applyMessage = (err as Error).message;
      }

      expect(previewMessage).toBe(rejected.message);
      expect(applyMessage).toBe(previewMessage);
    });
  }
});