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
5.8 KB
Raw Blame
/**
 * Write-session artifact validation and target policy
 * (Agent Write Contract Suite, t_bc36a8a2).
 */

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

import {
  buildCorrectionPrompt,
  inspectExistingTarget,
  validateArtifact,
  validateTargetPath,
} from "../../../../src/core/brain/write-session/validate.ts";
import { resolveSchemaVocabulary } from "../../../../src/core/brain/schema-vocab.ts";

let tmp: string;
let vault: string;

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-ws-validate-"));
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
});

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

const GOOD = ["---", "kind: note", "type: note", "---", "", "# Fixture", "", "Body."].join("\n");

// ----- target policy --------------------------------------------------------

test("target must be a vault-relative markdown path under Brain/", () => {
  expect(validateTargetPath("Brain/notes/x.md")).toEqual([]);
  expect(validateTargetPath("Brain/decisions/panels/p.md")).toEqual([]);

  expect(validateTargetPath("notes/x.md")[0]!.code).toBe("target-outside-brain");
  expect(validateTargetPath("/etc/passwd")[0]!.code).toBe("target-outside-brain");
  expect(validateTargetPath("Brain/../escape.md")[0]!.code).toBe("target-traversal");
  expect(validateTargetPath("Brain/notes/..\\win.md")[0]!.code).toBe("target-traversal");
  expect(validateTargetPath("Brain/notes/x.txt")[0]!.code).toBe("target-extension");
  expect(validateTargetPath("")[0]!.code).toBe("target-outside-brain");
});

test("reserved namespaces are denied with coded errors", () => {
  for (const target of [
    "Brain/preferences/pref-x.md",
    "Brain/log/2026-06-04.md",
    "Brain/.sessions/write/ws-1.md",
    "Brain/.payloads/abc.md",
    "Brain/_brain.yaml",
  ]) {
    const errors = validateTargetPath(target);
    expect(errors.length).toBeGreaterThan(0);
    expect(errors.map((e) => e.code)).toContain(
      target === "Brain/_brain.yaml" ? "target-reserved" : "target-reserved",
    );
  }
});

test("only the write-session lanes are writable under Brain/, however the path is spelled", () => {
  for (const target of [
    "Brain/sources/s.md",
    "Brain/reports/r.md",
    "Brain/distillations/d.md",
    "Brain/notes/deep/n.md",
    "Brain/decisions/panels/p.md",
  ]) {
    expect(validateTargetPath(target)).toEqual([]);
  }
  for (const target of [
    "Brain/standing-rules.md",
    "Brain/active.md",
    "Brain/pinned.md",
    "Brain/Preferences/x.md",
    "Brain/PREFERENCES/x.md",
    "Brain/log./x.md",
    "Brain/Log/2026-06-04.md",
    "Brain/inbox/sig-x.md",
    "Brain/retired/x.md",
    "Brain/decisions/d.md",
  ]) {
    expect(validateTargetPath(target).map((e) => e.code)).toEqual(["target-reserved"]);
  }
});

// ----- artifact validation --------------------------------------------------

test("a well-formed artifact with declared schema type validates cleanly", () => {
  const vocab = resolveSchemaVocabulary({ page_types: ["decision"] });
  const artifact = GOOD.replace("type: note", "type: decision");
  expect(validateArtifact(artifact, { schemaType: "decision", vocabulary: vocab })).toEqual([]);
});

test("empty and oversized artifacts are rejected", () => {
  expect(validateArtifact("", {})[0]!.code).toBe("artifact-empty");
  expect(validateArtifact("   \n  ", {})[0]!.code).toBe("artifact-empty");
  const big = `${GOOD}\n${"x".repeat(300_000)}`;
  expect(validateArtifact(big, {}).map((e) => e.code)).toContain("artifact-too-large");
});

test("missing or malformed frontmatter is a coded error", () => {
  expect(validateArtifact("# No frontmatter\n\nBody.", {})[0]!.code).toBe("frontmatter-missing");
  const codes = validateArtifact("---\nkind note\n---\n\nBody.", {}).map((e) => e.code);
  expect(codes.some((c) => c === "frontmatter-missing" || c === "frontmatter-malformed")).toBe(
    true,
  );
});

test("declared schema type must be known and must match the artifact", () => {
  const vocab = resolveSchemaVocabulary({ page_types: ["decision"] });
  const unknown = validateArtifact(GOOD, { schemaType: "bogus", vocabulary: vocab });
  expect(unknown.map((e) => e.code)).toContain("schema-type-unknown");

  const mismatch = validateArtifact(GOOD, { schemaType: "decision", vocabulary: vocab });
  expect(mismatch.map((e) => e.code)).toContain("schema-type-mismatch");
});

test("control characters in the body are rejected", () => {
  const sneaky = `${GOOD}\nbad: \u0000byte`;
  expect(validateArtifact(sneaky, {}).map((e) => e.code)).toContain("artifact-control-chars");
});

// ----- correction prompt ----------------------------------------------------

test("correction prompt is compact and lists every error", () => {
  const prompt = buildCorrectionPrompt([
    { code: "frontmatter-missing", path: "frontmatter", message: "artifact has no frontmatter" },
    { code: "schema-type-mismatch", path: "type", message: "expected 'decision'" },
  ]);
  expect(prompt).toContain("frontmatter-missing");
  expect(prompt).toContain("expected 'decision'");
  expect(prompt).toContain("full corrected artifact");
  expect(prompt.length).toBeLessThan(1000);
});

// ----- existing-target inspection -------------------------------------------

test("inspectExistingTarget returns null for a free path and metadata for an occupied one", () => {
  expect(inspectExistingTarget(vault, "Brain/notes/free.md")).toBeNull();
  mkdirSync(join(vault, "Brain", "notes"), { recursive: true });
  writeFileSync(join(vault, "Brain", "notes", "busy.md"), "---\nkind: note\n---\n\n# Busy note\n");
  const info = inspectExistingTarget(vault, "Brain/notes/busy.md");
  expect(info!.bytes).toBeGreaterThan(0);
  expect(info!.content_hash).toMatch(/^[0-9a-f]{64}$/);
  expect(info!.first_heading).toBe("Busy note");
});