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
8.7 KB
Raw Blame
/**
 * Operator standing rules (silence-is-not-an-answer, U8).
 *
 * The one lane of the session preamble the operator authors. Three
 * properties are load-bearing and each has a case here:
 *
 *   - ABSENCE IS NULL, FAILURE IS A THROW. A file that is not there and
 *     a file the process cannot read are different answers. The second
 *     one may never quietly become the first, because a constitution
 *     that vanishes without a word is worse than one that is missing.
 *   - OPACITY. The reader performs exactly three operations on the
 *     operator's bytes: read, trim, and line-boundary trimming at a
 *     character cap. A non-Latin body must round-trip byte-identically
 *     and count identically to a Latin body of the same length - the
 *     guard against any future word list, heading split, or classifier
 *     creeping into the reader.
 *   - LOUD TRUNCATION. A capped block says how much it kept, out of how
 *     much, in lines and characters, and where the whole text lives.
 */

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

import { brainStandingRulesPath } from "../../../src/core/brain/paths.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import {
  STANDING_RULES_HEADER,
  STANDING_RULES_MAX_CHARS_DEFAULT,
  STANDING_RULES_MAX_CHARS_MAX,
  STANDING_RULES_MAX_CHARS_MIN,
  readStandingRules,
  renderStandingRules,
  renderStandingRulesFailure,
} from "../../../src/core/brain/standing-rules.ts";

let vault: string;

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

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

function writeRules(body: string): string {
  const path = brainStandingRulesPath(vault);
  writeFileSync(path, body, "utf8");
  return path;
}

/** `n` lines of `char` repeated `width` times: a body of known char/line counts. */
function bodyOf(char: string, lines: number, width: number): string {
  return Array.from({ length: lines }, () => char.repeat(width)).join("\n");
}

describe("readStandingRules: absence and emptiness are null", () => {
  test("absent file returns null", () => {
    expect(readStandingRules(vault)).toBeNull();
  });

  test("whitespace-only file returns null", () => {
    writeRules("   \n\n\t\n  ");
    expect(readStandingRules(vault)).toBeNull();
  });
});

describe("readStandingRules: a present file", () => {
  const BODY = "Never force-push.\nAsk before deleting anything under Archive/.";

  test("carries the operator text verbatim and reports no truncation", () => {
    const path = writeRules(`\n${BODY}\n\n`);
    const rules = readStandingRules(vault);
    expect(rules).not.toBeNull();
    expect(rules!.path).toBe(path);
    expect(rules!.text).toBe(BODY);
    expect(rules!.truncated).toBe(false);
    expect(rules!.totalLines).toBe(2);
    expect(rules!.keptLines).toBe(2);
    expect(rules!.totalChars).toBe(BODY.length);
    expect(rules!.keptChars).toBe(BODY.length);
  });

  test("renders the header first, then the operator text unchanged", () => {
    writeRules(BODY);
    const block = renderStandingRules(readStandingRules(vault)!);
    expect(block.startsWith(STANDING_RULES_HEADER)).toBe(true);
    expect(block).toContain(BODY);
    // Nothing rides along when the body fits: the block is exactly the
    // header, the separator and the operator's own bytes.
    expect(block).toBe(`${STANDING_RULES_HEADER}\n\n${BODY}`);
  });
});

describe("readStandingRules: operator bytes are opaque", () => {
  // Equal LINE and CHARACTER counts, different scripts. Any reader that
  // inspected words, split on headings, or classified content would make
  // these two diverge; the counts and the round-trip say it does not.
  const LINES = 6;
  const WIDTH = 20;
  const LATIN = bodyOf("a", LINES, WIDTH);
  const NON_LATIN = bodyOf("Ñ„", LINES, WIDTH);
  const IDEOGRAPHIC = bodyOf("æ–¹", LINES, WIDTH);

  test("a non-Latin body round-trips byte-identically", () => {
    writeRules(NON_LATIN);
    expect(readStandingRules(vault)!.text).toBe(NON_LATIN);
  });

  test("scripts of equal length produce identical counts", () => {
    const counts = (body: string): Record<string, unknown> => {
      writeRules(body);
      const { text: _text, path: _path, ...rest } = readStandingRules(vault)!;
      return rest;
    };
    const latin = counts(LATIN);
    expect(counts(NON_LATIN)).toEqual(latin);
    expect(counts(IDEOGRAPHIC)).toEqual(latin);
  });

  test("a capped non-Latin body is cut identically to a Latin one", () => {
    const cap = STANDING_RULES_MAX_CHARS_MIN;
    const wide = (char: string): string => bodyOf(char, 200, WIDTH);
    writeRules(wide("a"));
    const latin = readStandingRules(vault, { maxChars: cap })!;
    writeRules(wide("Ñ„"));
    const nonLatin = readStandingRules(vault, { maxChars: cap })!;
    expect(nonLatin.keptLines).toBe(latin.keptLines);
    expect(nonLatin.keptChars).toBe(latin.keptChars);
    expect(nonLatin.text).toBe(bodyOf("Ñ„", latin.keptLines, WIDTH));
  });
});

