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
/**
* The config-declared write binding over caller-named write paths
* (provenance-at-the-boundary, unit B).
*
* Three properties are under test, and the third is the one that makes
* the other two mean anything:
*
* 1. ABSENT IS INERT. No `write_binding:` block - and a block that
* declares no `path_prefixes` - leaves every write path exactly as
* it was. Proved by running the three caller-named writes against a
* vault with no config at all and against a vault whose config
* omits the block, and comparing both against the PRE-FEATURE bytes
* in {@link GOLDEN_ABSENT_BINDING_BYTES}. The two runs are also
* compared to each other, but that comparison is the weaker of the
* two: both are the same inert path, so a change to the shared write
* envelope shows up in both and only the golden catches it.
* 2. DECLARED REFUSES OUTSIDE, ADMITS INSIDE, on all four caller-named
* surfaces (`createNote`, and the update / append / batch arms that
* share its envelope).
* 3. THE AUTHORITY IS THE CONFIG FILE, NOT THE CALLER'S CLAIM. This
* system has no credential: agent identity is an environment
* variable, else a config key, else the literal `agent`, and
* twenty-five MCP tool schemas accept a caller-supplied `agent`
* string that overrides it verbatim (the count is pinned as an
* equality by `tests/core/architecture/origin-channel-census.test.ts`). A fence keyed to that would be bypassed by
* passing a different string, so the binding never reads it - and
* that is asserted here by passing a different one and by moving
* the environment variable underneath the same call.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, test } from "bun:test";
import {
mkdirSync,
mkdtempSync,
readFileSync,
readdirSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
GovernedPathWriteRefusedError,
WRITE_BINDING_REFUSED_CODE,
checkWriteBinding,
governCallerNamedWritePath,
normaliseWriteBindingPrefix,
resolveWriteBinding,
writeBindingAdmits,
writeBindingPrefixCovers,
} from "../../src/core/write-binding/index.ts";
import { resolveNextStep } from "../../src/core/brain/next-step.ts";
import { CreateNoteError, createNote } from "../../src/core/brain/notes/create-note.ts";
import { WriteBatchError, applyWriteBatch } from "../../src/core/brain/write-batch.ts";
import { BrainConfigError } from "../../src/core/brain/policy.ts";
import { validateBrainConfig } from "../../src/core/brain/policy.ts";
import { parseBrainYaml } from "../../src/core/brain/yaml-parse.ts";
import { runCli } from "../helpers/run-cli.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
/** A caller-named note path that no declared prefix in these tests admits. */
const OUTSIDE_PATH = "Elsewhere/Note.md";
/** A caller-named note path under the prefix the tests declare. */
const INSIDE_PATH = "Projects/Note.md";
/** The single prefix the declared-binding fixtures use. */
const PREFIX = "Projects";
/**
* The exact bytes the three caller-named write arms left behind BEFORE
* this unit existed, captured by running the same sequence against the
* store as it stood at HEAD~ of the binding.
*
* Pinned as literals on purpose. Comparing one absent-binding run against
* another absent-binding run - which is what "no config file" versus "a
* config without the block" are, both of them the same inert path - can
* only show the two agree; a change to the shared write envelope every
* caller-named write funnels through moves BOTH arms identically and the
* comparison stays green. Only a fixed pre-feature reference can see it.
*
* It saw one, on purpose. `origin_channel` is the server-derived channel
* of the process that CREATED the note (Unit C of the
* nothing-writes-silently wave), stamped by `createNote` and by the batch
* `create_note` arm. `unset` is the explicit literal for "no entry point
* claimed this process" - a test harness is not one - and the suite
* preload unclaims before every test so it cannot depend on file order.
*
* Its POSITION in the `outside` note is the other half of the record: the
* stamp sits where creation put it, ahead of the `tag` a later
* `update_note` merged in. Update and append do not re-stamp, so this
* golden also pins that a mutation cannot overwrite the creating channel.
*/
const GOLDEN_ABSENT_BINDING_BYTES: Readonly<Record<string, string>> = Object.freeze({
/** `createNote`, then the batch `update_note` and `append_note` arms. */
outside: "---\ntitle: T\norigin_channel: unset\ntag: x\n---\n\nbody\n\nmore\n",
/** The batch `create_note` arm. */
inside: "---\norigin_channel: unset\n---\n\ninside\n",
});
const AGENT_ENV = "VAULT_AGENT_NAME";
let vault: string;
function writeBrainConfig(root: string, yaml: string): void {
mkdirSync(join(root, "Brain"), { recursive: true });
writeFileSync(join(root, "Brain", "_brain.yaml"), yaml, "utf8");
}
/** `_brain.yaml` declaring exactly one write-binding prefix. */
function declaredBindingYaml(...prefixes: ReadonlyArray<string>): string {
return `schema_version: 1\nwrite_binding:\n path_prefixes:\n${prefixes
.map((p) => ` - ${p}\n`)
.join("")}`;
}
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-write-binding-"));
});
afterEach(() => rmSync(vault, { recursive: true, force: true }));
describe("the binding is absent unless the operator declares it", () => {
test("a vault with no Brain config has no binding", () => {
expect(resolveWriteBinding(vault)).toBeNull();
expect(checkWriteBinding(vault, OUTSIDE_PATH)).toBeNull();
});
test("a config without the block has no binding", () => {
writeBrainConfig(vault, "schema_version: 1\n");
expect(resolveWriteBinding(vault)).toBeNull();
expect(checkWriteBinding(vault, OUTSIDE_PATH)).toBeNull();
});
test("a block that declares no path_prefixes has no binding", () => {
// Present-but-empty BLOCK is not a declaration of anything: the key
// the binding is made of is absent, exactly as `vault:` treats a
// missing `ignore_paths`.
writeBrainConfig(vault, "schema_version: 1\nwrite_binding:\n other_key: 1\n");
expect(resolveWriteBinding(vault)).toBeNull();
expect(checkWriteBinding(vault, OUTSIDE_PATH)).toBeNull();
});
test("an empty prefix list is refused at load rather than silently admitting nothing", () => {
// A list that admits no path is an off switch wearing a binding's
// clothes; the operator turns the binding off by removing the block.
expect(() =>
validateBrainConfig(
parseBrainYaml("schema_version: 1\nwrite_binding:\n path_prefixes: []\n"),
"<test>",
),
).toThrow(BrainConfigError);
});
});
describe("absent binding is byte-identical on every caller-named write path", () => {
/** Run the three caller-named write arms and return what landed. */
function runAllWritePaths(root: string): Record<string, string> {
createNote(root, { path: OUTSIDE_PATH, frontmatter: { title: "T" }, content: "body" });
applyWriteBatch(root, [
{ kind: "update_note", path: OUTSIDE_PATH, frontmatter: { tag: "x" } },
{ kind: "create_note", path: INSIDE_PATH, content: "inside" },
]);
applyWriteBatch(root, [{ kind: "append_note", path: OUTSIDE_PATH, content: "more" }]);
return {
outside: readFileSync(join(root, OUTSIDE_PATH), "utf8"),
inside: readFileSync(join(root, INSIDE_PATH), "utf8"),
};
}
test("a vault with no config at all writes the pre-feature bytes", () => {
expect(runAllWritePaths(vault)).toEqual({ ...GOLDEN_ABSENT_BINDING_BYTES });
});
test("a config without the block writes the same pre-feature bytes", () => {
const withConfig = mkdtempSync(join(tmpdir(), "o2b-write-binding-cfg-"));
try {
writeBrainConfig(withConfig, "schema_version: 1\n");
const written = runAllWritePaths(withConfig);
expect(written).toEqual({ ...GOLDEN_ABSENT_BINDING_BYTES });
// And the two inert arms still agree with each other, which is the
// property the golden alone does not state.
expect(written).toEqual(runAllWritePaths(vault));
} finally {
rmSync(withConfig, { recursive: true, force: true });
}
});
});
describe("a declared binding is rooted and segment-wise", () => {
test("the prefix admits itself and its descendants", () => {
const binding = { pathPrefixes: [PREFIX] };
expect(writeBindingAdmits(binding, "Projects")).toBe(true);
expect(writeBindingAdmits(binding, "Projects/Note.md")).toBe(true);
expect(writeBindingAdmits(binding, "Projects/deep/nested/Note.md")).toBe(true);
});
test("a longer sibling name is not a descendant", () => {
// Character-prefix matching would admit `ProjectsArchive/`; segment
// matching is what makes the declaration mean the folder.
expect(writeBindingAdmits({ pathPrefixes: [PREFIX] }, "ProjectsArchive/Note.md")).toBe(false);
});
test("a path under no declared prefix is refused", () => {
expect(writeBindingAdmits({ pathPrefixes: [PREFIX] }, OUTSIDE_PATH)).toBe(false);
});
test("any one of several prefixes admits", () => {
const binding = { pathPrefixes: ["Projects", "Journal/Weekly"] };
expect(writeBindingAdmits(binding, "Journal/Weekly/W1.md")).toBe(true);
expect(writeBindingAdmits(binding, "Journal/Daily/D1.md")).toBe(false);
});
});
describe("a declared binding refuses caller-named writes outside it", () => {
beforeEach(() => writeBrainConfig(vault, declaredBindingYaml(PREFIX)));
test("createNote refuses outside and admits inside", () => {
expect(() => createNote(vault, { path: OUTSIDE_PATH, content: "x" })).toThrow(CreateNoteError);
const res = createNote(vault, { path: INSIDE_PATH, content: "x" });
expect(res.created).toBe(true);
});
test("the refusal carries the registered code and names the declared prefixes", () => {
let caught: CreateNoteError | null = null;
try {
createNote(vault, { path: OUTSIDE_PATH, content: "x" });
} catch (err) {
caught = err as CreateNoteError;
}
expect(caught).not.toBeNull();
expect(caught!.code).toBe("write_binding");
expect(caught!.message).toContain(PREFIX);
expect(caught!.message).toContain(OUTSIDE_PATH);
});
test("the refusal names the exit its registered code resolves to", () => {
const step = resolveNextStep(WRITE_BINDING_REFUSED_CODE);
expect(step).not.toBeNull();
const refusal = checkWriteBinding(vault, OUTSIDE_PATH);
expect(refusal).not.toBeNull();
expect(refusal!.code).toBe(WRITE_BINDING_REFUSED_CODE);
expect(refusal!.nextCommand).toBe(step!.nextCommand);
expect(refusal!.message).toContain(step!.nextCommand);
});
test("the batch update and append arms are refused before any write", () => {
createNote(vault, { path: INSIDE_PATH, content: "x" });
// Seed a target outside the binding by hand, so the refusal cannot be
// mistaken for a missing-target error.
mkdirSync(join(vault, "Elsewhere"), { recursive: true });
writeFileSync(join(vault, OUTSIDE_PATH), "---\n---\n\nseed\n", "utf8");
for (const op of [
{ kind: "update_note", path: OUTSIDE_PATH, body: "replaced" },
{ kind: "append_note", path: OUTSIDE_PATH, content: "appended" },
{ kind: "create_note", path: "Elsewhere/Fresh.md", content: "x" },
] as const) {
let caught: WriteBatchError | null = null;
try {
applyWriteBatch(vault, [op]);
} catch (err) {
caught = err as WriteBatchError;
}
expect(caught).not.toBeNull();
expect(caught!.code).toBe("write_binding");
}
// Nothing landed: the seeded file is untouched and no new file exists.
expect(readFileSync(join(vault, OUTSIDE_PATH), "utf8")).toBe("---\n---\n\nseed\n");
});
test("a batch aborts entirely when one operation lands outside the binding", () => {
expect(() =>
applyWriteBatch(vault, [
{ kind: "create_note", path: INSIDE_PATH, content: "inside" },
{ kind: "create_note", path: OUTSIDE_PATH, content: "outside" },
]),
).toThrow(WriteBatchError);
// Validate-all-then-commit: the admitted operation must not have run.
expect(() => readFileSync(join(vault, INSIDE_PATH), "utf8")).toThrow();
});
});
describe("the caller's claimed identity cannot widen the binding", () => {
beforeEach(() => writeBrainConfig(vault, declaredBindingYaml(PREFIX)));
test("a caller-supplied agent string on the same batch does not widen it", () => {
// `brain_write_batch` accepts a caller-supplied `agent` on its
// evidence and log-line operations, and it is taken verbatim. The
// binding never reads it, so an operation outside the binding is
// refused with the same code whichever name rides along.
const codes = ["agent", "someone-else", ""].map((agent) => {
try {
applyWriteBatch(vault, [
{ kind: "append_log_line", input: { text: "note", agent } },
{ kind: "create_note", path: OUTSIDE_PATH, content: "x" },
]);
return "not-refused";
} catch (err) {
return (err as WriteBatchError).code;
}
});
expect(codes).toEqual(["write_binding", "write_binding", "write_binding"]);
});
test("moving the identity environment variable does not widen it", () => {
const before = process.env[AGENT_ENV];
try {
for (const name of ["agent", "operator", "root"]) {
process.env[AGENT_ENV] = name;
const refusal = checkWriteBinding(vault, OUTSIDE_PATH);
expect(refusal?.code).toBe(WRITE_BINDING_REFUSED_CODE);
}
} finally {
if (before === undefined) delete process.env[AGENT_ENV];
else process.env[AGENT_ENV] = before;
}
});
});
describe("the registered exit answers the question the refusal raises", () => {
// The rail forbids inventing a command, and a command that does not
// report the binding would be an invented one in all but name. So the
// exit this code resolves to is driven here, end to end, against a
// path the binding refuses.
test("`o2b vault inspect` reports the binding verdict and the declared prefixes", async () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
const configPath = join(vault, "cli-config.yaml");
const run = await runCli(["vault", "inspect", OUTSIDE_PATH, "--vault", vault, "--json"], {
env: { OPEN_SECOND_BRAIN_CONFIG: configPath },
});
expect(run.returncode).toBe(0);
const payload = JSON.parse(run.stdout) as {
write_binding: { declared: boolean; admits: boolean; path_prefixes: string[] };
};
expect(payload.write_binding).toEqual({
declared: true,
admits: false,
path_prefixes: [PREFIX],
});
});
test("an undeclared binding reads as undeclared, not as admitted", () => {
// The third state. Reporting `admits: true` for a vault that never
// declared a binding would tell an operator a boundary is holding
// when none exists.
expect(resolveWriteBinding(vault)).toBeNull();
});
});
describe("prefix declarations are validated at load", () => {
for (const [label, raw] of [
["a leading slash", "/Projects"],
["a traversal segment", "Projects/../etc"],
["an empty entry", '""'],
] as const) {
test(`${label} is refused`, () => {
expect(() =>
validateBrainConfig(
parseBrainYaml(`schema_version: 1\nwrite_binding:\n path_prefixes:\n - ${raw}\n`),
"<test>",
),
).toThrow(BrainConfigError);
});
}
test("a declared prefix normalises to its POSIX vault-relative form", () => {
writeBrainConfig(vault, declaredBindingYaml("./Projects/"));
expect(resolveWriteBinding(vault)?.pathPrefixes).toEqual(["Projects"]);
});
});
describe("the binding is checked against where the bytes land, not the name given", () => {
// Defect 1 of the v1.43.0 security review. `checkWriteBinding` used to
// compare the LEXICAL relative path, so one symlink under a declared
// prefix turned the binding into "may write anywhere in the vault" and
// the success payload named a path that did not hold the bytes.
const LINK_PATH = "Projects/link/escaped.md";
/** `<vault>/Projects/link` -> `<vault>/Journal`, both inside the vault. */
function linkProjectsToJournal(root: string): void {
mkdirSync(join(root, "Projects"), { recursive: true });
mkdirSync(join(root, "Journal"), { recursive: true });
symlinkSync(join(root, "Journal"), join(root, "Projects", "link"));
}
test("a symlinked directory under a declared prefix does not widen it", () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
linkProjectsToJournal(vault);
let caught: CreateNoteError | null = null;
try {
createNote(vault, { path: LINK_PATH, content: "x" });
} catch (err) {
caught = err as CreateNoteError;
}
expect(caught?.code).toBe("write_binding");
expect(readdirSync(join(vault, "Journal"))).toEqual([]);
});
test("the refusal names the destination the bytes would have reached", () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
linkProjectsToJournal(vault);
const refusal = checkWriteBinding(vault, LINK_PATH);
expect(refusal).not.toBeNull();
expect(refusal!.resolvedRelPath).toBe("Journal/escaped.md");
expect(refusal!.message).toContain("Journal/escaped.md");
expect(refusal!.message).toContain(LINK_PATH);
});
test("a symlink that stays inside the declared prefix is still admitted", () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
mkdirSync(join(vault, "Projects", "real"), { recursive: true });
symlinkSync(join(vault, "Projects", "real"), join(vault, "Projects", "alias"));
expect(checkWriteBinding(vault, "Projects/alias/Note.md")).toBeNull();
});
test("with no binding declared the same symlink write is untouched", () => {
// Absent stays byte-identical: the realpath comparison is reached
// only once a binding exists, so an unbound vault behaves exactly as
// it did before the key existed.
linkProjectsToJournal(vault);
const res = createNote(vault, { path: LINK_PATH, content: "x" });
expect(res.path).toBe(LINK_PATH);
expect(readdirSync(join(vault, "Journal"))).toEqual(["escaped.md"]);
});
});
describe("a destination that cannot be resolved is refused, not raised", () => {
test("checkWriteBinding refuses a note used as a folder", () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
mkdirSync(join(vault, "Projects"), { recursive: true });
writeFileSync(join(vault, "Projects", "existing.md"), "x\n");
const refusal = checkWriteBinding(vault, "Projects/existing.md/x.md");
expect(refusal).not.toBeNull();
expect(refusal!.code).toBe(WRITE_BINDING_REFUSED_CODE);
expect(refusal!.message).toContain("cannot be resolved");
});
test("checkWriteBinding refuses a symlink loop", () => {
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
mkdirSync(join(vault, "Projects"), { recursive: true });
symlinkSync(join(vault, "Projects", "b"), join(vault, "Projects", "a"));
symlinkSync(join(vault, "Projects", "a"), join(vault, "Projects", "b"));
const refusal = checkWriteBinding(vault, "Projects/a/x.md");
expect(refusal?.message).toContain("cannot be resolved");
});
test("governCallerNamedWritePath refuses with its typed error", () => {
writeFileSync(join(vault, "existing.md"), "x\n");
expect(() => governCallerNamedWritePath(vault, "existing.md/x.md", "test surface")).toThrow(
GovernedPathWriteRefusedError,
);
});
});
describe("a backslash is a filename character on POSIX, not a separator", () => {
// Defect 2 of the v1.43.0 security review. The matcher split on
// `[\\/]`, so a binding on `Projects` admitted `Projects\evil.md` -
// which on Linux is one filename that lands at the VAULT ROOT.
test("the matcher does not read a backslash as a segment boundary", () => {
expect(writeBindingPrefixCovers(PREFIX, "Projects\\evil.md")).toBe(false);
expect(writeBindingPrefixCovers(PREFIX, "Projects/evil.md")).toBe(true);
});
test("a declared prefix keeps its POSIX segments", () => {
expect(normaliseWriteBindingPrefix("./Projects//Sub/")).toBe("Projects/Sub");
});
});
describe("a config that does not load is a typed refusal, not a server fault", () => {
// Defect 3 of the v1.43.0 security review. A `_brain.yaml` that fails
// validation made every caller-named write throw a raw BrainConfigError
// carrying an ABSOLUTE host path, with no registered next step.
const MALFORMED = "schema_version: 99\n";
test("createNote refuses with a typed code, a vault-relative source, and a registered exit", () => {
writeBrainConfig(vault, MALFORMED);
let caught: CreateNoteError | null = null;
try {
createNote(vault, { path: INSIDE_PATH, content: "x" });
} catch (err) {
caught = err as CreateNoteError;
}
expect(caught).toBeInstanceOf(CreateNoteError);
expect(caught!.code).toBe("config_invalid");
expect(caught!.message).toContain("Brain/_brain.yaml");
expect(caught!.message).not.toContain(vault);
const step = resolveNextStep("config-invalid");
expect(step).not.toBeNull();
expect(caught!.message).toContain(step!.nextCommand);
});
test("the batch arms carry the same typed code", () => {
writeBrainConfig(vault, MALFORMED);
let caught: WriteBatchError | null = null;
try {
applyWriteBatch(vault, [{ kind: "create_note", path: INSIDE_PATH, content: "x" }]);
} catch (err) {
caught = err as WriteBatchError;
}
expect(caught).toBeInstanceOf(WriteBatchError);
expect(caught!.code).toBe("config_invalid");
expect(caught!.message).not.toContain(vault);
});
});
describe("a re-declared binding takes effect on the next call", () => {
test("rewriting the prefix list changes what is admitted", () => {
// Guards the per-vault memo that keeps a batch from re-reading and
// re-validating the whole config once per operation: the cached
// answer must never outlive the file it was read from.
writeBrainConfig(vault, declaredBindingYaml(PREFIX));
expect(checkWriteBinding(vault, INSIDE_PATH)).toBeNull();
expect(checkWriteBinding(vault, OUTSIDE_PATH)).not.toBeNull();
writeBrainConfig(vault, declaredBindingYaml("Elsewhere"));
expect(checkWriteBinding(vault, OUTSIDE_PATH)).toBeNull();
expect(checkWriteBinding(vault, INSIDE_PATH)).not.toBeNull();
});
});