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
17.2 KB
Raw Blame
/**
 * The published `schemas/brain/*.schema.json` contracts, checked against the
 * REAL output of the report generators they describe.
 *
 * These files are the documented shape of the lifecycle-review reports an
 * agent reads (`brain_intent_review`, `brain_retention`, `brain_brief
 * view=monthly`, `o2b brain intent-review|retention|monthly --json`) and of
 * the complexity block in the discipline report. They used to be mirrored
 * by a hand-written TS copy with its own tests, which only proved the copy
 * agreed with itself. Here the generator runs on a temp vault and its
 * output - plus the MCP projection an agent actually receives - is
 * validated against the file on disk, so a drift on either side fails.
 */

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

import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { buildIntentReview } from "../../../src/core/brain/intent-review.ts";
import { appendLogEvent } from "../../../src/core/brain/log.ts";
import { buildMonthlyReview } from "../../../src/core/brain/monthly-review.ts";
import { preferencePath, processedSignalPath, signalPath } from "../../../src/core/brain/paths.ts";
import { moveToRetired, writePreference } from "../../../src/core/brain/preference.ts";
import { buildRetentionReview } from "../../../src/core/brain/retention.ts";
import { writeSignal } from "../../../src/core/brain/signal.ts";
import {
  BRAIN_APPLY_RESULT,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_RETIRED_REASON,
} from "../../../src/core/brain/types.ts";
import {
  buildComplexityReport,
  complexityPathFactors,
} from "../../../src/core/discipline/complexity.ts";
import { BRAIN_TOOLS } from "../../../src/mcp/brain-tools.ts";
import { SEARCH_INPUT_SCHEMA } from "../../../src/mcp/search-tools.ts";
import { buildSearchQueryArtifact } from "../../../src/cli/search/verbs/schema-export.ts";
import {
  assertSupportedSchema,
  type SchemaNode,
  validateAgainstSchema,
} from "../../helpers/json-schema-subset.ts";

const SCHEMA_DIR = join(import.meta.dir, "..", "..", "..", "schemas", "brain");

/** Every published schema file, and the `$id` it must declare. */
const SCHEMA_IDS: Readonly<Record<string, string>> = {
  "intent-review.schema.json": "brain.intent_review.v1",
  "retention-review.schema.json": "brain.retention_review.v1",
  "monthly-review.schema.json": "brain.monthly_review.v1",
  "complexity-report.schema.json": "brain.complexity_report.v1",
  "search-query.schema.json": "brain.search_query.v1",
};

function loadSchema(file: string): SchemaNode {
  const raw: unknown = JSON.parse(readFileSync(join(SCHEMA_DIR, file), "utf8"));
  assertSupportedSchema(raw);
  return raw as SchemaNode;
}

/** A JSON round-trip: what a `--json` reader or MCP client actually parses. */
function asJson(value: unknown): unknown {
  return JSON.parse(JSON.stringify(value));
}

function expectValid(schema: SchemaNode, value: unknown): void {
  const result = validateAgainstSchema(schema, asJson(value));
  expect(result.errors).toEqual([]);
}

async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
  const tool = BRAIN_TOOLS.find((entry) => entry.name === name);
  if (tool === undefined) throw new Error(`tool not registered: ${name}`);
  return tool.handler({ vault, configPath: join(vault, "config.yaml") } as never, args);
}

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-published-schemas-"));
  bootstrapBrain(vault, {});
});

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

