Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v114 (#1941): link_source opened from a closed allowlist to a kebab-case
* regex + length cap, provenance exposed on the link ops with a managed-
* built-in guard, a new `list_link_sources` read op, and `link-add`/`link-rm`
* CLI aliases.
*
* Coverage:
* - Migration v114 shape (two engine branches, transaction:false, idempotent)
* - DB CHECK boundary: kebab accepted (incl. all 5 built-ins), garbage rejected
* - Upgrade-path: existing built-in row survives the constraint swap (re-run)
* - add_link op: provenance threaded, default 'manual', managed-built-in guard
* - remove_link op: link_type / link_source / both filters
* - list_link_sources op: counts, deterministic order, scalar + federated scope
* - CLI aliases resolve; printOpHelp shows the invoked alias name; no collisions
*
* Hermetic via PGLite. No DATABASE_URL needed.
*/
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MIGRATIONS, LATEST_VERSION } from '../src/core/migrate.ts';
import {
operations,
operationsByName,
MANAGED_LINK_SOURCES,
} from '../src/core/operations.ts';
import type { OperationContext } from '../src/core/operations.ts';
import { cliAliases, printOpHelp } from '../src/cli/main.ts';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { _resetPackCacheForTests } from '../src/core/schema-pack/registry.ts';
import { withEnv } from './helpers/with-env.ts';
const V = 114;
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
}, 60_000);
afterAll(async () => {
await engine.disconnect();
});
function makeCtx(overrides: Partial<OperationContext> = {}): OperationContext {
return {
engine,
remote: false,
config: {},
logger: console,
dryRun: false,
...overrides,
} as unknown as OperationContext;
}
// Two pages every link test reuses.
async function seedPages() {
await engine.putPage('lsrc-a', { type: 'note', title: 'A', compiled_truth: 'a', timeline: '', frontmatter: {} });
await engine.putPage('lsrc-b', { type: 'note', title: 'B', compiled_truth: 'b', timeline: '', frontmatter: {} });
}
describe('migration v114 — links_link_source_check_kebab_regex', () => {
test('registered with expected version + name', () => {
const m = MIGRATIONS.find(m => m.version === V);
expect(m).toBeDefined();
expect(m!.name).toBe('links_link_source_check_kebab_regex');
});
test('LATEST_VERSION >= 114', () => {
expect(LATEST_VERSION).toBeGreaterThanOrEqual(V);
});
test('both engine branches present; transaction:false; idempotent', () => {
const m = MIGRATIONS.find(m => m.version === V)!;
expect(m.transaction).toBe(false);
expect(m.idempotent).toBe(true);
expect(m.sqlFor?.postgres).toBeTruthy();
expect(m.sqlFor?.pglite).toBeTruthy();
});
test('postgres branch uses NOT VALID + VALIDATE (lock-friendly)', () => {
const m = MIGRATIONS.find(m => m.version === V)!;
const pg = m.sqlFor!.postgres!;
expect(pg).toMatch(/DROP CONSTRAINT IF EXISTS links_link_source_check/i);
expect(pg).toContain('NOT VALID');
expect(pg).toMatch(/VALIDATE CONSTRAINT links_link_source_check/i);
expect(pg).toContain("'^[a-z][a-z0-9]*(-[a-z0-9]+)*$'");
expect(pg).toContain('char_length(link_source) <= 64');
});
test('pglite branch is plain DROP+ADD with the same regex', () => {
const m = MIGRATIONS.find(m => m.version === V)!;
const pl = m.sqlFor!.pglite!;
expect(pl).toMatch(/DROP CONSTRAINT IF EXISTS links_link_source_check/i);
expect(pl).not.toContain('NOT VALID');
expect(pl).toContain("'^[a-z][a-z0-9]*(-[a-z0-9]+)*$'");
});
});
describe('DB CHECK — kebab format gate', () => {
beforeAll(seedPages);
const ACCEPTED = [
'citation-graph', 'derived', 'a',
// OV7 — all 5 reconciliation-managed built-ins must stay DB-valid
'markdown', 'frontmatter', 'manual', 'mentions', 'wikilink-resolved',
];
const REJECTED: Array<[string, string]> = [
['UPPER', 'uppercase'],
['has_underscore', 'underscore'],
['has space', 'space'],
['2bad', 'leading digit'],
['-lead', 'leading dash'],
['trail-', 'trailing dash'],
['a--b', 'double dash'],
['', 'empty'],
['a'.repeat(65), '65 chars (over cap)'],
];
for (const v of ACCEPTED) {
test(`accepts '${v}'`, async () => {
// engine.addLink writes link_source straight through (no op guard) — this
// is the DB CHECK under test, not the op layer.
await expect(
engine.addLink('lsrc-a', 'lsrc-b', '', `t-${v}`, v),
).resolves.toBeUndefined();
});
}
for (const [v, why] of REJECTED) {
test(`rejects '${v}' (${why})`, async () => {
await expect(
engine.addLink('lsrc-a', 'lsrc-b', '', `t-rej-${why}`, v),
).rejects.toThrow();
});
}
});
describe('upgrade-path — existing rows survive the constraint swap', () => {
test('built-in row present, re-running v114 succeeds, new kebab tag inserts', async () => {
await seedPages();
// A row tagged with a pre-existing built-in value (would have been valid
// under the old allowlist too).
await engine.addLink('lsrc-a', 'lsrc-b', '', 't-upgrade', 'markdown');
const m = MIGRATIONS.find(m => m.version === V)!;
// Re-apply the migration against the table that now holds data: ADD/VALIDATE
// must not fail on the existing row.
await expect(engine.runMigration(V, m.sqlFor!.pglite!)).resolves.toBeUndefined();
// And a brand-new external provenance still inserts afterward.
await expect(
engine.addLink('lsrc-a', 'lsrc-b', '', 't-upgrade', 'citation-graph'),
).resolves.toBeUndefined();
});
});
describe('add_link op — provenance + managed-built-in guard (OV4A)', () => {
// #4655 checks resolve the active pack from GBRAIN_HOME and
// GBRAIN_SCHEMA_PACK; pin both (plus a cold resolver cache) so a pack or
// home left behind by an earlier file in the shard cannot change which
// link verbs are declared mid-file.
let packHome: string;
beforeAll(async () => {
packHome = mkdtempSync(join(tmpdir(), 'gbrain-link-source-pack-'));
await seedPages();
});
afterAll(() => rmSync(packHome, { recursive: true, force: true }));
const addLink = (ctx: OperationContext, params: Record<string, unknown>) => {
_resetPackCacheForTests();
return withEnv({ GBRAIN_HOME: packHome, GBRAIN_SCHEMA_PACK: undefined },
() => operationsByName['add_link'].handler(ctx, params));
};
// #4655: link verbs below come from gbrain-base's declared link_types —
// the add_link op now rejects explicit undeclared verbs when a pack resolves.
test('threads custom provenance through to the row', async () => {
await addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'works_at', link_source: 'citation-graph' });
const links = await engine.getLinks('lsrc-a');
expect(links.some(l => (l as any).to_slug === 'lsrc-b' && (l as any).link_source === 'citation-graph' && (l as any).link_type === 'works_at')).toBe(true);
});
test("omitted link_source defaults to 'manual' (not 'markdown')", async () => {
await addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'attended' });
const links = await engine.getLinks('lsrc-a');
const row = links.find(l => (l as any).link_type === 'attended');
expect((row as any)?.link_source).toBe('manual');
});
test('rejects an undeclared link_type before inserting the row (#4655)', async () => {
await expect(
addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'definitely_not_a_verb' }),
).rejects.toMatchObject({
code: 'invalid_params',
message: expect.stringContaining("link type 'definitely_not_a_verb' is not declared"),
// The suggestion names the declared vocabulary so agents self-correct.
suggestion: expect.stringContaining('works_at'),
});
const links = await engine.getLinks('lsrc-a');
expect(links.some(l => (l as any).link_type === 'definitely_not_a_verb')).toBe(false);
});
test('rejects an undeclared link_type for remote callers too (#4655)', async () => {
await expect(
addLink(makeCtx({ remote: true }), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'definitely_not_a_verb' }),
).rejects.toMatchObject({ code: 'invalid_params' });
});
test('an omitted link_type stays unchecked (untyped-edge default)', async () => {
await expect(
addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b' }),
).resolves.toMatchObject({ status: 'ok' });
});
for (const managed of MANAGED_LINK_SOURCES) {
test(`rejects managed built-in '${managed}'`, async () => {
await expect(
addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'mentions', link_source: managed }),
).rejects.toThrow(/reconciliation-managed/);
});
}
test("'manual' is allowed (not in the managed set)", async () => {
await expect(
addLink(makeCtx(), { from: 'lsrc-a', to: 'lsrc-b', link_type: 'related_to', link_source: 'manual' }),
).resolves.toMatchObject({ status: 'ok' });
});
});
describe('remove_link op — type/source filters', () => {
async function seedTwoProvenances() {
await engine.putPage('rm-a', { type: 'note', title: 'A', compiled_truth: 'a', timeline: '', frontmatter: {} });
await engine.putPage('rm-b', { type: 'note', title: 'B', compiled_truth: 'b', timeline: '', frontmatter: {} });
await engine.addLink('rm-a', 'rm-b', '', 'cites', 'manual');
await engine.addLink('rm-a', 'rm-b', '', 'cites', 'citation-graph');
}
test('--link-source filter deletes only that provenance', async () => {
await seedTwoProvenances();
const op = operationsByName['remove_link'];
await op.handler(makeCtx(), { from: 'rm-a', to: 'rm-b', link_source: 'citation-graph' });
const links = await engine.getLinks('rm-a');
const sources = links.filter(l => (l as any).to_slug === 'rm-b').map(l => (l as any).link_source);
expect(sources).toContain('manual');
expect(sources).not.toContain('citation-graph');
});
test('--link-type-only filter deletes every provenance of that type', async () => {
await seedTwoProvenances();
const op = operationsByName['remove_link'];
await op.handler(makeCtx(), { from: 'rm-a', to: 'rm-b', link_type: 'cites' });
const links = await engine.getLinks('rm-a');
expect(links.filter(l => (l as any).to_slug === 'rm-b' && (l as any).link_type === 'cites').length).toBe(0);
});
test('both filters delete only the type+source match', async () => {
await seedTwoProvenances();
const op = operationsByName['remove_link'];
await op.handler(makeCtx(), { from: 'rm-a', to: 'rm-b', link_type: 'cites', link_source: 'manual' });
const links = await engine.getLinks('rm-a');
const sources = links.filter(l => (l as any).to_slug === 'rm-b').map(l => (l as any).link_source);
expect(sources).toContain('citation-graph');
expect(sources).not.toContain('manual');
});
});
describe('list_link_sources op (B4 + OV8 + OV9)', () => {
test('op declaration: read scope, link-sources CLI name, not localOnly', () => {
const op = operationsByName['list_link_sources'];
expect(op).toBeDefined();
expect(op.scope).toBe('read');
expect(op.localOnly).not.toBe(true);
expect(op.cliHints?.name).toBe('link-sources');
});
test('returns distinct provenances with counts, ordered count DESC then name ASC', async () => {
await engine.putPage('ls-a', { type: 'note', title: 'A', compiled_truth: 'a', timeline: '', frontmatter: {} });
await engine.putPage('ls-b', { type: 'note', title: 'B', compiled_truth: 'b', timeline: '', frontmatter: {} });
await engine.putPage('ls-c', { type: 'note', title: 'C', compiled_truth: 'c', timeline: '', frontmatter: {} });
// zeta:1, alpha:2 — alpha sorts first by count; within ties, name ASC.
await engine.addLink('ls-a', 'ls-b', '', 'r1', 'alpha-src');
await engine.addLink('ls-a', 'ls-c', '', 'r2', 'alpha-src');
await engine.addLink('ls-b', 'ls-c', '', 'r3', 'zeta-src');
const op = operationsByName['list_link_sources'];
const rows = (await op.handler(makeCtx(), {})) as Array<{ link_source: string | null; count: number }>;
const map = new Map(rows.map(r => [r.link_source, r.count]));
expect(map.get('alpha-src')).toBe(2);
expect(map.get('zeta-src')).toBe(1);
// Deterministic order: counts non-increasing.
for (let i = 1; i < rows.length; i++) {
expect(rows[i - 1].count >= rows[i].count).toBe(true);
}
});
test('scalar ctx.sourceId scopes; a non-matching source returns nothing', async () => {
const op = operationsByName['list_link_sources'];
// Pages above were written to the 'default' source.
const inDefault = (await op.handler(makeCtx({ sourceId: 'default' } as any), {})) as unknown[];
expect(inDefault.length).toBeGreaterThan(0);
const inOther = (await op.handler(makeCtx({ sourceId: 'no-such-source' } as any), {})) as unknown[];
expect(inOther.length).toBe(0);
});
test('federated allowedSources ({sourceIds}) scopes (OV8)', async () => {
const op = operationsByName['list_link_sources'];
const inDefault = (await op.handler(makeCtx({ auth: { allowedSources: ['default'] } } as any), {})) as unknown[];
expect(inDefault.length).toBeGreaterThan(0);
const inOther = (await op.handler(makeCtx({ auth: { allowedSources: ['no-such-source'] } } as any), {})) as unknown[];
expect(inOther.length).toBe(0);
});
});
describe('CLI aliases + help (OV10 + OV11)', () => {
test('link-add resolves to add_link, link-rm to remove_link', () => {
expect(cliAliases.get('link-add')?.name).toBe('add_link');
expect(cliAliases.get('link-rm')?.name).toBe('remove_link');
});
test('no alias collides with any primary CLI name or another alias', () => {
const primaries = new Set(operations.map(o => o.cliHints?.name).filter(Boolean) as string[]);
const seen = new Set<string>();
for (const op of operations) {
for (const alias of op.cliHints?.aliases ?? []) {
expect(primaries.has(alias)).toBe(false);
expect(seen.has(alias)).toBe(false);
seen.add(alias);
}
}
});
test('printOpHelp shows the invoked alias name, not the primary (OV10)', () => {
const op = operationsByName['add_link'];
const lines: string[] = [];
const orig = console.log;
console.log = (...a: unknown[]) => { lines.push(a.join(' ')); };
try {
printOpHelp(op, 'link-add');
} finally {
console.log = orig;
}
const out = lines.join('\n');
expect(out).toContain('Usage: gbrain link-add');
expect(out).not.toContain('Usage: gbrain link ');
});
});