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
/**
* Ownership is WRITTEN, or it is not a boundary.
*
* `integrity.owner_scope_delivery` withholds a preference whose
* `owner:` frontmatter names another agent, and every read-side surface
* honours it. Nothing wrote the field. Every production writer omitted
* `owner`, so `pageOwner` returned `null` for every page ever produced
* by this product, `isOwnerVisible` was trivially true, and the gate
* filtered a population that could not exist. A predicate over an empty
* set is a label, not a boundary.
*
* This file is the enforcement: with the gate switched on, a preference
* created through any production writer carries the server-resolved
* agent identity as its owner; with the gate off, not one byte moves.
*
* Two properties are load-bearing and asserted separately:
*
* - ownership is stamped at CREATION only. A rewrite carries the
* existing owner forward and never re-owns, so a dream pass run by
* one agent cannot quietly transfer another agent's memories, and a
* page created before the gate was switched on stays shared.
* - the identity is SERVER-resolved. No test in this file passes an
* `owner` argument to reach the withholding assertion; the vault is
* written entirely through shipped surfaces.
*/
import { afterEach, beforeEach, expect, setDefaultTimeout, test } from "bun:test";
import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { JSONRPC_VERSION, MCPServer, PROTOCOL_VERSION } from "../../../src/mcp/index.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { deriveFact } from "../../../src/core/brain/derived-fact.ts";
import { mergePreferences } from "../../../src/core/brain/merge.ts";
import { brainConfigPath, brainDirs, preferencePath } from "../../../src/core/brain/paths.ts";
import { brainConfigKnownKeys } from "../../../src/core/brain/policy.ts";
import { parsePreference, writePreference } from "../../../src/core/brain/preference.ts";
import { queryDecisionLedger } from "../../../src/core/brain/permissions/ledger.ts";
import { PLACEHOLDER_AGENT_VALUES } from "../../../src/core/agent-identity.ts";
import { ownerStampFor } from "../../../src/core/graph/agent-scope.ts";
import { writePreferenceTxn } from "../../../src/core/brain/preference-txn.ts";
import {
collectPreferences,
type OwnerScopeDelivery,
} from "../../../src/core/brain/preferences-collect.ts";
import { resetVaultIdentityPins } from "../../../src/core/brain/vault-identity.ts";
import { BRAIN_PREFERENCE_STATUS } from "../../../src/core/brain/types.ts";
import { GATE_MODE } from "../../../src/core/integrity/stamp.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";
import { changedPaths, treeEntries, digestVaultTree } from "../../helpers/vault-digest.ts";
import { runCli } from "../../helpers/run-cli.ts";
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
/** Wall clock every core writer in this file is pinned to. */
const NOW = new Date("2026-05-10T00:00:00Z");
/** The identity the ambient config resolves to, i.e. what a writer stamps. */
const SELF = "agent-self";
/** A second identity, used to prove the withholding is not vacuous. */
const OTHER = "agent-other";
/**
* Env this file owns. `HOME` is pinned per test file by convention
* (nothing pins it globally) and the identity vars are cleared so the
* developer's own install cannot decide what a writer stamps.
*/
const OWNED_ENV = [
"HOME",
"VAULT_AGENT_NAME",
"VAULT_DIR",
"VAULT_TIMEZONE",
"OPEN_SECOND_BRAIN_CONFIG",
] as const;
let tmp: string;
let home: string;
const savedEnv: Record<string, string | undefined> = {};
beforeEach(() => {
tmp = mkdtempSync(join(tmpdir(), "o2b-owner-stamp-"));
home = join(tmp, "home");
mkdirSync(home, { recursive: true });
for (const key of OWNED_ENV) {
savedEnv[key] = process.env[key];
delete process.env[key];
}
process.env["HOME"] = home;
resetVaultIdentityPins();
});
afterEach(() => {
resetVaultIdentityPins();
rmSync(tmp, { recursive: true, force: true });
for (const [key, value] of Object.entries(savedEnv)) {
if (value === undefined) delete process.env[key];
else process.env[key] = value;
}
});
/** A bare vault: Brain directories and a `_brain.yaml`, nothing else. */
function makeVault(name: string, gate: string | null, agent = SELF, writesGate?: string): string {
const vault = join(tmp, name);
for (const sub of ["preferences", "retired", "inbox", "log"]) {
mkdirSync(join(vault, "Brain", sub), { recursive: true });
}
const integrityLines =
(gate === null ? "" : ` owner_scope_delivery: ${gate}\n`) +
(writesGate === undefined ? "" : ` owner_scope_writes: ${writesGate}\n`);
atomicWriteFileSync(
brainConfigPath(vault),
`schema_version: 1\n${integrityLines === "" ? "" : `integrity:\n${integrityLines}`}`,
);
const configPath = join(tmp, `${name}-config.yaml`);
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: ${agent}\n`);
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
return vault;
}
/** The `owner:` a preference file carries on disk, or `null`. */
function ownerOf(vault: string, slug: string): string | null {
return parsePreference(preferencePath(vault, slug)).owner ?? null;
}
/** Minimal valid preference input; never carries an `owner`. */
function prefInput(slug: string): Parameters<typeof writePreference>[1] {
return {
slug,
topic: slug,
principle: `principle for ${slug}`,
created_at: "2026-05-01T00:00:00Z",
unconfirmed_until: "2026-05-08T00:00:00Z",
status: BRAIN_PREFERENCE_STATUS.confirmed,
evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
confirmed_at: "2026-05-02T00:00:00Z",
};
}
/** A gate verdict that actually withholds, i.e. `fail` with a scope. */
function enforcing(scope: string): OwnerScopeDelivery {
return { mode: GATE_MODE.fail, enforcedScope: scope, requestedScope: scope };
}
/**
* Every core writer that creates a preference, driven once, under a
* pinned clock. The two feedback surfaces are excluded here and covered
* by their own tests: both stamp `new Date()` into the signal they write
* alongside the preference, so two runs can never be byte-identical.
*/
function writeThroughEveryCoreWriter(vault: string): void {
writePreference(vault, prefInput("direct"));
writePreferenceTxn(vault, prefInput("txn"), []);
writePreference(vault, prefInput("premise"));
deriveFact(
vault,
{
slug: "derived",
topic: "derived",
principle: "a derived rule",
level: "deduced",
premises: ["pref-premise"],
},
{ now: NOW },
);
writePreference(vault, { ...prefInput("merge-keep"), topic: "merge" });
writePreference(vault, { ...prefInput("merge-drop"), topic: "merge" });
mergePreferences(vault, "pref-merge-keep", "pref-merge-drop", { now: NOW, agentName: SELF });
}
async function callTool(
server: MCPServer,
name: string,
args: Record<string, unknown>,
): Promise<{ isError: boolean; structuredContent: Record<string, unknown> }> {
await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 1,
method: "initialize",
params: {
protocolVersion: PROTOCOL_VERSION,
capabilities: {},
clientInfo: { name: "owner-stamp", version: "0" },
},
});
await server.handleRequest({ jsonrpc: JSONRPC_VERSION, method: "notifications/initialized" });
const response = (await server.handleRequest({
jsonrpc: JSONRPC_VERSION,
id: 2,
method: "tools/call",
params: { name, arguments: args },
})) as { result: { isError: boolean; structuredContent: Record<string, unknown> } };
return response.result;
}
// ----- The gate on: every production writer stamps ---------------------------
test("gate fail: every core preference writer stamps the resolved identity", () => {
const vault = makeVault("stamped", GATE_MODE.fail);
writeThroughEveryCoreWriter(vault);
for (const slug of ["direct", "txn", "derived"]) {
expect(`${slug}=${ownerOf(vault, slug)}`).toBe(`${slug}=${SELF}`);
}
});
test("gate warn: ownership is written so the operator can watch what fail would remove", () => {
const vault = makeVault("warned", GATE_MODE.warn);
writePreference(vault, prefInput("direct"));
expect(ownerOf(vault, "direct")).toBe(SELF);
});
test("gate fail: the MCP feedback writer stamps the server-resolved identity", async () => {
const vault = makeVault("mcp", GATE_MODE.fail);
const configPath = process.env["OPEN_SECOND_BRAIN_CONFIG"] as string;
const result = await callTool(new MCPServer({ vault, configPath }), "brain_feedback", {
topic: "mcp-topic",
signal: "positive",
principle: "A rule recorded through the MCP writer.",
force_confirmed: true,
});
expect(result.isError).toBe(false);
expect(ownerOf(vault, "mcp-topic")).toBe(SELF);
});
test("gate fail: the CLI feedback writer stamps the server-resolved identity", async () => {
const vault = makeVault("cli", GATE_MODE.fail);
const configPath = process.env["OPEN_SECOND_BRAIN_CONFIG"] as string;
const run = await runCli(
[
"brain",
"feedback",
"--vault",
vault,
"--topic",
"cli-topic",
"--signal",
"positive",
"--principle",
"A rule recorded through the CLI writer.",
"--force-confirmed",
],
{ env: { OPEN_SECOND_BRAIN_CONFIG: configPath, HOME: home } },
);
expect(`exit ${run.returncode}\n${run.stderr}`).toBe("exit 0\n");
expect(ownerOf(vault, "cli-topic")).toBe(SELF);
});
// ----- Creation-only: a rewrite never re-owns --------------------------------
test("a rewrite carries the existing owner forward and never transfers ownership", () => {
const vault = makeVault("carry", GATE_MODE.fail, OTHER);
writePreference(vault, prefInput("owned"));
expect(ownerOf(vault, "owned")).toBe(OTHER);
// A second agent rewrites the same preference. Ownership must not move.
atomicWriteFileSync(
process.env["OPEN_SECOND_BRAIN_CONFIG"] as string,
`vault: ${vault}\nagent_name: ${SELF}\n`,
);
writePreference(vault, { ...prefInput("owned"), principle: "rewritten" }, { overwrite: true });
expect(ownerOf(vault, "owned")).toBe(OTHER);
});
test("a page that predates the gate stays shared when the gate is switched on", () => {
const vault = makeVault("legacy", GATE_MODE.off);
writePreference(vault, prefInput("legacy"));
expect(ownerOf(vault, "legacy")).toBeNull();
// REWRITTEN, not appended: `makeVault` already emitted an `integrity:`
// block for the `off` gate, and appending a second one produces a
// duplicate top-level key - i.e. a config the parser rejects. That is
// the F5 condition, not this test's subject, and a writer now refuses
// it rather than inferring an owner from a file it could not read.
atomicWriteFileSync(
brainConfigPath(vault),
`schema_version: 1\nintegrity:\n owner_scope_delivery: ${GATE_MODE.fail}\n`,
);
writePreference(vault, { ...prefInput("legacy"), principle: "rewritten" }, { overwrite: true });
expect(ownerOf(vault, "legacy")).toBeNull();
});
test("merge keeps the surviving preference's owner instead of stripping it", () => {
const vault = makeVault("merged", GATE_MODE.fail);
writeThroughEveryCoreWriter(vault);
expect(ownerOf(vault, "merge-keep")).toBe(SELF);
});
test("an explicit caller-supplied owner still wins over the resolved identity", () => {
const vault = makeVault("explicit", GATE_MODE.fail);
writePreference(vault, { ...prefInput("explicit"), owner: OTHER });
expect(ownerOf(vault, "explicit")).toBe(OTHER);
});
// ----- The gate off: not one byte moves --------------------------------------
test("gate off: two vaults written by the same script are byte-identical and ownerless", () => {
const first = makeVault("digest-a", GATE_MODE.off);
writeThroughEveryCoreWriter(first);
const second = makeVault("digest-b", GATE_MODE.off);
writeThroughEveryCoreWriter(second);
// `_brain.yaml` names the vault only through the config file outside
// the tree, so the two trees are comparable file-for-file.
expect(digestVaultTree(second)).toBe(digestVaultTree(first));
expect(changedPaths(treeEntries(first), treeEntries(second))).toEqual([]);
const dir = brainDirs(first).preferences;
for (const file of collectPreferences(dir).entries) {
expect(`${file.name}: ${readFileSync(file.path, "utf8")}`).not.toContain("\nowner:");
}
});
test("gate off vs gate fail: the only files that differ are the preferences", () => {
const off = makeVault("off-tree", GATE_MODE.off);
writeThroughEveryCoreWriter(off);
const on = makeVault("on-tree", GATE_MODE.fail);
writeThroughEveryCoreWriter(on);
// `retired/` is in the expected set on purpose: `moveToRetired` copies
// every inherited field, so retiring an owner-private memory must not
// publish it. Nothing else in the tree may move.
const differing = changedPaths(treeEntries(off), treeEntries(on)).filter(
(path) => path !== "Brain/_brain.yaml",
);
expect(
differing.filter(
(path) => !path.startsWith("Brain/preferences/") && !path.startsWith("Brain/retired/"),
),
).toEqual([]);
expect(differing.length).toBeGreaterThan(0);
});
// ----- The owner-write gate (write-side-trust): a named owner is a claim ------
//
// `integrity.owner_scope_writes` is the write-side sibling of the delivery
// gate above: under `fail` an explicit `owner:` that disagrees with the
// resolved identity refuses, under `warn` it passes with one decision-ledger
// row, and under `off` (or with no document) nothing here changes - which is
// why every test above still runs with the key absent and passes untouched.
test("owner-write gate fail: an explicit owner other than the resolved identity refuses", () => {
const vault = makeVault("ow-fail", GATE_MODE.fail, SELF, GATE_MODE.fail);
let message = "";
try {
writePreference(vault, { ...prefInput("claimed"), owner: OTHER });
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain("owner-write-refused");
expect(message).toContain(OTHER);
expect(message).toContain(SELF);
expect(message).toContain("integrity.owner_scope_writes");
expect(existsSync(preferencePath(vault, "claimed"))).toBe(false);
});
test("owner-write gate warn: a cross-owner write is allowed with exactly one ledger row", () => {
const vault = makeVault("ow-warn", GATE_MODE.off, SELF, GATE_MODE.warn);
writePreference(vault, { ...prefInput("watched"), owner: OTHER });
expect(ownerOf(vault, "watched")).toBe(OTHER);
const rows = queryDecisionLedger(vault, { action: "owner_write" });
expect(rows.length).toBe(1);
expect(rows[0]!.source).toBe("integrity.owner_scope_writes");
expect(rows[0]!.verdict).toBe(GATE_MODE.warn);
expect(rows[0]!.actor).toBe(SELF);
expect(rows[0]!.target.replaceAll("\\", "/")).toBe("Brain/preferences/pref-watched.md");
expect(rows[0]!.reason).toContain(OTHER);
});
test("owner-write gate warn: a matching-identity explicit owner logs no ledger row", () => {
const vault = makeVault("ow-warn-self", GATE_MODE.off, SELF, GATE_MODE.warn);
writePreference(vault, { ...prefInput("own-claim"), owner: SELF });
expect(ownerOf(vault, "own-claim")).toBe(SELF);
expect(queryDecisionLedger(vault, {})).toEqual([]);
});
test("owner-write gate: an unreadable Brain config fails closed on a cross-owner claim", () => {
const vault = makeVault("ow-unreadable", GATE_MODE.off, SELF, GATE_MODE.warn);
atomicWriteFileSync(brainConfigPath(vault), "schema_version: 1\nintegrity: [ this is not yaml\n");
let message = "";
try {
writePreference(vault, { ...prefInput("closed"), owner: OTHER });
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain("owner-write-refused");
expect(existsSync(preferencePath(vault, "closed"))).toBe(false);
});
test("owner-write gate: an unreadable Brain config still passes the caller's own owner", () => {
// The strict fallback resolves the gate to `fail`, and `fail` refuses
// only the disagreement - a claim that agrees is not a boundary case,
// so the fallback must not turn every explicit owner into a refusal.
const vault = makeVault("ow-unreadable-own", GATE_MODE.off, SELF, GATE_MODE.warn);
atomicWriteFileSync(brainConfigPath(vault), "schema_version: 1\nintegrity: [ this is not yaml\n");
writePreference(vault, { ...prefInput("agreeing"), owner: SELF });
expect(ownerOf(vault, "agreeing")).toBe(SELF);
});
test("owner-write gate: a document denying owner_write refuses even with the gate off", () => {
const vault = makeVault("ow-doc-deny", GATE_MODE.off, SELF);
atomicWriteFileSync(
join(vault, "Brain", "_permissions.yaml"),
"version: 1\ndefault_action: deny\n",
);
let message = "";
try {
writePreference(vault, { ...prefInput("denied"), owner: OTHER });
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain("owner-write-refused");
expect(existsSync(preferencePath(vault, "denied"))).toBe(false);
});
test("owner-write gate: a document allow cannot talk a fail gate out of the refusal", () => {
const vault = makeVault("ow-doc-allow", GATE_MODE.off, SELF, GATE_MODE.fail);
atomicWriteFileSync(
join(vault, "Brain", "_permissions.yaml"),
`version: 1\ndefault_action: allow\nagents:\n ${SELF}:\n owner_write: allow\n`,
);
let message = "";
try {
writePreference(vault, { ...prefInput("still-refused"), owner: OTHER });
} catch (err) {
message = (err as Error).message;
}
expect(message).toContain("owner-write-refused");
expect(existsSync(preferencePath(vault, "still-refused"))).toBe(false);
});
// ----- No new config key ------------------------------------------------------
/**
* Owner stamping itself adds no config key: it rides
* `integrity.owner_scope_delivery`, which predates it. The block holds one
* further gate key since write-side-trust (`owner_scope_writes`, the
* write-side sibling this file's gate-on cases exercise); the list here is
* the whole block, so that key is pinned alongside rather than hidden.
*/
test("owner stamping adds no config key: the integrity block is unchanged", () => {
const known = brainConfigKnownKeys();
expect([...(known.subKeys.get("integrity") ?? [])].toSorted()).toEqual([
"embedding_abi",
"owner_scope_delivery",
"owner_scope_writes",
"pack_validity_seconds",
]);
});
// ----- The boundary, on a vault written entirely through production surfaces ---
test("withholding works on a vault no test-only owner argument ever touched", async () => {
const vault = makeVault("two-agents", GATE_MODE.fail, SELF);
const selfConfig = process.env["OPEN_SECOND_BRAIN_CONFIG"] as string;
bootstrapBrain(vault, { configPath: selfConfig });
await callTool(new MCPServer({ vault, configPath: selfConfig }), "brain_feedback", {
topic: "self-rule",
signal: "positive",
principle: "A rule only the first agent may read.",
force_confirmed: true,
});
const otherConfig = join(tmp, "other-config.yaml");
atomicWriteFileSync(otherConfig, `vault: ${vault}\nagent_name: ${OTHER}\n`);
process.env["OPEN_SECOND_BRAIN_CONFIG"] = otherConfig;
await callTool(new MCPServer({ vault, configPath: otherConfig }), "brain_feedback", {
topic: "other-rule",
signal: "positive",
principle: "A rule only the second agent may read.",
force_confirmed: true,
});
const dir = brainDirs(vault).preferences;
const asSelf = collectPreferences(dir, { ownerScope: enforcing(SELF) });
const asOther = collectPreferences(dir, { ownerScope: enforcing(OTHER) });
expect(asSelf.entries.map((e) => e.pref.id)).toEqual(["pref-self-rule"]);
expect(asOther.entries.map((e) => e.pref.id)).toEqual(["pref-other-rule"]);
expect(asSelf.hiddenByOwnerScope).toBe(1);
});
// ----- An identity that cannot be reduced to a token is a refusal --------------
test("an unusable resolved identity refuses the write instead of hiding the page", () => {
const vault = makeVault("blank-identity", GATE_MODE.fail);
process.env["VAULT_AGENT_NAME"] = " ";
expect(() => writePreference(vault, prefInput("blank"))).toThrow(/owner/i);
});
/**
* F4: an unconfigured install must not become a real owner named `agent`.
*
* `resolveAgentName` never fails - it returns `UNCONFIGURED_AGENT_NAME`,
* the literal `"agent"` - and `ownerStampFor` accepted it, so a vault
* with the gate on and no `agent_name` accumulated preferences owned by
* `agent` while `refuseOwnerScopeRequest` refused every caller asking to
* be answered as `agent` because that name is unverifiable. The two
* halves must agree: the predicate that refuses the placeholder as an
* identity is the one that prevents it becoming an owner.
*/
test("gate fail: the placeholder identity refuses the write instead of owning the page", () => {
const vault = join(tmp, "unconfigured");
for (const sub of ["preferences", "retired", "inbox", "log"]) {
mkdirSync(join(vault, "Brain", sub), { recursive: true });
}
atomicWriteFileSync(
brainConfigPath(vault),
`schema_version: 1\nintegrity:\n owner_scope_delivery: ${GATE_MODE.fail}\n`,
);
// A config with NO `agent_name`: the state `resolveAgentName` answers
// with the placeholder.
const configPath = join(tmp, "unconfigured-config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\n`);
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
expect(() => writePreference(vault, prefInput("unowned"))).toThrow(/placeholder/i);
expect(existsSync(preferencePath(vault, "unowned"))).toBe(false);
});
test("every placeholder identity is refused as an owner, not just the bare default", () => {
for (const name of PLACEHOLDER_AGENT_VALUES) {
expect(`${name} -> ${String(ownerStampFor(name))}`).toBe(`${name} -> null`);
}
// A real name still stamps, so the refusal is not a blanket one.
expect(ownerStampFor("claude-vps-agent")).toBe("claude-vps-agent");
});
/**
* F5: an unreadable `_brain.yaml` silently switched stamping ON, forever.
*
* `loadIntegrityConfigSafe`'s strict fallback is scoped to READERS - "the
* unreadable config cannot loosen a gate, it can only close one" - and a
* writer was wired to it. Strict here means STAMP, so one bad token in
* the YAML made every new preference carry an owner the operator never
* asked for, and ownership is carried forward, so the pages outlived the
* repair of the typo.
*/
test("an unreadable Brain config refuses the write rather than inferring an owner", () => {
const vault = makeVault("unreadable-config", GATE_MODE.off);
atomicWriteFileSync(brainConfigPath(vault), "schema_version: 1\nintegrity: [ this is not yaml\n");
let message = "";
try {
writePreference(vault, prefInput("guessed"));
} catch (err) {
message = (err as Error).message;
}
// Explicit on both counts: it names the unreadable config, and it says
// the writer will not guess - never a silent stamp, never a silent skip.
expect(message).toContain("Brain/_brain.yaml");
expect(existsSync(preferencePath(vault, "guessed"))).toBe(false);
});
test("an ABSENT Brain config still writes, ownerless, as the documented default", () => {
// The other half of the reader/writer split: absent is not unreadable.
const vault = join(tmp, "no-config");
for (const sub of ["preferences", "retired", "inbox", "log"]) {
mkdirSync(join(vault, "Brain", sub), { recursive: true });
}
const configPath = join(tmp, "no-config-config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: ${SELF}\n`);
process.env["OPEN_SECOND_BRAIN_CONFIG"] = configPath;
writePreference(vault, prefInput("defaulted"));
expect(ownerOf(vault, "defaulted")).toBeNull();
});
/**
* A3: the writer census - "every production writer stamps" measured, not
* listed.
*
* The claim above this line used to be held true by
* {@link writeThroughEveryCoreWriter}, a HAND-WRITTEN list of four
* writers. `import-claude-memory.ts` renders its own frontmatter and
* calls `atomicWriteFileSync` directly, so it was not on the list, never
* reached `withResolvedOwner`, and shipped every imported memory
* ownerless into a gated vault. A list is the failure mode this release
* is about.
*
* The population is SYNTACTIC and read off source: a module that both
* builds a preference path and writes bytes is a preference writer. Each
* one must reach the shared ownership resolution - `writePreference`,
* `writePreferenceTxn` or `resolvedOwnerFor` - or carry an entry here
* saying what it does instead. Never both, never neither.
*/
const PREFERENCE_PATH_BUILDERS = ["preferencePath(", "retiredPath("];
const FS_BYTE_WRITES = [
"atomicWriteFileSync(",
"writeFileSync(",
"appendFileSync(",
"renameSync(",
"copyFileSync(",
"cpSync(",
"writeFrontmatterAtomic(",
];
/** The three entry points that resolve ownership for a new preference. */
const OWNERSHIP_RESOLVERS = ["writePreference(", "writePreferenceTxn(", "resolvedOwnerFor("];
/** Modules in the syntactic population that write no preference bytes. */
const NO_PREFERENCE_BYTES: Readonly<Record<string, string>> = Object.freeze({
"src/core/store-migration/exporters.ts":
"the rollback exporter writes a preference page back from the fold of its store records, " +
"whose fields (`owner:` included) the writer that made each record already resolved; it " +
"replays decided state and decides no ownership of its own.",
"src/core/brain/write-batch.ts":
"builds a preference path only to ASSERT the target exists before an apply-evidence " +
"operation; every byte it writes goes to a caller-named note path.",
"src/core/brain/pin.ts":
"flips ONE existing frontmatter field on an EXISTING page (`{...meta, pinned}`) and never " +
"creates one, so the `owner:` already on disk is preserved by construction - the same " +
"outcome the carry-forward branch of the resolver produces, reached without re-deriving it.",
"src/core/brain/health/remediation.ts":
"re-stamps ONE derived frontmatter field (`_content_hash`) on an EXISTING page by spreading " +
"the parsed metadata, so ownership travels untouched and nothing new is created.",
"src/core/brain/portability/knowledge-pack.ts":
"builds preference paths only to detect install conflicts; its preferences land through " +
"`restorePreferences`, and its one direct write adds the install fingerprint to a page it " +
"just staged under `OKF Review/`, never to a preference.",
"src/core/brain/preference-page-write.ts":
"the shared write path of the page writers (task 2.10), not a writer of its own: it " +
"writes the text or the field its caller hands it, and every caller either resolved " +
"ownership already (the memory importers go through `resolvedOwnerFor`) or edits fields " +
"of an EXISTING preference, whose `owner:` it never touches.",
"src/core/brain/lessons-promotion.ts":
"builds a preference path only to READ the lesson's source preference; its two atomic " +
"writes land the lessons-approvals ledger in the derived store, outside Brain/ and outside " +
"any note surface, so there are no preference bytes to own (t_1e952e43).",
});
test("every module that writes preference bytes reaches the ownership resolver", async () => {
const { readFileSync: readFile } = await import("node:fs");
const { lexSource } = await import("../../helpers/source-lexer.ts");
const root = join(import.meta.dir, "..", "..", "..", "src");
const walk = (dir: string): string[] =>
readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
e.isDirectory() ? walk(join(dir, e.name)) : e.name.endsWith(".ts") ? [join(dir, e.name)] : [],
);
const offenders: string[] = [];
for (const abs of walk(root)) {
// Forward slashes so the census keys match on Windows too.
const posixAbs = abs.replaceAll("\\", "/");
const rel = posixAbs.slice(posixAbs.indexOf("src/"));
if (rel === "src/core/brain/preference.ts") continue; // the resolver's own home
const code = lexSource(readFile(abs, "utf8")).code;
const buildsPath = PREFERENCE_PATH_BUILDERS.some((p) => code.includes(p));
const writesBytes = FS_BYTE_WRITES.some((p) => code.includes(p));
if (!buildsPath || !writesBytes) continue;
if (OWNERSHIP_RESOLVERS.some((p) => code.includes(p))) continue;
if (rel in NO_PREFERENCE_BYTES) continue;
offenders.push(rel);
}
expect(
offenders,
"each of these writes preference bytes without reaching the ownership resolver; " +
"route it through one, or declare it in NO_PREFERENCE_BYTES with a reason",
).toEqual([]);
});
test("the claude-memory importer stamps the resolved identity like every other writer", async () => {
const vault = makeVault("imported", GATE_MODE.fail);
const memoryDir = join(tmp, "memory");
mkdirSync(memoryDir, { recursive: true });
atomicWriteFileSync(
join(memoryDir, "feedback_probe.md"),
"---\ntype: feedback\nname: feedback probe\ndescription: An imported rule.\n---\n\nscope: writing\n",
);
const { importClaudeMemory } = await import("../../../src/core/brain/import-claude-memory.ts");
const result = importClaudeMemory({
vault,
memoryDir,
mode: "apply",
now: NOW,
allowArbitraryMemoryPath: true,
});
expect(result.applied.length).toBe(1);
expect(ownerOf(vault, "feedback-probe")).toBe(SELF);
});
test("with the gate off the importer writes no owner at all", async () => {
const vault = makeVault("imported-off", GATE_MODE.off);
const memoryDir = join(tmp, "memory-off");
mkdirSync(memoryDir, { recursive: true });
atomicWriteFileSync(
join(memoryDir, "feedback_probe.md"),
"---\ntype: feedback\nname: feedback probe\ndescription: An imported rule.\n---\n\nscope: writing\n",
);
const { importClaudeMemory } = await import("../../../src/core/brain/import-claude-memory.ts");
importClaudeMemory({
vault,
memoryDir,
mode: "apply",
now: NOW,
allowArbitraryMemoryPath: true,
});
expect(ownerOf(vault, "feedback-probe")).toBeNull();
});