describe("the published schema set", () => {
  test("every file is covered here and declares the id it is known by", () => {
    const files = readdirSync(SCHEMA_DIR)
      .filter((file) => file.endsWith(".schema.json"))
      .toSorted();
    // A new published schema fails here until it gets a generator check below.
    expect(files).toEqual(Object.keys(SCHEMA_IDS).toSorted());
    for (const [file, id] of Object.entries(SCHEMA_IDS)) {
      expect(loadSchema(file).$id).toBe(id);
    }
  });

  test("the validator rejects the drift it exists to catch", () => {
    // Without this the suite could pass on a validator that accepts
    // everything; each case is a real report with one realistic drift.
    const schema = loadSchema("retention-review.schema.json");
    const report = asJson(
      buildRetentionReview(vault, { now: new Date("2026-05-28T00:00:00Z") }),
    ) as Record<string, unknown>;
    expect(validateAgainstSchema(schema, report).ok).toBe(true);

    const extraKey = { ...report, debug: true };
    expect(validateAgainstSchema(schema, extraKey).errors).toContain("debug is not allowed");

    const { summary: _summary, ...missing } = report;
    expect(validateAgainstSchema(schema, missing).errors).toContain("summary is required");

    const badVersion = { ...report, schema_version: 2 };
    expect(validateAgainstSchema(schema, badVersion).errors).toContain(
      "schema_version must be one of 1",
    );

    const badDate = { ...report, generated_at: "yesterday" };
    expect(validateAgainstSchema(schema, badDate).errors).toContain(
      "generated_at must be date-time",
    );

    const negative = { ...report, summary: { keep: -1, improve: 0, park: 0, prune: 0 } };
    expect(validateAgainstSchema(schema, negative).errors).toContain("summary.keep must be >= 0");

    const badAction = {
      ...report,
      recommendations: [
        { id: "x", artifact_type: "processed_signal", action: "delete", reason: "r", path: "p" },
      ],
    };
    expect(validateAgainstSchema(schema, badAction).errors[0]).toContain(
      "recommendations[0].action",
    );
  });

  test("an unsupported keyword is refused rather than silently skipped", () => {
    expect(() => assertSupportedSchema({ type: "string", pattern: "^x$" })).toThrow(
      'unsupported schema keyword "pattern"',
    );
    expect(() => assertSupportedSchema({ type: "string", format: "uri" })).toThrow(
      'unsupported format "uri"',
    );
  });

  test("the string and array length bounds the search schema uses are enforced", () => {
    // t_50c81d5c E4: the brain_search language bounds its strings
    // (minLength/maxLength) and arrays (maxItems); a validator that
    // skipped them would claim a guarantee the published file makes.
    const schema: SchemaNode = {
      type: "object",
      required: ["q"],
      additionalProperties: false,
      properties: {
        q: { type: "string", minLength: 1, maxLength: 4 },
        tags: { type: "array", maxItems: 2, items: { type: "string" } },
      },
    };
    expect(validateAgainstSchema(schema, { q: "ok", tags: ["a"] }).ok).toBe(true);
    expect(validateAgainstSchema(schema, { q: "", tags: [] }).errors).toContain(
      "q must be at least 1 character(s)",
    );
    expect(validateAgainstSchema(schema, { q: "toolong", tags: [] }).errors).toContain(
      "q must be at most 4 character(s)",
    );
    expect(validateAgainstSchema(schema, { q: "ok", tags: ["a", "b", "c"] }).errors).toContain(
      "tags must have at most 2 item(s)",
    );
  });

  test("additionalProperties as a SCHEMA validates unknown keys against it", () => {
    // The properties row of the search schema types its extra keys; the
    // boolean form keeps its exact previous meaning.
    const typed: SchemaNode = {
      type: "object",
      properties: { known: { type: "string" } },
      additionalProperties: { type: "array", items: { type: "string" } },
    };
    expect(
      validateAgainstSchema(typed, { known: "x", filter: ["a", "b"] }).ok,
      "unknown keys matching the schema pass",
    ).toBe(true);
    expect(validateAgainstSchema(typed, { known: "x", filter: "not-an-array" }).errors).toContain(
      "filter must be array",
    );
    const closed: SchemaNode = {
      type: "object",
      properties: { known: { type: "string" } },
      additionalProperties: false,
    };
    expect(validateAgainstSchema(closed, { known: "x", extra: 1 }).errors).toContain(
      "extra is not allowed",
    );
  });

  test("a $defs block is walked like any schema node, and its children are checked", () => {
    // The search-query artifact carries its query-document grammar as a
    // $defs sibling; an unsupported keyword hiding inside $defs must
    // still be refused.
    expect(() =>
      assertSupportedSchema({
        $defs: { doc: { type: "string", pattern: "^x$" } },
      }),
    ).toThrow('unsupported schema keyword "pattern"');
  });
});

