Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.31 Hot Memory — entity slug canonicalization.
*
* Per /plan-eng-review D4: at extract time, resolve a free-form entity name
* (e.g. "Alice") against `pages.slug` so that hot memory + the existing graph
* see the same canonical id. Falls back to a slugified form when no page
* matches.
*
* Pure helper; the engine layer is the data dependency injected by callers.
* Lives under `src/core/entities/` so signal-detector can reuse it for the
* Sonnet pass too without circular import through facts/.
*
* Bare-name prefix expansion lives before fuzzy match and slugify fallback.
* Bare first names like "Alice" score too low on pg_trgm (short strings
* have terrible trigram overlap), so without this step they fall through
* to slugify("Alice") → "alice", which spawns a phantom `people/alice.md`
* stub at brain root instead of resolving to the existing
* `people/alice-example` page. The fix queries `slug LIKE 'people/X-%'`
* (then `companies/X-%`) when fuzzy fails on a single-word bare name, and
* resolves only a single candidate; collisions fall through to the guarded
* unprefixed holding path rather than guessing from connection count.
*/
import type { BrainEngine } from '../engine.ts';
import { normalizeAlias } from '../search/alias-normalize.ts';
import { foldNonDecomposingLatin } from '../latin-fold.ts';
import { slugifySegment } from '../sync.ts';
/** Lazy: the mentions graph stays out of the OpenClaw plugin's static import graph. */
const siblingCanonical: typeof import('../mentions/siblings.ts').siblingCanonical = async (...args) =>
(await import('../mentions/siblings.ts')).siblingCanonical(...args);
import { isMissingSchemaObject } from '../utils.ts';
import { privatePagesFilterForCaller, remoteReadFloorSql } from '../search/private-visibility.ts';
import { rankingLinkSql } from '../link-ranking-policy.ts';
import { isHoldingSlug } from '../facts-fence.ts';
import { BASENAME_DIRS, PREFIX_EXPANSION_DIRS } from './basename-dirs.ts';
/**
* Canonicalize a free-form entity reference to a page slug.
*
* Resolution order:
* 1. If `raw` is already a page slug shape (contains a "/" or matches an
* exact pages.slug row in this source), return it untouched. A mention
* that is exactly one live page's own name (slug basename) resolves to
* it next, before any other page's alias, and so does (#6925) a
* slug-shaped organization reference's one live page under another
* organization directory (`companies/x` → `orgs/x`). Then an
* unambiguous alias.
* 2. Resolve a bare name only when prefix expansion finds one candidate,
* or one candidate whose title is exactly that name.
* 3. For multi-token input, take a fuzzy candidate within the source only
* when it carries the same name tokens (sameEntityName).
* 4. Fall back to a deterministic slugify: lowercase-no-spaces with
* hyphen-collapse. NOT prefixed with a directory — caller decides
* whether to prefix `people/`, `companies/`, etc.
*
* Returns null when raw is empty, whitespace-only, or holds no letter or
* number (the fallback would mint an empty slug). Any other input produces a
* non-null slug: the fallback path is the floor.
*/
export async function resolveEntitySlug(
engine: BrainEngine,
source_id: string,
raw: string,
): Promise<string | null> {
if (!raw) return null;
const trimmed = raw.trim();
if (!trimmed) return null;
// 1. Exact match on slug. If raw already looks like a slug (or matches
// a row exactly), use it.
if (looksLikeSlug(trimmed)) {
const exact = await tryExactSlug(engine, source_id, trimmed);
if (exact) return exact.retired ? (await followRetirement(engine, source_id, exact.slug))?.slug ?? fallbackSlugify(trimmed) : exact.slug;
}
// 1.25. Exact own name: a live page whose slug basename IS the mention wins
// over another page's alias — "Jordan Lee-Example" is
// people/jordan-lee-example even when a different person lists it as
// a former name.
const basenames = await findExactBasenameCandidates(engine, source_id, trimmed);
if (basenames.length === 1) return basenames[0].slug;
// 1.5. Alias-exact (v0.46.15 identity wave, #3730): an unambiguous
// page_aliases hit resolves BEFORE prefix expansion / fuzzy — the
// alias table is curated ground truth ("saoirse" → people/saoirse-x)
// while fuzzy is a guess. Live-page verified (page_aliases has no FK).
const orgVariant = await tryOrgDirVariant(engine, source_id, trimmed);
if (orgVariant) return orgVariant;
const aliased = await tryAliasExact(engine, source_id, trimmed);
if (aliased) return aliased;
if (basenames.length > 1) return fallbackSlugify(trimmed);
// 2. Prefix-expansion match: when the input looks like a bare first name
// (no slash, no prefix, slugifies to a single short token), try
// `people/<token>-%` then `companies/<token>-%`. Short bare names
// score terribly on pg_trgm — similarity('alice', 'alice-example')
// is below the fuzzy threshold — so this is the layer that catches
// `"Alice"` → `people/alice-example` before we phantom-stub a bare
// `people/alice.md`.
if (isBareName(trimmed)) {
const expanded = await tryUnambiguousPrefixExpansion(engine, source_id, trimmed);
if (expanded) return expanded;
} else {
// 3. Fuzzy match against existing pages within the source. Bare names
// deliberately skip this arm: a shared first name is not specific
// enough to choose one person by trigram score or popularity.
const fuzzy = await tryFuzzyMatch(engine, source_id, trimmed);
if (fuzzy) return fuzzy;
}
// 4. Fallback: deterministic slugify.
return fallbackSlugify(trimmed);
}
/**
* #3447 — shared fallback for both resolvers. slugify()'s `[^a-z0-9]+ → '-'`
* rule rewrites the path separator, so running slug-shaped input through it
* corrupts a well-formed slug (`people/alice-example` → `people-alice-example`)
* into one no page can ever have — and the flattened slug never resolves, so
* every re-extraction re-mints it. Path-shaped input is slugified PER SEGMENT
* (identity for already-well-formed slugs).
*
* #6691: a segment whose letters the ASCII slugify would delete (Cyrillic,
* CJK, any non-Latin script) takes the page-slug grammar sync mints
* (`slugifySegment`), so `Мария` lands on `мария`, not `''`. Latin names keep
* the ASCII form (`o-brien`, `soren`). Null when nothing is left.
*/
export function fallbackSlugify(trimmed: string): string | null {
const slug = trimmed.split('/').map(fallbackSegment).filter(Boolean).join('/');
return slug || null;
}
function fallbackSegment(segment: string): string {
return /[\p{L}\p{N}]/u.test(foldForSlug(segment).replace(/[a-z0-9]/g, '')) ? slugifySegment(segment) : slugify(segment);
}
const IDENTITY_TYPES = new Set(['person', 'company', 'fund', 'organization']);
const IDENTITY_DIRS = ['people/', 'companies/', 'funds/', 'orgs/', 'organizations/'];
/** #6925: directories that hold the same organization pages, so `companies/x`, `orgs/x` and `organizations/x` name one org. */
const ORG_DIRS = ['companies', 'orgs', 'organizations'];
function sameEntityDir(a: string | null, b: string | null): boolean {
return a === b || (a !== null && b !== null && ORG_DIRS.includes(a) && ORG_DIRS.includes(b));
}
/** #6925: the same slug under the other organization directories; empty for any other slug. */
function orgDirVariants(raw: string): string[] {
const slug = fallbackSlugify(raw.trim());
const [dir, name, ...rest] = slug?.split('/') ?? [];
if (!name || rest.length || !ORG_DIRS.includes(dir)) return [];
return ORG_DIRS.filter(d => d !== dir).map(d => `${d}/${name}`);
}
/** #6925: the one live page a slug-shaped organization reference names under another organization directory. */
async function tryOrgDirVariant(engine: BrainEngine, source_id: string, raw: string): Promise<string | null> {
const variants = orgDirVariants(raw);
if (!variants.length) return null;
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[])', [source_id, variants]);
const live = await canonicalPages(engine, source_id, rows.map(r => r.slug));
return live.length === 1 ? live[0].slug : null;
}
const NAME_NOISE_TOKENS = new Set(['the', 'inc', 'llc', 'ltd', 'co', 'corp', 'corporation', 'plc', 'gmbh']);
/** True for pages that name one real-world person, company, fund or organization. */
export function isIdentityEntity(slug: string, type?: string | null): boolean {
return !isHoldingSlug(slug) && ((type != null && IDENTITY_TYPES.has(type)) || IDENTITY_DIRS.some(dir => slug.startsWith(dir)));
}
const FACT_ENTITY_TYPES = new Set(['concept', 'project', 'deal']);
const FACT_ENTITY_DIRS = ['hosts/', 'projects/', 'concepts/', 'deals/'];
/** Pages a fuzzy fact attribution may land on: entities, never meetings, notes or other documents. */
export function isFactEntityPage(slug: string, type: string | null): boolean {
return !isHoldingSlug(slug) && (isIdentityEntity(slug, type) || (type != null && FACT_ENTITY_TYPES.has(type))
|| FACT_ENTITY_DIRS.some(dir => slug.startsWith(dir)));
}
function nameTokens(value: string): string {
const folded = foldNonDecomposingLatin(value).normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase();
const tokens = folded.split(/[^\p{L}\p{N}]+/u).filter(token => token && !NAME_NOISE_TOKENS.has(token));
return [...new Set(tokens)].sort().join(' ');
}
/**
* A fuzzy candidate names the same entity as a reference only when both carry
* the same name tokens, ignoring case, punctuation, order, accents and
* corporate suffixes. "Example, Alice" matches "Alice Example"; "Alicia
* Example" and "Alice Examples" do not, so a near-name never resolves to a
* different entity.
*/
export function sameEntityName(reference: string, candidateTitle: string | null | undefined, candidateSlug: string): boolean {
const wanted = nameTokens(reference);
return wanted !== '' && (wanted === nameTokens(candidateTitle ?? '') || wanted === nameTokens(candidateSlug.split('/').pop() ?? ''));
}
/**
* #6898: a page that hands its identity to another page. Frontmatter
* `canonical: false`, a `superseded_by` or `merged_into` (the concept-merge
* record, cycle/concept-redirects.ts) target, or a `status` that names the
* page an alias or a redirect (`historical-retired-alias`). A status that
* describes the entity itself (`retired`, `archived`, `merged`, `superseded`)
* does not retire the page: a person who retired is still that person's page,
* and a merged company or a superseded decision is still a record of its own
* unless it names a target.
*/
export function retiredPageSql(p: string): string {
return `(lower(COALESCE(${p}.frontmatter->>'canonical', '')) IN ('false', 'no')
OR btrim(COALESCE(${p}.frontmatter->>'superseded_by', '')) <> ''
OR btrim(COALESCE(${p}.frontmatter->>'merged_into', '')) <> ''
OR lower(COALESCE(${p}.frontmatter->>'status', '')) ~ '(^|[^a-z])(alias|redirect|redirected)([^a-z]|$)')`;
}
export const MAX_RETIREMENT_HOPS = 5;
/** A frontmatter redirect value as a slug: `[[people/x|X]]`, `people/x.md` and `/people/x` are `people/x`. */
function redirectSlug(value: string): string | null {
const slug = value.trim().replace(/^\[\[/, '').replace(/\]\]$/, '').split('|')[0].trim().replace(/\.md$/i, '').replace(/^\/+/, '');
return slug || null;
}
/**
* #6898: the live page that answers for `slug`. A page that is not retired
* answers for itself; a retired page hands over to its `superseded_by` (else
* `merged_into`) target in the same source, hop by hop up to
* MAX_RETIREMENT_HOPS. Null when the chain has no target, reaches a missing,
* deleted or (with `privacy`) unreadable page, cycles, or runs too long: the
* caller refuses rather than guess. The target is a human-written redirect,
* so it is followed whatever its type; the strict resolver still applies its
* fact-entity check to the page it lands on.
*/
export async function followRetirement(
engine: BrainEngine,
source_id: string,
slug: string,
privacy = '',
): Promise<{ slug: string; type: string | null } | null> {
const seen = new Set<string>();
let current: string | null = slug;
while (current && !seen.has(current) && seen.size <= MAX_RETIREMENT_HOPS) {
seen.add(current);
const [row]: Array<{ slug: string; type: string | null; retired: boolean; target: string | null }> = await engine.executeRaw(
`SELECT p.slug, p.type, ${retiredPageSql('p')} AS retired,
COALESCE(NULLIF(btrim(p.frontmatter->>'superseded_by'), ''), NULLIF(btrim(p.frontmatter->>'merged_into'), '')) AS target
FROM pages p
WHERE p.source_id = $1 AND p.slug = $2 AND p.deleted_at IS NULL ${privacy}
LIMIT 1`,
[source_id, current],
);
if (!row) return null;
if (!row.retired) return { slug: row.slug, type: row.type };
current = row.target ? redirectSlug(row.target) : null;
}
return null;
}
/** #6898: the distinct live pages that answer for `slugs` (see followRetirement); unfollowable ones drop out. */
async function canonicalPages(
engine: BrainEngine,
source_id: string,
slugs: string[],
privacy = '',
): Promise<Array<{ slug: string; type: string | null }>> {
const out = new Map<string, { slug: string; type: string | null }>();
for (const slug of new Set(slugs)) {
const page = await followRetirement(engine, source_id, slug, privacy);
if (page) out.set(page.slug, page);
}
return [...out.values()];
}
/**
* #6898: the normalized alias spellings a reference may be stored under.
* `/`, `-`, `_` and whitespace separate the same name words, so
* `Alice Example`, `alice_example` and `alice-example` meet whichever one
* the page declared. A slug-shaped reference (`people/alice-example`) names
* its last segment. The literal normalized form comes first.
*/
function aliasSpellings(raw: string): { literal: string; folded: string[]; dir: string | null } {
const literal = normalizeAlias(raw);
const segments = looksLikeSlug(raw.trim()) ? literal.split('/') : [literal];
const tokens = segments[segments.length - 1].split(/[\s/_-]+/u).filter(Boolean);
const folded = tokens.length ? [...new Set([' ', '-', '_'].map(sep => tokens.join(sep)))].filter(s => s !== literal) : [];
return { literal, folded, dir: segments.length > 1 ? segments[segments.length - 2] : null };
}
/**
* Slugs of the pages whose page_aliases row carries the reference: the
* literal spelling's hits when it has any, else the separator-folded
* spellings'. A folded hit for a slug-shaped reference must sit in the same
* directory (`projects/acme-example` never lands on a `companies/` alias);
* the organization directories count as one (#6925: `companies/acme-example`
* reaches an `orgs/` page's `acme example` alias).
* Throws what resolveAliases throws.
*/
async function aliasHitSlugs(engine: BrainEngine, source_id: string, raw: string): Promise<string[]> {
const { literal, folded, dir } = aliasSpellings(raw);
if (!literal) return [];
const hits = await engine.resolveAliases([literal, ...folded], { sourceId: source_id });
const exact = (hits.get(literal) ?? []).map(h => h.slug);
if (exact.length) return exact;
const parentDir = (slug: string) => slug.split('/').slice(-2, -1)[0] ?? null;
return folded.flatMap(s => hits.get(s) ?? []).map(h => h.slug).filter(slug => dir === null || sameEntityDir(parentDir(slug), dir));
}
/**
* Alias-exact arm (v0.46.15, #3730): unambiguous single-slug page_aliases hit,
* verified against LIVE pages — page_aliases has no FK to pages, so stale
* alias rows for deleted/renamed pages linger (outside-voice R2-8).
* Liveness is filtered BEFORE uniqueness (codex ship-review): a stale sibling
* row must not veto the sole live target — that fall-through would land on
* fuzzy/slugify and could recreate a phantom slug on a WRITE path.
* Fail-open on undefined-table (pre-v110 brains have no page_aliases table);
* other errors warn once per process so degradation isn't silent.
*/
let aliasExactWarned = false;
async function tryAliasExact(engine: BrainEngine, source_id: string, raw: string): Promise<string | null> {
try {
const hits = await aliasHitSlugs(engine, source_id, raw);
if (!hits.length) return null;
const live = await canonicalPages(engine, source_id, hits);
return live.length === 1 ? live[0].slug : await siblingCanonical(engine, source_id, live.map(p => p.slug));
} catch (err) {
if (!isMissingSchemaObject(err, 'table', 'page_aliases') && !aliasExactWarned) {
aliasExactWarned = true;
console.error(`[gbrain] alias-exact resolution degraded (falling through to fuzzy): ${err instanceof Error ? err.message : String(err)}`);
}
return null;
}
}
/**
* "Bare name" detector — true when the input is a single word with no
* slash, no embedded prefix marker, and slugifies to a non-empty token.
* Multi-word inputs (e.g. "Alice Example") are handled by fuzzy match;
* this gate only fires for short first-name-shaped tokens.
*/
function isBareName(raw: string): boolean {
if (raw.includes('/')) return false;
// One-token input. Whitespace-tokenize: "Alice" → 1, "Alice Example" → 2.
const tokens = raw.trim().split(/\s+/).filter(Boolean);
if (tokens.length !== 1) return false;
const slug = slugify(raw);
if (!slug) return false;
// Reject hyphenated multi-token slugs like "alice-example" — those
// should hit the exact-slug or fuzzy path, not prefix expansion.
if (slug.includes('-')) return false;
return true;
}
export { BASENAME_DIRS };
async function findExactBasenameCandidates(
engine: BrainEngine,
source_id: string,
raw: string,
): Promise<Array<{ slug: string }>> {
const token = slugify(raw);
if (raw.includes('/') || !token.includes('-')) return [];
let rows: Array<{ slug: string }>;
try {
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 2`,
[source_id, BASENAME_DIRS.map(dir => `${dir}/${token}`)],
);
} catch {
return [];
}
return canonicalPages(engine, source_id, rows.map(r => r.slug));
}
/**
* v0.40.2.0 — resolution-source-tagged variant for trajectory routing.
*
* Same resolution chain as `resolveEntitySlug` but returns the source
* (`exact_page` | `alias_exact` | `prefix_expansion` | `fuzzy_match` |
* `fallback_slugify`) alongside the slug so trajectory callers can gate on
* `resolution_source !== 'fallback_slugify'` — querying findTrajectory on an
* invented slug always returns [] and wastes a SQL round-trip.
*
* `prefix_expansion` is the bare single-token branch: it picks the sole
* `<dir>/<token>-*` page because it is the only candidate, not because
* anything confirms the mention is the same person or company (a bare
* "Victor" in an unrelated transcript landed on the brain's one
* `people/victor-*` page). It still verifies a live page, so
* `!== 'fallback_slugify'` gates are unaffected; `facts/backstop.ts` flags
* facts written through it as unverified.
*
* The original `resolveEntitySlug` keeps its existing contract (returns
* just the slug) for all pre-v0.40 call sites — no caller-side churn.
*/
export type ResolutionSource = 'exact_page' | 'alias_exact' | 'prefix_expansion' | 'fuzzy_match' | 'fallback_slugify';
export interface ResolveResult {
slug: string;
source: ResolutionSource;
}
export async function resolveEntitySlugWithSource(
engine: BrainEngine,
source_id: string,
raw: string,
): Promise<ResolveResult | null> {
if (!raw) return null;
const trimmed = raw.trim();
if (!trimmed) return null;
// Mirror resolveEntitySlug's resolution chain but tag each branch.
if (looksLikeSlug(trimmed)) {
const exact = await tryExactSlug(engine, source_id, trimmed);
if (exact) {
const canonical = exact.retired ? (await followRetirement(engine, source_id, exact.slug))?.slug : exact.slug;
return canonical ? { slug: canonical, source: 'exact_page' } : fallbackResult(trimmed);
}
}
const basenames = await findExactBasenameCandidates(engine, source_id, trimmed);
if (basenames.length === 1) return { slug: basenames[0].slug, source: 'fuzzy_match' };
const orgVariant = await tryOrgDirVariant(engine, source_id, trimmed);
if (orgVariant) return { slug: orgVariant, source: 'fuzzy_match' };
const aliased = await tryAliasExact(engine, source_id, trimmed);
if (aliased) return { slug: aliased, source: 'alias_exact' };
if (basenames.length > 1) {
const sibling = await siblingCanonical(engine, source_id, basenames.map(b => b.slug));
return sibling ? { slug: sibling, source: 'fuzzy_match' } : fallbackResult(trimmed);
}
if (isBareName(trimmed)) {
const expanded = await tryUnambiguousPrefixExpansion(engine, source_id, trimmed);
if (expanded) return { slug: expanded, source: 'prefix_expansion' };
} else {
const fuzzy = await tryFuzzyMatch(engine, source_id, trimmed);
if (fuzzy) return { slug: fuzzy, source: 'fuzzy_match' };
}
return fallbackResult(trimmed);
}
function fallbackResult(trimmed: string): ResolveResult | null {
const slug = fallbackSlugify(trimmed);
return slug ? { slug, source: 'fallback_slugify' } : null;
}
/**
* How a strict reference resolution found its page. `basename` is the
* unique-slug-basename arm and `same_name` the trigram arm restricted to
* pages carrying the same name tokens (both are `fuzzy_match` in
* resolveEntitySlugWithSource).
*/
export type StrictResolutionArm = 'exact_page' | 'alias_exact' | 'basename' | 'same_name';
/**
* A strict resolution miss: `ambiguous` (two live pages qualify),
* `unverified` (only a bare-name prefix guess exists), `not_entity` (the
* reference names a live page that is not a fact entity, e.g. a meeting) or
* `no_page`.
*/
export type StrictResolution =
| { slug: string; arm: StrictResolutionArm }
| { slug: null; miss: 'ambiguous' | 'unverified' | 'not_entity' | 'no_page' };
/**
* Resolve a name to a live fact-entity page using only identity evidence:
* exact slug, unique slug basename, unique alias and, with `sameName`, the
* same-name trigram arm. Never guesses from a bare-name prefix and never
* falls back to a slugified name. With `excludePrivate`, private pages are
* removed before uniqueness is counted, so an unreadable namesake can neither
* be returned nor change the outcome for a remote caller. `forCaller` reads with
* the caller's policy (a remote read); without it the plain privacy fragment
* applies, which a derived-visibility decision needs.
*/
export async function resolveStrictEntityReference(
engine: BrainEngine,
source_id: string,
raw: string,
opts: { sameName?: boolean; excludePrivate?: boolean; forCaller?: boolean } = {},
): Promise<StrictResolution> {
const trimmed = raw.trim();
if (!trimmed) return { slug: null, miss: 'no_page' };
const privacy = opts.excludePrivate ? `AND ${opts.forCaller ? privatePagesFilterForCaller('p') : remoteReadFloorSql('p')}` : '';
const live = async (slugs: string[]) => slugs.length === 0 ? [] : engine.executeRaw<{ slug: string; type: string | null }>(
`SELECT p.slug, p.type FROM pages p
WHERE p.source_id = $1 AND p.deleted_at IS NULL AND p.slug = ANY($2::text[]) ${privacy}`,
[source_id, [...new Set(slugs)]],
);
// The source pack's linkable entity types (accounts, CRM records, ...) are fact entities too.
let linkable: Set<string> | null = null;
const isEntity = async (r: { slug: string; type: string | null }) => {
if (isFactEntityPage(r.slug, r.type)) return true;
linkable ??= new Set((await (await import('../mentions/policy.ts')).loadLinkableTypes(engine, source_id).catch(() => ({ types: [] as string[] }))).types);
return r.type != null && linkable.has(r.type);
};
const pick = async (found: Array<{ slug: string; type: string | null }>, arm: StrictResolutionArm): Promise<StrictResolution | null> => {
if (found.length === 0) return null;
// #6898: a retired page answers through its superseded_by target, which must be readable too.
const rows = await canonicalPages(engine, source_id, found.map(r => r.slug), privacy);
if (rows.length === 0) return { slug: null, miss: 'not_entity' };
if (rows.length > 1) {
const sibling = await siblingCanonical(engine, source_id, rows.map(r => r.slug), { excludePrivate: opts.excludePrivate });
return sibling ? { slug: sibling, arm } : { slug: null, miss: 'ambiguous' };
}
return await isEntity(rows[0]) ? { slug: rows[0].slug, arm } : { slug: null, miss: 'not_entity' };
};
if (looksLikeSlug(trimmed)) {
const exact = await pick(await live([trimmed]), 'exact_page');
if (exact) return exact;
}
const token = slugify(trimmed);
if (!trimmed.includes('/') && token.includes('-')) {
const basename = await pick(await live(BASENAME_DIRS.map(dir => `${dir}/${token}`)), 'basename');
if (basename) return basename;
}
const orgVariant = await pick(await live(orgDirVariants(trimmed)), 'basename');
if (orgVariant) return orgVariant;
try {
const aliased = await pick(await live(await aliasHitSlugs(engine, source_id, trimmed)), 'alias_exact');
if (aliased) return aliased;
} catch (err) {
if (!isMissingSchemaObject(err, 'table', 'page_aliases')) throw err;
}
if (opts.sameName && !isBareName(trimmed)) {
try {
const rows = await engine.executeRaw<{ slug: string; title: string; type: string | null }>(
`SELECT p.slug, p.title, p.type FROM pages p
WHERE p.source_id = $1 AND p.deleted_at IS NULL ${privacy} AND NOT ${retiredPageSql('p')}
AND (lower(p.title) % $2 OR p.slug ILIKE '%' || $3 || '%')
ORDER BY GREATEST(similarity(lower(p.title), $2), similarity(p.slug, $3)) DESC, p.slug ASC
LIMIT 5`,
[source_id, trimmed.toLowerCase(), token],
);
const named = await pick(rows.filter(row => isFactEntityPage(row.slug, row.type) && sameEntityName(trimmed, row.title, row.slug)), 'same_name');
if (named) return named;
} catch (err) {
if (!isMissingTrigramError(err)) throw err;
}
}
if (isBareName(trimmed) && token) {
const prefixed = (await findPrefixCandidates(engine, source_id, token)).map(c => c.slug);
// Readable scope applies here too, so a private namesake never changes a remote outcome.
if ((opts.excludePrivate ? await live(prefixed) : prefixed).length > 0) return { slug: null, miss: 'unverified' };
}
return { slug: null, miss: 'no_page' };
}
/**
* #7248: up to five readable live pages a reference could mean, sorted by
* slug, for a refusal to name: the entity-directory basenames, organization
* variants, alias hits and bare-name prefix expansions, else the nearest
* entity pages by title or slug similarity that share the reference's first
* name token. Never a slugified guess.
*/
export async function entityReferenceCandidates(
engine: BrainEngine,
source_id: string,
raw: string,
opts: { excludePrivate?: boolean; forCaller?: boolean } = {},
): Promise<string[]> {
const trimmed = raw.trim();
const token = slugify(trimmed);
if (!token) return [];
const privacy = opts.excludePrivate ? `AND ${opts.forCaller ? privatePagesFilterForCaller('p') : remoteReadFloorSql('p')}` : '';
const aliases = await aliasHitSlugs(engine, source_id, trimmed).catch(() => [] as string[]);
const prefixed = (await findPrefixCandidates(engine, source_id, token)).map(c => c.slug);
const named = await engine.executeRaw<{ slug: string }>(
`SELECT p.slug FROM pages p
WHERE p.source_id = $1 AND p.deleted_at IS NULL AND NOT ${retiredPageSql('p')} AND p.slug = ANY($2::text[]) ${privacy}
ORDER BY p.slug LIMIT 5`,
[source_id, [...new Set([...BASENAME_DIRS.map(dir => `${dir}/${token}`), ...orgDirVariants(trimmed), ...aliases, ...prefixed])]],
);
if (named.length) return named.map(r => r.slug);
const near = await engine.executeRaw<{ slug: string; title: string; type: string | null }>(
`SELECT p.slug, p.title, p.type FROM pages p
WHERE p.source_id = $1 AND p.deleted_at IS NULL AND NOT ${retiredPageSql('p')} ${privacy}
AND (lower(p.title) % $2 OR p.slug ILIKE '%' || $3 || '%')
ORDER BY GREATEST(similarity(lower(p.title), $2), similarity(p.slug, $3)) DESC, p.slug ASC
LIMIT 20`,
[source_id, trimmed.toLowerCase(), token],
).catch(err => { if (isMissingTrigramError(err)) return []; throw err; });
const lead = token.split('-')[0]!;
const sharesLead = (r: { slug: string; title: string }) => slugify(r.title).split('-')[0] === lead || (r.slug.split('/').pop() ?? '').split('-')[0] === lead;
return near.filter(r => isFactEntityPage(r.slug, r.type) && sharesLead(r)).slice(0, 5).map(r => r.slug).sort();
}
/**
* v0.35.5 — phantom-canonical resolver. Variant of `resolveEntitySlug` that
* SKIPS the exact-slug step at the top: a phantom slug like `'alice'` would
* always exact-match itself (the phantom page exists as that exact slug),
* which made the original phantom-redirect handler a no-op (codex #1).
*
* Resolution order for phantoms:
* 1. Fuzzy match against `pages.title` / `pages.slug` within the source
* — catches Liz → Elizabeth-Warren style fuzzy title hits when no
* prefix-expansion candidate exists (round-22 case).
* 2. Prefix expansion: `people/<token>-*` then `companies/<token>-*`.
* 3. Returns null if neither path finds a prefixed canonical.
*
* The output is filtered to require `result !== phantomSlug AND result.includes('/')`
* so a fuzzy match that bounces back to the phantom itself (e.g. fuzzy on
* its own bare title) doesn't trigger a self-redirect. Caller treats null
* as `'no_canonical'`.
*/
export async function resolvePhantomCanonical(
engine: BrainEngine,
source_id: string,
phantomSlug: string,
opts: { type?: string | null } = {},
): Promise<string | null> {
if (!phantomSlug) return null;
const trimmed = phantomSlug.trim();
if (!trimmed) return null;
// Type guard: a phantom that declares an entity type only merges into a page
// of that type's directory (a company phantom never lands on people/…).
const allowedDirs = opts.type ? PHANTOM_TYPE_DIRS[opts.type] : undefined;
const typeOk = (slug: string) => !allowedDirs || allowedDirs.some(dir => slug.startsWith(`${dir}/`));
// The phantom slug is the input; we treat it as the search term too,
// because phantom slugs ARE the lowercased bare name a fuzzy / prefix
// lookup would naturally target. Short or repetitive names carry too little
// signal for a trigram match, so they skip the fuzzy tier.
if (hasNameSignal(trimmed.replace(/-/g, ' '))) {
const fuzzy = await tryFuzzyMatch(engine, source_id, trimmed, false);
if (fuzzy && fuzzy !== phantomSlug && fuzzy.includes('/') && typeOk(fuzzy)) return fuzzy;
}
const expanded = await tryPrefixExpansion(engine, source_id, slugify(trimmed));
if (expanded && expanded !== phantomSlug && expanded.includes('/') && typeOk(expanded)) return expanded;
return null;
}
/** Entity types whose phantoms may only merge into their own directories. */
const PHANTOM_TYPE_DIRS: Readonly<Record<string, readonly string[]>> = {
person: ['people'],
company: ['companies'],
project: ['projects'],
host: ['hosts'],
};
/**
* Name-specificity gate for fuzzy phantom merges: at least 6 characters or two
* tokens, and Shannon character entropy of at least 1.5 bits. Short or
* repetitive names ("ai", "aaaa") defer to the stricter prefix tier.
*/
export function hasNameSignal(name: string): boolean {
const normalized = name.trim().toLowerCase().replace(/\s+/g, ' ');
if (normalized.length < 6 && normalized.split(' ').length < 2) return false;
const chars = normalized.replace(/ /g, '');
if (!chars) return false;
const counts = new Map<string, number>();
for (const c of chars) counts.set(c, (counts.get(c) ?? 0) + 1);
let entropy = 0;
for (const n of counts.values()) { const p = n / chars.length; entropy -= p * Math.log2(p); }
return entropy >= 1.5;
}
/**
* v0.35.5 — standalone candidate query for ambiguity detection (codex #11).
*
* `tryPrefixExpansion` returns top-1-per-directory and short-circuits on
* the first non-empty directory. That's correct for the resolver hot path
* (we want the most likely match, not all of them) but wrong for the
* phantom-redirect handler which needs to KNOW whether multiple canonicals
* could absorb the phantom. This query returns every prefixed page across
* every configured dir whose slug matches `<dir>/<token>` OR `<dir>/<token>-*`,
* so the caller can count candidates and refuse to redirect when ambiguous.
*
* Returns rows ordered by `connection_count DESC, slug ASC` (deterministic
* tiebreaker for test pinning). Cap of 10 — beyond that we treat the input
* as too generic anyway and the caller skips with audit.
*/
export async function findPrefixCandidates(
engine: BrainEngine,
source_id: string,
token: string,
): Promise<Array<{ slug: string; connection_count: number }>> {
if (!token) return [];
// Build LIKE pattern set for each configured directory:
// people/<token> (bare child — covers `people/alice` exactly)
// people/<token>-% (suffixed child — covers `people/alice-example`)
// ... same for companies/
// We deliberately do NOT use `people/<token>%` (no hyphen) because that
// also matches `people/aliceberg` for token="alice" — a false positive.
const patterns: string[] = [];
for (const dir of PREFIX_EXPANSION_DIRS) {
patterns.push(`${dir}/${token}`);
patterns.push(`${dir}/${token}-%`);
}
try {
const rows = await engine.executeRaw<{
slug: string;
connection_count: number;
}>(
`SELECT p.slug,
((SELECT COUNT(*)::int FROM links l WHERE l.to_page_id = p.id AND ${rankingLinkSql('l')})
+ (SELECT COUNT(*)::int FROM links l WHERE l.from_page_id = p.id AND ${rankingLinkSql('l')})
+ (SELECT COUNT(*)::int FROM content_chunks WHERE page_id = p.id))
AS connection_count
FROM pages p
WHERE p.source_id = $1
AND p.deleted_at IS NULL
AND NOT ${retiredPageSql('p')}
AND p.slug LIKE ANY($2::text[])
ORDER BY connection_count DESC, p.slug ASC
LIMIT 10`,
[source_id, patterns],
);
return rows;
} catch {
// Defensive: any SQL hiccup returns "no candidates" so the caller's
// ambiguity gate doesn't crash the cycle. The downstream
// `resolvePhantomCanonical` runs the per-dir tryPrefixExpansion path
// separately and will surface its own errors.
return [];
}
}
/**
* The sole prefix candidate, or, when every candidate sits in one entity
* directory, the one page whose title is exactly the bare name: "Acme" is
* `companies/acme-0` titled "Acme", not `companies/acme-labs-50` titled
* "Acme Labs" (gbrain-evals N9-5). A collision across directories (a person
* and a host) or two exact titles stays ambiguous.
*/
async function tryUnambiguousPrefixExpansion(
engine: BrainEngine,
source_id: string,
raw: string,
): Promise<string | null> {
const token = slugify(raw);
const candidates = await findPrefixCandidates(engine, source_id, token);
if (candidates.length === 1) return candidates[0].slug;
if (candidates.length === 0) return null;
const patterns = PREFIX_EXPANSION_DIRS.flatMap(dir => [`${dir}/${token}`, `${dir}/${token}-%`]);
try {
const dirs = await engine.executeRaw<{ dir: string }>(
`SELECT DISTINCT split_part(slug, '/', 1) AS dir FROM pages
WHERE source_id = $1 AND deleted_at IS NULL AND NOT ${retiredPageSql('pages')} AND slug LIKE ANY($2::text[])
LIMIT 2`,
[source_id, patterns],
);
if (dirs.length !== 1) return null;
const rows = await engine.executeRaw<{ slug: string; title: string | null }>(
`SELECT slug, title FROM pages
WHERE source_id = $1 AND deleted_at IS NULL AND NOT ${retiredPageSql('pages')}
AND slug LIKE ANY($2::text[]) AND lower(title) = lower($3)
LIMIT 3`,
[source_id, patterns, raw.trim()],
);
const exact = rows.filter(r => sameEntityName(raw, r.title, r.slug));
return exact.length === 1 ? exact[0].slug : null;
} catch {
return null;
}
}
/**
* Look up pages whose slug starts with `<dir>/<token>-` for each known
* entity directory. When multiple candidates match within a directory,
* pick the one with the highest connection count (links_in + links_out +
* chunk count) — the most-mentioned entity is the most likely canonical
* target for a bare-name reference. When no candidates match in any
* directory, returns null and the caller falls through to slugify.
*/
async function tryPrefixExpansion(
engine: BrainEngine,
source_id: string,
token: string,
): Promise<string | null> {
for (const dir of PREFIX_EXPANSION_DIRS) {
const pattern = `${dir}/${token}-%`;
try {
const rows = await engine.executeRaw<{
slug: string;
connection_count: number;
}>(
// Connection count is a simple proxy for canonicality:
// (incoming links) + (outgoing links) + (content chunks).
//
// SQL shape: correlated subqueries scoped to the slug-LIKE
// candidates. The pre-v0.34.5 version used derived-table JOINs
// (SELECT FROM links GROUP BY to_page_id, etc.) which forced the
// planner to aggregate the FULL links + content_chunks tables on
// every prefix-expansion call — O(N) per call where N is total
// links/chunks in the brain. On a 100K-link / 50K-chunk brain
// that's slow.
//
// The slug LIKE filter is already selective in practice (typical
// brain has 0-5 pages per prefix), so the correlated subqueries
// run N=3 times per matched row, hitting the indexes on
// links.to_page_id, links.from_page_id, and content_chunks.page_id
// directly. Even on a pathological prefix matching 1000+ pages,
// work is bounded per-candidate, not whole-table.
`SELECT p.slug,
((SELECT COUNT(*)::int FROM links l WHERE l.to_page_id = p.id AND ${rankingLinkSql('l')})
+ (SELECT COUNT(*)::int FROM links l WHERE l.from_page_id = p.id AND ${rankingLinkSql('l')})
+ (SELECT COUNT(*)::int FROM content_chunks WHERE page_id = p.id))
AS connection_count
FROM pages p
WHERE p.source_id = $1
AND p.deleted_at IS NULL
AND NOT ${retiredPageSql('p')}
AND p.slug LIKE $2
ORDER BY connection_count DESC, p.slug ASC
LIMIT 5`,
[source_id, pattern],
);
if (rows.length === 0) continue;
// Single unambiguous match: return it.
if (rows.length === 1) return rows[0].slug;
// Multiple matches: the top row (sorted by connection_count desc)
// wins. The slug-ASC secondary key makes ties deterministic when
// connection counts collide — important for test pinning. The
// phantom pass's findPrefixCandidates gate refuses any multi-candidate
// redirect, so this top row is never taken on its own.
return rows[0].slug;
} catch {
// Defensive: a missing table or index shouldn't crash extraction.
// Try the next directory (or fall through to slugify).
continue;
}
}
return null;
}
export function looksLikeSlug(s: string): boolean {
// Slug shape: lowercase Unicode letters/numbers plus the path and slug
// separators. Slugs are not ASCII-only: a non-Latin entity page such as
// `people/<hangul-name>` must take the exact-match path before fuzzy
// matching. Anything with whitespace or uppercase letters still fails.
if (/\s/.test(s)) return false;
if (s !== s.toLowerCase()) return false;
return /^[\p{L}\p{N}/_-]+$/u.test(s);
}
async function tryExactSlug(
engine: BrainEngine,
source_id: string,
candidate: string,
): Promise<{ slug: string; retired: boolean } | null> {
// A database error propagates: degrading to the fallback slug would
// silently attribute the caller's facts to a different entity.
const exact = (retired: boolean) => engine.executeRaw<{ slug: string }>(
`SELECT slug FROM pages WHERE source_id = $1 AND slug = $2 AND deleted_at IS NULL AND ${retired ? '' : 'NOT'} ${retiredPageSql('pages')} LIMIT 1`,
[source_id, candidate],
);
const [live] = await exact(false);
if (live) return { slug: live.slug, retired: false };
const [retired] = await exact(true);
return retired ? { slug: retired.slug, retired: true } : null;
}
async function tryFuzzyMatch(
engine: BrainEngine,
source_id: string,
raw: string,
sameNameOnly = true,
): Promise<string | null> {
const lc = raw.toLowerCase();
const fragment = slugify(raw);
// Prefer titles (display names) over slug fragments since user input
// tends to be display-name-shaped ("Alice Example" vs "alice-example"). Cap at
// 3 candidates; pick the first deterministic one.
try {
const rows = await engine.executeRaw<{ slug: string; title: string; type: string | null; score: number }>(
`SELECT slug, title, type,
GREATEST(
similarity(lower(title), $2),
similarity(slug, $3)
) AS score
FROM pages
WHERE source_id = $1
AND deleted_at IS NULL
AND NOT ${retiredPageSql('pages')}
AND (
lower(title) % $2
OR slug ILIKE '%' || $3 || '%'
)
ORDER BY score DESC, slug ASC
LIMIT 5`,
[source_id, lc, fragment],
);
// A trigram score alone attributes facts about "Alicia Example" to Alice,
// and facts about a person with no page to a meeting page that carries
// their name. Entity resolution takes a candidate only when it names the
// same entity; anything else falls back to the reference's own slug.
// Only entity pages are candidates (a meeting titled "Dana Jones Example"
// is not Dana), and two entity pages carrying the same name are
// ambiguous: neither wins by trigram score.
if (sameNameOnly) {
const named = rows.filter(row => isFactEntityPage(row.slug, row.type) && sameEntityName(raw, row.title, row.slug));
return named.length === 1 ? named[0].slug : null;
}
// Phantom canonicals: a clear winner only, with a margin over the runner-up.
if (rows.length > 0 && rows[0].score >= 0.7 && (rows.length === 1 || rows[0].score - rows[1].score >= 0.1)) return rows[0].slug;
} catch (err) {
// pg_trgm might not be installed on every engine config: that brain has
// no fuzzy arm and falls through to slugify. Any other database error
// propagates rather than becoming a silent misattribution.
if (!isMissingTrigramError(err)) throw err;
}
return null;
}
function isMissingTrigramError(err: unknown): boolean {
const code = typeof err === 'object' && err !== null && 'code' in err ? String((err as { code?: unknown }).code) : '';
const message = err instanceof Error ? err.message : String(err);
return code === '42883' || /function similarity|operator does not exist: text %/i.test(message);
}
/**
* Deterministic slugify: lowercase, fold accents and stroke letters to their
* base letter, replace non-alphanumerics with hyphens, collapse repeated
* hyphens, trim leading/trailing hyphens.
*
* Exported for tests + callers who want the same fallback shape independently.
*/
export function slugify(raw: string): string {
// Stroke letters carry no decomposition, so the mark strip cannot fold them
// and the sweep below would DELETE them: "Đăng Example" slugged to
// "ang-example". Fold after the strip so composed forms reduce in one pass
// ("ǿ" → "ø" → "o").
return foldForSlug(raw)
.replace(/[^a-z0-9]+/g, '-')
.replace(/-+/g, '-')
.replace(/^-+|-+$/g, '');
}
/** Lowercase, accent marks stripped, stroke letters folded: what `slugify` keeps `[a-z0-9]` from. */
function foldForSlug(raw: string): string {
// NFKD decomposes accents into combining marks (U+0300..U+036F); strip them
// before replacing the rest with hyphens so "è" → "e", not "e" + "-".
return foldNonDecomposingLatin(raw.toLowerCase().normalize('NFKD').replace(/[\u0300-\u036f]/g, ''));
}