Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #4109 — same-source graph mutation diagnostics at the source boundary.
*
* `get_page` reads may span the caller's federated grant, but `add_link` /
* `add_timeline_entry` intentionally write only to the caller's scalar write
* source. Pre-fix, targeting a page the caller can READ from another granted
* source hit the engine's exact-source existence check, whose generic Error
* surfaced over MCP as `internal_error` — intentional source isolation looked
* like data loss.
*
* Pinned behavior:
* - a visible foreign endpoint → `permission_denied` naming the readable
* source and the client's write source (per endpoint: from / to / page);
* - a page outside the read grant → `page_not_found` that never names the
* foreign source (same anti-enumeration posture as get_page);
* - a soft-deleted foreign page is indistinguishable from absence;
* - soft-deleted pages IN the write source keep the existing engine
* mutation contract (graph rows may reference them);
* - same-source mutations are unchanged;
* - the engines report the missing endpoint individually (from vs to) in
* lockstep parity, so dispatch can classify mutation-time misses.
*
* Runs end to end through `dispatchToolCall` (the path both MCP transports
* share) against a real PGLiteEngine, per mcp-dispatch-optional-params.test.ts.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import { withEnv } from './helpers/with-env.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import type { BrainEngine } from '../src/core/engine.ts';
import { PageMissingError } from '../src/core/engine-errors.ts';
import { dispatchToolCall as dispatchToolCallImpl } from '../src/mcp/dispatch.ts';
import { runSources } from '../src/commands/sources.ts';
import { importFromContent } from '../src/core/import-file.ts';
import type { AuthInfo } from '../src/core/operations.ts';
let engine: PGLiteEngine;
const home = mkdtempSync(join(tmpdir(), 'gbrain-source-boundary-'));
async function dispatchToolCall(...args: Parameters<typeof dispatchToolCallImpl>) {
return withEnv({ GBRAIN_HOME: home }, async () => {
try { return await dispatchToolCallImpl(...args); }
finally { await disposePersistenceConsumer(args[0]); }
});
}
// Source ids chosen so the foreign one ('privsrc') shares no substring with
// the 'internal_error' envelope code — the no-disclosure assertions below
// check the raw payload text.
const WRITE_SRC = 'shared';
const FOREIGN_SRC = 'privsrc';
const FROM_SLUG = 'topics/sbme-from';
const TO_SHARED = 'topics/sbme-to-shared';
const TO_FOREIGN = 'topics/sbme-to-foreign';
const TL_FOREIGN = 'topics/sbme-tl-foreign';
const DELETED_FOREIGN = 'topics/sbme-deleted-foreign';
const SD_FROM = 'topics/sbme-sd-from';
const SD_TO = 'topics/sbme-sd-to';
function auth(allowedSources: string[]): AuthInfo {
return { token: 'test-token', clientId: 'gbrain_cl_source_boundary', principal: { kind: 'oauth_client', id: 'gbrain_cl_source_boundary' }, sourceId: WRITE_SRC, scopes: ['read', 'write'], allowedSources };
}
// Grant spans both sources (can READ the foreign page) vs write source only.
const GRANTED = { remote: true, sourceId: WRITE_SRC, auth: auth([WRITE_SRC, FOREIGN_SRC]) };
const UNGRANTED = { remote: true, sourceId: WRITE_SRC, auth: auth([WRITE_SRC]) };
function payload(result: { content: Array<{ type: string; text: string }> }) {
return JSON.parse(result.content[0]!.text);
}
async function seed(slug: string, sourceId: string): Promise<void> {
await engine.putPage(slug, {
type: 'concept',
title: slug,
compiled_truth: 'source-boundary fixture',
}, { sourceId });
}
async function countLinks(from: string, to: string): Promise<number> {
const rows = await engine.executeRaw<{ count: number }>(
`SELECT COUNT(*)::int AS count
FROM links l
JOIN pages f ON f.id = l.from_page_id
JOIN pages t ON t.id = l.to_page_id
WHERE f.slug = $1 AND t.slug = $2`,
[from, to],
);
return rows[0].count;
}
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
mkdirSync(join(home, '.gbrain'));
writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', embedding_disabled: true }));
await runSources(engine, ['add', WRITE_SRC, '--no-federated']);
await runSources(engine, ['add', FOREIGN_SRC, '--no-federated']);
await engine.executeRaw(`INSERT INTO oauth_clients(client_id,client_name,scope,source_id,federated_read) VALUES('gbrain_cl_source_boundary','Source boundary fixture','read write',$1,$2)`, [WRITE_SRC, [WRITE_SRC, FOREIGN_SRC]]);
await seed(FROM_SLUG, WRITE_SRC);
await seed(TO_SHARED, WRITE_SRC);
await seed(TO_FOREIGN, FOREIGN_SRC);
await seed(TL_FOREIGN, FOREIGN_SRC);
await seed(DELETED_FOREIGN, FOREIGN_SRC);
await engine.softDeletePage(DELETED_FOREIGN, { sourceId: FOREIGN_SRC });
await seed(SD_FROM, WRITE_SRC);
await seed(SD_TO, WRITE_SRC);
await engine.softDeletePage(SD_FROM, { sourceId: WRITE_SRC });
await engine.softDeletePage(SD_TO, { sourceId: WRITE_SRC });
}, 120_000); // full PGLite schema init can exceed the default hook timeout under suite load
afterAll(async () => {
await disposePersistenceConsumer(engine);
await engine.disconnect();
rmSync(home, { recursive: true, force: true });
}, 30_000);
describe('add_link source-boundary diagnostics (#4109)', () => {
test('a visible foreign `to` endpoint is permission_denied naming the boundary', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: FROM_SLUG,
to: TO_FOREIGN,
link_type: 'mentions',
}, GRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'permission_denied',
message: `add_link to page "${TO_FOREIGN}" is readable from source "${FOREIGN_SRC}" but this client writes to source "${WRITE_SRC}".`,
});
expect(await countLinks(FROM_SLUG, TO_FOREIGN)).toBe(0);
});
test('a visible foreign `from` endpoint is identified as `from`', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: TO_FOREIGN,
to: TO_SHARED,
link_type: 'mentions',
}, GRANTED);
expect(result.isError).toBe(true);
expect(payload(result).error).toBe('permission_denied');
expect(payload(result).message).toContain(`add_link from page "${TO_FOREIGN}"`);
expect(await countLinks(TO_FOREIGN, TO_SHARED)).toBe(0);
});
test('a foreign page outside the read grant stays page_not_found without disclosure', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: FROM_SLUG,
to: TO_FOREIGN,
link_type: 'mentions',
}, UNGRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'page_not_found',
message: `add_link to page "${TO_FOREIGN}" was not found in writable source "${WRITE_SRC}".`,
});
expect(result.content[0]!.text).not.toContain(FOREIGN_SRC);
});
test('a soft-deleted foreign page is indistinguishable from absence', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: FROM_SLUG,
to: DELETED_FOREIGN,
link_type: 'mentions',
}, GRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({ error: 'page_not_found' });
expect(result.content[0]!.text).not.toContain(FOREIGN_SRC);
});
test('soft-deleted pages in the write source preserve the engine mutation contract', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: SD_FROM,
to: SD_TO,
link_type: 'mentions',
}, GRANTED);
expect(result.isError).toBeUndefined();
expect(await countLinks(SD_FROM, SD_TO)).toBe(1);
});
test('same-source add_link still reaches the engine', async () => {
const result = await dispatchToolCall(engine, 'add_link', {
from: FROM_SLUG,
to: TO_SHARED,
link_type: 'mentions',
}, GRANTED);
expect(result.isError).toBeUndefined();
expect(await countLinks(FROM_SLUG, TO_SHARED)).toBe(1);
});
});
describe('add_timeline_entry source-boundary diagnostics (#4109)', () => {
const ENTRY = { date: '2026-08-14', summary: 'Reviewed next steps.' };
test('a visible foreign page is permission_denied naming the boundary', async () => {
const result = await dispatchToolCall(engine, 'add_timeline_entry', {
slug: TL_FOREIGN,
...ENTRY,
}, GRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'permission_denied',
message: `add_timeline_entry page "${TL_FOREIGN}" is readable from source "${FOREIGN_SRC}" but this client writes to source "${WRITE_SRC}".`,
});
const entries = await engine.getTimeline(TL_FOREIGN, { sourceId: FOREIGN_SRC });
expect(entries.length).toBe(0);
});
test('a foreign page outside the read grant stays page_not_found without disclosure', async () => {
const result = await dispatchToolCall(engine, 'add_timeline_entry', {
slug: TL_FOREIGN,
...ENTRY,
}, UNGRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'page_not_found',
message: `add_timeline_entry page "${TL_FOREIGN}" was not found in writable source "${WRITE_SRC}".`,
});
expect(result.content[0]!.text).not.toContain(FOREIGN_SRC);
});
test('same-source add_timeline_entry still reaches the engine', async () => {
const result = await dispatchToolCall(engine, 'add_timeline_entry', {
slug: FROM_SLUG,
...ENTRY,
}, GRANTED);
expect(result.isError).toBeUndefined();
expect(payload(result)).toMatchObject({ status: 'ok' });
const entries = await engine.getTimeline(FROM_SLUG, { sourceId: WRITE_SRC });
expect(entries.length).toBe(1);
});
});
describe('engine per-endpoint miss messages (lockstep parity contract)', () => {
test('addLink identifies a missing `to` endpoint', async () => {
await expect(
engine.addLink(FROM_SLUG, 'topics/sbme-missing', '', 'documents', 'manual', undefined, undefined,
{ fromSourceId: WRITE_SRC, toSourceId: WRITE_SRC, originSourceId: WRITE_SRC }),
).rejects.toThrow(
`addLink failed: to page "topics/sbme-missing" (source=${WRITE_SRC}) not found`,
);
});
test('addLink identifies a missing `from` endpoint', async () => {
await expect(
engine.addLink('topics/sbme-missing', TO_SHARED, '', 'documents', 'manual', undefined, undefined,
{ fromSourceId: WRITE_SRC, toSourceId: WRITE_SRC, originSourceId: WRITE_SRC }),
).rejects.toThrow(
`addLink failed: from page "topics/sbme-missing" (source=${WRITE_SRC}) not found`,
);
});
test('the miss is typed, not a message-prefix contract', async () => {
// The ops layer reclassifies by instanceof; a reworded message must not
// silently disable the reclassification (the #4109 string-matching trap).
try {
await engine.addTimelineEntry('topics/sbme-missing', {
date: '2026-08-14',
summary: 'never lands',
}, { sourceId: WRITE_SRC });
throw new Error('should have thrown');
} catch (e) {
expect(e).toBeInstanceOf(PageMissingError);
expect((e as PageMissingError).endpoint).toBe('page');
expect((e as PageMissingError).slug).toBe('topics/sbme-missing');
expect((e as PageMissingError).sourceId).toBe(WRITE_SRC);
}
});
});
describe('mutation-time deletion race reclassification (#4109)', () => {
// A hard delete can land between the ops-layer preflight and the engine
// mutation. The engine's typed miss must be reclassified into the same
// caller-facing envelope — deterministically faked here since a real race
// needs a second writer (covered against real Postgres by
// test/e2e/source-boundary-mutation-postgres.test.ts).
type StoredPage = { slug: string; source_id: string };
function fakeEngine(pages: StoredPage[], raceDeleteSlug: string) {
return {
async getPage(slug: string, opts: { sourceId?: string; sourceIds?: string[] } = {}) {
const sources = opts.sourceIds ?? (opts.sourceId ? [opts.sourceId] : []);
const page = pages.find(
(candidate) => candidate.slug === slug && sources.includes(candidate.source_id),
);
return page ? ({ ...page } as never) : null;
},
async addLink(from: string, to: string) {
const endpoint = raceDeleteSlug === from ? 'from' : 'to';
pages.splice(pages.findIndex((page) => page.slug === raceDeleteSlug), 1);
throw new PageMissingError('addLink', endpoint, raceDeleteSlug, WRITE_SRC);
},
async addTimelineEntry(slug: string) {
pages.splice(pages.findIndex((page) => page.slug === raceDeleteSlug), 1);
throw new PageMissingError('addTimelineEntry', 'page', slug, WRITE_SRC);
},
// DB-only brain: no source local_path / repo_path, so the timeline
// write-through takes its handled:false path and the op falls through
// to the insert. #6482: the strict mode reader needs one well-formed unmanaged row.
async executeRaw(sql: string) {
return sql.includes('FROM persistence_brain') ? [{ enabled: false }] : [];
},
async getConfig() {
return null;
},
} as unknown as BrainEngine;
}
test('add_link reclassifies an endpoint hard-deleted after preflight', async () => {
const eng = fakeEngine(
[{ slug: 'topics/race-from', source_id: WRITE_SRC }, { slug: 'topics/race-to', source_id: WRITE_SRC }],
'topics/race-to',
);
const result = await dispatchToolCall(eng, 'add_link', {
from: 'topics/race-from',
to: 'topics/race-to',
}, UNGRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'page_not_found',
message: `add_link to page "topics/race-to" was not found in writable source "${WRITE_SRC}".`,
});
});
test('add_timeline_entry refuses a page replaced after the accepted snapshot', async () => {
const slug = 'topics/race-tl';
await seed(slug, WRITE_SRC);
const original = engine.readPageSnapshot;
let replaced = false;
let targetReads = 0;
engine.readPageSnapshot = async function (target, opts) {
const snapshot = await original.call(this, target, opts);
// The first read is the source-boundary preflight; the second is the
// snapshot whose page identity admission retains in the durable row.
if (target === slug && ++targetReads === 2) {
replaced = true;
await engine.deletePage(slug, { sourceId: WRITE_SRC });
await seed(slug, WRITE_SRC);
}
return snapshot;
};
try {
const result = await dispatchToolCall(engine, 'add_timeline_entry', {
slug, date: '2026-08-14', summary: 'must not reach the replacement page',
}, UNGRANTED);
expect(replaced).toBe(true);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({ write_error: 'page_identity_changed', write_request: { state: 'conflict' } });
expect(await engine.getTimeline(slug, { sourceId: WRITE_SRC })).toEqual([]);
expect((await engine.getPage(slug, { sourceId: WRITE_SRC }))?.compiled_truth).toBe('source-boundary fixture');
} finally { engine.readPageSnapshot = original; }
});
test('a page restored between reclassification reads still misses deterministically', async () => {
// The engine miss fired, but by the time the reclassifier re-reads, the
// page is back (delete + restore race): never internal_error.
const eng = {
async getPage(slug: string) {
return { slug, source_id: WRITE_SRC } as never;
},
async addLink() {
throw new PageMissingError('addLink', 'to', 'topics/race-restored', WRITE_SRC);
},
async executeRaw(sql: string) { return sql.includes('FROM persistence_brain') ? [{ enabled: false }] : []; }, // explicitly unmanaged fixture (#6482: one well-formed row)
} as unknown as BrainEngine;
const result = await dispatchToolCall(eng, 'add_link', {
from: 'topics/race-from',
to: 'topics/race-restored',
}, UNGRANTED);
expect(result.isError).toBe(true);
expect(payload(result)).toMatchObject({
error: 'page_not_found',
message: `add_link to page "topics/race-restored" was unavailable in writable source "${WRITE_SRC}" during the mutation.`,
});
});
});
describe('GBRA-218: the source-boundary diagnostic never reveals a page the caller cannot read', () => {
const MISSING = 'topics/sbme-never-written';
const swap = <T,>(v: T, from: string, to: string): T => JSON.parse(JSON.stringify(v).replaceAll(from, to));
const ops = (slug: string): Array<[string, Record<string, unknown>]> => [
['put_raw_data', { slug, source: 'acme-example', data: { a: 1 } }],
['add_link', { from: FROM_SLUG, to: slug, link_type: 'mentions' }],
['add_timeline_entry', { slug, date: '2026-01-01', summary: 'Boundary call' }],
];
async function sameAsMissing(slug: string, missing: string, hiddenSource: string) {
for (const [op, params] of ops(slug)) {
const hidden = await dispatchToolCall(engine, op, params, GRANTED);
const absent = await dispatchToolCall(engine, op, swap(params, slug, missing), GRANTED);
expect({ op, isError: hidden.isError, body: swap(payload(hidden), slug, missing) }).toEqual({ op, isError: absent.isError, body: payload(absent) });
expect({ op, isError: hidden.isError }).toEqual({ op, isError: true });
if (hiddenSource === FOREIGN_SRC) expect(hidden.content[0]!.text).not.toContain(FOREIGN_SRC);
}
}
test('a private page that exists only in another granted source answers exactly as a missing slug', async () => {
const slug = 'topics/sbme-private-foreign';
await importFromContent(engine, slug, '---\ntype: concept\ntitle: Private foreign\nvisibility: private\n---\nPrivate fixture.', { sourceId: FOREIGN_SRC, noEmbed: true });
await sameAsMissing(slug, MISSING, FOREIGN_SRC);
});
test('a member-hidden write-source page with a readable twin answers exactly as a slug only the twin holds', async () => {
const slug = 'topics/sbme-twin-hidden', twinOnly = 'topics/sbme-twin-only';
await engine.executeRaw('INSERT INTO access_members (id) VALUES ($1) ON CONFLICT DO NOTHING', ['alice-example']);
await importFromContent(engine, slug, '---\ntype: concept\ntitle: Twin hidden\nreadable_by: [alice-example]\n---\nHidden fixture.', { sourceId: WRITE_SRC, noEmbed: true });
await seed(slug, FOREIGN_SRC);
await seed(twinOnly, FOREIGN_SRC);
await sameAsMissing(slug, twinOnly, WRITE_SRC);
});
});