describe("brain.intent_review.v1", () => {
  function signal(topic: string, sign: "positive" | "negative", index: number): void {
    writeSignal(vault, {
      topic,
      signal: sign,
      agent: index % 2 === 0 ? "claude" : "codex",
      principle: `${topic} ${sign} principle`,
      created_at: `2026-05-2${index}T10:00:00Z`,
      date: `2026-05-2${index}`,
      slug: `${topic}-${index}`,
    });
  }

  beforeEach(() => {
    signal("ready-topic", "positive", 1);
    signal("ready-topic", "positive", 2);
    signal("ready-topic", "positive", 3);
    signal("weak-topic", "negative", 1);
    signal("conflicted-topic", "positive", 1);
    signal("conflicted-topic", "negative", 2);
  });

  test("buildIntentReview output matches the published schema", () => {
    const report = buildIntentReview(vault, { now: new Date("2026-05-28T00:00:00Z") });
    // Guard against a vacuous pass on an empty review list.
    expect(new Set(report.reviews.map((r) => r.decision)).size).toBeGreaterThanOrEqual(3);
    expectValid(loadSchema("intent-review.schema.json"), report);
  });

  test("the brain_intent_review MCP payload matches the published schema", async () => {
    const out = await callTool("brain_intent_review", { now: "2026-05-28T00:00:00Z" });
    expect((out as { reviews: unknown[] }).reviews.length).toBe(3);
    expectValid(loadSchema("intent-review.schema.json"), out);
  });
});

describe("brain.retention_review.v1", () => {
  beforeEach(() => {
    writePreference(vault, {
      slug: "useful-rule",
      topic: "useful-rule",
      principle: "keep useful retired rules visible",
      created_at: "2026-05-01T00:00:00Z",
      unconfirmed_until: "2026-05-08T00:00:00Z",
      confirmed_at: "2026-05-08T00:00:00Z",
      status: "confirmed",
      evidenced_by: [],
      applied_count: 3,
      violated_count: 0,
      last_evidence_at: "2026-05-20T00:00:00Z",
    });
    moveToRetired(
      vault,
      preferencePath(vault, "useful-rule"),
      BRAIN_RETIRED_REASON.staleNoEvidence,
      {
        now: new Date("2026-05-21T00:00:00Z"),
        retired_by: "test",
        evidenceApplied: [],
        evidenceViolated: [],
      },
    );
    writeSignal(vault, {
      topic: "discarded-signal",
      signal: "negative",
      agent: "test",
      principle: "old one-off signal",
      created_at: "2026-04-01T00:00:00Z",
      date: "2026-04-01",
      slug: "discarded-signal",
    });
    renameSync(
      signalPath(vault, "2026-04-01", "discarded-signal"),
      processedSignalPath(vault, "2026-04-01", "discarded-signal"),
    );
  });

  test("buildRetentionReview output matches the published schema", () => {
    const report = buildRetentionReview(vault, { now: new Date("2026-05-28T00:00:00Z") });
    expect(report.recommendations.map((r) => r.artifact_type).toSorted()).toEqual([
      "processed_signal",
      "retired_preference",
    ]);
    expectValid(loadSchema("retention-review.schema.json"), report);
  });

  test("the brain_retention MCP payload matches the published schema", async () => {
    const out = await callTool("brain_retention", { now: "2026-05-28T00:00:00Z" });
    expect((out as { recommendations: unknown[] }).recommendations.length).toBeGreaterThan(0);
    expectValid(loadSchema("retention-review.schema.json"), out);
  });
});

describe("brain.monthly_review.v1", () => {
  beforeEach(() => {
    appendLogEvent(vault, {
      timestamp: "2026-05-10T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.dream,
      body: {
        confirmed: ["[[pref-use-tests|Use tests]]"],
        retired: ["[[ret-old-rule|Old rule]] (stale-no-evidence)"],
      },
    });
    appendLogEvent(vault, {
      timestamp: "2026-05-11T10:00:00Z",
      eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
      body: {
        preference: "[[pref-use-tests]]",
        artifact: "[[src/core/example.ts]]",
        result: BRAIN_APPLY_RESULT.violated,
      },
    });
  });

  test("buildMonthlyReview output matches the published schema", () => {
    const report = buildMonthlyReview(vault, {
      month: "2026-05",
      now: new Date("2026-06-01T00:00:00Z"),
      expectedAreas: ["writing"],
    });
    expect(report.summary.events).toBe(2);
    expect(report.summary.neglected_areas.length).toBeGreaterThan(0);
    expectValid(loadSchema("monthly-review.schema.json"), report);
  });

  test("the brain_brief view=monthly MCP payload matches the published schema", async () => {
    // brain_monthly_review was folded into brain_brief in 1.0.0; the
    // monthly view still returns this contract's shape.
    const out = await callTool("brain_brief", { view: "monthly", month: "2026-05" });
    expect((out as { summary: { events: number } }).summary.events).toBe(2);
    expectValid(loadSchema("monthly-review.schema.json"), out);
  });
});

