Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Identity siblings: pages in one source whose titles name the same subject
* under different prefixes ("Account sheet: Widget Co" and "CRM record:
* Widget Co"). gbrain never treats them as one identity on the title alone
* (no `entity_identities` row, no union of aliases or references). It shows
* them side by side instead: the entity card lists them with their own aliases
* and identity lines, search's alias fan-out also searches their names (each
* spliced row names the alias and page that found it), and the gazetteer links
* a name both pages claim to every candidate instead of dropping it.
*
* One rule decides a group, shared by the card, the fan-out and the
* gazetteer: same source, the same normalized title subject, pairwise
* different title prefixes, every page a linkable entity of one canonical
* type that is not `person`, none in `mentions.exclude_slugs`, none with
* frontmatter `identity: separate`, and at most SIBLING_GROUP_CAP pages (a
* larger group is `capped` and groups nothing). `mentions.sibling_merge=false`
* turns the rule off. Untrusted callers never see a private page as a sibling.
*/
import type { BrainEngine } from '../engine.ts';
import { normalizeAlias } from '../search/alias-normalize.ts';
import { canonicalTypeOf, linkableTypesFor, loadSourcePack, readMentionPolicy, type MentionPolicy, type PackTypes } from './policy.ts';
import { titleName } from './aliases.ts';
export const SIBLING_GROUP_CAP = 3;
export interface SiblingCandidate { slug: string; title: string | null; type: string | null; identity?: unknown }
export type SiblingVerdict = 'group' | 'disabled' | 'capped' | 'person' | 'type_mismatch' | 'separate' | 'excluded' | 'same_prefix' | 'subject_mismatch';
/** The prefix of a title before its last `: ` (empty for an unprefixed title), normalized. */
function titlePrefix(title: string | null): string {
const t = (title ?? '').trim();
const at = t.lastIndexOf(': ');
return at < 0 ? '' : normalizeAlias(t.slice(0, at));
}
/** Whether `pages` (two or more) form one identity-sibling group under the rule above. */
export function siblingVerdict(pages: SiblingCandidate[], pack: PackTypes | null, policy: Pick<MentionPolicy, 'siblingMerge' | 'excludeSlugs'>): SiblingVerdict {
if (!policy.siblingMerge) return 'disabled';
if (pages.length > SIBLING_GROUP_CAP) return 'capped';
const types = new Set(pages.map(p => canonicalTypeOf(p.type, pack)));
if (types.has('person')) return 'person';
if (types.size > 1) return 'type_mismatch';
if (pages.some(p => String(p.identity ?? '').trim().toLowerCase() === 'separate')) return 'separate';
if (pages.some(p => policy.excludeSlugs.includes(p.slug))) return 'excluded';
if (new Set(pages.map(p => normalizeAlias(titleName(p.title ?? '')))).size > 1) return 'subject_mismatch';
if (new Set(pages.map(p => titlePrefix(p.title))).size < pages.length) return 'same_prefix';
return 'group';
}
export interface IdentitySiblings {
/** The other pages of the group (the asked page excluded), by slug. */
pages: Array<{ slug: string; title: string; type: string | null }>;
/** True when more than SIBLING_GROUP_CAP pages share the subject, so none are shown. */
capped: boolean;
/** Why no group formed, for `extract mentions --explain`; absent when `pages` is non-empty. */
verdict?: SiblingVerdict;
}
/**
* The identity siblings of one page. Fail-soft: a read error returns no
* siblings. `excludePrivate` applies the private-page predicate to every
* candidate (untrusted callers).
*/
export async function readIdentitySiblings(engine: BrainEngine, sourceId: string, page: { slug: string; title: string | null },
opts: { excludePrivate: boolean; excludeQuarantined?: boolean; policy?: MentionPolicy; pack?: PackTypes | null }): Promise<IdentitySiblings> {
const subject = normalizeAlias(titleName(page.title ?? ''));
if (!subject) return { pages: [], capped: false, verdict: 'subject_mismatch' };
try {
const policy = opts.policy ?? await readMentionPolicy(engine);
if (!policy.siblingMerge) return { pages: [], capped: false, verdict: 'disabled' };
const pack = opts.pack !== undefined ? opts.pack : await loadSourcePack(engine, sourceId);
const types = linkableTypesFor(pack, policy);
const { privatePagesFilterForCaller } = await import('../search/private-visibility.ts');
const { quarantineFilterFragment } = await import('../quarantine.ts');
const privacy = (opts.excludePrivate ? ` AND ${privatePagesFilterForCaller('pages')}` : '')
+ (opts.excludeQuarantined ? ` AND ${quarantineFilterFragment('pages')}` : '');
const like = `%: ${subject.replace(/[\\%_]/g, m => `\\${m}`)}`;
const rows = await engine.executeRaw<{ slug: string; title: string | null; type: string | null; identity: unknown }>(
`SELECT slug, title, type, frontmatter->>'identity' AS identity FROM pages
WHERE source_id = $1 AND deleted_at IS NULL AND type = ANY($2::text[])
AND (lower(title) = $3 OR lower(title) LIKE $4)${privacy}
ORDER BY slug LIMIT ${SIBLING_GROUP_CAP + 2}`,
[sourceId, types, subject, like]);
const members = rows.filter(r => normalizeAlias(titleName(r.title ?? '')) === subject);
if (!members.some(r => r.slug === page.slug) || members.length < 2) return { pages: [], capped: false };
const verdict = siblingVerdict(members, pack, policy);
if (verdict !== 'group') return { pages: [], capped: verdict === 'capped', verdict };
return { pages: members.filter(r => r.slug !== page.slug).map(r => ({ slug: r.slug, title: r.title ?? r.slug, type: r.type })), capped: false };
} catch {
return { pages: [], capped: false };
}
}
/**
* The page facts about an identity-sibling group are attributed to: when
* `slugs` (two or three live pages one name resolved to) form one group, the
* lowest slug; otherwise null (a real ambiguity). Fact writers use it so a
* name both siblings claim ("Telostra Robotics" for its account sheet and
* CRM record) resolves instead of falling back to a slug no page has.
*/
export async function siblingCanonical(engine: BrainEngine, sourceId: string, slugs: string[], opts: { excludePrivate?: boolean } = {}): Promise<string | null> {
const unique = [...new Set(slugs)].sort();
if (unique.length < 2 || unique.length > SIBLING_GROUP_CAP) return null;
try {
const policy = await readMentionPolicy(engine);
if (!policy.siblingMerge) return null;
const { privatePagesFilterForCaller } = await import('../search/private-visibility.ts');
const rows = await engine.executeRaw<{ slug: string; title: string | null; type: string | null; identity: unknown }>(
`SELECT slug, title, type, frontmatter->>'identity' AS identity FROM pages
WHERE source_id = $1 AND deleted_at IS NULL AND slug = ANY($2::text[])${opts.excludePrivate ? ` AND ${privatePagesFilterForCaller('pages')}` : ''}`,
[sourceId, unique]);
if (rows.length !== unique.length) return null;
const pack = await loadSourcePack(engine, sourceId);
const types = new Set(linkableTypesFor(pack, policy));
if (!rows.every(r => r.type != null && types.has(r.type))) return null;
return siblingVerdict(rows, pack, policy) === 'group' ? unique[0]! : null;
} catch {
return null;
}
}
/**
* Every `entity_slug` facts about this page may be stored under: the page,
* its identity siblings, the slug of its title subject (what a fact saved
* by name got before its siblings resolved) and its bare basename
* (`companies/acme-example` -> `acme-example`, what a fact saved before the
* page existed got, #4828) when no other page claims that basename. The
* entity card and recall read all of them, so a saved fact shows up whichever
* sibling a reader asks for.
*/
export async function factEntitySlugs(engine: BrainEngine, sourceId: string, slug: string, opts: { excludePrivate?: boolean } = {}): Promise<string[]> {
const [page] = await engine.executeRaw<{ title: string | null }>(
'SELECT title FROM pages WHERE source_id = $1 AND slug = $2 AND deleted_at IS NULL', [sourceId, slug]).catch(() => []);
if (!page) return [slug];
const siblings = await readIdentitySiblings(engine, sourceId, { slug, title: page.title }, { excludePrivate: opts.excludePrivate ?? true });
const { slugify } = await import('../entities/resolve.ts');
const subject = slugify(titleName(page.title ?? ''));
const basename = await unclaimedBasename(engine, sourceId, slug);
return [...new Set([slug, ...siblings.pages.map(p => p.slug), ...(subject && subject !== slug ? [subject] : []), ...(basename ? [basename] : [])])];
}
/** The page's bare basename, when no page sits at it or at the same basename under another entity directory. */
async function unclaimedBasename(engine: BrainEngine, sourceId: string, slug: string): Promise<string | null> {
const cut = slug.lastIndexOf('/');
if (cut <= 0) return null;
const basename = slug.slice(cut + 1);
if (!basename) return null;
const { BASENAME_DIRS } = await import('../entities/resolve.ts');
const claimants = [basename, ...BASENAME_DIRS.map(dir => `${dir}/${basename}`)].filter(s => s !== slug);
const rows = await engine.executeRaw<{ slug: string }>(
'SELECT slug FROM pages WHERE source_id = $1 AND deleted_at IS NULL AND slug = ANY($2::text[]) LIMIT 1', [sourceId, claimants]).catch(() => null);
return rows && rows.length === 0 ? basename : null;
}