describe("readStandingRules: capping is loud and cut on a line boundary", () => {
  const LINES = 400;
  const WIDTH = 30;

  test("an over-cap body is cut at a line boundary", () => {
    writeRules(bodyOf("r", LINES, WIDTH));
    const rules = readStandingRules(vault, { maxChars: STANDING_RULES_MAX_CHARS_MIN })!;
    expect(rules.truncated).toBe(true);
    expect(rules.totalLines).toBe(LINES);
    expect(rules.keptLines).toBeLessThan(LINES);
    expect(rules.keptChars).toBeLessThanOrEqual(STANDING_RULES_MAX_CHARS_MIN);
    // Every kept line is a whole line of the original.
    for (const line of rules.text.split("\n")) expect(line).toBe("r".repeat(WIDTH));
  });

  test("the notice names kept and total lines, kept and total characters, and the path", () => {
    const path = writeRules(bodyOf("r", LINES, WIDTH));
    const rules = readStandingRules(vault, { maxChars: STANDING_RULES_MAX_CHARS_MIN })!;
    const block = renderStandingRules(rules);
    const notice = block.slice(block.indexOf(rules.text) + rules.text.length);
    for (const n of [rules.keptLines, rules.totalLines, rules.keptChars, rules.totalChars]) {
      expect(notice).toContain(String(n));
    }
    expect(notice).toContain(path);
    // The operator's own bytes still lead the block, header aside.
    expect(block.startsWith(`${STANDING_RULES_HEADER}\n\n${rules.text}`)).toBe(true);
  });

  test("the default cap applies when the caller names none", () => {
    writeRules(bodyOf("r", LINES, WIDTH));
    const rules = readStandingRules(vault)!;
    expect(rules.keptChars).toBeLessThanOrEqual(STANDING_RULES_MAX_CHARS_DEFAULT);
  });

  test("a cap above the body length keeps everything", () => {
    const body = bodyOf("r", LINES, WIDTH);
    writeRules(body);
    const rules = readStandingRules(vault, { maxChars: STANDING_RULES_MAX_CHARS_MAX })!;
    expect(rules.truncated).toBe(false);
    expect(rules.text).toBe(body);
  });
});

describe("readStandingRules: an unreadable file throws rather than returning null", () => {
  // A mode change cannot make a file unreadable to uid 0, nor on Windows.
  test.skipIf(CHMOD_CANNOT_DENY)("the throw names the path and the reason", () => {
    const path = writeRules("Never force-push.\n");
    chmodSync(path, 0o000);
    try {
      let thrown: unknown;
      try {
        readStandingRules(vault);
      } catch (err) {
        thrown = err;
      }
      // Stated as two separate claims: it threw, AND what it did not do
      // was return the same null an absent file returns.
      expect(thrown).toBeInstanceOf(Error);
      expect((thrown as Error).message).toContain(path);
      expect((thrown as Error).message.toLowerCase()).toContain("permission denied");
    } finally {
      chmodSync(path, 0o600);
    }
  });

  test("a directory at the rules path is a failure, not an absence", () => {
    mkdirSync(brainStandingRulesPath(vault));
    expect(() => readStandingRules(vault)).toThrow(brainStandingRulesPath(vault));
  });
});

describe("renderStandingRulesFailure", () => {
  test("names the path, the reason, and that no rules are in force", () => {
    const path = brainStandingRulesPath(vault);
    const block = renderStandingRulesFailure(path, new Error("EACCES: permission denied"));
    expect(block).toContain(path);
    expect(block).toContain("EACCES: permission denied");
    expect(block.toLowerCase()).toContain("unavailable");
    expect(block.toLowerCase()).toContain("no standing rules are in force");
  });

  test("a non-Error reason is still reported", () => {
    const block = renderStandingRulesFailure("/v/Brain/standing-rules.md", "disk went away");
    expect(block).toContain("disk went away");
  });
});