describe("brain.complexity_report.v1", () => {
  test("buildComplexityReport over real changed paths matches the published schema", () => {
    mkdirSync(join(vault, "Templates", "deep", "nested"), { recursive: true });
    writeFileSync(join(vault, "Templates", "deep", "nested", "daily.md"), "#alpha #beta\n");
    mkdirSync(join(vault, ".obsidian"), { recursive: true });
    writeFileSync(join(vault, ".obsidian", "app.json"), "{}\n");
    const factors = complexityPathFactors([
      { root: vault, relativePath: "Templates/deep/nested/daily.md" },
      { root: vault, relativePath: ".obsidian/app.json" },
      { root: vault, relativePath: "Brain/_brain.yaml" },
    ]);

    const report = buildComplexityReport(
      { thinkingActivity: 3, structuralFilesChanged: 12, ...factors },
      { now: new Date("2026-05-28T00:00:00Z") },
    );
    // A non-integer ratio and a raised warning exercise the number and
    // boolean branches, not just the quiet-day zeros.
    expect(Number.isInteger(report.ratio)).toBe(false);
    expect(report.warning).toBe(true);
    expect(report.factors.length).toBe(5);
    expectValid(loadSchema("complexity-report.schema.json"), report);
  });

  test("a quiet day (no factors, no activity) still matches", () => {
    const report = buildComplexityReport(
      { thinkingActivity: 0, structuralFilesChanged: 0 },
      { now: new Date("2026-05-28T00:00:00Z") },
    );
    expect(report.factors).toEqual([]);
    expectValid(loadSchema("complexity-report.schema.json"), report);
  });
});

describe("brain.search_query.v1 (t_50c81d5c E4)", () => {
  test("the committed file equals what the descriptor derives - the generator check", () => {
    // JSON equality, not byte equality: the file is hand-formatted like
    // its siblings and the generator owns the content, not the layout.
    const onDisk: unknown = JSON.parse(
      readFileSync(join(SCHEMA_DIR, "search-query.schema.json"), "utf8"),
    );
    expect(onDisk).toEqual(asJson(buildSearchQueryArtifact()));
  });

  test("the artifact is the mcp projection plus the query-document grammar", () => {
    const artifact = loadSchema("search-query.schema.json");
    expect(artifact.$id).toBe("brain.search_query.v1");
    const served = SEARCH_INPUT_SCHEMA as unknown as Record<string, unknown>;
    const properties = artifact.properties as Record<string, SchemaNode>;
    // Every served brain_search argument is a property of the artifact,
    // spelled identically.
    for (const [name, fragment] of Object.entries(served.properties as Record<string, unknown>)) {
      expect(properties[name] as unknown).toEqual(fragment);
    }
    expect(Object.keys(properties).toSorted()).toEqual(
      Object.keys(served.properties as Record<string, unknown>).toSorted(),
    );
    expect(artifact.required).toEqual(["query"]);
    expect(artifact.additionalProperties).toBe(false);
    // The sibling grammar block declares its own versioned id.
    const docGrammar = (
      (artifact as unknown as Record<string, unknown>)["$defs"] as Record<string, SchemaNode>
    )["search_query_document"];
    expect(docGrammar).toBeDefined();
    expect(docGrammar!.$id).toBe("brain.search_query_document.v1");
  });

  test("a documented brain_search argument object validates against the artifact", () => {
    const artifact = loadSchema("search-query.schema.json");
    const args = {
      query: "project alpha",
      query_document: 'intent: entity\nlex: "project alpha" -archived\nvec: active context',
      kind: "section",
      since: "last week",
      limit: 10,
      disclosure: "cards",
      match_mode: "any",
    };
    expectValid(artifact, args);
    // And the drift the contract exists to catch is refused by name.
    const unknown = { ...args, definitely_not_an_argument: true };
    expect(validateAgainstSchema(artifact, unknown).errors).toContain(
      "definitely_not_an_argument is not allowed",
    );
    const badEnum = { ...args, disclosure: "essays" };
    expect(validateAgainstSchema(artifact, badEnum).errors[0]).toContain("disclosure");
  });
});